【Bug已解决】Codex CLI 报 stream disconnected before completion 解决方案

1. 问题描述

在使用 Codex 处理任务的过程中，经常在响应生成到一半时突然中断，终端提示：

Reconnecting... (attempt 1/5)
Error: stream disconnected before completion

有些情况下还会伴随一些完全无关、看起来"灵异"的乱码或异常字符输出。

1.1 具体现象

1. 任务执行到一半，流式响应突然断开，反复触发重连
2. 换了网络环境后，问题时好时坏，让人怀疑是网络不稳定
3. 排查很久发现和网络本身关系不大，反而是本机的某个系统组件出了问题
4. Windows 用户遇到的概率相对更高

这个问题看起来像典型的网络问题，但社区排查的多个真实案例显示，很多时候真正的根因是本机系统的 TLS 证书信任链异常，而不是网络连接质量本身。

2. 原因分析

Codex CLI 与服务端之间建立的是长连接的流式 HTTPS 请求，这类连接对底层 TLS/SSL 证书链的校验要求较高。如果本机的根证书库存在异常（比如证书过期、证书存储损坏、系统时间不准确导致证书有效期校验失败），会导致 HTTPS 连接在建立或维持过程中被判定为不可信，从而被操作系统或底层网络库主动中断。

用一张流程图梳理排查思路：

Codex 发起流式请求
        ↓
建立 TLS 连接，校验服务端证书链
        ↓
本机根证书库/信任链是否正常？
   ├─ 正常 → TLS 连接稳定，流式响应持续到完成
   └─ 异常 → 证书校验失败或连接不稳定
              ↓
       stream disconnected before completion

除了证书链问题，也存在少数情况是本地遗留了错误的服务商配置（比如某个 model_provider 的 base_url 配置本身有误），导致请求被发送到了一个不稳定或错误的端点，这种情况需要结合配置文件一并排查。

3. 解决方案

方案一：检查并更新系统根证书库（社区验证的核心根因）

# Windows：通过系统更新确保根证书库为最新
# 设置 → 更新和安全 → Windows 更新 → 检查更新

# 也可以手动检查根证书更新情况
certutil -generateSSTFromWU roots.sst

# macOS：确保系统更新到最新版本，系统会自动维护根证书库
softwareupdate --list

# Linux：更新 CA 证书包
sudo apt update && sudo apt install --only-upgrade ca-certificates

方案二：检查本机系统时间是否准确

证书有效期校验依赖准确的系统时间，如果本机时间明显偏差，会导致本应有效的证书被误判为无效：

# macOS/Linux
date
sudo ntpdate time.apple.com

# Windows
w32tm /resync

方案三：确认配置文件中的 base_url 是否正确无误

排除证书问题后，如果依然反复断线，检查配置的服务端地址是否正确：

# ~/.codex/config.toml
[model_providers.your_provider]
base_url = "https://api.example.com/v1"  # 仔细核对，确认没有多余字符或拼写错误

方案四：临时切换网络环境排除本地网络设备问题

部分场景下问题确实和当前所连接的网络设备（比如某些家用路由器、公共 Wi-Fi 的深度包检测策略）有关，可以尝试更换一个稳定的有线网络连接进行对比测试，排除本地网络设备层面的干扰。

方案五：升级到修复了相关问题的最新版本 Codex CLI

如果确认是特定版本的已知缺陷（社区已有类似问题的版本相关讨论），及时升级到官方发布的修复版本是最直接的解决方式：

npm update -g @openai/codex
codex --version

4. 各方案对比总结

方案	适用场景	推荐指数
更新根证书库	社区验证的最常见根因	⭐⭐⭐⭐⭐
检查系统时间	虚拟机/容器等特殊运行环境	⭐⭐⭐⭐
核对 base_url 配置	排除证书问题后的下一步排查	⭐⭐⭐⭐
更换网络环境测试	怀疑本地网络设备存在干扰	⭐⭐⭐
升级到最新版本	已知版本缺陷的场景	⭐⭐⭐⭐

5. 常见问题 FAQ

5.1 为什么第一反应总是怀疑网络问题，而不是证书问题？

因为报错信息本身（stream disconnected、Reconnecting）从字面上看确实很像典型的网络连接问题，这也是这个问题容易让人排查方向跑偏的关键原因。建议遇到类似报错时，把"检查证书链和系统时间"也纳入标准排查清单，而不是只盯着网络本身。

5.2 换了手机热点网络后问题消失了，是不是就能确定是网络问题？

不一定。切换网络环境的同时，往往也切换了对应的 DNS 解析、路由路径，如果之前的问题恰好和某个特定网络路径下的证书链校验相关，换网络后现象消失也可能只是"绕开了"触发条件，并不代表根因就是网络质量本身，建议结合本文方案一并排查证书库状态。

5.3 企业电脑的证书库是否可能被 IT 部门统一管理，个人无法修改？

有可能，企业环境下的证书策略可能由统一的终端管理软件控制。如果怀疑是企业证书策略导致的问题，建议联系 IT 部门确认相关证书配置，而不是自行尝试绕开这类统一管理机制。

5.4 这个问题会不会随着 Codex 版本升级而彻底消失？

如果根因确实是系统层面的证书/时间问题，版本升级本身不能解决这类环境问题；但如果是 Codex 客户端自身在处理连接异常时的重试逻辑存在缺陷，官方后续版本的改进可能会让类似问题的表现变得更友好（比如更清晰的错误提示、更智能的重连策略）。

5.5 排查清单速查表

□ 1. 检查系统根证书库是否已更新到最新
□ 2. 确认本机系统时间是否准确
□ 3. 核对配置文件中 base_url 是否正确无误
□ 4. 尝试更换网络环境进行对比测试
□ 5. 确认当前 Codex CLI 版本是否存在已知的相关缺陷
□ 6. 企业电脑场景确认证书策略是否由统一终端管理软件控制

6. 总结

stream disconnected before completion 报错虽然表现形式很像网络连接问题，但社区排查的多个真实案例表明，很大一部分情况的根因其实是本机系统的 TLS 证书信任链异常或系统时间不准确，而不是单纯的网络质量问题。核心处理思路：

1. 优先检查并更新系统根证书库，这是社区验证过的高频根因；
2. 确认本机系统时间是否准确，尤其是虚拟机/容器等特殊运行环境；
3. 排除证书和配置问题后，再考虑网络环境本身的稳定性因素。

最佳实践建议：遇到流式连接中断类问题时，不要第一时间就把排查精力全部投入到"网络是否稳定"上，把系统证书库和时间同步状态也作为标准排查项，往往能更快找到真正的根因。