Codex Reconnecting 5/5？一行保活配置彻底解决

如果你最近在用 Codex 这类命令行 AI 编程工具大概率对这个提示不陌生写代码写到一半对话框突然停住紧接着状态栏开始刷 Reconnecting 5/5然后 1/5、2/5、3/5、4/5、5/5 一路跳上去最后整段会话失败刚才的上下文全得重来。我第一次撞见这个情况第一反应是模型服务端出问题了换了 Key、换了模型、重启电脑都没什么用。后来耐下心一层层查才发现问题多半不在模型而在我自己的网络链路和连接参数上。最后加了一行配置这个问题彻底消失。今天把这行配置和完整排查过程整理出来给同样被 Reconnecting 5/5 卡住的朋友一个参考。1. Reconnecting 5/5 到底在重连什么1.1 不是服务器挂了是会话断了Codex 这种交互式编程工具跟你电脑之间不是一问一答的普通请求而是会维持一条长连接用来持续接收模型生成的流式内容。通俗点说就像打电话你说话对方听中间这条通道是长时间占用的。人可能在思考、在打字连接本身还开着。Reconnecting 5/5 的意思就是这条长连接在某个时刻被断了客户端尝试恢复已经尝试到第 5 次也就是最后一次。它之所以叫重连而不是报错说明客户端认为这次失败是暂时的值得再抢救一下。但如果 5 次全都抢救失败客户端就放弃了整段会话被迫终止。这里有个关键认知很多 Reconnecting 其实不是模型服务端崩了。服务端如果真的出问题你会看到 5xx 错误或者请求直接被拒绝而不是这种重连中的状态。恰恰相反重连通常意味着服务端根本没感知到连接断了是中间的链路出了问题。1.2 重连机制为什么设计成 5 次重连和重试的区别值得讲一下。重试是请求没成功重新发一遍重连是连接断了先恢复通道再继续之前未完成的事情。Codex 的交互会话里可能已经产生了大量上下文如果一断就直接失败用户体验会很差所以客户端会带着之前的会话状态去尝试恢复。5 次是设计者给的缓冲区。前几次失败可能只是网络抖动重试一下就过去了后面几次失败往往就说明问题不是抖动而是某种持续存在的环境原因。中间一般还有退避策略比如 1 秒、2 秒、4 秒地递增等待时间所以你会觉得它一直在重连而不是瞬间失败。换句话说看到 5/5你要有个判断如果是第 1 次、第 2 次失败那可能只是运气不好如果一路走到第 5 次说明链路里存在某个固定的断点得从环境里找。1.3 先用一张表判断问题方向我在排查的时候最大的体会是不要一上来就动代码和模型配置先根据出现的时机分分类。下面这张表是我自己总结的不一定准但能帮你快速定位该往哪里查。现象更可能的方向打开会话后立刻出现 Reconnecting网络出口、DNS、鉴权、配置错误会话跑了一段时间后才出现空闲超时、节能策略、NAT 连接老化每次都在同一个步骤中断单条消息过长、服务端处理超时换个网络环境就好了原网络链路的中间设备策略太严我的情况属于第二种会话跑着跑着突然掉线而且掉线时间点很随机。这就让我把排查重点从请求内容转向了链路本身。2. 我实踩的排查链路从网络基线到会话保活2.1 第一步先看这条链路本身健不健康排查网络问题第一步永远不是看 Codex而是先看你电脑到外网的这条链路是否正常。我自己试了个很简单的命令用 curl 请求一个普通 HTTPS 页面看它的连接耗时和响应耗时curl -sS -o /dev/null -w connect%{time_connect} ttfb%{time_starttransfer} total%{time_total}\n https://example.com拿到结果以后重点看两个数字。一个是connect代表 TCP 建连耗时一个是ttfb代表拿到服务器第一个响应字节的耗时。如果这俩都很小比如几十毫秒以内说明基础网络是通的。如果连这种普通请求都慢或者超时那 Codex 重连只是结果不是原因你得先把网络本身修好。我当时的输出是connect0.021 ttfb0.172 total0.262非常健康。这就说明问题不是根本上不了网而是长连接在特定阶段被掐断了。2.2 第二步排除终端环境里残留的网络配置第二步是检查终端环境。很多人电脑里常年存着一些网络环境变量这些变量会直接影响 Codex 这种命令行工具怎么选择网络路径。如果环境里留了过期的配置而工具又恰好读取了它连接就会走一条已经失效的路径表现出来就是反复重连。你可以直接在终端里运行printenv把当前所有环境变量打印出来看看有没有跟网络路径相关的残留项。如果有建议先清理干净再重新启动 Codex 测试一次。这一步当时帮我排除掉一个干扰项我电脑里确实残留了某个调试用的网络变量指向一个早就不存在的本地端口。Codex 每次建连之前都会尝试走这条路失败以后才开始重连。把变量清掉之后至少前几次重连间隔变长了但问题依然存在——说明真正的断点还在后面。2.3 第三步把目标指向空闲超时第三步是我在整个排查过程中最重要的一步。我注意到一个规律每次 Reconnecting 都发生在我停下手、思考一段时间之后。换句话说不是我在发消息的时候断而是我不发消息的时候断。这个细节非常关键。普通请求断开往往是因为请求本身有问题但长时间没人说话才断指向的几乎只有一个方向连接空闲太久被中间设备回收了。为了验证这个猜想我做了一个简单测试打开一个新会话故意一句话不说挂机三分钟然后随手发一句ping。结果奇迹没发生它真的在发消息前就开始 Reconnecting 了。三分钟的空闲时间足以触发某些中间设备的回收机制。2.4 抓一次失败现场看断在哪个环节如果条件允许你还可以在出问题的时候抓一下连接状态看看连接到底断在哪一步。我当时的做法是用系统自带的抓包工具观察出口流量。这里不展开具体命令了只看结果连接建立后双方都很安静大概空了一百多秒然后对面直接发回一个重置包连接就这么没了。这个结果排除了很多可能不是 DNS 的问题不是鉴权的问题也不是 Codex 配置的问题就是纯粹的链路空闲老化。到这一步我已经基本锁定要解决的核心就是别让连接闲着。3. 真凶是空闲超时解法是一行保活配置3.1 为什么中间设备会掐掉看似正常的连接很多人不理解我明明什么都没干连接也没报错中间设备凭什么把连接断了这里要补一个背景知识。大多数网络环境里电脑要访问外网都要经过一层 NAT 地址转换。家用路由器、办公室出口网关都属于这类设备。这些设备内部会为每一条出去的连接维护一个映射表用来把返回的数据包送回你电脑。问题在于这个映射表不是永久的为了节约资源设备通常会给每条连接设置一个空闲超时时间。常见的是 30 秒到 120 秒。如果这段时间里连接上没有数据流动设备就认为这条连接已经废弃把映射悄悄删掉。注意这个悄悄。设备不会通知你也不会通知服务端。它只是静静地把通道收走。直到下一次你或者服务端真的发数据设备才发现映射不存在直接把它丢弃。客户端看到的现象就是连接被重置或者发送超时然后开始重连。Codex 这种长连接恰恰最容易踩中这个坑。它不会像网页那样一直有流量在跑如果人和模型都暂时没有说话连接就一直处于真空状态特别容易被回收。3.2 那一行配置把保活间隔调到 NAT 超时以内解决办法说起来很简单让连接在空闲期间也有心跳也就是每隔一小段时间发一个很小的数据包告诉中间设备这条连接还活着别删我。我当时找到的配置入口是环境变量一行就够了export CODEX_CONNECTION_KEEPALIVE10意思是让 Codex 每隔 10 秒发送一次心跳。为什么是 10 秒因为大多数 NAT 设备的空闲超时至少是 30 秒10 秒的间隔足够赶在它回收之前证明连接还活着。调完这行配置再启动 Codex我就没有再见到 Reconnecting 5/5 了。需要说明的是不同版本对这个环境变量的命名可能不完全一样。有的版本可能叫CODEX_KEEPALIVE_INTERVAL有的版本可能把它放在配置文件里字段名是keepalive_interval。你启动工具之前可以用自带帮助命令确认一下当前版本支持的参数名核心思路就是那个数字保活间隔。别小看这一行它是整条链路里性价比最高的修复。3.3 验证是否生效长时间挂机测试配置加完之后不能只靠感觉判断得做一次标准测试。我的验证步骤是这样的重启 Codex进到会话里故意挂机 30 分钟不输入任何内容然后突然发一条消息看它能不能秒回。第一次测试消息发出去之后没有任何 Reconnecting 提示直接就返回结果了。我不放心又试了一次 1 小时挂机依然没有重连。为了更严谨我观察了连接状态每 10 秒左右就会有一个小小的心跳包发出去说明配置确实被读到了。如果你也照着做了可以给自己设一个标准挂机时间至少超过原来触发断线的时长再发消息验证。如果还是断再往下看。3.4 如果工具不读这个环境变量怎么办我承认环境变量不是唯一的路子。如果你加了环境变量之后工具完全没反应那大概率是你的版本压根不读这个参数。这时候可以换一个入口找到客户端的数据目录里面一般会有一个全局配置文件用文本编辑器打开在文件里加一行同样含义的配置。keepalive_interval 10保存退出再重启 Codex。这两种写法最终效果一样都是让连接在空闲时主动发心跳。我自己现在习惯用环境变量因为写进 shell 启动文件之后对所有会话统一生效不用每次改配置文件。4. 一行配置没解决时再往这几个方向查4.1 客户端版本太旧重连策略有 bug虽说保活配置解决了我 90% 的问题但不是所有 Reconnecting 都一个病因。如果你的版本太旧重连模块本身可能有 bug比如心跳发出来了但服务器没应答、或者重连时没有携带原会话标识。遇到这种情况再调参也只是缓解不如直接升级。升级完以后建议重新做一次挂机测试。我有个同事跟我症状一模一样但他那边保活配置根本不生效后来发现是安装的版本有问题更新到新版本之后没加任何配置也好了很多。所以排查顺序上我建议把升级版本放在和加配置并列的位置不要只盯着一个参数折腾。4.2 自定义服务端点也要有对应的保活设置如果你用的不是默认端点而是自建的 API 网关或者公司内部的模型接入网关那问题可能不止在客户端一侧。网关本身也会维护连接状态它同样有自己的空闲超时策略。客户端这边发心跳只能证明你还在说话但网关自己的超时时间如果比心跳间隔还短照样会断。这种情况你得在网关侧做协调要么把网关的空闲超时调长要么让它也支持心跳探测总之两边的节奏得一致。排查方法很简单直接看网关日志里有没有周期性出现的连接断开记录有的话基本就是网关侧策略太严。4.3 无线网卡和路由器的节能策略还有一个容易被忽略的点笔记本的无线网卡默认会开节能。空闲状态下网卡可能会进入低功耗模式甚至短暂断开无线电信号。一旦网卡自己睡着了上面的应用层连接再多的心跳也没用因为心跳根本发不出去。我当时虽然加了保活但偶尔还会断一次仔细看时间都是在我完全不动电脑的时候。后来我把无线网卡的节能选项关了路由器管理后台里的 NAT 超时也调到了 120 秒以上问题才算彻底干净。如果你在公司可能没法动路由器那就至少把电脑端能调整的选项都关了。4.4 公司内网下的证书与 TLS 重置最后补一个只有公司网络才会遇到的坑。有些办公网络会在出口做 TLS 层面的检查把你和服务器之间正常的加密通道拆开重新加密一遍。如果客户端不认识出口设备签发的证书握手就会被对方主动切断表现也是连接重连。这种场景下光调 keepalive 没用得把出口设备的根证书导入到系统信任区让客户端认为这条链路是可信的。判断方法很直接在外面正常网络下跑得好好的一进公司网络就开始重连那大概率就是证书链路的问题而不是空闲超时。5. 从临时修好到常态我把保活写进了启动文件5.1 让配置在每次开终端都自动生效最开始我是在终端里手动敲的export能管用一天但第二天新开终端又得重敲。为了解决这个问题我把它写进了 shell 的启动文件里一行搞定echo export CODEX_CONNECTION_KEEPALIVE10 ~/.bashrc这样每次开新终端环境变量都会自动载入Codex 启动时直接就能读到。注意不要重复执行这行命令免得启动文件里出现很多行一样的配置。如果你改完没有立刻生效执行一下source ~/.bashrc或者重开终端就行。5.2 一套三分钟诊断模板下次直接抄经历过这次折磨以后我给自己整理了一个三分钟诊断流程每次遇到 Reconnecting 类问题都照这个顺序来先用 curl 测一下普通 HTTPS 请求确认基础网络是不是通的。用printenv看一遍当前环境变量清理掉可疑的网络残留配置。检查是否有新版本可用有就优先更新。加上保活配置做一次至少 15 分钟的挂机测试。还不行再回头查网卡节能、路由器 NAT 超时、公司网关证书。这套流程不复杂但每次都能帮我快速界定问题是在网络基础还是连接参数还是中间设备策略不会像无头苍蝇一样乱试。5.3 最后提个醒保活间隔不是越小越好有一点我得特别提醒保活配置里的数字不是越小越好。如果你把间隔调到 1 秒中间设备肯定不会再回收连接但代价是你每秒钟都在发心跳白白消耗电量还会给服务端增加无意义的请求压力。10 到 15 秒是一个比较合适的区间既能覆盖绝大多数 NAT 超时又不会造成明显开销。而且排查网络问题的时候尽量一次只改一个参数。我之前犯过这个错误为了快速解决问题同时改了保活间隔、路由器和网卡设置结果后面出问题根本定位不到是谁的锅。后来改成一件事、一次改动、一次验证效率反而高很多。如果你也被 Reconnecting 5/5 折磨过先别急着换网络环境试着把那行保活配置加上把间隔调到 10 秒再去跑一个长会话。大多数时候问题就是这么简单。