stream disconnected：长连接被掐的排查

用 AI 编程智能体 Codex 跑一个长任务，进度走到一半，终端里突然吐出 stream disconnected before completion，任务被迫中断——这是企业网与家庭网络环境里都高频出现的报错。它字面意思直白：一条流式长连接在任务完成前被掐断了。麻烦在于，掐连接的位置可能在链路上的任何一环，盲目重试往往只是再断一次。这篇按代理、超时、服务端三个顺位给一套排查清单，并解释为什么缩短单次任务常常是最快的止血手段。

流式长连接：为什么它会断

Codex 与服务端之间跑的是流式连接：任务执行期间，模型边推理边把结果一段段推回终端，这条连接要保持几分钟到几十分钟不断。它与常见的「请求—应答」短连接不同——短连接几秒钟完成使命，长连接则要在网络设备面前长时间挂着，而许多中间设备对挂着的连接并不友好：防火墙按空闲时长回收会话，代理对长响应体有自己的缓冲上限，NAT 表项超时后悄悄丢弃映射。于是出现一个典型现象：短对话一切正常，任务一长就断。判断断点在哪不靠猜，按下面三个顺位逐项排除。

第一顺位：代理与防火墙

排查从最常见的一环开始。企业网里掐断长流式连接的高发位置是代理与防火墙：公司出口的代理设备对单个连接的持续时间、响应体大小常常设有上限，长任务跑到几分钟，连接就被中途收回，表现正是 stream disconnected before completion。办公网里部署了流量审计或自签 TLS 证书的代理时，问题更常见——这类设备要拆开检视流量，与流式长连接的相处天然别扭。自查办法也直接：同一个任务换到手机热点或家庭网络跑一遍，断不断立刻见分晓；若换网后不再报错，基本可以锁定企业网这一环，接下来走代理配置的专项处理，代理配置专项一篇有完整方案。掐连接的多半不是模型服务本身，而是链路中间的这些设备。

第二顺位：超时与任务时长

换网之后仍然断，第二顺位看超时。这里有一个很有用的 tell：如果短聊天一路畅通、长任务必断，断点时刻还相对固定，多半是链路上某个环节的超时阈值在起作用——代理的空闲超时、网关的会话时长，都可能卡在某几分钟的整数附近。核对终端输出里断开前的推进情况，记录几次断开的时刻，规律会自己浮出来。对应办法是缩短单次任务：把一个要跑半小时的大活拆成几个几分钟的小步骤，每步落盘、验收、再继续，单次连接的时长被压到阈值以内，断无可断。任务拆分不只是应急，长任务的进度可控性也会随之改善，具体跑法见下一节。

第三顺位：服务端与版本因素

代理与超时都排除后，才轮到服务端。服务端降级或事故期间，长连接同样容易被中断，此时别人也在报错，状态页与社群会有印证，服务端问题的判断与等待策略见503 处理一篇，思路相通。版本因素也别放过：重试与断线处理的行为在版本之间有过变化，某些版本对断流的容错更差，升级或降级前先看更新日志、行为异常先回旧版验证，流程见版本升级与回滚一篇；截至发稿版本，具体行为以官方更新日志为准。这一顺位的关键是沉住气：前两顺位没查完就急着归因服务端，往往会错过真正的本地病灶。

缩短单次任务：长任务的稳态跑法

排查之外，长任务的跑法本身值得调整。第一，任务粒度收窄：让 Codex 每次只完成一个可验收的小目标，跑完即停，人工确认后开下一段，单次连接的时长自然可控。第二，状态落盘：每段结束时把已完成的改动与下一步计划写进项目文件，下一段从文件续起，即便中断也不丢上下文。第三，断后处理有章法：报错先看是第几次、断在什么阶段，首断直接重试，反复断再按本文顺位排查；与本地网络相关的其他报错清单，见本地网络报错一篇。想让排查更快收敛，可以让 DeepSeek 把终端里断开前的完整日志整理成时间线，标出每次报错对应的任务时长，再用豆包对照本文清单生成一份逐项打勾的排查表，两步做完，断点位置八九不离十。

stream disconnected 排查顺序速查

• 报错含义：流式长连接在任务完成前被中途掐断
• 第一顺位查代理与防火墙：换热点验证，企业网高发
• 第二顺位查超时：短通长断、断点时刻固定是特征
• 第三顺位查服务端：状态页印证，别急着归因远端
• 止血手段：拆小任务、状态落盘、按段续跑

stream disconnected 怎么办速查

• 重试几次能自己好吗？：偶发一次多半是网络抖动，重试即可；反复在相近时长断开，说明链路里有稳定的掐点，重试只是重复撞墙，按代理、超时、服务端的顺位排查。
• 为什么短对话没事、长任务必断？：流式长连接要在中间设备面前长时间保持会话，空闲超时、连接时长上限、NAT 表项过期都会瞄准它；短连接几秒内完成，碰不到这些阈值。
• 断开后改到一半的代码会乱吗？：Codex 的改动以本地工作区为准，中断不会删除已落盘的修改；续跑前先看 diff 核对当前状态，再让任务从断点继续。