Codex 常见错误汇总：unable to connect、429、超时怎么处理

Codex 报错时最忌讳的做法是反复重试。同一条错误信息背后可能是终端没走代理、节点断流、账号配额耗尽三种完全不同的原因，盲目重试只会把时间浪费在错误的方向上。本文把 Codex CLI 与云端版的常见错误按「网络 → 账号 → 本地环境」三类整理成对照表，每一类给出判断方法与处理步骤。安装与基础用法请先看 Codex CLI 安装与基础使用教程。

先用对照表定位错误类别

错误信息或现象	类别	最可能的原因	第一步动作
unable to connect / fetch failed	网络	终端未走代理	运行 curl 验证命令
ETIMEDOUT / ECONNRESET	网络	节点不稳或被阻断	换节点后重试
stream disconnected / 任务中途断开	网络	长连接被掐断	换线路类型
输出整段一次出现，不是逐字流式	网络	线路缓冲 SSE	换专线节点
401 Unauthorized	账号	登录过期或 Key 无效	重新登录
403 Forbidden	账号	地区不支持或 IP 被拒	换受支持地区节点
429 Too Many Requests	账号/网络	配额、并发或 IP 限流	查看提示文案再决定
command not found: codex	本地	PATH 未包含 npm 全局目录	加入 PATH
Unsupported Node version	本地	Node 版本过低	升级到 LTS
登录后浏览器回调一直等待	网络	浏览器与终端出口不一致	统一节点

网络类：unable to connect 与各种超时

这一类占了 Codex 连接失败的绝大多数。排查按以下顺序：

1. 确认终端代理变量已在当前窗口导出（新开的窗口不会继承）。
2. 用 curl 验证到 OpenAI 的连通性与耗时。
3. 若 curl 不通，检查客户端端口与变量是否一致。
4. 若 curl 通但 Codex 不通，检查 NO_PROXY 是否误写、是否同时开了 TUN。
5. 若时通时断，换节点，并观察是否集中在晚高峰。

验证命令：

curl -sS -o /dev/null -w "%{http_code} %{time_total}s\n" https://api.openai.com/v1/models

返回 401 且耗时一两秒是正常状态。代理变量的两组写法如下，端口以客户端实际显示为准：

# macOS / Linux
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890

# Windows PowerShell
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:ALL_PROXY = "socks5://127.0.0.1:7890"

完整的代理配置与 TUN 模式步骤见 Codex CLI 代理设置。

任务中途断开与输出卡住

这是最让人困惑的一类：登录正常、简单问答正常，但让 Codex 重构一个目录时跑到一半就 stream disconnected。原因几乎都在节点而不在配置。Codex 的流式输出依赖一条持续几十分钟的长连接，普通中转节点在晚高峰丢包、运营商重置长连接、节点限制单账号连接数，都会表现为中途断开。

处理方法只有换节点，但要换对方向：

• 从中转换到 IEPL / IPLC 专线，专线对长连接最友好，原理见 IEPL 与 IPLC 的区别。
• 从共享出口换到 IP 相对固定的节点，减少被判定为异常流量的概率。
• 避开晚高峰测试，确认是时段问题还是节点本身问题。

账号类：401、403 与 429

401 最简单：登录态过期或 API Key 失效，运行 codex 重新走一遍登录流程，或检查 OPENAI_API_KEY 是否正确注入当前会话。

403 多数与地区有关。节点出口所在地区不在 OpenAI 支持列表，或出口 IP 被标记为高风险，都会返回 403。处理方式是换到日本、新加坡、美国等明确支持的地区，并先在浏览器里确认 ChatGPT 网页可以正常对话。

429 要看提示文案区分三种情况：

提示特征	含义	处理
提到 usage limit 或配额	账号当期额度用尽	等待重置周期，或切换登录方式
提到 rate limit 且短时间多次出现	请求频率过高	减少并行任务，稍等再试
换节点后立刻消失	出口 IP 被限流	固定使用信誉好的节点

第三种情况最容易被误判为账号问题。共享出口的节点上有很多用户同时访问 OpenAI，整个 IP 被限流时，你的账号明明还有额度也会收到 429。遇到这种情况换节点即可，不必等待。

本地环境类：命令找不到与版本问题

这一类与机场无关，但经常被混在一起：

• command not found: codex：运行 npm config get prefix，把输出路径下的 bin 目录加入 PATH 后重开终端。
• Unsupported Node version：Codex 要求较新的 Node 版本，用 nvm 安装 LTS 版本后重新安装 Codex。
• EACCES 权限错误：不要用 sudo，把 npm 全局目录改到用户目录下。
• Windows 下 PowerShell 执行策略阻止脚本：以管理员身份运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。

排查流程总结

1. 看错误信息，按对照表归类为网络、账号或本地环境。
2. 网络类先跑 curl 验证命令，不通查代理变量，通则换节点。
3. 账号类 401 重登录，403 换地区，429 看文案区分配额与限流。
4. 本地类按 PATH、Node 版本、权限逐项处理。
5. 任务中途断开或输出卡住，直接换专线或固定 IP 节点，不要重试。

长期来看，减少 Codex 报错最有效的办法不是记住所有错误码，而是用一个稳定的节点。Codex 稳定机场的判断标准见 Codex 稳定机场与网络环境分析，经过站内连接测试的品牌可以在 Codex 机场推荐 栏目查看，其中 宇宙云 的 IEPL 专线对长连接表现稳定，极连云 对 AI 服务做了专门适配。通用的超时原因分析见 连接超时的常见原因，更多 AI 访问问题可以到 AI 访问诊断 栏目查找。