AI精品店

Appearance

问题解决 ​

本页整理自 CodexZH 官方「常见问题解决方案」教程，并把关键步骤写成可操作的排查清单。

排查前先做一件事

先打开 服务运行状态 看一眼——如果服务端正在维护或故障，本地怎么改配置都没用，等恢复即可。

1. 401：认证失败 ​

现象：请求返回 401（Unauthorized），提示认证失败。

401 只有 3 种原因：配置不对、额度用完、套餐到期。逐项排查：

  1. 检查 base_url 和密钥是否"正确对应"，密钥复制完整（不缺字符、不带多余空格）
  2. 排查环境变量是否有冲突
  3. 确认账户已激活、订阅未到期
  4. 确认额度未用完（包月套餐为周限额，每周刷新，具体以定价页为准）

建议对照：环境配置 中的最小配置示例，逐项核对。

2. 流式中断：stream disconnected before completion ​

错误示例：

stream error: stream disconnected before completion
stream disconnected before completion: stream closed before response.completed

可能原因：

  • AI 思考时间过长（超过 150 秒会被系统截断）
  • 网络连接不稳定
  • 网络代理设置问题

解决思路：

  • 简化问题，减少单次对话需要的长思考
  • 更换更稳定的网络环境或线路节点

3. 路径配置错误：系统找不到指定的路径 ​

错误示例：

Unable to persist auth file: 系统找不到指定的路径

解决方案：

  • 搜索并删除/清理所有额外的 .codex 文件夹（避免写到错误目录）
  • 严格按照教程重新配置
  • Windows 用户确认在正确目录下创建文件
  • 检查文件夹权限

4. CLI / VSCode 切换模型问题 ​

更新 Codex CLI 后，可能出现无法通过 /model 切换模型的问题，VSCode 与 CLI 的处理方式不同。

4.1 VSCode ​

修改 config.toml，添加：

toml
[model_providers.codexzh]
requires_openai_auth = true

完整示例：

toml
model_provider = "codexzh"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"

[model_providers.codexzh]
name = "codexzh"
base_url = "https://api.codexzh.com/v1"
wire_api = "responses"
requires_openai_auth = true

web_search = "live"

4.2 CLI ​

  1. 将 auth.json 改为（注意 null）：
json
{
  "OPENAI_API_KEY": null
}
  1. 在环境变量中添加 CODEXZH_API_KEY，值为控制台里 sk- 开头的密钥。

macOS / Linux（当前终端会话临时生效）：

bash
export CODEXZH_API_KEY="sk-你的实际密钥"

配置后若出现 401，检查环境变量是否配置正确。

5. Codex 0.36.0 已知问题 ​

5.1 历史会话丢失 ​

更新 VSCode 插件后，之前的对话记录可能消失。降级到之前的插件版本可能找回记录。

5.2 思考等级设置 ​

界面上无法直接调整思考等级。目前只能通过配置文件修改，等待官方修复。

5.3 文件编辑模式差异 ​

  • gpt-5：支持可视化编辑器，有完整的变更列表
  • gpt-5-codex：只能通过命令行编辑，无法追踪变更历史

5.4 插件配置简化 ​

新版本插件不再需要在 settings.json 中配置 chatgpt.* 选项，只读取 config.toml。

常见错误速查 ​

504 Gateway Timeout 错误 ​

网络问题，检查代理和网络连接是否正常。

Connection failed: error sending request 错误 ​

网络问题，打开或关闭代理、切换网络后重试。

413 错误 ​

当前会话记录已超过 20MB，只能新建会话继续。

VSCode 插件一直在转圈，进不去 ​

官方插件自身的问题，第一次访问可能会访问外网，最快的解决办法是使用代理。若还是不行则检查配置是否正确。

401 Unauthorized 错误 ​

见上方 1. 401：认证失败。

UTF-8 错误 ​

99% 是 Windows 系统中文编码错误导致的，将配置中的中文内容删除即可。

503 Service Unavailable 错误 ​

如果报错信息包含 No available channel for model：报错里出现哪个模型名，就换一个当前可用的型号，并新建会话后再选；原有会话无法切换。常见对照：gpt-5.4 / gpt-5.4-mini / gpt-5.6-luna → gpt-5.6-terra，gpt-5.5 → gpt-5.6-sol，grok-4.5 → grok-4.7 或 grok-4.6（Grok 配置见使用 Grok 模型）。完整对照表见常见问题。

