1. 从一次深夜调试说起Reconnecting 到底卡在哪一环凌晨一点半终端里那行Reconnecting...已经刷了十几遍紧接着就是stream disconnected before completion: stream closed before response.completed。如果你正在用 codex 这类基于流式响应的命令行工具这个画面大概率不陌生。它不像普通的报错那样干脆利落而是先给你一点希望——重连中然后啪一下把连接掐断留下一个半截的响应和满屏的疑惑。这个问题的本质是客户端与服务端之间的流式连接在响应完成之前被中断了。codex 的工作模式是发起一个请求服务端以 SSEServer-Sent Events的方式持续推送数据块客户端边接收边渲染。只要这个流在中途断掉无论是网络抖动、代理层超时、服务端过载还是认证令牌失效都会表现为stream disconnected before completion。而Reconnecting是客户端的自动重试机制在起作用它试图重新建立连接但如果根因没解决重连只会无限循环。我写这篇东西的目的很直接把这类报错按根因分类拆开给出每一类的判断依据和可落地的处理办法。适合正在被 codex 连接问题折磨的开发者也适合任何在用流式 API 的工具比如某些 AI 编程助手、SSE 长连接客户端时遇到类似断流的人。下面这些内容是我在实际排查中反复验证过的不是照搬文档而是踩坑之后总结出来的路径。需要先明确一点stream closed before response.completed和stream disconnected before completion经常一起出现前者偏向服务端主动关闭后者偏向传输层中断。区分这两个语义是定位问题的第一步。2. 先分清报错语义几种 stream 断流信息的差异很多人一看到报错就去改配置结果改了半天发现方向错了。原因在于 codex 的报错信息其实携带了相当多的线索只是被Reconnecting的刷屏掩盖了。我习惯先把完整报错抓下来逐条对照。2.1 报错文本与真实含义对照报错片段大致含义优先排查方向stream closed before response.completed服务端在响应未完成时关闭了流服务端过载、请求超时、模型不支持stream disconnected before completion: transport error传输层出错连接被中断本地网络、代理层、DNSidle timeout waiting for sseSSE 长时间没有数据推送触发空闲超时代理超时设置、服务端卡住connection refused (os error 61)连接被拒绝端口没人监听本地代理未启动、端口写错由于目标计算机积极拒绝无法连接同上Windows 下的中文表述本地服务未运行our servers are currently overloaded服务端明确告知过载错峰重试、降低并发the gpt-5.6-sol model is not supported模型名不被当前 codex 版本支持模型配置、版本匹配auth token is unavailable认证令牌缺失或过期重新登录、检查凭证存储这张表是我自己整理的每次遇到新报错就往里加一行。它的价值在于把模糊的连不上变成具体的哪一层断了。比如connection refused和transport error看起来都是连不上但前者几乎一定是本地代理或端口问题后者才可能是网络链路问题。2.2 为什么 Reconnecting 会掩盖真正的错误codex 的重连逻辑是先重试再报错。当流断开时它不会立刻把底层异常抛给你而是先尝试重新建立连接。这个设计本身是合理的——网络抖动导致的短暂断流重连一次就好了。但问题在于当根因是配置错误或认证失效时重连永远不会成功于是你看到的就是无限循环的Reconnecting真正的错误信息被淹没在重试日志里。我的做法是先把日志级别调高或者用--verbose之类的参数让底层错误完整输出。如果工具本身不支持就用抓包或代理日志来看真实的请求响应。这一步很关键否则你就是在盲猜。提示遇到无限 Reconnecting 时第一件事不是改配置而是想办法让底层错误暴露出来。看不到真实错误所有修改都是碰运气。3. 网络链路层代理、端口与本地回环的那些坑流式连接对网络链路的要求比普通请求高得多。普通 HTTP 请求发出去、收回来就结束了而 SSE 需要一条长时间保持的连接中间任何一环超时或重置都会导致断流。这一层的问题占了实际案例的一大半。3.1 本地代理未启动或端口不匹配connection refused (os error 61)和中文的由于目标计算机积极拒绝无法连接是同一类问题客户端试图连接某个本地端口但那个端口上没有服务在监听。在 codex 的使用场景里这通常意味着你配置了一个本地代理比如某些转发工具但代理进程没起来或者端口号和配置里写的不一致。排查步骤很直接确认代理进程是否在运行。用ps aux | grep 进程名Linux/macOS或任务管理器Windows看一眼。确认监听端口。netstat -an | grep 端口或lsof -i :端口看有没有进程在 LISTEN。确认 codex 配置里的端口和实际监听端口一致。这一步最容易出错因为配置文件可能有多处涉及端口。我踩过的一个坑是代理配置里写的是127.0.0.1:8080但实际代理监听在0.0.0.0:8080理论上应该能通结果因为某些系统的 IPv6 优先解析客户端去连了::1:8080而代理只监听了 IPv4于是连接被拒。解决办法是把地址明确写成127.0.0.1而不是localhost强制走 IPv4。3.2 代理层的超时设置与 SSE 的冲突这是最隐蔽的一类问题。很多代理工具默认有一个空闲超时比如 30 秒或 60 秒内没有数据传输就断开连接。对于普通请求这没问题但 SSE 流在模型思考期间可能长时间没有数据块推送代理就误以为连接空闲直接掐断于是你看到idle timeout waiting for sse。处理办法是调整代理的超时参数。不同工具参数名不一样但核心是两类读超时read timeout调大到 300 秒甚至更长。空闲超时idle timeout如果工具支持直接设为 0 或禁用。以常见的反向代理配置为例思路是这样的# 反向代理场景下的关键参数 proxy_read_timeout 300s; proxy_send_timeout 300s; proxy_buffering off; # 关闭缓冲让 SSE 数据实时透传 proxy_cache off;proxy_buffering off这一条特别重要。如果代理开启了缓冲它会等数据攒够一块再转发SSE 的实时性就没了而且容易触发超时。关掉缓冲数据块才能即时到达客户端。3.3 DNS 解析与网络抖动transport error: network error这类报错往往指向 DNS 解析失败或链路抖动。判断方法很简单用ping或curl直接测试目标域名看是否能稳定解析和连接。如果 DNS 不稳定可以换一个可靠的解析方式或者在本地 hosts 里固定解析结果前提是目标 IP 相对稳定。网络抖动导致的断流有个特征重连有时能成功有时失败呈现随机性。如果每次都在固定位置断那更可能是配置或服务端问题而不是网络抖动。4. 认证与配置层token、模型名与版本匹配网络通了不代表就能跑起来。认证和配置层面的问题往往表现为连接建立了但立刻被关闭报错可能是auth token is unavailable也可能是stream closed before response.completed。4.1 认证令牌失效的几种表现codex auth token is unavailable是最直白的认证报错但认证问题不一定都这么明显。有时候令牌过期了客户端仍然带着旧令牌发起请求服务端在流开始后才发现无效于是关闭连接你看到的就是stream closed before response.completed。处理认证问题的顺序重新执行登录流程确保拿到新的令牌。检查令牌的存储位置和读取权限。有些工具把令牌存在配置目录下如果权限不对或文件损坏读取会失败。确认令牌没有过期。如果工具有查看令牌状态的命令先用它确认。我遇到过一次诡异的情况令牌文件存在内容也对但工具读取的是另一个路径下的旧文件。原因是环境变量里配置了一个自定义的配置目录而登录时写入的是默认目录。这种写读路径不一致的问题只能通过打印实际使用的配置路径来定位。4.2 模型名不被支持版本与配置的错配the gpt-5.6-sol model is not supported when using codex with a...这类报错说明你配置的模型名和当前 codex 版本不匹配。可能的原因有几个模型名拼写错误或者用了服务端不认识的别名。codex 版本太旧不支持新模型。配置里指定的模型和实际可用的模型列表不一致。解决办法是先确认当前版本支持的模型列表然后对照配置修改。如果工具支持列出可用模型直接用它来核对。版本太旧的话升级到最新版通常能解决。4.3 配置文件的多处冲突codex 的配置可能分散在多个地方全局配置、项目级配置、环境变量、命令行参数。当这些来源的值冲突时实际生效的往往不是你预期的那个。比如全局配置里写了模型 A项目配置里写了模型 B命令行又传了模型 C最终用哪个取决于优先级规则。我的建议是排查阶段只保留一处配置把其他来源的值清空或注释掉确认能跑通之后再逐步加回来。这样能快速定位是哪个来源在捣乱。5. 服务端侧过载、限流与请求本身的问题排除了本地网络和配置剩下的就是服务端侧的原因。这类问题的特征是你的配置没变之前能跑突然就不行了或者高峰期必挂低峰期正常。5.1 服务端过载与限流our servers are currently overloaded. please try again later.是服务端明确告诉你它扛不住了。这种情况下客户端做什么都没用只能等或者错峰。但有几个技巧可以缓解降低并发如果你同时开了多个请求减少到单个降低服务端压力。错峰使用避开使用高峰通常深夜和清晨相对空闲。增加重试间隔默认的重连间隔可能太短导致刚断开就重连反而加重服务端负担。适当调大间隔给服务端喘息时间。5.2 请求体过大或格式问题an error occurred while processing your request这类报错可能是请求体本身有问题。比如上下文太长超出了模型限制或者请求格式不符合服务端预期。排查方法是用一个最小的、最简单的请求测试如果最小请求能通说明是请求内容的问题如果最小请求也不通说明是链路或配置问题。这个最小请求法是我排查问题的常用手段它能快速把问题范围缩小到请求内容还是环境。5.3 流式响应的中途失败有时候连接建立成功流也开始推送了推到一半突然断掉。这种情况可能是服务端在处理过程中遇到了内部错误也可能是某个数据块太大导致传输中断。如果是前者重试通常能成功如果是后者可能需要调整客户端的分块处理逻辑。判断依据是断流的位置是否固定。如果每次都在差不多的位置断偏向数据或处理逻辑问题如果位置随机偏向网络或服务端负载问题。6. 一套可复用的排查流程上面把各类原因拆开讲了但实际排查时不可能一条条试。我总结了一套从外到内的流程按这个顺序走大部分问题能在十分钟内定位。6.1 第一步确认底层错误不要被Reconnecting迷惑先想办法看到真实的底层报错。方法包括提高日志级别、查看代理日志、用抓包工具观察实际请求。拿到真实错误后对照第 2 节的表格确定问题层级。6.2 第二步分层验证按网络层 → 认证层 → 配置层 → 服务端层的顺序验证网络层curl或ping目标地址确认能连通。检查本地代理是否运行、端口是否匹配。认证层确认令牌有效、路径正确、没有过期。配置层确认模型名、版本、配置来源没有冲突。服务端层用最小请求测试确认服务端是否正常响应。每一层验证通过后再进入下一层避免同时改多个地方导致问题定位困难。6.3 第三步最小化复现如果问题依然存在构造一个最小复现环境最简配置、最小请求、单一网络路径。在这个环境里如果能复现问题就锁定在最小配置涉及的范围内如果不能复现说明是某个被移除的配置项导致的逐步加回来定位。6.4 第四步记录与固化问题解决后把根因、处理办法、涉及的配置项记录下来。我习惯在项目里放一个troubleshooting.md每次遇到新问题就追加一条。下次再遇到类似报错直接查记录不用重新排查。7. 几个容易被忽略的细节与实操心得排查过程中有些细节很容易被忽略但往往是问题的关键。这里分享几个我实际踩过的坑。7.1 Windows 下的路径与权限问题codex windows安装未完成这类问题很多时候是路径里有空格或中文导致安装脚本解析失败。解决办法是把安装目录换成纯英文、无空格的路径。另外Windows 下某些目录需要管理员权限才能写入如果安装或配置写入失败检查一下权限。7.2 环境变量的优先级陷阱环境变量里的配置往往优先级最高而且容易被遗忘。排查时用env | grep -i codex之类的命令看一眼确认没有残留的旧配置在捣乱。我就遇到过环境变量里写着一个早已废弃的代理地址导致所有请求都往那个地址发自然连不上。7.3 版本升级后的配置兼容性升级 codex 之后旧配置可能不再兼容。比如某个参数名变了或者默认值改了。升级后如果突然出问题先检查配置是否需要迁移。很多工具会在升级时提示配置变更但如果你跳过了提示就容易踩坑。7.4 重连间隔的合理设置默认的重连间隔通常比较激进比如 1 秒一次。在服务端过载的情况下这么频繁的重连反而有害。我一般会把间隔调到 5 到 10 秒并设置最大重试次数避免无限重连。如果工具支持指数退避每次重连间隔翻倍那就更好了。7.5 日志的保存与分析Reconnecting刷屏的时候终端里的日志很快就被冲掉了。建议把日志重定向到文件方便事后分析。命令大概是这样的codex 你的命令 21 | tee codex-debug.log保存下来之后用grep过滤关键错误比在终端里翻找高效得多。8. 关于这类流式连接问题的个人体会流式连接的问题本质上比普通请求复杂因为它多了一个时间维度——连接要维持一段时间这段时间里任何环节出问题都会导致断流。所以排查时不能只看能不能连上还要看能连多久中途有没有断。我个人的经验是大部分stream disconnected before completion最终都落在三个地方代理超时、认证失效、服务端过载。把这三个方向排查清楚八成的问题都能解决。剩下的两成往往是配置冲突或版本不匹配这类需要耐心比对的问题。还有一点值得强调不要迷信重装。很多人一遇到问题就重装工具但如果是配置或网络问题重装根本没用反而浪费 time。先定位根因再动手这是我一直坚持的原则。最后分享一个小习惯每次成功跑通一个配置后把当时的完整配置和版本号备份一份。下次出问题时对比当前配置和备份配置的差异往往能一眼看出是哪里改了导致的。这个习惯帮我省下了大量排查时间。