# Codex 一直 Reconnecting：先保住任务，再定位是哪一层断了

> Codex 反复 Reconnecting、卡在 Thinking 或提示 stream disconnected 时，先保留任务上下文，再区分单会话、客户端版本、认证、网络路径和临时服务故障。

- Source: https://www.aifreeapi.com/zh/posts/codex-stuck-reconnecting-fix
- Language: zh
- Published: 2026-08-31
- Updated: 2026-09-12
- Publisher: AI Free API (https://www.aifreeapi.com)

`Reconnecting` 是结果，不是根因。它表示 Codex 正在尝试恢复一条中断的连接；同样的提示可能来自临时服务抖动、客户端版本问题、当前任务状态、认证失效，或实际运行 Codex 的主机无法稳定建立响应流。

因此，先不要删除 `~/.codex`、会话记录文件、登录凭据或整个应用。项目里的文件改动通常独立存在，但未完成的对话上下文、错误时间与日志正是判断问题的证据。最安全的目标不是立刻猜中原因，而是用最少的改动把影响范围缩小。

如果界面已经从 `Reconnecting 1/5` 走到 `5/5`，并出现：

```text
stream disconnected before completion
```

先复制最后一条指令，记下正在处理的文件和最后确认完成的步骤。不要反复发送同一条会产生外部写入或不可逆操作的指令；重连成功后，旧请求可能仍然继续。

## 先确认影响范围

保持原任务不动，依次做三个低风险观察：

1. 在同一项目新建一个很小的任务，例如只让 Codex 说明当前目录，不要求修改文件。
2. 打开集成终端，运行 `pwd` 或 `git status`。
3. 如果同时安装了 CLI 或 IDE 扩展，只做一个同等大小的只读请求，比较另一种入口。

结果比任何通用“修复命令”更有价值：

| 观察结果 | 更可能受影响的范围 | 下一步 |
|---|---|---|
| 只有旧任务反复重连，新任务正常 | 当前任务的流或持久化状态 | 保留旧任务，先在新任务用保存的上下文继续；不要清空全部会话记录 |
| 桌面端失败，但 CLI 正常 | 桌面端版本、宿主进程或该入口的连接路径 | 比较版本，完整退出并重开桌面端 |
| CLI 与 IDE 扩展都失败，基本 shell 正常 | Codex 认证或服务响应路径，而非项目命令本身 | 记录完整错误，检查登录状态与网络对照 |
| `git status` 也卡住 | 本地项目、文件系统、shell 或进程问题 | 先解决本地命令；此时 Reconnecting 可能只是同时出现的表象 |
| 新旧任务、多个入口和两个网络都失败 | 账号、服务或广泛客户端问题的可能性上升 | 停止改配置，查看官方状态并提交诊断 |

![Codex Reconnecting 分层恢复决策流程，从保护任务证据、最小影响范围测试和结果归类，到选择低风险动作、转向相邻错误指南和准备诊断材料](https://www.aifreeapi.com/posts/zh/codex-stuck-reconnecting-fix/img/layered-recovery-decision-flow.webp)

OpenAI 的[官方排障说明](https://learn.chatgpt.com/docs/reference/troubleshooting#stuck-states-and-recovery-patterns)也把“是否在等待批准”“基本终端命令能否运行”和“新建目标更明确的任务”列为卡住状态的首要检查。这些动作不会破坏现有任务，且能把问题缩小到具体任务、客户端或本地环境。

## 更新客户端，但不要把“最新版”当结论

先记录各入口自己的版本。CLI 使用：

```bash
codex --version
codex --help
```

桌面端在 About 界面查看版本，IDE 扩展在扩展详情里查看版本。不要只记录“Codex 最新版”，因为桌面端、CLI 和 IDE 可能包含不同构建。OpenAI 的官方排障页明确提醒，这些客户端使用的 Codex 版本可能不同。

更新值得优先做，是因为问题确实曾在客户端层被修复。OpenAI 的 [Codex changelog](https://learn.chatgpt.com/docs/changelog)记录，CLI 0.148.0 改善了服务商临时故障时的任务重连；同日的客户端更新也修复了任务空闲或重连后无法继续使用的情况。后续版本仍在继续发布。

但这个事实只能支持“先比较并更新版本”，不能支持“所有 Reconnecting 都是旧版本”。如果更新后只有一个旧任务失败，继续按任务范围处理；如果多个入口都失败，再看认证和网络。

## 把认证错误、限额和连接中断分开

不要只看最后一行。完整错误文本通常已经给出更具体的排查方向：

- 明确出现 `access token could not be refreshed`，转到 [Codex token 刷新排查](/zh/posts/codex-access-token-could-not-be-refreshed)。
- 明确出现 HTTP 429、usage limit 或 reset time，转到 [Codex 429 与用量限制](/zh/posts/codex-rate-limits)。
- 明确是 command、MCP 或 cloud config bundle 的 timeout，先按 [Codex timeout 边界](/zh/posts/codex-timeout)判断等待对象。
- 只有 `stream disconnected before completion` 或反复 `Reconnecting`，继续检查客户端响应流；不要把它自动归类为配额不足。

![Codex 重连错误路由与诊断清单，区分 token refresh、HTTP 429、timeout 和单纯 stream disconnected，并列出提交反馈前需要保留的版本、主机、时间线和脱敏日志](https://www.aifreeapi.com/posts/zh/codex-stuck-reconnecting-fix/img/error-routing-and-diagnostic-checklist.webp)

如果账号刚刚切换、多因素认证刚完成，或公司工作区策略刚更新，先完整退出 Codex，再重新打开并确认当前身份。不要因为一次通用连接中断就先 `logout`；退出登录会改变现场，让你无法判断原来是令牌失效、连接路径异常还是临时断线。

## 网络只改变一个条件

浏览器能打开 ChatGPT，不证明 Codex 桌面端、终端、VS Code 扩展宿主进程、WSL、容器或 Remote SSH 使用同一条代理、DNS、证书信任和防火墙路径。先写清 Codex 进程实际运行在哪里。

然后只做一次允许范围内的对照：

- 公司网络与获准的普通网络二选一；
- 保持账号、项目和客户端版本不变，只暂时比较 VPN 开/关；
- 如果必须通过本地代理，确认代理进程仍在监听、端口与 Codex 进程实际继承的环境一致；
- 在 WSL、容器或 Remote SSH 中失败时，从那台主机检查，而不是只检查本机浏览器。

记录对照前后的时间、最后可见状态和完整错误。如果换网络后立刻恢复，这支持“原路径相关”，但仍不能单凭一次成功断言是 DNS、TLS、WebSocket、代理规则还是中间设备中的哪一项。

### 为什么不应直接复制“禁用 WebSocket”配置

网上常把 `.env`、`HTTP_PROXY` 或一个 WebSocket 开关写成通用答案。这里至少有两类不同的网络连接：

1. Codex 客户端与服务之间承载模型响应的连接；
2. Codex 在沙箱中运行命令时允许的出站网络。

OpenAI 的 [permissions 配置说明](https://learn.chatgpt.com/docs/permissions#configuration-spec)明确把权限配置中的网络代理用于控制**沙箱内命令流量**（sandboxed command traffic），并说明它向工具提供 HTTP(S) 与 WebSocket 代理环境。修改这部分可以改变 `curl`、包管理器或其他命令的网络，却不能证明 Codex App 自己的响应流也会因此改变。

如果你的实际错误来自自定义模型服务商，先查该服务商与当前 Codex 版本的文档；如果只是普通 ChatGPT 登录的 Codex App，不要把未出现在当前官方配置参考中的配置项写进 `config.toml` 后就视为已修复。需要长期保留的配置应记录修改前值，并确保能一键回滚。

## 何时重启，何时新建任务

完成上述观察后，按范围选择最小恢复动作：

- **单任务失败：** 保留原任务；在新任务粘贴精简后的目标、已完成步骤和文件范围，让它先只读确认现场。旧任务不要删除，后续日志可能需要它的 session ID。
- **单一客户端失败：** 等其他正在执行的任务结束，完整退出应用或 IDE 宿主进程，再重新打开。只关闭窗口不一定结束后台进程。
- **多个客户端同样失败：** 不要继续清缓存或重装。先检查 [OpenAI Status](https://status.openai.com/)，记录本地时间，再用另一个获准网络做一次对照。
- **更新或重启后恢复：** 回到原任务前先检查 `git status` 和实际文件，确认没有把同一外部动作执行两次。

官方排障说明建议在持续卡住时等待其他任务完成后再重启应用。这一停止条件很重要：强制退出可能中断仍在写文件或执行命令的其他任务。

## 不要把删除会话记录当第一步

只有“一个特定旧任务稳定失败、同项目新任务稳定正常、版本与网络对照均无变化”时，才有理由怀疑该任务保存的状态。即使如此，也先备份和隔离，不要直接删整个目录。

OpenAI 官方给出的数据位置包括：

- macOS App 日志：`~/Library/Logs/com.openai.codex/YYYY/MM/DD`
- 活跃会话记录：`$CODEX_HOME/sessions`，默认 `~/.codex/sessions`
- 已归档会话记录：`$CODEX_HOME/archived_sessions`

这些文件可能包含提示词、路径、仓库名、工具输出或其他敏感信息。分享前先检查并删除不必要的内容，不要上传整个数据目录。若你不确定哪个文件属于故障任务，优先使用 Codex 输入框里的 `/feedback` 流程，而不是根据修改时间批量删除。

## 提交一份别人能复现的诊断

如果问题在更新、单次网络对照和完整重启后仍存在，整理以下最小材料：

- Codex 客户端类型与准确版本；
- 操作系统，以及进程实际运行在本机、WSL、容器还是远程主机；
- 错误发生时间与时区；
- 完整状态序列，例如 `Reconnecting 1/5` 到 `5/5`；
- 新任务是否正常、另一个客户端是否正常；
- 基本命令是否运行；
- 只改变一个网络条件后的结果；
- 已脱敏的相关日志片段。

通过 `/feedback` 提交时，可以选择是否附带当前会话。官方排障说明还建议先查找 openai/codex 的现有 issue，再提交新的故障报告。不要公开 token、cookie、邮箱、内部工作区名、私有仓库内容或整段商业代码。

最有用的“解决”不是一次性猜中代理端口，而是得到一个明确结论：问题只在旧任务、只在某个客户端、只在某条网络路径，还是跨客户端持续存在。范围一旦缩小，下一步才真正可验证，也不需要用清空全部 Codex 数据来碰运气。