Codex 报错大全与诊断树
Codex 失败时，先看请求走到了哪一步。命令找不到，问题还在本机；HTTP 401 说明有服务返回了鉴权错误；模型已经输出文字、但修改文件失败，则需要检查工具调用和工作目录。它们可能出现在同一个任务里，却不该用同一种办法处理。
这篇文章把常见报错按处理层次整理成诊断树。错误文字会随客户端和服务商变化，HTTP 状态也需要结合响应体判断，不能仅凭一个数字断定原因。本文更新于 2026 年 10 月 24 日，适用于定位思路；实际参数要与本机版本及服务商文档核对。
先保存证据，再改配置
出现故障后，先记下时间、时区、客户端版本、模型、provider、脱敏后的请求地址和完整错误类型。若响应带请求标识，也一起保存。日志中的 Key、Cookie、代码和用户数据需要按情况遮盖，但不要把能区分问题的错误码和字段名全部删掉。
随后确认最近改过什么：升级客户端、换模型、修改代理，还是从 ChatGPT 登录切到了 API Key？恢复到最近能工作的配置，能帮助缩小范围。每轮只改变一个条件，并记录结果。一次更换模型、地址、密钥和客户端版本，即使恢复了，也很难知道原因。
不要一开始就删除整个 ~/.codex。配置、会话或其他状态可能仍有诊断价值。需要调整配置时，先保留备份，确认只改与故障有关的部分。下面的命令只读取版本和命令位置；Windows 可在 PowerShell 使用 Get-Command codex 查找入口。
codex --version
command -v codex从这里进入诊断树
Codex 是否能启动？
├─ 否：检查安装入口、PATH、运行环境、权限
└─ 是：配置是否能加载？
├─ 否：检查 TOML/JSON 格式、字段和文件路径
└─ 是：是否收到 HTTP 响应？
├─ 否：检查 DNS、代理、TLS、连接超时
└─ 是：看状态码与错误体
├─ 401/403：鉴权、权限、访问策略
├─ 404：地址路径、模型、端点支持情况
├─ 400/422：参数与协议不匹配
├─ 429：区分限流和额度问题
├─ 5xx：网关或上游故障
└─ 2xx：继续检查流式事件和工具执行这棵树用来决定下一步检查位置，不保证某个状态只有一种解释。代理可能把错误包装成 HTML，路由服务也可能转换上游状态。若终端只显示“连接失败”，需要尽可能保留底层响应，而不是根据界面提示反复充值或更换模型。
命令找不到，或者启动了另一个版本
command not found 一类错误优先检查安装是否成功、命令目录是否位于 PATH，以及当前终端是否加载了对应配置。使用多个 Node 环境、多个包管理器或多个系统账户时，安装位置和实际执行位置可能不同。先定位入口，再决定是否重新安装。
如果终端启动正常、编辑器里失败，比较两者使用的可执行文件和环境。应用启动时获得的环境不一定与后来打开的 shell 相同；终端里新增变量后，已有进程也未必随之更新。不要把“我刚 export 过”当成目标进程已经收到变量的证据。
修复后重新运行版本命令，确认读到预期入口。若组织统一管理客户端，使用组织提供的安装和升级方式，避免个人安装覆盖受管版本。具体版本支持范围应查看当前官方安装资料，不宜根据旧教程的运行时要求作判断。
配置解析错误与 provider 找不到
TOML 报错通常会附行号，先看该行及前后结构。常见问题包括引号不完整、复制了中文引号、同一张表重复定义，以及把本应属于顶层的字段写进了 provider 表。TOML 的表头会影响后续字段的归属，不能只看缩进判断层级。
model_provider 必须对应已经声明的 provider 名称。名称拼写、大小写或配置来源不一致，都值得检查。若涉及模型目录文件，还要确认路径存在、JSON 合法，以及所选模型确实在目录中声明。相关字段可对照 Codex 官方配置参考。
配置没有生效时，还应检查是否有其他配置层或启动参数覆盖。与其把所有配置打印到群聊，不如提取相关字段并脱敏。模型名、provider 名、环境变量名和地址通常足以开始讨论；密钥本身不应作为排查材料传播。
401：先确认密钥属于哪个入口
401 通常需要检查凭证缺失、无效或使用方式不匹配，但最终以服务端错误体为准。先确认当前会话是 ChatGPT 登录还是自定义 provider，再检查 provider 指向谁。OpenAI Key、ClawSocket Key 和模型官方平台的 Key，不能因为外观类似就交换使用。
环境变量只写在另一个终端，也可能导致当前进程没有凭证。可以只检查变量是否存在，不打印值。下面是测试 CLAWSOCKET_API_KEY 的方式；它不验证密钥有效性，也不检查余额。
python3 - <<'PY'
import os
print('已设置' if os.environ.get('CLAWSOCKET_API_KEY') else '未设置')
PY如果变量存在，继续核对密钥所属账户、有效状态和端点。某些编程套餐与标准 API 使用独立密钥，例如智谱官方文档明确要求匹配产品类型。单纯更换字符串前缀或反复复制同一把 Key，不能解决产品不匹配。
403：权限和策略要分开看
403 可以出现在模型访问、项目权限、组织策略或网关拦截等位置。保留返回内容中的原因，再检查账户是否允许该模型、目标操作是否受组织限制，以及响应是否确实来自预期 API。不要只看到 Forbidden 就认定是余额不足。
如果企业代理或访问网关返回自己的页面，应先在该网络环境内处理访问规则。若 API 服务明确返回模型权限问题，则到对应账户核对。更换网络、关闭安全设置或复制他人凭证不应成为没有证据时的默认动作。
对团队任务，还需要区分本地执行权限和远端服务权限。模型请求成功不代表本地文件可以写入；本地有写权限也不代表远端允许调用指定模型。把这两项分别验证，能避免在错误的控制台里查找问题。
404：路径错误和模型不存在都要检查
404 可能来自主机上的路径不存在，也可能由服务商表示模型不可用。先看错误体是否指出模型，再检查实际 URL。base_url 通常填写接口基础路径，客户端再追加资源路径；如果把完整 /responses 写进去，可能得到重复路径。
ClawSocket 的本站接入入口是 https://api.clawsocket.com/v1。连接它时应在 ClawSocket 控制台核对模型 ID 与 Responses 支持情况，不要直接照搬某篇旧文章中的模型别名。不同服务商的 /v1 也不能互相套用，GLM 官方 Codex 入口就有自己的路径。
/models 返回成功，只能证明对应列表入口和鉴权在这次请求下可用。它不能证明 /responses 存在，更不能证明指定模型支持工具调用。若列表正常而实际任务 404，应继续查具体请求端点和模型权限。
400 或 422：检查协议和参数
这类错误常伴随参数名，例如不支持的推理等级、无效工具定义、消息结构不符合要求。保留字段名，先按当前模型文档缩减可选参数。不要为了绕过错误，把所有设置一口气删掉；这样可能让后续工具流程换一种方式失败。
Codex 使用 Responses 工作流，Chat Completions 的文本请求成功不能替代验证。供应商可能需要模型目录文件来声明工具格式、推理等级和输入类型；这些声明也不能让后端获得原本没有的能力。应按照对应供应商的官方 Codex 文档配置。
如果纯文本能返回，工具任务才报错，可以把问题缩到工具定义、事件结构和结果回传环节。测试时只保留一个很小的文件操作，不必拿真实项目的大任务反复复现。完整接入方法见国产模型接入教程。
429：分清限流与额度耗尽
OpenAI 错误码文档区分请求速率过高和当前额度不足等情况。第三方服务也可能使用自己的错误类型。先读错误体，再检查账户用量；不能把所有 429 都交给无限重试。
若是请求频率、Token 速率或并发限制，降低同时运行的任务，按服务端提示等待；需要重试时设置最大次数和总等待上限。若是余额、套餐额度或账户限制，应处理账户状态。重复发送同一请求不会增加可用额度，还可能干扰你观察原始问题。
同时检查有没有多个终端、自动化脚本和 CI 共用同一凭证。单个会话看起来请求不多，所有调用加起来却可能触发限制。进一步的客户端设计见429 限流指南，费用归属见Codex 费用说明。
没有响应、5xx 与流式中断
没有收到 HTTP 响应时，依次检查域名解析、连接、TLS 和代理。先确认错误发生在哪个阶段，再比较同一环境中的简单请求。浏览器能打开控制台，不代表终端到 API 的路径相同；控制台页面和模型接口也可能由不同服务处理。
5xx 应结合响应来源判断，是本地代理、路由网关还是上游返回。可以先保存请求标识，隔一段时间做有限重试；持续出现时，向对应服务提供脱敏记录。不能仅凭一次 502 就断定模型整体不可用，也不该把所有失败都归因于自己的配置。
流式中断还有一类特点：任务已经收到部分内容，但在结束事件之前断开。此时不要直接整段重放。先查看文件和 Git diff，确认此前有没有执行命令或写入内容。已发生的副作用不会因为连接断开自动撤销，恢复任务前要告诉工具当前状态。
模型有回复，文件却没有正确修改
这时需要把模型输出和工具执行分开检查。工具是否真正被调用，是否返回权限错误，当前目录是否正确，命令是否因依赖或环境缺失而失败？一句“已经完成”不能替代工作区里的实际变更，终端有文字也不能证明工具循环完整。
如果是补丁失败，检查目标文件是否被其他进程改变、行内容是否与预期一致；如果是测试失败，区分原有失败和本次引入的问题。保留具体命令、退出码和相关输出。恢复时先读已有状态，再补做剩余工作，避免重复生成或覆盖用户修改。
涉及沙箱与审批的行为，可查阅 Codex 安全说明。解决问题应针对需要的操作和目录设置权限，不应仅为了让一条命令跑通就扩大整个环境的权限范围。
把故障记录写到别人能继续排查
一份有效记录包含复现时间、版本、provider、模型、脱敏 URL、错误类型、请求标识、最小复现和已尝试的单项变化。再补充失败前是否有文件修改、是否执行了外部动作、当前工作区是否能安全重试。这样接手的人才知道哪里还能继续。
如果需要通过 ClawSocket 复现，先建立独立测试配置，在小仓库验证一条请求；不要把生产任务原样复制多次。无论最终定位在客户端还是服务端，都应以“相同条件下复现失败、调整后通过对应检查”为依据。没有复现条件时，保留推测的身份，比写一个未经验证的确定结论更有帮助。