Codex 报错怎么排查？401、403、429、400、413、502 与断流诊断指南
Codex 报错最麻烦的地方，往往不是错误信息太短，而是同一个现象可能来自完全不同的位置：本地配置没有读进进程、API Key 失效、账户没有模型权限、服务端不认请求协议，或者模型能返回文字却不能完成工具调用。看到“请求失败”就反复改 config.toml，很容易把本来正常的一项也改坏。
更稳妥的方法是先分层，再一次只改一个变量。下图把常见问题分成五层：客户端配置、身份与权限、请求协议、模型能力、服务端运行状态。先从最容易留下证据的一层查起，再缩小范围。
先留下能复现问题的信息
排查之前，先记录时间、Codex 版本、使用的模型 ID、Provider、base_url 的域名和路径、错误发生阶段，以及服务端返回的 request ID。不要在截图或日志里暴露完整 API Key。密钥只需要确认“存在、长度合理、启动进程能读到”，没有必要把它打印出来。
| 需要记录 | 用来判断什么 | 注意 |
|---|---|---|
| 错误时间与时区 | 是否与限流、服务故障或账户变更同时发生 | 尽量写完整日期和时间 |
| Codex 版本与入口 | CLI、桌面应用还是编辑器扩展 | 不同版本的支持范围可能不同 |
| Provider 与 Base URL | 请求究竟发往哪里 | 保留路径，隐藏密钥 |
| API Model ID | 是否使用了控制台真实模型名 | 展示名和 API ID 可能不同 |
| request ID | 服务商能否定位单次请求 | 不要只发“报错了” |
| 最小复现任务 | 是否与项目规模、工具调用有关 | 优先使用只读小任务 |
错误信息建议原样保存，但提交给他人之前要去掉密钥、内部域名、用户数据和完整代码。若服务商提供了日志导出，保留时间范围和 request ID 比截取半行报错更有用。
401：请求没有通过身份验证
401 通常表示服务端没有确认调用者身份。第一项检查是 Codex 启动进程里到底有没有对应环境变量。你在一个终端里执行 export，并不保证桌面应用、IDE 或另一个终端会话也能读到。配置里写的是 env_key = "CLAWSOCKET_API_KEY"，进程环境里就必须存在同名变量。
第二项检查密钥是否完整。复制时可能带上空格、换行、引号，或者只复制了前半段。不要把 Key 写进 Markdown、命令历史、项目配置或 Git 仓库。可以在终端里用下面这种方式只验证变量非空，不输出内容：
bash
test -n "$CLAWSOCKET_API_KEY" && echo "API key is set"第三项检查账户状态和 Key 状态：是否撤销、过期、被轮换，是否属于当前组织，是否有调用目标模型的权限。第四项检查 Header 是否被自定义脚本改写。有些用户为了加代理，会手写 Authorization，结果重复携带了两个认证头，或者把 Bearer 前缀弄丢。
如果同一个 Key 在普通 HTTP 客户端里可用、在 Codex 里却返回 401，先确认客户端确实读取了这份配置。如果 HTTP 客户端也返回 401，问题已经在身份层，不需要继续改模型参数或工具设置。
403：身份通过了，但没有做这件事的权限
403 和 401 的含义不同。前者更像“知道你是谁，但不允许访问这个资源”。常见原因包括账户没有目标模型权限、组织策略禁止该端点、项目 Key 的权限范围不足，或者请求经过的网关不允许当前模型与协议组合。
不要靠换一个模型名试探到底。先到 Clawsocket 控制台 核对当前账户、Key 权限、可用模型和协议。若控制台明确列出某个模型只支持某种接口，而 Codex 正在请求另一种协议，403 或 404 都可能出现。不同服务商的错误映射并不完全一致，必须结合响应正文判断。
还要区分“账户没有权限”和“服务端策略拒绝”。前者修改 Key 或套餐可能解决，后者可能要求更换端点或协议。把 403 直接当作 Key 错误反复生成新 Key，往往解决不了协议层面的限制。
404：地址或端点没有对上
404 常见于 Base URL 拼错、路径重复、接口版本不对，或者把展示页面地址当成了 API 地址。例如服务商给的根地址已经包含 /v1，配置中又追加了一次；又或者你手工填入了 /responses，客户端根据协议再次追加。
排错时先照抄服务商文档中的根地址，再核对 Codex 配置里的 wire_api。不要在不知道客户端拼接规则的情况下自己补路径。域名、协议、端口和版本路径要逐项比对，大小写和末尾斜杠也可能有影响。
如果错误正文是 HTML 登录页或网站 404 页面，说明请求大概率没有到达模型 API。若响应是 JSON，并且带有模型或 endpoint 提示，优先检查模型 ID 和协议支持。Clawsocket 的具体模型与接口信息以控制台当前说明为准，可结合 Codex 接入 Clawsocket API 对照字段。
400：请求格式、参数或模型能力不匹配
400 的范围很宽，可能表示 JSON 字段不对、模型 ID 不存在、消息角色不符合要求、工具定义格式错误，或者服务端不支持客户端发来的请求类型。它不是“模型太笨”，通常也不该通过修改提示词来解决。
先查看响应正文里的参数名和错误类型。把请求缩小到一个最小任务，例如只读一个文件，不启用图片、不传超长上下文、不并发执行多个工具。确认基础请求成功后再逐项恢复功能。这样能判断问题来自基础协议，还是某个高级能力。
| 现象 | 优先检查 | 不要先做什么 |
|---|---|---|
| 模型不存在 | 控制台 API Model ID、大小写、版本后缀 | 改成相似展示名 |
| 参数不识别 | 客户端版本、服务端协议与字段 | 随意删除未知字段 |
| 工具定义失败 | 模型和端点是否支持工具调用 | 把文本回答当成功 |
| 多模态请求失败 | 模型是否支持图片或附件输入 | 换更大的文件继续试 |
| 上下文过长 | 实际输入规模和模型窗口 | 只删提示词不删附件 |
“OpenAI 兼容”不是完整兼容的同义词。一个服务能接受普通的聊天请求，并不自动支持 Responses API、流式事件、工具结果回传或多轮 Agent。第三方模型接入时，请继续阅读 Codex 第三方模型兼容性指南。
413：请求体太大
413 表示服务端或中间代理拒绝了过大的请求。Codex 处理项目时会把文件内容、工具结果和历史上下文放进请求。即使单个文件不大，累计上下文也可能超过限制。另一个常见来源是附件、图片、日志或构建输出一次传入过多。
先确认是模型上下文限制，还是网关请求体限制。两者表现可能相似，但解决方式不同：前者需要减少上下文，后者需要按服务商规则调整请求规模。不要直接把错误理解为“磁盘空间不足”。
实用做法是缩小任务范围，让 Codex 先搜索目录、再读取命中文件，而不是一次加载整个仓库。把大型日志过滤成关键片段，把图片压缩到实际需要的大小，并避免在同一轮重复粘贴已经能读取的文件。若服务端有明确的单请求上限，应以控制台当前说明为准。
429：额度、速率或并发限制
429 通常表示请求频率、并发数、账户额度或上游容量受限。先看响应头或正文是否给出重试时间。可以等待后重试，但不要在一个循环里立即连发几十次；失败请求也可能消耗额度，并让恢复更慢。
| 429 子类型 | 常见信号 | 处理顺序 |
|---|---|---|
| 速率限制 | 短时间请求数或 token 太多 | 降低并发，等待窗口恢复 |
| 账户额度 | 余额、套餐或周期用量提示 | 检查控制台账户状态 |
| 并发限制 | 多 Agent 或并行工具同时失败 | 降低并行数 |
| 上游容量 | 服务端提示暂时不可用 | 稍后重试或换可用模型 |
如果只是偶尔发生，记录请求时间和规模，观察是否集中在长上下文任务或并发执行时。若每次都发生，先检查账户和模型权限，再考虑任务规模。Clawsocket 的余额、速率、模型状态以控制台为准；不要把“能登录控制台”等同于“这个 Key 有无限调用额度”。
500、502、503、504：服务端或链路没有稳定完成
5xx 表示请求已经到达服务端附近，但服务端或中间代理未能完成。502 常见于网关与上游之间失败，503 可能代表暂时不可用，504 则是链路超时。它们不一定说明你的配置错了，但也不能简单归纳成“服务商全挂了”。
先使用同一 Key、同一模型、同一端点做一次小请求。若小请求成功、大任务失败，问题更可能在请求规模或执行时长；若小请求也失败，再看服务状态、代理、网络和账户。代理配置可能只影响某个进程，也可能改写流式响应，需要分别验证。
遇到 5xx 时保留 request ID 和发生时间。可以先等待服务端给出的恢复时间，再进行一次有节制的重试。不要在项目仍处于半完成状态时重复执行写操作，先检查工作区 diff，防止自动重试叠加修改。
断流：连接建立了，但回答没有完整结束
“Stream disconnected before completion”“connection reset”或输出到一半停止，说明流式连接中断。常见原因包括网络波动、代理缓冲、空闲超时、服务端重启，以及客户端与服务端的流式事件格式不完全一致。
排查时先用短回答测试，再换成需要工具调用的任务。如果短回答正常、工具调用时断开，重点检查模型和协议对工具事件的支持；如果所有请求都在固定时长后断开，重点检查代理和超时设置。关闭会主动缓冲流式响应的代理后再测试，但修改网络配置前要保留原值。
客户端可能已经收到一部分输出，却没有收到完成事件。不要看到屏幕上出现了代码就认为任务成功。检查文件是否写入、命令是否结束、测试是否真的运行。必要时让 Codex 重新汇报当前状态，而不是直接重复整个任务。
OAuth、Token Exchange 与登录失败
如果错误发生在浏览器登录、令牌交换或凭据刷新阶段，它还没有进入普通模型请求。先检查系统时间是否准确、浏览器回调是否被拦截、代理是否改变回调域名，以及当前账户是否可用。清理旧凭据前先确认不会丢失其他账户配置。
第三方 Provider 通常使用 API Key，但 Codex 官方账户登录可能采用另一套流程。不要把 API Key 问题套用到 OAuth，也不要把浏览器登录成功当作自定义 Provider 已验证。两条认证链路应该分别测试。
一个最小化验证流程
排错时建议按下面顺序执行，每一步只回答一个问题：
- Codex 启动进程能读到 Key 吗？
- 同一个 Key 能访问服务商的最小端点吗？
- 当前账户与 Key 是否有目标模型权限？
- 模型 ID 与 Base URL 是否逐字一致？
- Codex 需要的协议是否被该模型支持？
- 只读一个小文件能否完成？
- 工具调用、流式输出和多轮任务是否分别通过？
- 只有大项目失败时，是否属于上下文或请求体限制？
这样做的目的，是让每次修改都有证据。若第 2 步就失败，不要继续改第 6 步的提示词；若第 6 步成功但第 7 步失败，则要把问题定位在 Agent 能力，而不是认证。
可以用下面的任务作为最小只读测试：
text
读取当前项目的 package.json，只回答项目名称、使用的框架和测试命令。
不要修改任何文件，不要安装依赖，不要运行写入命令。
如果文件不存在，只说明不存在，不要猜测内容。成功标准不只是“有文字返回”，还要确认它确实读到了项目内容，并且没有越过只读边界。随后再让它查看一个小文件，提出修改建议但不执行，最后才进入真实编辑。
Clawsocket 场景的核对清单
使用 Clawsocket 控制台 时，先确认 API Key、模型 ID、Base URL 和协议。然后用 Codex 接入 Clawsocket API 的示例检查配置结构。控制台展示名称不能替代 API Model ID；模型可聊天也不能证明支持 Responses 工具链。
若只读请求失败，把问题停留在连接和权限层；若只读成功、编辑失败，检查模型工具调用与服务端事件；若小任务成功、大任务失败，检查上下文规模和超时。不要把三个层的问题混在一次修改里。
什么时候该停止自己排错
涉及账户异常扣费、密钥疑似泄露、生产数据被发送到错误端点时，应先停止请求、撤销相关凭据并按组织流程处理。不要在公开文章中粘贴完整错误日志；日志里可能包含仓库路径、内部域名、业务字段或密钥片段。
如果错误持续出现，提交给支持人员的信息应包含最小复现、发生时间、request ID、模型 ID、协议、客户端版本和已经排除的步骤。一个可复现的小案例，通常比“Codex 一直报错”更容易定位。
FAQ
换模型能解决所有报错吗？
不能。401、403、请求格式、服务端故障和上下文超限有不同原因。换模型只适合验证模型可用性，无法替代身份和网络检查。
能对话就说明 Codex 已经接通了吗？
不能。它只说明一次基础模型请求可能成功。完整 Codex 任务还涉及项目读取、流式响应、工具调用和结果回传。
429 是不是应该马上重试？
先看重试时间并降低并发。立即循环重试可能加重限流，也会制造更多失败记录。
502 一定是本地配置错误吗？
不一定。它通常指向服务端或链路。用最小请求确认范围后，再决定是否调整本地设置。