Codex 报错 stream disconnected before completion：config.toml 骨架与排查清单

1. 先搞清楚 stream disconnected before completion 到底在报什么stream disconnected before completion是 Codex 在流式对话里最常见的一类中断提示字面意思是「流还没传完连接就断了」。它跟普通的 401、404 不一样认证和路由大概率是通的否则请求根本进不到流式阶段。真正出问题的是「已经开始吐字但中途断了」。这个报错通常出现在三种场景。第一种是base_url拼错比如漏了/v1或者多打了一个/请求被网关当成非法路径返回一个非流式的错误页Codex 解析不了就判定流中断。第二种是超时设置太短模型还在思考客户端已经等不及把连接掐了。第三种是网络链路本身不稳定长连接被中间设备重置。适合读这篇的人正在用config.toml配置 Codex、接了自定义 API 通道、并且已经能看到报错但不知道从哪下手的人。下面我会给一份可直接复制的config.toml骨架再配一套从网络到超时的逐步验证动作帮你把「到底是哪一层断了」定位出来。先说结论这个报错九成不是模型的问题而是配置和链路的问题。把base_url、超时、流式开关这三处对齐大部分情况当场就能恢复。2. 用 TaoToken 统一 Key 和 API 通道做前置准备在动手改配置之前先把「请求往哪发、用什么身份发」这两件事固定下来否则后面排查会一直在变量里打转。我习惯用 TaoToken 做统一入口原因是它把 Key 和 API 通道收敛成一套Codex、其他 CLI 工具、脚本可以共用同一个地址排查时只需要盯一个变量。你需要准备两样东西一个可用的 API Key以及确认好要用的模型名。Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/api-keys 创建后复制保存后面填进config.toml。模型对话能力可以先在网页端验证确认 Key 和模型本身没问题再去配 Codex。模型对话入口https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果网页端能正常流式回复说明 Key 和通道是好的问题就锁定在 Codex 本地配置。API 的基础地址统一用 https://taotoken.net/api 注意这个地址后面拼路径时要接/v1也就是最终请求形如https://taotoken.net/api/v1/chat/completions。很多人漏掉/v1或者写成https://taotoken.net/api//v1这两种都会触发本篇的报错。提示先把 Key 和 base_url 写在一张便签上后面config.toml里只改这两个值其他保持骨架不动排查效率最高。3. 可复制的 config.toml 骨架Codex 的配置文件一般放在~/.codex/config.tomlWindows 在用户目录下的.codex\config.toml。下面这份骨架可以直接抄把api_key换成你自己的即可。核心是base_url必须带/v1且不能出现双斜杠。# ~/.codex/config.toml # Codex 基础配置骨架配合 TaoToken 统一通道使用 model gpt-4o model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api/v1 env_key TAOTOKEN_API_KEY wire_api chat # 流式与超时相关排查 stream disconnected 时重点看这里 [model_providers.taotoken.stream] enabled true [request] timeout_ms 120000 stream_idle_timeout_ms 60000几个参数逐个说明。base_url是重灾区正确写法是https://taotoken.net/api/v1结尾不要再加/。env_key表示 Key 从环境变量读取比明文写进文件更安全。wire_api chat走的是标准 chat completions 协议兼容性最好。timeout_ms是整体请求超时给到 120 秒比较稳。stream_idle_timeout_ms是流式空闲超时意思是「多久没收到新 token 就判定断了」设成 60 秒能避免模型思考稍久就被误杀。这两个值如果设得太小正是stream disconnected before completion的高发原因。Key 通过环境变量注入Linux/macOS 这样写export TAOTOKEN_API_KEYsk-你的KeyWindows PowerShell$env:TAOTOKEN_API_KEYsk-你的Key想让它永久生效Linux/macOS 写进~/.bashrc或~/.zshrcWindows 用系统环境变量面板添加。改完记得重开终端否则 Codex 读不到。4. 逐步验证请求是否真的通了配置写完别急着跑复杂任务先用最小请求验证链路。第一步确认环境变量真的被读到了echo $TAOTOKEN_API_KEY能打印出sk-开头的字符串就对了。如果为空说明环境变量没生效回到上一步检查。第二步直接用 curl 打一次非流式请求绕开 Codex 本身确认通道是通的curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: ping}], stream: false }如果这里返回正常的 JSON 补全结果说明 Key、base_url、模型名三者都对。如果这里就报错那问题不在 Codex而在配置或 Key 本身先解决这一步。第三步把stream改成true验证流式是否稳定curl -N https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 写一段100字的介绍}], stream: true }-N关闭 curl 缓冲你能看到 token 一段段吐出来。如果流能完整结束说明链路支持流式Codex 里的报错就只剩本地超时或配置问题。如果 curl 流式也中途断那就是网络链路或超时重点调stream_idle_timeout_ms。第四步回到 Codex 跑一次真实任务观察是否还报stream disconnected before completion。到这一步基本能定位到具体层。5. 本篇常见错误逐条排查下面这张表是我实际踩过的坑按出现频率排序对照着查最快。现象大概率原因处理动作一启动就报 stream disconnectedbase_url 漏了/v1改成https://taotoken.net/api/v1偶发中断重试能好流式空闲超时太短调大stream_idle_timeout_ms长回答必断短回答正常整体超时不够调大timeout_ms到 120000报错伴随 404base_url 出现双斜杠删掉多余的/环境变量读不到没重开终端重开或写进 shell 配置重点说两个高频坑。第一个是base_url结尾的斜杠。https://taotoken.net/api/v1/和https://taotoken.net/api/v1在有些客户端里会被拼成//chat/completions网关直接拒绝表现就是流中断。统一不带结尾斜杠。第二个是超时。Codex 默认超时往往偏短模型遇到长任务思考时间一长客户端就主动断开报错文案正是stream disconnected before completion。把timeout_ms和stream_idle_timeout_ms按骨架里的值设好这类误报会明显减少。如果 curl 流式测试也断那要怀疑网络链路。可以换一个网络环境再测一次确认是不是本地链路对长连接不友好。这一步能排除掉大部分「配置没问题但就是断」的情况。注意改完config.toml后Codex 需要重启才会重新读取配置。很多人改完直接重试其实跑的还是旧配置。6. 长期跑 Codex 编码任务时的接入建议如果你只是偶尔用 Codex 问几句上面这套配置够用了。但如果你打算把 Codex 当成日常编码和 Agent 任务的主力频繁的长会话、多轮工具调用会让流式稳定性变得更重要这时候建议把接入方式固定下来减少每次排查的成本。接入文档里有完整的参数说明和不同客户端的配置示例遇到骨架里没覆盖的字段可以对照查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。长期编码场景可以了解 Coding Plan它更适合高频、长会话的使用方式https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后留一个我自己的习惯把config.toml里base_url、timeout_ms、stream_idle_timeout_ms这三个值当成「排查三件套」一旦再遇到stream disconnected before completion先看这三个八成问题当场解决。配置这东西稳定比花哨重要骨架固定下来就别频繁动它。