解决 Stream Disconnected：Cockpit 反代与 Codex 桌面版连接中断排查指南

最近在折腾本地开发环境的时候，遇到了一个挺让人头疼的问题：使用 cockpit-tools 做反向代理中转流量，在配合 Codex 桌面版进行 AI 对话时，时不时就会蹦出一个报错——“stream disconnected before completion: stream closed before response.completed”。

不仅对话被打断，体验感极差，好不容易跑起来的长上下文推理也直接报废。如果你也遇到了这个问题，别慌，这大概率不是显卡炸了，而是代理层面的配置没对齐。今天咱们就把这个问题拆开揉碎了，聊聊怎么排查和解决。

一、 搞清楚“Stream”断在哪里？

首先，我们要理解这个错误的字面意思。它说的是“流在完成之前断开了”。在使用 AI 大模型（如 ChatGPT/Claude/Codex）的 SSE（Server-Sent Events）流式传输中，数据包是像水流一样一点点推过来的。

出现这个提示，说明数据流中间“断水”了。既然是通过 cockpit-tools 反代，那么嫌疑最大通常有两个环节：

1. 中间层超时： 也就是你的 cockpit-tools 或其底层的 Web 服务器（如 Nginx/Caddy）等太“没耐心”，认为服务器响应太慢或持续时间太长，主动切断了连接。
2. 协议不兼容： HTTP/1.1 与 HTTP/2 的差异，或者 SSE 相关的 Header 头部信息缺失，导致代理层不知道这是一个“长连接”，从而误杀了请求。

二、 逐步排查与解决方案

针对上述分析，我们可以按以下步骤进行“手术”式修复。

1. 检查并调整超时设置

这是最常见的坑。流式生成的特点就是响应时间不可控，可能持续一分钟甚至更久。默认的超时配置（通常只有 60 秒）显然是不够用的。

如果你是在配置文件中定义的代理规则，请务必关注以下几个参数（以常见配置为例）：

• proxy_read_timeout：这是主要嫌疑对象。必须将其设置得足够大。建议直接设置为 3600s（1小时） 或更高，确保长生成不被截断。
• proxy_connect_timeout 和 proxy_send_timeout：虽然主要影响握手和发送阶段，但为了稳妥，建议也适当放宽，例如设置在 60s 到 120s 之间。

image1264×718 31.8 KB

修改参考思路： 找到 cockpit-tools 的代理配置区域，将类似 timeout: 60s 的值改为 timeout: 0（无限）或一个极大值。

2. SSE 专用 Header 头部补全

SSE 流式连接需要特定的 HTTP 响应头来告知客户端“别断开，后面还有数据”。如果反向代理过滤掉了某些 Header，或者没有正确透传，客户端就会误以为传输结束。

务必确保你的反向代理配置中保留了以下关键 Header，并允许其透传给 Codex 客户端：

• Content-Type: text/event-stream：这是核心，标识这是一个事件流。
• Cache-Control: no-cache：防止任何中间节点缓存流数据，导致客户端读旧数据或卡顿。
• Connection: keep-alive：保持长连接的关键。
• X-Accel-Buffering: no：如果是 Nginx 类环境，这条指令至关重要，它关闭了 Nginx 的缓冲，让数据实时到达客户端，而不是等攒够了一坨再发。

3. 禁用 Body 缓冲

很多代理组件为了“性能”会尝试缓冲整个响应体再发出去，这对于 SSE 这种场景是毁灭性的。

在 cockpit-tools 的配置中，寻找关于 “Buffer”（缓冲）的选项。如果有 proxy_buffering 之类的开关，请将其关闭。这能确保生成的每一个 token 都第一时间推送到桌面端，而不是被代理软件“扣留”在内存里。

三、 终极排查思路

如果改了超时和 Header 还是不行，那就得用排除法了：

• 直连测试： 绕过 cockpit-tools，直接让 Codex 连接后端服务。如果直连流畅，那锅绝对是代理的。
• 抓包分析： 使用 Wireshark 或浏览器开发者工具，观察断开那一瞬间是谁发的 FIN 包。如果是代理服务器 IP 发的，说明是代理主动断开的；如果是服务端 IP 发的，可能是 API 端不稳定（不过概率较低，既然报错提示是代理相关的问题）。

四、 总结

遇到 “stream disconnected before completion” 别慌，核心就是**“时间给够，缓冲关掉，Header 透传”**。

绝大多数情况下，把代理的读取超时拉长，并关闭代理缓冲，问题就能迎刃而解。希望这篇笔记能帮你省下几个小时的排错时间，让 AI 助手安安静静地把代码写完！

如果你在尝试以上方法后依然无法解决，欢迎在评论区分享你的具体配置细节，大家一块儿看看哪里还有遗漏。