发布日期：2026-10-20 | 话题：Codex 报错 / stream disconnected / OpenAI Codex CLI 断流

stream disconnected before completion 是 OpenAI Codex 桌面应用和 Codex CLI 中最常见的网络类报错，2026 年 10 月仍有大量用户在 GitHub Issues 中反馈（#54029、#54407、#54459 等），官方尚未提供统一修复版本。本文汇总了来自 GitHub 的实测数据：错误触发场景分为四大类——Windows 网络层终止（os error 10053）、远程上下文压缩失败（长会话约 370 秒触发）、旧会话与退役模型绑定、以及代理工具干扰（本地网络中间件等）；对应的临时解法包括新建会话、切换网络环境测试、手动清除 thread-store 写入锁、以及调整 TCP keep-alive 设置。对于频繁在多模型之间切换调用的开发者，将调用层统一到兼容 OpenAI 格式的推理平台也能绕开客户端历史绑定问题。

报错的准确含义

stream disconnected before completion 字面意思是：服务端响应流在返回完整内容之前就被中断了。Codex 的响应通过 Server-Sent Events（SSE）或 WebSocket 流式传输，任何一方中途关闭连接都会触发这条错误。

错误信息有几种变体，含义略有不同：

错误变体

含义

stream disconnected before completion: IO error: os error 10053

Windows TCP 层主动终止连接（WSAECONNABORTED）

stream disconnected before completion: stream closed before response.completed

WebSocket 在 response.completed 事件到达前关闭

stream disconnected before completion: Transport error: network error: error decoding response body

远程上下文压缩任务的响应体解码失败

stream disconnected before completion: An error occurred while processing your request.

服务端通用错误，常见于代理中间层干扰

四种变体背后对应四类不同根因，修复路径也不同。

四类根因与对应修复

根因一：Windows TCP 层终止空闲连接（os error 10053）

现象：对话闲置 5-15 分钟后突然报错，图片/概念艺术类对话更易触发（来源：GitHub Issue #54459，2026 年 10 月，Windows 10 19045 + Codex App v26.1007.71326）。

根因：Windows 错误码 10053 = WSAECONNABORTED，表示本地 TCP 软件（防火墙、杀毒程序）主动终止了一个已建立的空闲连接，Codex 客户端没有在断连后自动重连。

修复方案：

  1. 调整 Windows TCP keep-alive 间隔（PowerShell，管理员权限）：

# 将 TCP keep-alive 间隔从默认 2 小时缩短为 60 秒
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters" `
  -Name "KeepAliveTime" -Value 60000 -Type DWord
# 修改后重启网络适配器（将"以太网"替换为 Get-NetAdapter 显示的实际名称）
Restart-NetAdapter -Name "以太网"

  1. 临时方案：对话中途每隔 5 分钟主动发一条消息（如"继续"），保持连接活跃。

  2. 排查防火墙/杀毒：临时关闭 Windows Defender 防火墙或第三方杀毒测试是否复现。

根因二：远程上下文压缩（Remote Compaction）超时失败

现象：长时间运行的 goal/agent 任务在执行约 369-371 秒后报错，同一会话重试多次均失败，日志显示 Error running remote compact task: stream disconnected before completion（来源：GitHub Issue #54029，版本 CLI 0.162.1 + gpt-6.1-sol）。

根因：Codex 在会话历史超过一定规模时触发"远程压缩"——服务端对历史 JSONL 调用模型做摘要，这个过程本身是一个流式请求，超时或解码失败即报错。Issue #54029 的会话已有 19,856 条 JSONL 记录和 18 次成功压缩历史，第 19 次开始连续失败。

修复方案：

  1. 新建会话，将未完成任务的关键上下文手动粘贴进新对话（官方 workaround，Issue #54029 用户确认有效）。

  2. 减少历史积累：定期用 codex history clean 或手动删除 ~/.codex/history/ 中的旧线程文件，防止单会话历史体积失控。

  3. 等待官方修复：PR #53932（"Preserve conversation history when compaction fails"）已合并，部分缓解历史丢失，但根本问题仍在跟踪中。

根因三：旧会话与退役/切换模型绑定

现象：恢复旧会话报 stream disconnected，新建会话完全正常；日志同时出现 thread-store conflict: thread xxx already has an active writer（来源：GitHub Issue #54407，codex-cli 0.162.1 + Windows x64）。

根因：旧会话线程状态绑定了已退役的 gpt-5.5 模型，切换到 gpt-6.1-sol 或 gpt-6-luna 后恢复时，线程写入锁未释放叠加流式传输失败，双重错误导致无法恢复。

修复方案（按优先级）：

  1. 关闭所有桌面进程（包括后台 Codex Helper），再重开应用——可解除 thread-store conflict 写入锁，但流错误可能仍存在。

  2. 手动清理 thread-store 写入锁：

# macOS / Linux：找到对应 thread 的锁文件并删除
ls ~/.codex/threads/
# 找到对应 thread ID 的 .lock 文件
rm ~/.codex/threads/<thread_id>.lock

  1. 放弃旧会话，新建对话：这是目前成功率最高的方案，Issue #54407 用户确认有效。

根因四：本地网络中间件干扰 WebSocket 心跳

