声明：社区排错手册，非官方。先读完整错误正文，不要只看状态码。命令与文件路径可能随版本变化。
更新核验：2026.09
30 秒分流
| 你看到的 | 多半是 | 先做什么 |
|---|---|---|
401 / Unauthorized / Incorrect API key | 鉴权 | 统一登录方式 → 重新 login |
429 / Too Many Requests / rate limit / usage limit | 限流或额度 | 看重置时间；对照 重置雷达 |
| 超时 / Reconnecting / stream disconnected | 网络或链路 | 查代理、VPN、Base URL、稳定性 |
404（改过 base_url 后） | 地址配错 | 检查 /v1 是否丢了或拼重了 |
本地 Missing environment variable | 环境变量没进当前进程 | 不是 401；检查启动方式 |
桌面端路径、权限、命令失败的排查顺序，仍见：桌面端排查。
排错顺序
- 完整复制错误正文（含 message，不只 code）
- 能跑诊断就跑（若当前版本提供）：
codex doctor - 确认只用一种鉴权：ChatGPT 登录 或 API Key
- 仍失败再动
config.toml/ 中转配置 - 改崩了就恢复备份，不要反复把真实 Key 贴进对话
401：鉴权失败
常见原因
- ChatGPT 登录态过期，需要重新
codex login - API Key 错误、撤销、跨账号、或带了换行/空格
- 只
export OPENAI_API_KEY，但当前 provider 实际不读这个变量 - ChatGPT OAuth 与 API Key 混用，表现不稳定
- 自定义 provider 的
env_key与真实环境变量名不一致
处理步骤
A. 官方登录路径
codex logout
unset OPENAI_API_KEY
codex login
然后新开终端，在测试目录跑一个只读任务。
B. API Key 路径
codex logout
# 确认 Key 无换行
printenv OPENAI_API_KEY | od -c | head
codex login --with-api-key
# 若你的版本交互不同，按 CLI 当前提示操作
C. 自定义 / 中转 provider
- 核对
model_provider名称 - 核对
base_url（通常到/v1） - 核对
env_key对应的变量在启动 Codex 的同一个 shell里存在 - 详见：第三方 API / 中转
401 验收
- 同一错误不再复现
codex doctor（如有）鉴权项通过- 只读任务可返回
429：限流 / 额度
怎么理解
- 有的 429 是短时请求过频（可等待后重试）
- 有的是订阅额度窗口用尽（要等到重置点，或调整用量/订阅）
- CLI / 界面若给出重置时间，以显示为准
处理步骤
- 停下重试风暴，先读提示里的 reset 时间
- 打开 重置雷达 对照公开重置信号（情报参考，非官方承诺）
- 缩小并行任务、拆长任务，避免短窗口打满
- 若长期顶满，再考虑订阅档位或用量策略（以官方账单/计划页为准）
概念分工见：额度、订阅与重置说明。窗口细节见：5 小时与每周额度。
429 验收
- 重置时间过后，同任务可继续
- 不再被短时限流打断（或频率已降到可接受）
超时 / 重连
先检查
- 能否访问官方或你配置的 API 域名
- 公司代理 / VPN / 系统代理是否干扰
- 自定义
base_url是否可达 - 任务是否过大（上下文过长、一次性改太多文件）
处理建议
- 换网络或校正代理后再试
- 把任务拆小，先只读分析再改文件
- 仍不稳定：保存日志（如
~/.codex/log/下近期日志）再对照版本说明
