故障排查

报错对照表：Claude Code 与 Codex 接中转 API 常见错误

同一句报错，直连官方和走中转的成因往往完全不同。这张对照表按「网络 → 鉴权 → 协议 → 模型 → 上下文」五层组织，每层给出可复制的探测命令和判断标准。

核查日期 2026-10-26适用于

Claude Code 2.xCodex CLI 0.154.0

怎么用这张表

别急着在报错原文里找答案，先确定是哪一层出的问题。AI 客户端的报错几乎都来自这五层：

网络层：请求根本没到服务器
鉴权层：到了但 key 不认
协议层：key 认了但路径/格式不对
模型层：协议通了但模型不存在
上下文层：模型在跑但输入太长

分层的价值在于：每一层的修法完全不同，而且从报错原文往往看不出是哪一层。

按 HTTP 状态分层排查

以下命令分别检测模型列表和三种协议，并显示每次请求的 HTTP 状态：

先在运行 curl 的同一个终端设置自己的 KimiSeek API Key（替换占位值）。客户端中的凭证不会自动变成这个 shell 环境变量：

Shell · API key

# Replace the placeholder with your own key from the dashboard.
export KIMISEEK_API_KEY="ks-your-key"

Shell · API diagnostics

# Inspect each HTTP status and error body; a model list does not prove sufficient balance.
# 1. Is the key valid at all? (lists models)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/models\n' https://api.kimiseek.app/v1/models \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}"

# 2. OpenAI Chat Completions
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/chat/completions\n' https://api.kimiseek.app/v1/chat/completions \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

# 3. Anthropic Messages (the protocol Claude Code speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/messages\n' https://api.kimiseek.app/v1/messages \
  -H "x-api-key: ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}'

# 4. OpenAI Responses (the protocol Codex speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/responses\n' https://api.kimiseek.app/v1/responses \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","input":"ping","max_output_tokens":16}'

请读取每段响应末尾的 HTTP 状态，以及响应正文中的 error.code、error.type 和 message，不要仅凭失败步骤判断协议是否实现。模型列表返回 200 只说明 Key 有效，不代表余额充足；例如余额为 0 时，第 1 步可返回 200，而第 2 步会返回 402。

状态或错误	如何判断	下一步
200 且响应结构正确	当前接口请求成功，不代表所有工具能力都正常	再验证客户端配置和实际工具调用
401 / 403	凭证、Key 限额或模型访问权限问题	检查 Key 是否有效、启用、过期或达到限额，以及上游授权
402 / `insufficient_balance`	账户余额不足	充值后重试，无需修改协议配置
400 / 404，正文提示 `model_not_found`、`not_found_error` 或模型不存在	模型 ID 不正确、已停用，或上游没有该模型权限	从模型列表选择完整 ID，确认渠道和模型授权
400，正文提示参数无效	请求字段或模型限制不兼容	按错误正文检查消息、工具和 token 限制
404，正文明确提示路由或 endpoint 不存在	请求路径可能不正确，或网关未提供该接口	先核对 Base URL 与 `/v1`，再确认网关的协议支持；404 本身不能区分模型和路由问题
429	限流、额度限制或上游过载	查看错误正文，等待后重试或调整用量
5xx	网关或上游暂时故障	保留错误信息与请求 ID，稍后重试
HTTP 000 / curl 连接或超时错误	没有收到 HTTP 响应；探测命令每次最多等待 30 秒	检查 DNS、代理和网络；探测超时不代表协议未实现

Claude Code 侧

没有凭证

Claude Code · no credentials

Invalid API key · Please run /login

出现这句说明 Claude Code 没拿到任何凭证。检查 ANTHROPIC_AUTH_TOKEN 是否在启动 Claude Code 的那个 shell 里生效——常见错误是在 A 终端 export、在 B 终端启动。

401 鉴权失败

Claude Code · 401

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid api key"}}

成因按概率排：

key 复制时带了空格或换行
key 已被吊销或额度耗尽
用了 ANTHROPIC_API_KEY 但值是空的，客户端回退到登录态

403 forbidden

Claude Code · 403

API Error: 403 {"type":"error","error":{"type":"forbidden","message":"invalid x-api-key"}}

这句在直连时通常意味着 key 无效；在走中转时更常见的成因是请求头的写法不对：有的网关只认 Authorization: Bearer，有的只认 x-api-key。KimiSeek 两种都认，但如果你中间又套了一层代理，header 可能被改写。

model not found

Claude Code · model not found

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"model: deepseek-v4-flash-0731 not found"}}

