常见问题总览
本页按客户端收录接入和使用过程中较常见的问题。先确认你用的是哪个客户端，再进入对应页面排查 —— 不同客户端的配置文件和启动方式不能混用。
按客户端选择
| 客户端 | 配置教程 | 常见问题 |
|---|---|---|
| Codex CLI / VS Code 插件 | Codex 配置 | Codex 常见问题 |
| ChatGPT 桌面版 | ChatGPT 桌面版配置 | ChatGPT 常见问题 |
| Claude Code CLI | Claude Code 配置 | Claude Code 常见问题 |
| Claude Code 桌面版 | Claude 桌面版配置 | Claude 桌面版常见问题 |
| Gemini CLI / Antigravity | Gemini 配置 | Gemini 常见问题 |
| OpenClaw | OpenClaw 配置 | OpenClaw 常见问题 |
| Hermes Agent | Hermes Agent 配置 | Hermes 常见问题 |
| WorkBuddy | WorkBuddy 配置 | WorkBuddy 常见问题 |
| Kimi Code CLI | Kimi Code 配置 | Kimi Code 常见问题 |
| Grok Build | Grok Build 配置 | Grok Build 常见问题 |
| GLM（通过 Claude Code） | GLM 配置 | GLM 常见问题 |
| Cherry Studio / Chatbox | 小白教程 | 本页下方 |
常见报错速查
先看状态码，能快速分清是密钥、路径还是上游问题。
| 状态码 | 含义 | 优先检查 |
|---|---|---|
| 401 | 未授权 / API_KEY_REQUIRED | Authorization: Bearer *** 是否存在、环境变量是否为空、Key 是否填到了错误字段 |
| 404 | 找不到 chat/completions | 主调用路径是 /v1/messages 与 Responses API；客户端只能发 /v1/chat/completions 时，切换到对应模式 |
| 200 但模型不可用 | 有响应但不能用 | 先确认 CC-Switch 当前 Provider 已启用；直接调 API 的开发者请求 /v1/models，用返回的模型 ID |
| 429 | 限流 | 降低并发与频率；免费/赠送额度账号限流更严 |
| 503 | get_channel_failed | 该模型暂时没有可用通道，稍后重试 |
| 请求卡住 / 超时 | 上游或本地问题 | 先用最短文本测试；确认没有额外代理、错误的流式设置或重复的 /v1 路径 |
再逐项排查：
| 现象 | 优先检查 |
|---|---|
model_not_found / 当前服务暂不支持该模型 | 模型名称是否正确，令牌分组是否支持该模型 |
403 Forbidden / 令牌无权访问模型 | 令牌的「模型可用列表」是否限制了当前模型 |
仍在连接 api.anthropic.com | Claude Code 是否读取了正确的 settings.json 和 ANTHROPIC_BASE_URL |
API Error: 524 | 是否用了长连接地址；完全重启客户端 |
API Error: 400 | 模型名称和令牌分组 |
| 修改配置后没有变化 | 完全退出并重启客户端；检查 CODEX_HOME / CLAUDE_CONFIG_DIR |
Failed to parse JSON | 关闭代理或更换网络 |
合规与封禁风险
请仅将 API 用于合法、正常的开发和测试
以下行为可能触发风控，导致 API Key、令牌分组或相关账号被限制甚至封禁：
- 发送探针、扫描或批量试探请求，用于探测接口、模型、账号状态或平台规则
- 将 API 对接到沉浸式翻译、酒馆等工具，并用于违规内容、绕过平台限制或其他违法违规用途
- 连续触发官方账号的风险提示或风控规则
- 破解、盗用、撞库、绕过验证，或以其他方式破坏、规避官方账号安全机制
请控制请求频率和并发，遵守相关平台的服务条款与法律法规；出现风险提示时应立即停止相关请求并排查调用内容。