所有文章
CodexOpenAI报错修复

Codex 报 stream disconnected before completion 怎么办?4 种报错尾巴,5 个办法(0.167.0 实测)

Codex 的 stream disconnected before completion 只说明数据流在 response.completed 之前断了,真正的原因要看报错尾巴。我们在 Codex CLI 0.167.0 上用本地模拟服务端复现了其中两种和 WebSocket 回退,其余对照官方配置文档和 GitHub issue。

Codex 数据流提前断开:浅蓝色黏土管道中间断开一道缝,米色黏土珠子沿管道滚动,最后一颗停在一面小旗前,柔和自然光和树叶影子

Codex 里的「stream disconnected before completion」只说明一件事:回答还没传完,数据流就断了,Codex 没等到结束标记 response.completed。后面的原因要看这条报错尾巴写了什么:stream closed before response.completed、idle timeout waiting for SSE、websocket closed by server、Transport error 是四种不同的情况,处理办法也不一样。我们在 Codex CLI 0.167.0 上用本地模拟的 Responses 服务端复现了前两种,WebSocket 回退也实测了;其余几种来自官方配置文档和 GitHub issue,文中逐条标了出处。下面按报错尾巴分类,再讲每种怎么处理。

这条报错是什么意思

Codex 向模型服务发请求,服务端用流式方式(SSE 或 WebSocket)一段一段把回答推回来,最后会发一个 response.completed 事件,表示这一轮结束。流在这个事件之前断了,Codex 就报 stream disconnected before completion,然后自动重连。终端里能看到 Reconnecting... 1/5,默认最多重试 5 次,5 次都不行才真正失败。这个重试次数在官方 配置参考里是 stream_max_retries,默认值 5。

所以看到 Reconnecting... 2/5 先别急着改配置:网络抖一下、服务端掐了一次连接,下一次重连多半就好了。只有 5/5 之后仍然失败,才需要往下查。

看报错尾巴,对号入座

Codex 流式报错五种常见尾巴对照表:stream closed before response.completed、idle timeout waiting for SSE、websocket closed by server、Transport error、error sending request,各自含义和先试什么

几条补充:

  • stream closed before response.completed:服务端把连接正常关了,但没发结束事件。用官方 OpenAI 登录时较少见;用第三方中转或自建网关(自定义 provider)时最常见,GitHub 上的 #41340 和 #41989 都是这种。#41340 的作者用 curl 直连中转站,响应是完整的、带 response.completed,只有 Codex 报错,所以也不一定是网关的锅,这个 issue 在我们查的时候还开着。
  • idle timeout waiting for SSE:服务端一直没发新数据,超过 stream_idle_timeout_ms(官方文档默认 300000 毫秒,也就是 5 分钟)。
  • websocket closed by server before response.completed 和 idle timeout waiting for websocket:走的是 WebSocket 通道,见 issue #20739、#30933、#38638。
  • Transport error: error decoding response body:连接在响应体传到一半时被切断。#3835 里有人查到,问题出在他自己转发 LLM 请求的服务端:SSE 停了大约 10 秒没发心跳,服务端就给 Codex 的 HTTP 客户端发了 FIN。
  • error sending request for url (…/responses):请求没发出去或被中途掐断。#20844 里有人用 SOCKS5 代理(环境变量 ALL_PROXY 之类)时 Codex 不稳定,改成 HTTP 代理(HTTP_PROXY / HTTPS_PROXY)就好了。这是 issue 里的报告,我们没有复测。

5 种处理办法

1. 先等重试,再换个时间发一次

前几次重连只说明连接断过。5/5 之后还失败,就在 Codex 里重发上一句,或者用 codex resume 找回刚才的会话继续。要提醒的是,Codex 的重连发生在同一轮里,中断(esc)后这一轮的状态可能不确定,issue #30933 的作者专门提了这个问题。

2. 用 codex doctor 看 provider 地址通不通

0.167.0 带了 codex doctor。我们把 provider 的 base_url 指向一个没人监听的端口,它在 reachability 一栏报 ✗:one or more required provider endpoints are unreachable over HTTP,建议检查代理、VPN、防火墙、DNS 和自定义 CA,并在对应行写出 connect failed。地址是通的时,它会显示 reachable。先排除这一层,再往下看。

3. 第三方 provider:确认服务端真的发了 response.completed

自定义 provider 要走 Responses 协议(wire_api = "responses",官方文档里目前也只支持这一个值)。用 curl 直接请求中转站的 /responses 并加上流式参数,看最后有没有 response.completed。如果没有,是中转站要改;如果有,Codex 还是报错,就像 #41340 那样,换个 Codex 版本试,并到 issue 里补充你的版本和 provider。另外,中间一旦有网关缓冲或在空闲时掐连接,也会出现 idle timeout 或 Transport error,#3835 就是这个原因。

4. 调大空闲超时和重试次数(仅限自定义 provider)

[model_providers.my-gateway]
name = "my-gateway"
base_url = "https://example.com/v1"
env_key = "MY_GATEWAY_KEY"
wire_api = "responses"
stream_idle_timeout_ms = 600000
stream_max_retries = 8