两种可能：模型名拼错，或者用了已下线的模型。已下线的模型 id 会一直报 not found，而不是提示已下线，这是最容易浪费时间的坑——翻半天配置，其实是模型换了代。

去模型页用真实的 id 替换。

流式响应中途断开

Claude Code · stream cut

API Error: stream disconnected before completion: stream closed before completion

流式连接被中途截断。按这个顺序查：

本地 HTTP 代理（HTTPS_PROXY）是否在拦
公司网络是否有响应超时
服务端是否触发了单次请求时限

Claude Code 使用的 /v1/messages 上游请求超时为 600 秒；Codex 使用的 /v1/responses 为 175 秒。客户端或中间代理可能更早断开连接，请结合实际接口和错误信息判断。

上下文超限

Claude Code · context overflow

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 210000 tokens > 200000 maximum"}}

注意这里的 200000 是客户端或模型的上限，不是你想的那个数字。接 DeepSeek V4 Pro 时实际上限是 1M，如果你看到 200000，说明请求没走到目标模型，或者客户端自己按 Claude 的规格截断了。

Codex 侧

401 Missing bearer

Codex · 401

■ unexpected status 401 Unauthorized: Missing bearer

config.toml 里的 env_key 只是变量名，真正的值要在环境里。这句报错就是「变量名写了，但环境变量是空的」。

404 Not Found

Codex · 404

■ unexpected status 404 Not Found

八成是 base_url 少写了 /v1。Codex 会拼 base_url + "/responses"，少了 /v1 就打到站点路径上。

确认 base_url 后，还要检查返回体是否提示模型不存在。如果网关确实没有 /v1/responses，请使用支持 Responses 的网关或转换层；当前 Codex 不接受 wire_api = "chat"。详见 Codex 教程。

流中断

Codex · stream cut

■ stream disconnected before completion

同 Claude Code 的流式问题，但 Codex 对中断更敏感——它的执行循环依赖完整的事件流。网络不稳时优先换网络，不要靠重试。

网络层的两种典型

Shell · network layer

fetch failed
ECONNREFUSED 127.0.0.1:7890

fetch failed 是 Node 的通用网络错误，字面意思没有信息量。要看具体原因得看 ECONNREFUSED 那一行——如果指向 127.0.0.1:7890 这类本地端口，说明请求被本地代理接管了，而代理没跑或规则不对。

这类问题最容易被误判成「网关挂了」。判断方法：curl 能通但客户端不通，基本就是客户端所在的 shell 环境变量与 curl 所在的 shell 不同。

同一句报错，直连与中转成因不同

这是走中转时最需要建立的心智模型：

报错	直连官方	走中转
`invalid x-api-key`	key 本身无效	header 名不被网关识别，或被中间代理改写
`model not found`	模型名写错	网关的模型映射表里没有这个 id，或用了已下线模型
`stream disconnected`	官方服务抖动	本地代理、公司网络、网关超时三者之一
`prompt is too long`	超过 200K	网关把请求转给了上下文更小的上游模型
401	key 错	key 对，但环境变量没传到客户端进程

提交问题时带上这些

如果你要问人（或提工单），下面四样缺一不可，否则没人能帮你定位：

报错原文（完整一行，不要截图半截）
curl 分层探测的结果——四步里哪步失败了
客户端版本（claude --version / codex --version）
用的模型 id 与 Base URL（key 打码）

核查日期

核查日期：2026-10-26
错误示例用于定位问题，具体文案可能随客户端版本变化；排查时请附上实际版本号。当前 Codex 配置按 0.154.0 核对。

常见问题

为什么 curl 能通，客户端就是不通？

最常见的原因是环境变量不在同一个 shell 里。客户端读的是它自己进程的环境，你在另一个终端 export 是没用的。先确认启动客户端的那个 shell 里 echo $ANTHROPIC_AUTH_TOKEN 有值。

403 和 401 到底怎么区分？

401 是「不知道你是谁」，403 是「知道你是谁但不让你干」。走中转时 403 更多是 header 写法或路由策略问题，401 更多是 key 本身或环境变量问题。

上下文超限报 200000，但模型写着 1M，为什么？

说明请求没走到你以为的那个模型。可能模型 id 写错被落到了默认模型，也可能客户端按 Claude 的规格自己截断了。用 /v1/models 确认 id，再看客户端设置里的 context window。

重试能解决流中断吗？

通常不能。流中断是连接层的问题，重试只是重复一次同样的失败。先查代理和网络，再考虑把长任务拆小。