现象：普通提问频繁出现重连（高达 5/5），日志显示 closeCode=1006, failureReason=open_timeout, transport=websocket，在某些本地网络配置下复现稳定（来源：GitHub Issue #54318，macOS 27.2）。

根因：本地网络中间件（企业防火墙、网络安全软件、本地流量管理工具等）对 WebSocket 升级请求的处理不一致，中间层可能截断长连接的心跳包，导致 open_timeout 后客户端认为流已断开。

修复方案：

  1. 排查本地网络环境：切换到其他网络（如手机热点）测试是否复现——如果切换后正常，则确认是当前网络环境的问题。

  2. 检查网络安全软件设置：企业防火墙或本地安全软件可能对长连接有超时限制，可临时关闭排查。

  3. 企业网络 SSL 检测：检查 SSL Inspection 是否开启，该功能会重新签发证书并可能导致 SSL_BAD_RECORD_MAC_ALERT，联系网络管理员将 Codex 相关域名加入白名单。

快速诊断流程

拿到报错后，先用三个问题缩小根因范围：

1. 新建对话是否正常？
   → 是：根因三（旧会话/模型绑定）或根因二（历史过大）
   → 否：进入第 2 步

2. 切换网络环境（如手机热点）后是否正常？
   → 是：根因四（本地网络中间件干扰）
   → 否：进入第 3 步

3. 错误是否在空闲 5-15 分钟后触发？
   → 是：根因一（Windows TCP 空闲超时）
   → 否：根因二（远程压缩超时）或服务端临时故障

根因

主要平台

临时解法

彻底解法

Windows TCP 超时

Windows

保持对话活跃

调整 KeepAliveTime

远程压缩失败

全平台

新建会话

等待 PR#53932 修复

旧会话模型绑定

全平台

新建会话

清除 thread-store 锁

本地网络中间件干扰

macOS/全平台

切换网络环境测试

联系网络管理员排查白名单

长会话的预防建议

与其等报错再处理，不如从工作流层面降低触发概率：

  1. 单会话长度控制：超过 200 条消息的会话触发远程压缩的概率显著上升。复杂任务可以分拆为多个独立子任务会话。

  2. 定期保存中间结果：在 agent 任务中间插入"请将当前进展总结为一个 markdown 文件"，把上下文固化到文件而非会话历史中。

  3. 多模型 API 统一管理：如果同时调用多个模型做对比测试，推荐通过兼容 OpenAI 格式的统一 API 入口管理——例如七牛云 Token Plan 支持 50+ 模型用同一个 API Key 调用，切换模型只需改 model 参数，不会产生新旧会话历史的绑定问题。

常见问题

Q：stream disconnected 报错后，当前对话的内容会丢失吗？

取决于触发原因。根因三（旧会话/写入锁）情形下，内容通常没有丢失，重启应用清除锁文件后可恢复。根因二（远程压缩失败）情形下，PR #53932 合并后会保留本地历史，但新消息可能无法继续发送。建议定期手动导出重要对话内容。

Q：报错 os error 10053 只有 Windows 才有吗？

目前 GitHub Issues 中 os error 10053 的报告几乎全来自 Windows 用户，macOS 上的类似问题通常表现为 closeCode=1006 或代理超时，不同系统的底层 TCP 实现差异导致错误码不同，但根本原因（空闲连接被中断）是一致的。

Q：远程压缩（Remote Compaction）具体在什么时候触发？

官方未公开明确阈值。根据 Issue #54029 的实测，该用户在 19,856 条 JSONL 记录时稳定触发。一般规律是：长时间 goal 任务、历史消息积累超过一定量（推测 5-10 万 token 级别）后 Codex 会尝试在服务端压缩历史，这个压缩请求本身是流式的，网络不稳时容易中断。

Q：新建对话后，之前未完成的 goal/任务还能恢复吗？

不能直接从断流的旧会话恢复，但可以：① 查看 ~/.codex/threads/ 下的本地历史文件（如果 PR #53932 的修复在你的版本中已生效），手动提取未完成的任务描述；② 在新会话中粘贴任务背景和断点位置，重新启动。

Q：这个报错在 Codex CLI（命令行版本）和桌面应用中表现一样吗？

根因二（远程压缩）和根因三（模型绑定）在两个版本中均可触发，报错信息相同。根因一（os error 10053 Windows TCP 超时）和根因四（本地网络中间件干扰 WebSocket）在桌面应用中报告更多，CLI 场景相对少见，可能因为 CLI 用户更倾向于在稳定网络环境下操作。

结语

stream disconnected before completion 报错目前没有一键修复方案，根因差异大，需要先定位再对症处理。最高优先级的临时方案始终是新建会话——它能绕开根因二和根因三，成本最低。Windows 用户如果频繁遇到空闲超时（os error 10053），调整 TCP keep-alive 可以显著降低频率。如果问题出在本地网络环境，切换网络测试后再联系管理员排查中间件白名单配置。

本文数据来源：OpenAI Codex GitHub Issues（#54029、#54407、#54459、#54318，2026 年 10 月），问题仍在跟踪中，建议关注 Codex 官方更新日志获取最新进展。

延伸资源