很多时候Codex桌面端跑任务跑一半弹出一句“stream disconnected before completion”然后整个会话直接中断。我最早碰到这个问题的时候第一反应是网络不好赶紧检查宽带、重启路由结果问题照旧。后来在命令行里手动跑同样请求发现链路其实是通的这才意识到这个报错只是表面现象真正的坑藏在后面。这篇文章我会把这类问题拆成五类原因再给你一套我自己常用的排查顺序。无论你是用Codex桌面版刚入门还是已经在VSCode、CLI里接入了自定义模型这篇文章都值得看完。搞清楚报错的分布逻辑比单纯搜某一个错误码更有用。1. 先搞清楚这个报错到底是什么意思1.1 “流断开”并不是一个具体故障Codex的请求方式和我们平时打开网页不太一样。它和服务端之间是一条长连接服务端会持续把内容推给你就像水管一直在放水。只要这条水流中途断掉客户端就会抛出一个“stream disconnected before completion”的提示。关键在于这个提示只说明“水流断了”但没说断在哪一段。是服务端那边主动掐断还是你家到服务端之间的链路出了问题又或者是客户端自己没接住数据这些信息在报错里是看不全的需要结合上下文和后缀来判断。我之前遇到过一种情况后缀是“transport error: network error”一开始以为是本地网络故障结果用其他工具测了一圈网络完全正常。最后排查到是本地的API网关配置多了一层多余转发导致流量被重复封装服务端一收到头部解析失败就直接断流。如果不是把日志翻到最底层这个原因很容易漏掉。1.2 五类原因的整体地图根据我自己的踩坑经历以及大量用户反馈Codex桌面端出现“stream disconnected before completion”的原因基本可以归成五类。类别典型表现关键线索配置与模型问题模型名写错、Base URL不对、鉴权失败auth token is unavailable、model is not supported本地链路问题本地转发服务没启动、端口被占、DNS异常connection refused (os error 61)、local proxy failed服务端过载与限流返回429、提示服务器过载overloaded、429 too many requests连接生命周期问题等待时间过长、空闲超时、大任务中断idle timeout waiting for sse、remote compact task客户端版本与状态旧版本bug、缓存冲突、并发任务过多中断无规律、更新后恢复你可能会说第一类“配置和模型”也算其实特别算。很多人以为报错都是网络问题结果一看配置模型名带了个不存在的版本号服务端直接就拒绝处理了。这类问题在报错文本里往往也会伪装成“stream disconnected”但排查成本最低我建议先从这类入手。2. 五类原因之一配置与模型打架2.1 模型名不匹配一个字符的代价如果你在Codex里通过自定义Base URL接入了第三方模型服务模型名必须严格按照服务商文档填写。有段时间我图省事直接复制了别人分享的配置里面写着“gpt-5.6-sol”但实际支持列表里根本没有这个版本。结果请求发出去之后服务端返回一个“model is not supported”的错误Codex桌面端却只显示“stream disconnected before completion”如果不看日志根本不知道模型名才是元凶。类似的情况还出现在接入DeepSeek这类兼容模型服务时。Codex支持的模型和服务商实际提供的模型可能存在差异你需要确认当前使用的Codex版本是否允许自定义模型名。部分版本会在桌面端弹窗提示“模型不支持”但在自动执行模式下这种提示可能不会出现只留下断流报错。2.2 鉴权配置错误另一个常见坑是鉴权配置。Codex桌面端登录获取的token和命令行工具通过auth login获取的token可能被存放在不同位置。你在桌面端正常登录但底层请求走的是另一个配置文件里的旧token时间一长token过期服务端就会拒绝接受输入连接自然被掐断。我处理过一个典型问题用户反馈桌面端经常断流但每天第一次启动是好的之后越用越容易断。最后发现是系统Keychain里保存了一个旧凭证桌面端每次启动去读取时新旧凭证冲突鉴权失败后连接就被服务端关闭。注意遇到断流问题先别急着反复重试。把当前账号信息里的token清除重新登录一次能解决相当一部分“看似随机”的断流。2.3 配置切换工具带来的隐藏问题现在有不少人会用cc switch这类配置切换工具来管理Codex的多个API端点。在不同服务商之间切换时工具会改写Codex的配置文件。如果切换过程异常退出或者配置文件里残留了上一个服务商的参数就会导致请求发往错误的地址轻则404重则直接断流。有一次我切换完配置后桌面端一直提示“cc switch本地转发失败”同时指向了codex endpoint /responses。我查了半天发现是切换工具的本地辅助进程没起来导致Codex以为自己在访问本地服务但端口没人监听。这类问题在切换配置、升级工具后尤其容易发生恢复办法是先重启切换工具的本地辅助进程再重启Codex桌面端。3. 五类原因之二本地链路异常3.1 端口没监听connection refused的真相Codex桌面端在某些情况下会依赖本地端口进行数据交换比如配合一些第三方工具或本地插件时。如果这个本地服务没有启动或者端口被其他程序占用Codex连接时就会收到“connection refused”或者类似“os error 61”的提示最终显示成“stream disconnected before completion”。我在macOS上遇到过一次排查时发现某个插件占用了我常用的端口段Codex启动后用不了这个端口只能放弃连接。解决方式很简单找出占用端口的进程并停掉或者改掉Codex配置里的端口号。3.2 底层链路的隐藏断点除了端口底层链路的DNS解析、MTU设置、网络栈异常也都可能让长连接中途断掉。这种问题有个共同特点短请求一切正常长任务跑到一半就断而且断的时间点没有规律。我自己遇到过一次最诡异的情况Codex跑小任务完全没问题跑大任务必定在某个时间点断流。最后发现是网络链路中某一层对空闲连接做了一分钟不活跃就断开的策略而Codex在处理复杂任务时中间会有几十秒的思考时间这个时间一旦超过链路允许的空闲阈值服务端推数据就断了。把那个不活跃阈值调大之后问题彻底消失。3.3 本地防火墙和安全软件桌面端安装时一般会申请网络权限。如果你用的是macOS系统防火墙或者安全软件会拦截Codex的主动连接。被拦截时网络请求会表现为“transport error: network error”。排查方法很直接临时关闭防火墙和安全软件再复现一次。如果问题消失就把Codex加入白名单。注意测试完记得把防火墙打开别为了排查问题把安全防护关一整晚。4. 五类原因之三服务端过载与限流4.1 429和“exceeded retry limit”服务端过载最直接的表现是HTTP 429意思是请求太多超出了服务端的限额。Codex的错误日志里如果出现“exceeded retry limit, last status: 429 too many requests”就说明不是你的配置问题也不是你的网络问题而是服务端暂时不想给你更多资源。这种情况最常见于高峰期或者你同时开了太多并发任务。我试过几十个并发任务同时跑服务端很快就返回429然后任务全部断掉。另一个容易踩的坑是同一个API密钥被多个终端共用只要其中一个人触发了限流其余终端也会跟着断流。4.2 “servers are currently overloaded”是服务端明确表态如果报错后缀是“our servers are currently overloaded. please try again later.”那基本不用再排查本地了。这是服务端主动告诉你它们的机器忙不过来。遇到这种情况我的建议是停止重试等15到30分钟再继续而不是拼命点重试按钮。4.3 怎么判断是服务端问题还是本地问题区分服务端问题最有效的办法换一个端点配置或者换一个账号。如果你切换到另一个备用API端点后同样的任务能正常跑完那就说明问题出在原本的服务端或账号限额而不是你的本地环境。提示我习惯在每次排查断流问题时同步打开命令行工具用最小请求样例测试当前端点。如果命令行同样报错问题就在服务端或配置如果命令行正常问题大概率在桌面端或本地链路。5. 五类原因之四超时设计与长连接生命周期5.1 SSE长连接和空闲超时的博弈Codex的响应是基于SSEServer-Sent Events的也就是说服务端会持续向客户端推送事件。这种模式对网络链路的中途设备很不友好因为连接需要长时间保持打开而很多链路中间层都会对空闲连接做超时回收。如果你看到“idle timeout waiting for sse”意思就是连接已经建立但在指定时间内没有收到任何数据链路中间层或者服务端主动断开了连接。原因可能是任务过于复杂模型思考时间太长也可能是中间链路不活跃阈值太小。5.2 上下文过长和compact task还有一个容易被忽视的场景任务跑到中途上下文已经非常长Codex会触发一个远程压缩任务remote compact task。这个压缩任务本身也需要调用模型相当于在原来任务的基础上额外发起了一次请求。如果这段时间网络波动或者压缩任务本身超时就会报“error running remote compact task: stream disconnected before completion”。遇到这类问题我的建议是把大任务拆成小块多轮对话控制在合理长度需要处理超长代码库时先让Codex生成索引或者总结再开始执行具体任务减少中途压缩的次数。5.3 时间消耗在服务端而不是本地有些用户以为断流是本地网络慢了其实本地带宽和延迟都挺低真正耗时的是服务端的生成过程。长任务动辄好几分钟任何环节只要出现一次超过阈值的等待连接就会被判定超时。所以调整连接超时参数确实有用但前提是你调整的是正确的那一层。如果客户端允许配置超时时间可以适当调大同时也要检查链路中间层是否存在不活跃断流策略必要时把它关掉。只调客户端参数但不解决中间层的断开策略问题还是会反复出现。6. 五类原因之五客户端自身与版本问题6.1 桌面端和CLI表现不同同一个Codex核心桌面端和CLI的表现往往不一样。桌面端封装了更多逻辑比如自动更新、同步配置、消息通知这些逻辑一旦出错可能干扰正常的请求流。我见过一种情况CLI跑任务死活没问题桌面端一跑就断。后来发现桌面端的自动更新进程在后台重启了网络模块导致当前长连接被重置。把自动更新改成手动模式之后问题再也没出现。如果你也是桌面端频繁断流但CLI正常优先检查桌面端有没有后台自动更新、云端同步、状态检查这类功能先关掉试试。6.2 版本缓存和旧配置残留Codex迭代速度不慢新版本可能会修改配置格式。如果你的配置文件还是旧版格式新版本读取的时候可能不会报错但某些字段会被忽略导致请求参数缺失。服务端无法解析这种请求就会直接断开流。我每次升级Codex之后都会做一次“干净验证”把旧配置备份删掉当前配置重启客户端重新登录。如果问题消失那基本就是配置残留或旧缓存导致的。这招看着简单解决率很高。6.3 并发任务太多客户端先撑不住桌面端不适合同时开太多会话。有人喜欢一个窗口跑好几个任务结果内存占用暴涨网络连接数也达到操作系统限制新请求无法建立旧请求被系统回收。这个时候报错文本不一定和网络相关但因为最终表现是“stream disconnected before completion”照样会被归类到断流问题里。我的经验是桌面端同时跑两三个任务就是上限再多就开始用CLI或者脚本去调别让一个GUI进程承受所有并发压力。7. 一套实操排查顺序半小时内定位问题7.1 第一步把完整报错复制下来看后缀不要只看第一行“stream disconnected before completion”关键是冒号后面的后缀。不同后缀指向不同原因transport error: network error优先查本地链路和网络栈。connection refused优先查本地端口和服务状态。idle timeout waiting for sse核查空闲超时和链路中间层。our servers are currently overloaded服务端问题等待后重试。429 too many requests查询账号限流和并发数。看后缀是最快的分流方式。我排错时会把完整报错复制到记事本再看出现这个报错前两分钟的操作而不是直接按“重试”。7.2 第二步用最小请求复现先在命令行里跑一个最简单的请求比如“你好”如果这个请求都断流那说明问题出在配置或服务端。如果小请求正常但大任务断流说明问题在连接生命周期或上下文长度。最小复现很关键它能帮你把问题范围快速缩小。我一般会准备三个测试用例极短文本请求验证基本链路。中等长度代码任务验证多轮对话。长上下文任务验证超时与压缩逻辑。哪个用例先出错就往哪个方向排查。7.3 第三步检查本地转发服务和端口占用如果你的环境里配了本地转发服务或配置切换工具需要确认本地服务进程是否正常。ps aux | grep -i codex lsof -i :端口号如果进程没起来手动启动后再试。如果端口被占用换一个端口并在配置里同步修改。这个步骤看起来基础但很多“local proxy failed”类的断流都是这里的问题。7.4 第四步判断是服务端还是客户端用同一个API密钥和同一个模型在CLI里跑同样的任务。如果CLI正常问题大概率在桌面端如果CLI也断流问题在配置或服务端。接着看服务端状态。如果服务端有状态页面先查看有没有异常公告。如果都没有就换一个备用API端点再试一次。7.5 第五步重置配置并回归验证如果前面几步都没定位到问题就做一次干净重置备份当前配置。删除本地配置目录。重新登录Codex。用最小请求样例测试。再跑一次之前失败的任务。我遇到过一个很隐蔽的bug旧配置里有一项开关已经不再生效但新版本读取后会覆盖默认参数导致请求异常。删除配置重新登录之后问题就消失了。这个操作成本很低建议在其他手段没效果时优先尝试。8. 报错速查表与我的几点体会8.1 常见报错信息速查表报错片段可能原因排查方向model is not supported模型名不兼容或写错检查模型名和当前模式是否匹配auth token is unavailable登录凭证缺失或过期清理旧凭证、重新登录connection refused (os error 61)本地端口无服务监听检查本地转发服务和端口占用transport error: network error底层链路异常检查DNS、防火墙、安全软件overloaded. please try again later服务端过载等待后重试更换端点429 too many requests请求频率超限降低并发等待退避idle timeout waiting for sse连接空闲超时调整超时参数、检查链路中间层error running remote compact task上下文压缩任务失败减少上下文长度、拆分任务这张表不是万能药但能帮你把排查面缩小到具体方向。8.2 我踩过几次坑之后总结的几点经验第一断流不要只重试先看日志。很多人在报错弹窗出现后直接点重试重复好几次才想起看日志。实际上Codex日志里记录了每个请求的完整生命周期包括HTTP状态码、请求耗时、服务端返回的错误信息。先看日志通常能省掉一半的排查时间。第二切换配置后记得重启客户端。像cc switch这类配置切换工具改了配置文件之后Codex桌面端并不会立刻全部重新读取。如果不重启新旧配置混用就会出现各种奇怪断流。我一直以来的习惯是切换配置后重启一次客户端再跑最小请求验证。第三本地鉴权问题比你想的常见。token过期、凭证冲突、Keychain里存了旧token这些都是触发“stream disconnected”的高频原因。特别是那些今天能用、明天断流的场景优先看鉴权状态。第四服务端过载和限流不等于你操作失误。很多人遇到429或者overloaded就怀疑自己配置错了其实服务端繁忙是常态。尤其是高峰期接口压力大限流反而是正常保护机制。这种情况该等就等不用反复折腾本地环境。第五别小看版本问题。Codex桌面端的功能迭代速度快偶尔会引入回归问题。遇到无法解释的断流先升级到最新版本或者去查一下当前版本的已知问题列表说不定你踩的坑已经在官方的待修复清单里了。我个人在实际排查中收获最大的一条是养成了看日志和记录复现步骤的习惯。报错信息只是入口真正有用的是入口背后的一连串上下文。希望这份排查顺序能帮你在下次遇到“stream disconnected before completion”时少走点弯路。