其他 503 情况依次检查：

  1. 网络是否正常
  2. 新建会话查看是否正常答复
  3. 套餐是否到期
  4. 配置是否正确

Your input exceeds the context window of this model 错误 ​

上下文超长了。建议：

  • 将项目相关规则编写到 AGENTS.md 文件中
  • 细分功能模块，完成一个功能就新建一个对话

上下文过长且功能不相关会导致后续结果不准确。

stream 开头的流错误 ​

99% 是网络问题，见上方 2. 流式中断。

403 Forbidden：检测到您的客户端存在异常 ​

报错原文里带这段话：

我们检测到您的客户端存在异常，请使用标准 Codex 客户端请求，请避免任何基于我方 API 二次分发的 API 转接接入。

平台只对标准 Codex 客户端开放接入，出现这个提示说明请求被判定为非标准客户端。常见触发场景：

  • 用 Python / Node 的 openai SDK 直接调用平台 API
  • 请求先经过自建中转、二次分发的 API 网关再转发过来
  • 客户端版本过旧

按顺序处理：

  1. 换回标准 Codex 客户端（Codex CLI / VSCode 插件 / Codex App）发起请求
  2. 把客户端升级到最新版本；用 CC-Switch 的同时也升级 CC-Switch 本体
  3. 确认请求路径上没有额外的 API 转发层
  4. 仍不行就联系客服，把报错里的 request id 一起提供

通过 CC-Switch 使用时，报错会显示成 CC Switch local proxy failed while handling Codex endpoint /responses，其中 cause 字段是同一段文案——属于同一个问题，按上面步骤处理即可。

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

报错 token quota is not enough，或 403 Forbidden 提示用户额度不足、剩余额度为负数，说明账号额度不够了，不是接口故障。报错里的 token remain quota 是剩余额度，need quota 是本次请求需要的额度；剩余额度为负表示已经超出。

包月套餐不是无限用量，而是按周给固定额度，见周限额度怎么算？。

可以先重试或新建会话；仍然报错就是额度确实不够，需要续费、购买加油包或升级套餐。

429 Too Many Requests 错误 ​

先看完整报错再判断，两种 429 不是一回事：

  • exceeded retry limit, last status: 429 Too Many Requests：Codex 客户端重试次数用完了，不是平台 RPM 限流。上游偶发 429（含官方容量不足）时客户端会自动重试，次数打满就报这句。稍等再发，或换个模型。详见常见问题解答。
  • 当前令牌已达到 RPM 限制：1分钟内最多请求40次：这才是触发了平台 RPM 限制。所有套餐都是 RPM = 40（每分钟最多 40 次请求），等一会儿再试即可。

400 错误 ​

看报错里的具体文案分辨：

  • 模型 xxx 不支持 chat completions 协议：Codex 系列模型走的是 Responses 协议（/v1/responses），不是 /v1/chat/completions。在客户端里把接口协议改过来——Codex CLI 的 config.toml 用 wire_api = "responses"，CC-Switch 里选 openai-responses。
  • System messages are not allowed：客户端（如 OpenClaw 等第三方工具）发送了 system 角色的消息，而当前模型不接受这种消息。换一个模型试试，或联系客服确认该模型支持的消息格式。
  • Your input exceeds the context window of this model：上下文超长，见上方条目。

204 No Content ​

204 不是错误。它表示"请求已成功处理，但没有返回内容"，在浏览器 F12 的 Network 面板里很常见（统计上报、预检请求等都会是 204）。

只要页面功能正常，就不用管它。如果页面确实有功能不工作，按界面上的实际报错排查，或先看服务运行状态确认服务端是否正常。

历史聊天记录不见了 ​

分两种原因：

  • 切换过 API 平台，或在平台账号与官方账号之间切换过：记录没丢，Codex 按 provider 名称隔离历史，只要 config.toml 里 3 个相关的值和之前一致就能找回，见恢复聊天记录。
  • 刚升级过 VSCode 插件：属于插件自身问题，见上方 5.1 历史会话丢失。

这页没解决你的问题？