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

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

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

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

text
stream disconnected before completion

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

先用 90 秒确认影响范围

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

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

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

OpenAI 的官方 Troubleshooting也把“是否在等待 approval”“基本终端命令能否运行”和“新建更聚焦的 chat”列为卡住状态的首要检查。这些动作不会破坏现有任务，且能把问题分到不同责任边界。

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

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

bash
codex --version
codex --help

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

更新值得优先做，是因为问题确实曾在客户端层被修复。OpenAI 的 Codex changelog记录，CLI 0.148.0 改善了临时 provider outage 下的 turn reconnect；同日的客户端更新也修复了任务在 idle 或 reconnecting 后不可用的情况。后续版本仍在继续发布。

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

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

不要只看最后一行。完整错误文本通常已经给出更窄的 owner：

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

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

网络只改变一个条件

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

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

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

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

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

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

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

OpenAI 的 permissions 配置说明明确把 permission profile 的 network proxy 定义为 sandboxed command traffic 的控制，并说明它向工具提供 HTTP(S) 与 WebSocket 代理环境。修改这部分可以改变 curl、包管理器或其他命令的网络，却不能证明 Codex App 自己的响应流也会因此改变。

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

何时重启，何时新建任务

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

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

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

不要把删除 session 当第一步

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

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

• macOS App 日志：~/Library/Logs/com.openai.codex/YYYY/MM/DD
• 活跃 session：$CODEX_HOME/sessions，默认 ~/.codex/sessions
• 已归档 session：$CODEX_HOME/archived_sessions

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

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

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

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

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

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