Codex 接入排障：401、404、429 与网关超时

1. 先保留现场，不急着重试

记录发生时间与时区、客户端及版本、完整模型 ID、HTTP 状态码、错误正文中的 code/message、请求 ID，以及是否开启 CC Switch。截图前遮住密钥、Authorization、Cookie、官方登录令牌和私人代码。

先判断是「还没发出请求」「连接失败」「收到 HTTP 错误」还是「流式输出中途断开」。同一个 404 或 502 可能来自不同层，不能仅凭数字判断故障归属。

• CLI 配置：检查实际生效的 model_provider、env_key、base_url 和启动时所选 profile。
• 本地代理：记录实际监听地址与端口、目标应用是否被接管、转发到哪一个上游。不要凭旧教程假定端口。
• 平台记录：查看相同时间、模型和请求 ID 的调用。没有记录不一定没发请求，也可能在鉴权、边缘或路由阶段就被拒绝。

2. 检查协议与最终路径

最终地址中出现 /v1/v1/、/responses/responses，或者返回网站 HTML，优先修正配置与代理路由。不要关闭 TLS 验证，也不要为了绕开错误改用不明第三方域名。

3. 无扣费的本地检查

先确认使用的是哪一个可执行文件和版本：

macOS / Linux

command -v codex

codex --version

test -n "${API8848_KEY:-}" && printf "API8848_KEY 已设置\n" || printf "API8848_KEY 未设置\n"

Windows PowerShell

Get-Command codex

codex --version

if ([string]::IsNullOrWhiteSpace($env:API8848_KEY)) { "API8848_KEY 未设置" } else { "API8848_KEY 已设置" }

这些命令只报告变量是否存在，不输出密钥。变量存在不代表内容有效；不同终端、IDE、WSL 和系统服务的环境并不共享。修改后在准备运行 Codex 的同一环境中检查。

4. 按状态码处理，而不是猜原因

400 / 422：格式或能力不匹配

查看具体字段：模型、工具定义、图片、上下文或不支持的参数。先在新会话去掉额外工具和附件；不要用同一请求反复重发。若错误包含敏感提示词，提交工单前先脱敏。

401：认证未通过

检查 env_key 与变量名是否一致、令牌是否完整/过期/禁用、应用是否仍读旧配置。本地代理也可能有自己的认证要求；上游官方账号令牌不能当平台 API Key 使用。不要公开运行 printenv 或把 auth.json 发给别人。

403：请求被拒绝

按正文区分账户/令牌权限、IP限制、模型权限和 Cloudflare/WAF 拒绝。记录响应类型与 CF-Ray（若有），交给管理员核查；不反复改指纹、关闭安全规则或绕过访问限制。

404：路径、资源或模型不存在

核对最终域名与路径、是否重复拼接 /v1、模型 ID 是否完整。404不自动证明平台没有 Responses；有些错误是模型无路由或本地代理映射问题。不要拿浏览器直接访问 POST 地址得到的404来判断生成接口不可用。

405：请求方法不对

浏览器地址栏和常规 HEAD 检测不能替代 POST 请求。先核接口约定；不要为试方法随意提交生成请求。

429：限流、并发或配额

读错误 code/message 和 Retry-After（若提供），分别核用户额度、令牌限额、并发和上游限制。不把所有429都解释为余额不足。停止自动重试风暴，减少同时运行的任务；更换模型也可能扣费，且不能用于绕过访问限制。

500 / 502 / 503 / 504：服务、转发或超时

保留请求 ID 和响应正文，核本地代理、平台及上游状态。没有日志依据不要直接说是厂商故障。等候后最多按需做一次受控验证，避免反复重装、轮换所有模型或提高并发。

524 / 连接中断 / SSE未完成

边缘或中间层超时不等于上游没执行、没收费。先查调用记录、任务状态和已生成输出；不要因没看到最后一段就自动重发整个 Agent 工作。流式兼容也要看该模型/渠道是否完整支持，不以延长客户端超时承诺解决边缘超时。

5. 只有接管后出错：检查 CC Switch

1. 先备份当前配置，确认选中了正确应用和供应商，而非仅创建了一个未启用的条目。
2. 记录面板显示的真实监听地址和端口；只监听本机回环地址，不为排错开放到公网。
3. 用脱敏日志确认「客户端 → 本地代理 → 平台」的目标协议和模型映射是否一致。代理在运行不代表请求确实经过它。
4. 每次只改变一个变量：例如保留模型与令牌，只比较是否经过代理。不要同时改域名、Key、模型和协议。
5. 需要恢复原连接时用应用的停止接管/恢复功能，再重新启动客户端；不要在代理还接管时手改占位认证文件。

详细配置见 CC Switch指南 和 Codex CLI指南。

6. 需要真实验证时，先控制次数

1. 确认现有请求是否仍在运行；记录可能发生的用量。
2. 只保留一个已授权模型和一个短输入，在新会话或测试项目中验证，不携带完整生产仓库。
3. 核对返回结果、平台调用记录和模型名；仅有「能拉取模型列表」不能证明 Responses、流式或工具调用正常。
4. 短对话通过后，再测试一个需要人工批准的只读工具任务。不要开启跳过审批或无限自动重试。

7. 一次提交足够的信息

工单可按下面模板整理，不包含密钥、Cookie、原始配置导出或私人提示词：

发生时间 / 时区：
客户端与版本：
系统 / CLI、IDE、桌面版或WSL：
模型完整ID：
是否经过CC Switch及其版本：
请求路径（去掉密钥和签名查询参数）：
HTTP状态 / 错误code / 脱敏message：
请求ID / CF-Ray（如有）：
是否已在调用记录找到：
最近一次改动：
已做的检查与重试次数：

如果密钥已经泄露，先在控制台停用并替换，再提交不含密钥的新日志；不用发更多完整截图来确认泄露范围。

官方资料与核验边界

• Codex官方仓库与文档入口
• CC Switch发布与使用说明

本文整理安装与配置方法，不代表所有客户端版本、模型、工具调用或远程功能均已实测。本次文档更新未发起付费模型请求；文中的模型验证、首次对话和自动化运行可能计费，请确认模型与预算后自行执行。