> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4096bytes.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

> 排查 4096bytes 客户端接入中的常见错误

这里列出接入 4096bytes 时最常见的问题。排查时先确认三件事：API Key 是否完整、Base URL 是否正确、模型名是否和控制台一致。

## 接入参数

<AccordionGroup>
  <Accordion title="Base URL 应该填什么">
    OpenAI 兼容客户端通常填写 `https://api.4096bytes.com`。如果控制台在 **使用密钥** 弹窗中给出了客户端专用地址，请以控制台显示为准。
  </Accordion>

  <Accordion title="需要自己加 /v1、/chat/completions 或 /messages 吗">
    不要手动拼接接口路径。大多数客户端只需要填写 Base URL 根地址，具体路径由客户端自己追加。Claude Code、Codex、Cursor 等客户端的地址格式也不完全相同，请按对应章节配置。
  </Accordion>

  <Accordion title="模型名从哪里获取">
    模型名以控制台展示为准。复制时要保留大小写、数字、短横线和版本号。不要直接复制其他用户截图、旧文档或聊天记录里的模型名。
  </Accordion>

  <Accordion title="文档里的示例值可以直接复制吗">
    `YOUR_4096BYTES_API_KEY`、`PASTE_MODEL_NAME_FROM_DASHBOARD` 这类值是占位符。真实 API Key 和模型名需要从控制台复制。文档中固定出现的 `https://api.4096bytes.com` 是当前 OpenAI 兼容接入地址。
  </Accordion>
</AccordionGroup>

## API Key 管理

<AccordionGroup>
  <Accordion title="多个客户端可以共用同一个 API Key 吗">
    技术上可以，但不推荐。建议 Codex、Claude Code、Cursor、Cherry Studio 分别使用独立 API Key。这样可以按客户端查看消耗来源，也能在某个客户端泄露时只停用对应 Key。
  </Accordion>

  <Accordion title="API Key 创建后还能再次查看完整内容吗">
    通常不能。请在创建成功后立即复制并保存。如果忘记保存，建议删除旧 Key 后重新创建。
  </Accordion>

  <Accordion title="API Key 泄露了怎么办">
    立即到控制台删除泄露的 API Key。然后创建新的 Key，并更新对应客户端配置。不要继续使用已经出现在截图、聊天记录、日志或公开仓库里的 Key。
  </Accordion>

  <Accordion title="要不要给 API Key 设置额度限制">
    个人长期使用可以先不设置。临时测试、团队成员、共享设备或不常用客户端建议设置较小额度，避免异常请求消耗过多余额。
  </Accordion>
</AccordionGroup>

## 报错排查

<AccordionGroup>
  <Accordion title="报 401 或认证失败怎么办">
    401 通常表示 API Key 无效、已删除、复制不完整或带有多余字符。请从控制台重新复制 API Key，确认没有空格、换行、中文引号或隐藏字符。
  </Accordion>

  <Accordion title="报 403 或没有权限怎么办">
    403 通常和 Key 权限、分组、模型可用范围或账号状态有关。请确认 Key 所属分组可用，并且该分组包含你正在调用的模型。
  </Accordion>

  <Accordion title="报 404 或接口不存在怎么办">
    404 通常表示 Base URL 填错，或客户端把接口路径拼接到了错误位置。请使用 `https://api.4096bytes.com`，并删除手动添加的完整接口路径。
  </Accordion>

  <Accordion title="报 429 或请求过多怎么办">
    429 通常表示当前请求频率、并发或额度达到限制。请降低并发，稍后重试，或检查控制台里的余额、Key 额度和速率限制。
  </Accordion>

  <Accordion title="报 model not found 怎么办">
    模型名需要和控制台显示完全一致。请重新复制模型名，确认大小写、数字、短横线和后缀没有变化。
  </Accordion>

  <Accordion title="报 unsupported protocol 或 invalid URL 怎么办">
    通常是 Base URL 格式不完整。确认地址以 `https://` 开头，不要写成 `api.4096bytes.com`，也不要多写空格、引号或换行。
  </Accordion>
</AccordionGroup>

## 客户端行为

<AccordionGroup>
  <Accordion title="客户端保存配置后还是失败怎么办">
    先重启客户端。再检查是否有多个配置位置、多个供应商或多个模型列表。确认当前会话选中的模型来自 4096bytes。
  </Accordion>

  <Accordion title="为什么 Cursor 仍然走官方模型">
    Cursor 的自定义 API Key 不一定覆盖所有内置功能。请在 Chat 或 Agent 的模型选择器中手动选择 4096bytes 模型。Tab、补全、索引等功能可能仍由 Cursor 自身服务处理。
  </Accordion>

  <Accordion title="为什么 Claude Code 配置了 Base URL 仍然不生效">
    Claude Code 读取 Anthropic 相关环境变量。请按 [Claude Code](/clients/claude-code) 页面使用 `ANTHROPIC_BASE_URL` 和对应认证变量，不要把 OpenAI 兼容路径直接填入其他字段。
  </Accordion>

  <Accordion title="Codex 仍然使用旧模型怎么办">
    确认新的配置位于 `~/.codex/config.toml` 文件开头，并且 `model_provider` 指向 4096bytes 对应的 Provider。保存后重新打开终端。
  </Accordion>

  <Accordion title="Cherry Studio 或其他客户端没有显示模型怎么办">
    如果客户端不能自动拉取模型列表，请手动添加控制台展示的模型名。添加后重新选择当前会话使用的模型。
  </Accordion>
</AccordionGroup>

## 使用与性能

<AccordionGroup>
  <Accordion title="为什么第一次请求比较慢">
    第一次请求可能包含客户端初始化、网络连接、模型冷启动或较长上下文处理。可以先用短问题测试，再逐步增加上下文长度。
  </Accordion>

  <Accordion title="响应慢应该怎么排查">
    先减少上下文、附件和并发请求。再检查本地网络、代理、客户端日志和控制台请求记录。大型代码库、长对话和多 Agent 并行都会增加耗时。
  </Accordion>

  <Accordion title="余额充足但请求失败怎么办">
    还需要检查 Key 额度、Key 有效期、速率限制、分组状态和模型可用性。账户余额只是其中一个条件。
  </Accordion>

  <Accordion title="请求记录或用量怎么看">
    进入控制台查看账号、Key 或分组相关的用量记录。为了方便定位问题，建议每个客户端使用独立 Key。
  </Accordion>
</AccordionGroup>

## 联系支持

<AccordionGroup>
  <Accordion title="联系支持时需要提供哪些信息">
    请提供客户端名称和版本、报错文本、请求时间、模型名、Base URL、账号邮箱或账号标识、脱敏后的配置截图。不要发送完整 API Key。
  </Accordion>

  <Accordion title="哪些信息不要发给支持人员">
    不要发送完整 API Key、账号密码、支付凭证、私有代码仓库内容或包含敏感信息的完整日志。截图前请遮挡 Key 和个人信息。
  </Accordion>
</AccordionGroup>

## 推荐排查顺序

1. 重新复制 API Key。
2. 确认 Base URL 是 `https://api.4096bytes.com`，或使用控制台给出的客户端专用地址。
3. 重新复制模型名。
4. 确认供应商类型和客户端页面匹配。
5. 重启客户端或终端。
6. 检查账号余额、Key 额度、有效期、速率限制和分组状态。
7. 带上脱敏信息联系支持。

如果你还没有完成基础配置，请先阅读 [获取 API Key](/quickstart/get-api-key)，再进入对应客户端页面。