Codex 客户端频繁提示「正在重连 / Reconnecting」的原因与完整解决方案

Codex 客户端频繁提示「正在重连 / Reconnecting」的原因与完整解决方案

一、问题现象

在使用 OpenAI Codex（CLI、桌面 App 或 VS Code 插件）时，对话过程中反复出现类似提示：

Reconnecting... 1/5
Reconnecting... 2/5
Reconnecting... 3/5
Reconnecting... 4/5
Reconnecting... 5/5
stream disconnected before completion: error sending request for url (https://chatgpt.com/backend-api/codex/responses)

典型表现为：

• 对话已经创建，但回复过程中频繁断流重连；
• 重连 5 次后仍失败，最终报 stream disconnected before completion；
• 偶发情况：重连几次后能继续输出，但过一会又开始新一轮重连；
• 有时还伴随 Falling back from WebSockets to HTTPS transport（从 WebSocket 降级到 HTTPS）。

---

二、为什么会出现「正在重连」

1. 根本原因：Codex 用的是「长连接流式传输」

Coding Agent 和普通聊天不一样。一次任务可能持续数分钟，期间要读文件、跑终端、等测试结果，模型回复是通过 SSE（Server-Sent Events）流式连接持续推送的。只要这条长连接中间被任何一环掐断------本地网络、出口链路、网关、OpenAI 服务端------客户端就会收到断流错误并开始自动重连。

「Reconnecting 1/5 ~ 5/5」只是外层计数提示，真正的原因藏在后面的错误原文里（如 timeout、401/403/429、failed to lookup address information 等），看错误原文比看重连计数重要得多。

2. 常见原因分类

类别	具体原因	典型错误特征
网络出口问题	本地网络对长连接处理不稳；TLS 握手失败；出口链路质量差	error sending request for url、Connection reset by peer
子进程环境变量丢失	终端环境变量正常，但 Codex 启动的子进程没有继承相关配置	终端里网络正常，CLI 一直断
网络切换	切换 Wi-Fi 后 DNS/路由缓存失效（组网工具会加剧）	failed to lookup address information
客户端版本 Bug	某些版本存在已知回归（如部分版本在 WSL 中不稳定）	刚升级后开始出现
上下文过大	大项目 + 长对话导致 context 接近上限，服务端处理超时截断流	总在对话进行到某个阶段后断开
服务端问题	OpenAI 侧拥堵或特定模型/速度档位异常	换模型或换速度档位后恢复
网关超时问题	自建 API 网关的空闲超时时间过短、不支持 Responses 流式协议	约 5 秒固定断开

---

三、解决方案（按排查顺序执行）

第一步：先做五分钟定位

在改动任何配置之前，先确定故障层级：

codex --version   # 记录版本
which codex       # 确认安装来源（npm / Homebrew / 桌面端内置）

然后在 CLI 中执行 /status 查看当前会话状态。

做两个对照实验：

1. 短任务测试 ：新建空目录，发一条「只回复 OK」的短请求。
   • 短请求也失败 → 优先查网络、认证；
   • 短请求成功、长任务失败 → 查上下文长度、长连接稳定性、网关超时。
2. 换网络测试 ：切换手机热点复测一次。
   • 换网络后恢复 → 问题在本地出口链路、DNS 或防火墙；
   • 两条网络都失败 → 查账号认证、版本和服务状态。

第二步：清理本地认证状态（最多人验证有效）

Token 过期或本地缓存损坏时，请求能发出但流走到一半就被拒绝。直接清掉重来：

codex logout
rm -rf ~/.codex
codex login

⚠️ rm -rf 前确认路径没多打空格。Windows 下对应目录是 C:\Users\<用户名>\.codex。

第三步：开新会话，别 resume 旧会话

Codex 的 resume 机制会把之前的上下文整体重新注入。会话挂得越久、上下文越大，流式传输的数据量越大，断流概率越高。旧会话出问题后，直接开新 session，从零开始。

第四步：处理本地网络与出口链路问题

这一步是断流最高发的原因，但也是最容易误诊的一步。几个自查要点：

1. 确认终端环境的网络变量能被子进程继承

在终端里设置好的网络环境变量，Codex 默认出于安全考虑不会全部传给子进程。如果你的网络环境依赖这些变量，需要在 ~/.codex/config.toml 中显式允许传递：

[shell_environment_policy]
include_only = ["PATH", "Path", "HOME", "USERPROFILE", "TEMP", "TMP", "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy"]

2. 检查系统级网络设置

如果你所在的企业、校园或组织网络有统一的出口管理策略，请按照该网络环境管理方提供的合规配置方式进行设置，并确认 Codex 进程能走相同的出口链路。改完后完全退出 Codex 再重启。

3. 排除 Wi-Fi 切换和组网软件干扰

切换过 Wi-Fi、用过 Tailscale 等组网工具后，DNS 和路由缓存可能残留旧状态，表现为 failed to lookup address information。简单处理：重连网络或重启机器，再开新会话测试。

第五步：调整重试与超时参数

如果你使用自建的 API 网关或第三方 API 服务，长任务中断流往往是网关的空闲超时太短。在 ~/.codex/config.toml 的 provider 配置中补充：

[model_providers.your_provider]
base_url = "https://your-gateway.example.com/v1"
env_key = "YOUR_API_KEY"
wire_api = "responses"
request_max_retries = 6
stream_max_retries = 8
stream_idle_timeout_ms = 600000

三个参数的含义：

• request_max_retries：普通 HTTP 请求失败后的重试次数；
• stream_max_retries：流式连接中断后的重试次数；
• stream_idle_timeout_ms：流式连接无新数据时允许等待的时长（毫秒）。

注意：加重试只能缓解偶发断流，修不了错误的接口地址，也没法把一个只支持 Chat Completions 的网关变成 Responses 网关。如果每次都固定在约 5 秒断开，基本就是网关侧超时配置问题，要去改网关。

第六步：检查版本问题

Codex 发版快，偶尔带回归 bug：

• 如果刚升级后开始出现重连，尝试降级：

npm install -g @openai/codex@<旧版本号>

• 如果长期没升级，升级到最新版：

npm update -g @openai/codex

• WSL 用户尤其注意版本兼容性，可优先考虑在原生 Linux / macOS 终端中运行。

第七步：排除上下文溢出

「网络错误」有时是假象------实际是上下文窗口爆了。大项目 + 超长对话时，服务端处理超时截断响应，客户端收到不完整的流，表现和网络问题一模一样。

区分方法：如果每次都在对话进行到某个阶段之后才掉线，大概率是 context 问题。开新 session 验证；日常使用中养成「一个任务一个会话」的习惯。

第八步：确认不是服务端问题

上面都做完还是断，去查一下 OpenAI 服务状态（status.openai.com）。GitHub issue 区里不少帖子最后的结局是「什么都没动，第二天自己好了」------服务端拥堵时，等一等确实是唯一办法。

---

四、一图流排查顺序

出现 Reconnecting
      │
      ▼
① 短任务测试 + 换网络测试（定位故障层级）
      │
      ▼
② codex logout → 清 ~/.codex → 重新 login
      │
      ▼
③ 开新会话（不要 resume）
      │
      ▼
④ 网络：子进程环境变量 / 出口链路 / DNS 与组网软件干扰
      │
      ▼
⑤ 自建网关：调 stream_max_retries 和 stream_idle_timeout_ms
      │
      ▼
⑥ 版本：刚升级就降级，久未升就升级
      │
      ▼
⑦ 怀疑上下文溢出 → 开新 session 验证
      │
      ▼
⑧ 都不行 → 查 status.openai.com，等服务端恢复

---

五、几个关键结论

1. 「Reconnecting 5/5」只是现象不是原因------后面的错误原文（timeout、DNS 失败、401/429、connection reset）才有诊断价值。
2. 终端正常 ≠ CLI 正常 ：Codex 子进程默认不继承全部环境变量，网络相关的变量需要在 config.toml 里显式放行。
3. 固定时间断开（如约 5 秒）基本是网关/中转的空闲超时，改客户端没用，要改网关。
4. 长任务天然更容易断流，保持会话精简、及时开新会话是最便宜的预防手段。
5. 别急着换模型、卸载重装------按链路逐段验证（认证 → 网络 → 协议 → 服务端），比碰运气高效得多。