官方参考里这两个键的默认值分别是 300000 和 5。我们测试时把超时设成 3000,Codex 在约 3 秒后报 idle timeout waiting for SSE;把重试设成 2,终端只出现 1/2、2/2,说明这两个键是实际生效的。不过它们只管自定义 provider,内置的 openai provider 不能这样覆盖(官方说明:openai、ollama、lmstudio 是保留 ID)。

5. 出现 Reconnecting... 1/5 到 5/5 但最后能成功:关掉 WebSocket

默认 provider 会先试 WebSocket,连不上或被代理拦住时,每次失败都算一次重连,5 次用完才回退到 HTTPS。我们用一个不支持 WebSocket 的模拟服务端测了:supports_websockets = true 时,终端打出 2/5 到 5/5,最后出现 Falling back from WebSockets to HTTPS transport,整条命令用了约 8 秒;改成 false 后直接走 HTTPS,约 1.4 秒。真实环境里 issue #22634 的作者在 Windows 上测到每次要多等约 75 秒,原因是每次 WebSocket 尝试 15 秒超时,乘以 5 次;#19821 也说这种情况在使用代理的用户里很常见。

issue #13103 和 #22634 里的做法是新建一个只走 HTTPS 的自定义 provider,沿用 ChatGPT 登录:

model_provider = "openai_http"

[model_providers.openai_http]
name = "OpenAI HTTP only"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false
base_url = "https://chatgpt.com/backend-api/codex"

说明几点:这是 issue 评论里的社区做法,不是官方文档推荐;有人在 #13103 里提醒这个 provider 可能没有完整继承官方 provider 的全部功能;官方的 responses_websockets 开关在 0.167.0 里状态是 removed(我们跑 codex features list 看到的),不能再用 features 关闭。我们验证了 0.167.0 能读这份配置,并且请求会发往那个 HTTPS 地址(没登录,返回 401);没有用真实 ChatGPT 账号完整跑一轮。

我们实测了什么,哪些来自文档

我们在 Linux 上安装了 Codex CLI 0.167.0,用 Python 写了一个本地模拟的 Responses 服务端,通过自定义 provider 让 codex exec 连上它,让服务端分别「正常结束」「发出第一个字就关连接」「发出第一个字就不再发数据」。

Codex 0.167.0 对模拟服务端的终端输出:Reconnecting 1/5 到 5/5、stream closed before response.completed、idle timeout waiting for SSE、WebSocket 回退 HTTPS

这个测试能说明报错在什么条件下出现、重试和超时的配置是否生效;说明不了真实服务(OpenAI 或中转站)为什么断流,也没覆盖 Windows、macOS、代理和真实的 WebSocket 掉线。

Codex provider 里控制流式重试的配置:stream_max_retries 默认 5,stream_idle_timeout_ms 默认 300000,request_max_retries 默认 4,supports_websockets,log_dir,以及哪些我们测过
  • 实测:stream closed before response.completed、idle timeout waiting for SSE、Reconnecting n/N 的次数、WebSocket 回退、codex doctor 的可达性提示、features list 里的 removed。
  • 来自文档或 issue,没有复测:各配置项默认值、WebSocket 相关的真实掉线、SOCKS5 代理问题、中转站的具体行为。
  • 来源:Codex Configuration Reference,以及 GitHub 上 openai/codex 的 issue #3835、#13103、#19821、#20739、#20844、#22634、#30933、#38638、#41340、#41989。资料查询日期 2026 年 11 月 10 日。

想看 Codex 其他报错,可以看OpenAI Codex 报错速查。登录阶段的问题见Codex token exchange failed 403和localhost 拒绝连接。模型繁忙的另一种提示见Selected model is at capacity。额度问题见Claude / Codex 额度重置追踪。

常见问题

stream disconnected before completion 是账号被限制了吗?

不是。额度或限流通常会有明确的提示,这条报错只说明数据流在结束前断了,没有提到账号。

为什么会一直 Reconnecting 1/5 到 5/5?

5 是 stream_max_retries 的默认值。每断一次,Codex 重连一次,用完才报最终错误。走 WebSocket 时,每次失败也算一次,最后才回退 HTTPS。

是 Codex 的 bug 还是我的网络问题?

看尾巴。connect failed、SOCKS5 代理、WebSocket 被拦,多半是网络;自定义 provider 下 curl 正常、Codex 报错,更像客户端或版本问题,issue #41340 和 #41989 就是这类,我们查的时候都还开着。

官方 OpenAI 登录也会遇到吗?

会。#20739 和 #30933 的作者用的是官方 provider 加 WebSocket,遇到了 websocket closed by server before response.completed。

怎么看更详细的日志?

官方参考里 log_dir 默认是 $CODEX_HOME/log,显式设置后还会写一份明文 TUI 日志 codex-tui.log。贴 issue 时记得去掉里面的令牌和路径。

留下你的想法

你的邮箱不会公开。