跳到正文

/troubleshooting

排错手册

按错误现象索引：401、404、wire_api 报错、模型不存在、429 限流、MCP 工具搜索失效、后台任务不走中转。

按你看到的现象往下找。每条给的是「为什么」和「怎么定位」，不是让你挨个试。

先做这一步：把问题分成两半

配置类问题九成能靠这条命令定位。它绕开客户端，直接打中转站：

终端
curl -i -X POST "https://otokapi.com/v1/messages" \
  -H "Authorization: Bearer sk-YOUR-API-KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
把 sk-YOUR-API-KEY 换成真实密钥再跑。
  • curl 通了，客户端不通 → 问题在客户端配置。往下看对应的条目。
  • curl 也不通 → 问题在密钥、地址或账户状态，和客户端无关。

401 API_KEY_REQUIRED

{"code":"API_KEY_REQUIRED","message":"API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"}

服务端没收到有效凭据。按可能性排序：

  1. 密钥写错或过期。 去控制台密钥页核对。密钥以 sk- 开头。
  2. Claude Code 用错了变量。 确认写的是 ANTHROPIC_AUTH_TOKEN 而不是别的名字。拼错的变量不会报错，只会被忽略，表现就是 401。
  3. Codex 的环境变量没生效。 env_key 指向的变量在当前 shell 里是不是真的有值：
终端
echo "${OPENTOKEN_API_KEY:-（未设置）}"
输出为空说明变量没设上，或者你改了 rc 文件但没重开终端。
  1. 改了 shell 但 settings.json 里有旧值。 见下面改了配置却没生效。

404 page not found

地址错了。绝大多数情况是 /v1 加错了位置：

客户端正确写法常见错误
Claude Codehttps://otokapi.com多写了 /v1
Codex CLIhttps://otokapi.com/v1少写了 /v1

Claude Code 会自己拼 /v1/messages，Codex 会自己拼 /responses。两个客户端一起配的时候最容易搞反。

另一种可能是你在请求 OpenToken 不提供的端点（embeddings、图像生成等），清单见模型与端点。

Codex 报 wire_api 错误

`wire_api = "chat"` is no longer supported.
How to fix: set `wire_api = "responses"` in your provider config.

chat 这个值已被官方移除。打开 ~/.codex/config.toml，把它改成 responses：

~/.codex/config.toml
[model_providers.opentoken]
wire_api = "responses"
也可以整行删掉——省略时默认就是 responses。

你大概率是照着某篇中文教程配的——网上绝大多数 Codex 接入中转的教程还停留在 chat 时代。完整的正确配置见 Codex 接入页。

模型不存在 / 模型名报错

两个客户端走中转时都不校验模型名，所以错误要到第一次请求才出现。跑一次实时列表对拼写：

终端
curl -s -H "Authorization: Bearer sk-YOUR-API-KEY" \
  https://otokapi.com/v1/models | jq -r '.data[].id'

Claude Code 可以干脆不配 ANTHROPIC_MODEL，用默认模型名即可。Codex 的 model 是必填的，只能填对。

429 / 请求被限流

默认限额是每分钟 60 次请求、突发 10、并发 5 条连接。触发限流通常是这两种情况：

  • 并发跑多个 agent 或多个终端窗口。 并发上限只有 5，Claude Code 的子任务也算在内。
  • 脚本循环里连续打请求。 加个间隔，或者做指数退避重试。

限额是账户级的，和你开几个客户端无关。

改了配置却没生效

其他几种可能：

  • 改完没重启客户端。 配置在启动时读取，改完要重开 claude / codex。
  • Codex 的配置放进了项目目录。 项目里的 .codex/config.toml 会忽略 model_provider 和 model_providers，只在启动时打一行警告。中转配置只能放在用户级的 ~/.codex/config.toml。
  • CC Switch 把你手动改的覆盖了。 CC Switch 每次切换供应商都会重写这些文件。两条路别混用，见 CC Switch 到底改了哪些文件。
  • Windows 上 setx 只影响新窗口。 当前这个终端窗口拿不到新值，重开一个。

MCP 工具搜索失效

ANTHROPIC_BASE_URL 指向非官方主机时，Claude Code 会默认关闭 MCP tool search。这是客户端的策略，不是 OpenToken 的限制。

需要它就显式打开：

~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://otokapi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-YOUR-API-KEY",
    "ENABLE_TOOL_SEARCH": "true"
  }
}
前提是中转站原样转发 tool_reference 块。打开后如果 MCP 工具行为异常，把这行去掉。

Remote Control 用不了

从 Claude Code v2.1.196 起，只要 ANTHROPIC_BASE_URL 指向 api.anthropic.com 以外的主机，Remote Control 就会被禁用。这个没有开关，用中转就用不了它。要用只能切回官方账号。

后台任务不走中转

在 shell 里 export 的变量传不到 Claude Code 派生的后台 agent。官方的建议很直接：需要后台任务也走网关，就把配置写进 ~/.claude/settings.json 的 env 块，别依赖 shell 变量。

Codex 登录态没了

用了 auth.json 方案（requires_openai_auth = true），或者用 CC Switch 切换过 Codex 供应商，~/.codex/auth.json 就被覆盖了——那也是 Codex 存 ChatGPT 登录态的文件。

恢复官方账号要重新 codex login。想避免这个问题，Codex 走环境变量方案（env_key），它完全不碰 auth.json。

还是不行