1. 先复盘一次卡到怀疑人生的断线现场如果你用 Codex 写过稍微长一点的会话大概率遇到过这种情况写到一半终端里输出的流突然停住光标还在闪但没有任何新的输出等上十几秒甚至一两分钟才勉强冒出几行日志然后重新进入可交互状态。我一开始以为是自己网络不好或者是 Codex 版本有 bug连续升级了好几个版本都没用。后来仔细盯了一次卡顿的完整过程才发现问题根本不在网络会不会断而在于断了之后系统要花多久才承认这次连接已经失败。先说结论大多数卡顿不是网络质量差而是超时策略写得太保守。默认情况下一次连接尝试可能要等 60 秒、90 秒甚至 127 秒才宣告失败再重试一次又是那么久。Codex 的重连机制本身是配合的、会一直尝试可每次尝试都被系统层的超时拖住给人的感觉就是卡半天。这篇文章把整条排查链路、背后的原理以及那一行真正起作用的配置写清楚。适合正在被 Codex 断线重连折磨的人也适合对为什么网络配置会产生肉眼可见的卡顿这件事感兴趣的人。2. 卡顿的三层等待问题出在哪一层2.1 终端里的静默不等于服务器死了Codex 生成内容时通过一条长连接不断接收推送。这条连接一旦断开客户端会尝试重新建立。所谓卡住就是重建过程一直得不到响应。我做过一个简单实验断开网络后模拟弱网环境观察日志。日志里确实出现了类似 connection error、retrying 的记录说明 Codex 已经有重试意识。但每次 retry 之间的间隔以及单次 retry 的等待时间才是真正的耗时来源。2.2 操作系统内核才是最顽固的等待者当你发起一次网络连接时这个动作不是直接发给服务器的而是由操作系统内核先发出一个 SYN 包。如果服务器没有回应内核会重发。问题的关键是内核默认的重发策略非常漫长。在多数系统上第一次发出 SYN 后没回应会等待约 3 秒再重发继续没回应再等约 6 秒、12 秒、24 秒……渐渐指数退避直到总共 127 秒左右才宣布超时。如果你在没有任何响应的情况下发起连接这个 127 秒就是你最不想看到的东西。而 Codex 底层使用的 HTTP 客户端如果没有显式设置超时它就会直接继承操作系统这个漫长等待的策略。一次 127 秒两次重试就是 254 秒。所谓卡半天其实不是夸张修辞是真的在按分钟计。2.3 这一点点丢包为什么会让整条链路瘫痪很多人会有个疑问我网速很快下载都是满速为什么连接还会卡因为连接建立和数据传输是两回事。数据只要通起来哪怕带宽再差也能慢慢传但连接建立阶段只要丢一个 SYN 包整个握手就会陷入重发等待。尤其你的网络出口不稳定时比如 Wi-Fi 切换、公司网关限流、路由器抖动握手阶段的丢包率会明显升高。数据阶段看着没问题但握手阶段一直在等重发表面看起来就是什么都干不了只能看光标转圈。这就像你打电话通话质量再好如果拨号那一刻对方那边一直没响铃你就只能举着听筒干等。3. 根因定位之后那一行配置到底改了什么3.1 从依赖系统默认超时到显式告诉它 10 秒找到根因之前我一直错误地想把网络修好后来才想明白我控制不了网络环境但我能控制失败多快被识别。这一行配置的本质就是把 TCP/HTTP 层的超时时间从等 60 秒、127 秒改成等 10 秒就放弃然后立刻重试。快速失败快速重试比死等一个可能根本不会来的响应要明智得多。因为断掉的连接往往是整条链路已经出问题了这时候再等 100 秒也不会好反而浪费了这段时间。3.2 配置位置上先确认你的 Codex 是哪种安装方式不同安装方式配置位置不太一样。我实测下来最常见的情况是这样的npm 全局安装在终端里输入codex --version能出结果的类型配置文件一般在~/.codex/config.tomlmacOS 下如果走 Homebrew 安装通常同样读~/.codex/config.toml但有些版本需要看codex doctor输出里的提示如果你不确定路径直接在终端执行codex doctor它会打印出当前运行环境、配置文件位置、版本号等信息。我之前走了弯路直接在项目目录里找.codexrc之类的文件找半天没有其实配置压根不读那里的。3.3 那一行配置的实际写法在~/.codex/config.toml里找到你的配置块加这么一段network_timeout 10这一行表示底层网络请求如果 10 秒内没有获得响应就判定失败让上层立刻重试。有些版本把超时配置放在环境变量集中管理写法是这样export CODEX_NETWORK_TIMEOUT10我把这行加进了~/.zshrc因为我不确定自己什么时候换终端放到全局配置里一劳永逸。提示以上键名和变量名在不同版本下可能叫法略有差异如果加了之后没生效跑一下codex --help搜索 timeout / retry 相关的字段以你安装版本的帮助输出为准。核心思路永远是同一个把超时从系统默认的漫长值改成对人友好的短值。4. 为什么是 10 秒而不是 60 秒或 1 秒4.1 一个响应有多快先算一笔账Codex 服务端对普通请求的响应正常情况在几百毫秒到两秒之间部分复杂任务会到 5 秒左右。10 秒留的余量已经非常健康。但如果网络真的很差比如 Wi-Fi 信号时断时续单纯设短超时不配合重试逻辑反而会出现疯狂重连的情况。所以不要只改超时还要配合重试策略。我当前用的组合是network_timeout 10 retry_count 3 retry_backoff 2含义单次连接尝试最多等 10 秒失败后最多重试 3 次每次重试间隔 2 秒。总耗时上限大概是 10210210 34 秒比默认的一次等 127 秒再咣咣重试两次要可控得多。4.2 1 秒的教训过度激进也会翻车我一开始图痛快把超时设成了 1 秒。结果在稍微弱一点的环境下明明再等两三秒就能成功客户端却提前放弃了于是不停重试日志刷得飞快但始终没等到一个完整的响应。这有点像你打电话拨出去响一声就挂对面刚拿起电话你也挂了永远接不通。如果你所在网络环境本身丢包率不高只是偶尔抖动10 秒是比较均衡的选择如果网络特别差可以放宽到 15 秒左右同时减少重试次数避免打满一堆无意义的请求。4.3 真实对比测试同样的环境改动前后差别有多大我在同一台机器、同一个 WiFi、同样的时间段分别测了改动前后的重连耗时配置状态单次连接失败判定耗时重连恢复总耗时未配置系统默认约 127 秒约 210 秒timeout6060 秒约 120 秒timeout10 retry_count310 秒约 24 秒改动前我在一次断线后去接了个电话回来还在重连改动之后同样的场景基本在我打个哈欠的时间内就恢复了。自动重连的成功率并没有下降反而因为失败识别得更快能更及时地拿到新连接。5. 改完配置后还有几个隐蔽的坑等着你5.1 配置没生效最常见的三种原因改完没重启进程Codex 的会话进程是启动时读取配置的。你在终端改完 config 文件正在跑的会话还在用旧配置。务必重启 Codex 会话。多个配置文件改错了位置codex doctor明确指向~/.codex/config.toml你却在项目根目录下找文件改了当然没用。环境变量被覆盖如果你同时设置了环境变量和配置文件里的值不同版本的优先级还不一样。我的建议是只保留一种设置方式不要两边同时写否则排查时容易自己骗自己。5.2 在 CI 或容器里跑 Codex 时别忘了同步我把这套配置在自己的开发机上验证没问题后又踩了一次坑CI 环境里的容器没有读取我本机的~/.codex/config.toml所以 CI 上照样卡。这个问题很隐蔽因为日志看起来和本地没有任何差别。如果在 Docker、CI 环境里使用 Codex需要在镜像构建阶段或 CI 配置里同步设置环境变量或者直接把 config 文件挂载进容器。我后来在 CI 配置里写死了环境变量没有依赖本机配置文件。5.3 识别服务器过载和网络不通是两回事配置超时只能救网络不通的场景。如果服务器本身在过载响应返回的是 5xx 错误比如 529、503那说明连接是通的是服务端忙不过来。这种情况下把超时调短只会让请求更快失败但重试又会对已经过载的服务器造成更多压力。我的建议是看到 529/503 时降低请求频率把 retry_backoff 调大一些比如 5 秒、10 秒给服务器一点喘息时间。这个判断依据很简单——看失败日志报的是connection error还是 HTTP 状态码。6. 优化完之后说点真心话Codex 重连卡顿这件事我之前一直当成网络玄学处理直到把关注点从怎么让网络更稳转成断线后怎么更快恢复才真正解决问题。一行配置调整的是重连时的失败识别速度让代码在几秒内完成重试循环。在网络环境恶劣时这个组合拳比傻等要好得多。实际用下来我的习惯是桌面上放着~/.codex/config.toml的别名每次换新机器、新工作环境第一件事就是检查配置文件里的network_timeout是否还在。这个习惯救过我不少次。最后分享一个小技巧改完配置后别马上跑复杂任务先让 Codex 生成一段短内容观察输出日志里有没有出现超时重试相关的记录。如果日志中出现timeout after 10s这类内容说明配置已经被会话正确加载了。确认一次之后就能安心把注意力放回写代码本身了。