Skip to content

错误排查指南 ​

按界面报错或状态码查找对应小节。

排查前先看服务状态

先打开 服务运行状态。服务端在维护或故障时,本地改配置无法解决,等待恢复即可。

1. 401:认证失败 / 无效的令牌 / 仍提示登录 ​

1.1 请求地址是平台(api.codexzh.com) ​

按顺序排查:

  1. 客户端未彻底重启:Windows 上的 ChatGPT / Codex 客户端必须从右下角托盘退出(或在任务管理器结束进程),macOS 按 Command + Q 完全退出再重开。
  2. 核对配置与密钥:对照 手动配置 检查 ~/.codex/config.toml 和 auth.json,确认 Key 复制完整、无多余空格。如果通过 VS Code SSH 连接远程服务器,配置必须写在远程服务器的 ~/.codex/ 下。
  3. 检查套餐与周限额:登录控制台确认套餐未到期、本周剩余额度大于 0(显示 - 或负数代表本周额度已耗尽)。
  4. macOS 读取 auth.json 权限异常:如果套餐和 Key 都正常,仍提示 unexpected status 401 Unauthorized: 无效的令牌,打开 ~/.codex/config.toml,在已有的 [model_providers.codexzh] 段末尾补充一行 experimental_bearer_token:
    toml
    [model_providers.codexzh]
    name = "codexzh"
    base_url = "https://api.codexzh.com/v1"
    wire_api = "responses"
    requires_openai_auth = true
    web_search = "live"
    experimental_bearer_token = "sk-替换为你的CodexZH密钥"
    保存后彻底退出客户端,重新打开并新建会话。

1.2 报错 url 里是 api.openai.com(invalid_api_key) ​

完整报错包含 url: https://api.openai.com/v1/responses, auth error code: invalid_api_key。说明请求没有走平台中转,直接发到了 OpenAI 官方。

常见触发原因是会话开启了「让 Codex 替我审批」,而默认审查模型已下架,客户端回落到了官方地址。

解决方法:

  • 新建一个会话,在权限里选「请求审批」或「完全访问权限」,不要选「替我审批」(旧会话无法直接改)。
  • 如果确实需要自动审批,按 Auto Review 自动审批配置 显式指定审查模型和 provider。

2. 403:客户端异常 / 用户额度不足 ​

2.1 检测到您的客户端存在异常,请使用标准 Codex 客户端请求 ​

平台仅对标准 Codex 客户端开放接入,用 Python/Node SDK 直连、经过二次分发网关或客户端版本过旧会触发此拦截(通过 CC-Switch 使用时也会在 cause 中显示同一段文案)。

解决方法:

  1. 换回标准客户端(ChatGPT 客户端 Codex 模式 / Codex CLI / 官方 VSCode 插件)。
  2. 将客户端和 CC-Switch 升级到最新版,并确认中间没有额外的 API 转发层。
  3. 仍报错请提供报错里的 request id 联系客服。

2.2 token quota is not enough / 用户额度不足 ​

说明当周额度已用完(token remain quota 为剩余额度,负数代表已超支),并非接口故障。可等待下周一 0 点自动刷新,或购买 加油包 / 升级套餐。


3. 429:请求过多 / 重试次数超限 ​

先看完整报错文案,两种 429 原因不同:

  • exceeded retry limit, last status: 429 Too Many Requests(或提示 Selected model is at capacity):上游官方算力偶发紧张,Codex 客户端自动重试次数打满后抛出的提示,不是平台把你限流了。稍等片刻再发,或临时换一个模型。
  • 当前令牌已达到 RPM 限制:1分钟内最多请求40次:触发了平台每分钟 40 次请求上限(RPM = 40),停十几秒再继续即可。

4. 503:No available channel for model ​

报错里出现哪个模型名,说明该型号已下架或当前分组不支持。

解决方法:对照 模型与切换 换成当前可用型号(如 gpt-5.4 / gpt-5.6-luna → gpt-5.6-terra,gpt-5.5 → gpt-5.6-sol,grok-4.5 → grok-4.7),改完后必须新建会话(旧会话不会切换模型)。


5. 400 / 413:请求参数或上下文超限 ​

  • 400 模型 xxx 不支持 chat completions 协议:Codex 系列模型必须走 Responses 协议(/v1/responses)。在 config.toml 中确认 wire_api = "responses",或在 CC-Switch / OpenClaw 中选择 openai-responses。
  • 400 Your input exceeds the context window of this model:当前会话上下文超长。请新建会话,将项目规范写入 AGENTS.md,按功能模块拆分对话。
  • 400 System messages are not allowed:第三方工具发送了当前模型不接受的 system 角色消息,更换模型或调整工具配置。
  • 413 Payload Too Large:当前单次会话记录已超过 20MB。建议新建会话,或在 config.toml 中将 base_url 改为 https://us-api.codexzh.com/v1(无 20MB 限制)。

6. 网络与流式中断(stream disconnected / Connection failed / 504) ​

出现 stream error: stream disconnected before completion、Connection failed: error sending request 或 504 Gateway Timeout:

  1. 检查代理与网络:API 走 CN2 优化专线,通常直连最快。本机开了代理就先关掉试试;若直连不通,再开启代理或切换节点。
  2. 单次思考过长:AI 连续思考超过 150 秒可能被网关截断,尽量拆分复杂问题。
  3. ChatGPT 桌面版不走系统代理:若你必须通过代理连接,但代理软件只开了系统代理、没开虚拟网卡(TUN 模式),可在 ~/.codex/.env 中手动写入代理地址后重启客户端:
    ini
    HTTP_PROXY=http://127.0.0.1:7897
    HTTPS_PROXY=http://127.0.0.1:7897
    ALL_PROXY=http://127.0.0.1:7897

7. 其他常见异常 ​

  • 报错 Unable to persist auth file: 系统找不到指定的路径:清理多余的 .codex 文件夹,按 手动配置 确认文件建在当前系统的用户主目录(~/.codex 或 %USERPROFILE%\.codex)下并有读写权限。
  • Windows 中文乱码 / UTF-8 报错:删除配置文件中的中文注释;读写项目文件乱码见专篇 Windows 中文乱码解决方案。
  • 历史聊天记录不见了:Codex 按 model_provider 隔离本地会话记录,找回方法见专篇 恢复聊天记录。
  • 用久了响应变慢、感觉“降智”:本地 SQLite 状态库或 TUI 日志体积过大时,按 清理本地缓存解决降智 归档清理。
  • VSCode 插件一直转圈进不去:插件首次启动可能尝试连接外网,先开代理进一次,之后再检查 ~/.codex 配置。
  • 用 /image 生图报沙盒无法解析域名 / 503:Codex 默认「只读」沙盒禁止命令联网,在聊天框左下角把权限切成「完全访问权限」即可,图示见 生图失败怎么办。
  • 浏览器 F12 看到 204 No Content:204 代表预检或统计请求成功处理且无返回内容,不是错误,无需处理。