1.3 本地自动重试工具的整体设计思路

为什么选择“本地 wrapper”而不是去改 Codex 的内部机制？因为 Codex 是外部工具，不同版本的行为不一致，直接去 hack 它的内部流程风险很高，升级一次可能就失效了。用系统级的包装脚本包一层，对 Codex 本身是透明的，它的启动方式、退出行为、日志输出都保持原样，只是在外层多了一个“看门狗”，发现异常就重新拉起任务。

在设计这个工具时，我给自己定了几个原则。第一，对 Codex 透明，不修改它的任何配置和文件。第二，只处理明确可重试的错误，不确定的错误一律直接放行，避免误判导致重复执行任务。第三，保留原始退出码，如果最终重试次数耗尽，工具返回的应该是最后一次失败时的退出码，而不是假装成功返回 0。第四，保留所有日志输出，原始输出、重试原因、等待时长都要能看到，方便事后复盘。第五，尽量支持会话续跑，条件允许的时候自动在重试命令里追加 --continue ，让 Codex 可以接着上一次的对话继续干活，而不是每次从头开始。

这套原则落实到代码里，就是一个主循环：执行命令 → 采集输出 → 判断是否命中可重试错误 → 命中则按退避算法等待 → 继续执行，直到成功或者重试次数用尽。

2. 核心细节解析与实操要点

2.1 退避策略：固定等待 vs 指数退避加抖动

重试最关键的一个参数就是“等多久再重试”。最省事的做法是每次固定等 30 秒，但实测下来效果并不好。如果服务端处于持续过载状态，固定等待会让你的重试一次次撞在枪口上，白白浪费大量时间；如果服务端很快就恢复了，固定等待又显得太保守，明明 5 秒就能恢复，你偏要等满 30 秒才继续。

更好的方案是指数退避：第一次等待较短，比如 10 秒，之后每次翻倍，20 秒、40 秒、80 秒，最多不超过一个上限值，比如 300 秒。这样在服务端短暂波动时，你能快速恢复；在持续过载时，你也不会高频地反复冲击服务端。

光有指数退避还不够，还需要加入随机抖动。抖动的作用是打破“同步重试”的节奏。你可以想象一下，如果所有客户端都按完全相同的退避序列去重试，那它们会在同一时刻再次一起撞上服务端，形成所谓的“重试风暴”。加入随机抖动后，大家的重试时间点被分散开，服务端的压力会平滑很多。

实现上我采用了 20% 的等量抖动，公式是：

这样实际等待时间在退避基准值的正负 20% 范围内浮动，既保留了指数退避的趋势，又避免所有实例齐步走。

重试次数建议控制在 6 到 8 次。太少的话，高峰期可能还没等到服务端恢复就放弃了；太多的话，如果问题不是瞬时过载而是持续性的，你会在一个不可能成功的任务上空耗大量时间。我默认设置的是 6 次，配合初始 10 秒、最大 300 秒，整体重试窗口大概在十几分钟，能覆盖绝大多数短暂波动的情况。

2.2 错误识别：匹配要精准，别把正常输出当成失败

重试工具最怕的其实不是“该重试时没重试”，而是“不该重试时瞎重试”。Codex CLI 在执行过程中会输出大量日志和中间结果，这些文本里完全可能包含 capacity 或者 overloaded 这些单词，比如任务描述里有一句“capacity planning”，或者代码里有一个字符串 overloaded 。如果你直接用 if "capacity" in output 这种全文本子串匹配，很容易把正常完成的任务误判成失败，然后傻乎乎地重新跑一遍，既浪费时间又浪费额度。

我自己就踩过这个坑。第一版脚本用 if "capacity" in output 做判断，结果有一次 Codex 输出的代码里含有一个 capacity 变量名，脚本以为又挂了一次，把一个已经顺利完成的测试任务重复跑了三遍。后来我改成用正则匹配完整的错误语句，比如 selected model is at capacity 和 service is overloaded ，并且忽略大小写，误判问题就基本消失了。

另外还可以加一道保险：先判断输出里是否有任务完成的标志。比如 Codex 执行完成后通常会输出类似 task completed 或者 finished successfully 的文本，如果检测到这些成功标志，即使文本里同时包含 capacity 字样，也优先判定为成功。这个逻辑本质上是一个“白名单优先”策略，能进一步减少误杀。

还有一个细节是匹配前要做文本归一化。把输出里多余的空格、换行压缩成单个空格，再统一转小写，这样即使原文里是 Selected model is at capacity 这种大小写混排，也能稳定命中。

2.3 会话保持：重试时用不用 --continue

Codex CLI 每次执行任务默认会创建一个会话，如果你直接重新执行原来的命令，其实是从零开始一个新会话。对于短任务来说问题不大，但对于那种需要跑很久的复杂任务，任务已经执行到一半却因为过载中断，重新跑一遍的成本非常高。

好在 Codex 支持从历史会话继续，对应的参数是 --continue 。所以工具可以提供一个选项，在重试时自动追加 --continue ，让 Codex 接着上次的上下文继续干活，而不是从头再来。这个功能听起来很美好，但实际用起来有几个坑要处理。

第一个坑是 --continue 的兼容性。不同版本的 Codex，在不同子命令下，对 --continue 的支持程度不一样。有的版本你加了这个参数它会正常续跑，有的版本可能直接报错说参数无效。所以在工具里最好把“是否追加 --continue”做成可配置项，默认不要打开，让用户根据自己装的 Codex 版本决定。

第二个坑是 --continue 会改变任务语义。如果你执行的是 codex exec "修复登录页的 bug" ，追加 --continue 后，Codex 很可能会忽略你新给的“修复登录页 bug”这句话，直接去续跑最近一次的历史任务。这在某些场景下是你想要的，但在另外一些场景下反而会跑偏。我个人的习惯是：如果任务是“继续上次没跑完的内容”，就开 --continue ；如果任务是一个全新的独立指令，就别开，宁可重新跑一遍，也不要让它跑到别的任务上去。

第三个坑是成本问题。续跑会保留之前的上下文，“从上次会话继续”意味着历史对话里的 token 依然占用模型上下文，费用会比较高。有些复杂的任务做一次重试，可能比从头跑更费额度。所以这个选项我会建议按需开启，而不是默认全开。

2.4 本地工具选型：Python wrapper 和 Bash 循环怎么选

做这个本地重试工具，语言选型不是关键，方案落地才是关键。你可以用 Python 写一个完整的脚本，也可以用 Bash 的 while 循环加 grep 加 sleep 实现，两个都能达到基本目的，但体验差别还是有的。

我选 Python 的主要原因有这几个。第一，字符串匹配和正则处理方便，写 re.search 比 Bash 里套多级 grep 要清晰得多。第二，随机数、时间控制、参数解析都有现成库，代码写起来干净。第三，后续如果要扩展功能，比如记录重试日志、发通知、统计错误率，Python 明显比 Bash 顺手。第四，Python 跨平台性好，Windows 上装个解释器也能跑，而 Bash 脚本在原生 Windows 环境里跑起来比较麻烦。

当然，如果你本机环境里没有 Python，或者你的使用场景就是一个简单的 Linux 服务器，那 Bash 版本完全够用。核心逻辑十几行就能写完：while 循环执行命令，捕获输出，grep 匹配错误关键字，匹配到了就 sleep 一下再重试，没匹配到就正常返回退出码。它的缺点是实时性差，一次性收集输出再打印，看不到过程；也没有随机抖动；字符串匹配用 grep -i 做全局匹配，误判概率比正则匹配整句要高一些。

工具写完之后最重要的是符合你自己的操作习惯。下面我重点讲一下 Python 版本的完整实现，Bash 版本也会给出参考代码。

3. 实操过程：写一个可直接用的 retry-codex

3.1 核心需求与脚本结构

在动手写代码之前，我先把需求梳理了一遍，脚本需要具备以下能力：

• 接收任意 Codex 命令，不限制具体参数；
• 实时透传 Codex 的输出，不在工具层吞掉日志；
• 自动识别 Selected model is at capacity 和 service is overloaded ；
• 采用指数退避加抖动的方式进行重试；
• 保留最后一次失败的退出码作为工具自身的退出码；
• 支持可选的 --continue-on-retry 参数，按需追加 --continue 。

按照这个需求，脚本的结构分成四块：参数解析、单次执行、重试判断、主循环。参数解析负责处理用户传入的 Codex 命令和重试参数；单次执行负责启动一个 Codex 子进程，实时打印输出并收集日志；重试判断负责分析日志文本，决定是否需要重试；主循环负责把前面三块串起来，控制重试次数和退避等待。

需要注意的一点是用户传入的 Codex 命令里可能有各种参数，比如 codex exec --full-auto "任务" ，为了避免参数解析冲突，我在工具里用 argparse.REMAINDER 来捕获剩余参数，并且在用例层面要求用户用 -- 分隔工具参数和 Codex 命令。这样工具本身的参数和 Codex 的参数就不会互相干扰。

3.2 完整代码实现

把脚本命名为 retry-codex.py 。完整代码如下：

代码本身不算长，但有几个细节值得说明。用 subprocess.Popen 而不是 subprocess.run ，是为了实时打印 Codex 的输出。如果直接用 subprocess.run(capture_output=True) ，那么整个过程你是看不到任何输出的，只能等命令结束，这样你就不知道 Codex 卡在哪一步，体验很差。Popen 加 bufsize=1 之后，可以按行读取 stdout，每读到一行就原样打印一行，同时把行内容收集到一个列表里，为后面的错误识别留一份完整的原始文本。

把 stderr 重定向到 stdout ，是希望把所有输出合并到一个管道里统一处理。这样 Codex 的报错信息一定会出现在 stdout 的字节流中，不会被遗漏。

3.3 使用方式与参数说明

脚本写完之后，使用方式非常直接。最基础的用法：

这里的 -- 是刻意加的分隔符，它告诉脚本，后面的内容都是要传递给 Codex 的命令，脚本自身不再解析。如果你不放心参数会不会被吞掉，可以先用 --help 查看解析结果。

如果你希望更激进一点，可以把重试次数调高，比如最多试 8 次：

如果你确认自己装的 Codex 版本支持 --continue ，而且任务就是接着上次继续跑：

这种情况下，脚本在第一次执行时按原命令跑，如果命中过载错误，从第二次执行开始会在原命令末尾追加 --continue 。这样 Codex 会尝试接着上一次的会话往下走。

脚本的退出码设计是按“透传真实结果”的原则来的：任务成功返回 0；遇到无法识别的失败，返回原命令的错误码；一直重试到上限，最后返回最后一次失败的退出码。这样你可以在 CI 或脚本里直接通过 $? 判断是否真的成功，不会因为工具层“重试过”就掩盖了真实失败。

3.4 不用 Python 的替代方案：Bash 版

如果你不喜欢装 Python，或者你的运行环境就是一个干净的 Linux 服务器，下面这个 Bash 版本也可以直接用。它虽然少了实时输出和抖动，但核心的“识别错误并退避重试”能力是完整的：

Bash 版本的核心逻辑是：把整个 Codex 命令的输出一次性捕获到变量里，如果退出码非 0 且输出里匹配到了过载错误，就先 sleep 再重试。它的主要问题是命令运行期间看不到实时输出，长任务跑起来比较煎熬。另外 grep 的匹配是整段文本的全局匹配，用户任务文本或代码里如果出现相同的关键词，也可能误判。如果只是临时应急用，这个版本足够；如果你要把这个工具长期留在工作流里，建议还是上 Python 版。

4. 常见问题与排查技巧实录

4.1 我踩过的几个坑

先说误判的问题。第一版工具里我用 if "capacity" in output 做判断，结果 Codex 输出的代码里有一个变量名带了 capacity 字样，工具立刻判定为过载，把一个已经成功的任务重复跑了好几遍。这个问题后来通过“成功标志优先 + 整句正则匹配”解决了。现在 should_retry() 的逻辑是先检查是否有任务完成标志，再检查是否命中过载错误，双重保险。

再说退出码的问题。最初版本里，只要检测到过载错误并开始重试，脚本最终就返回 0，因为我当时的想法是“只要我重试了，就说明工具工作了”。但这样做带来的后果是：即使重试了 6 次全部失败，外层脚本也会认为任务成功了，下游流程会被误导。后来改成始终透传最后一次命令的退出码，才算把这个问题解决。在 CI 环境里，退出码是很重要的信号，工具设计时一定要尊重它。

还有一个比较隐蔽的问题是 --continue 的行为差异。我一开始默认所有重试都追加 --continue ，结果在某个版本的 Codex 里，追加之后原有的任务描述被忽略了，导致它跑到上一个会话的任务里去。后来我加了一个开关，默认关闭，只有用户明确指定时才启用。如果你用了这个选项，建议先跑一个小任务验证一下你当前 Codex 版本对 --continue 的处理行为。

4.2 持续过载时应该怎么办

如果你已经重试了 6 次还是失败，这时候基本可以确定服务端处于一段较长时间的过载状态，继续硬刚已经没有意义了。我的做法是先把工具停掉，等几分钟再手动跑一次。如果连续几天都在高峰时段遇到这个报错，可以考虑调整自己的使用习惯。

第一是降低并发。如果你同时开着多个 Codex 任务，它们会同时向服务端发起请求，更容易触发过载。尽量把任务改成串行执行，一个跑完再跑下一个，会发现报错频率明显下降。第二是错峰执行。如果你的任务对时间不敏感，比如批量跑测试、生成文档、重构代码这类工作，尽量安排到相对空闲的时段。第三是检查任务本身的粒度。大任务容易被过载打断，而且一旦打断损失大，小任务则灵活很多。把一个长任务拆成几个短任务，即使某个片段在重试多次后仍然失败，损失的也只是那一小段的工作量。

4.3 报错排查速查表

我把这段时间遇到的现象和对应的处理方式整理成了一张速查表，方便遇到问题时快速定位。

这张表并不是说遇到这些情况只能按表格处理，而是提供一个排查思路。工具能做的只是自动重试，真正决定任务能否顺利完成的，还是你对 Codex 运行机制和任务本身的理解。

4.4 后续可以扩展的方向

如果你觉得现在这个工具还不够顺手，有几个方向可以继续完善。最常见的是加日志记录，把每次重试的时间、原因、等待时长写到文件里，方便事后统计分析服务端过载的频率。更进一步，可以在连续失败超过阈值时发一个通知，钉钉、飞书或者 Slack 都可以，这样就不需要人一直盯着终端。还可以把脚本打包成一个可执行文件或者一个 npm 包，让团队里其他人也能直接用。如果你对 Codex 的会话机制比较熟悉，甚至可以做得更智能，根据任务类型自动决定是重新执行还是 --continue 续跑，不过这需要针对你自己的任务特征多做一些规则配置。

这个工具我用了差不多三周，最大的感受就是终于不用一直盯终端了。以前每次看到 overloaded 都只能干等，现在让它自己退避重试，我就能抽空做别的事，过一阵回来再看结果。按我个人的经验，重试参数不要调太激进，6 次、初始 10 秒、最大 300 秒是一个比较舒服的组合，既能覆盖绝大多数高峰时段的波动，又不会在持续故障时无限空耗时间。如果你也经常跑 Codex 长任务，这个思路可以直接抄走，根据自己的报错文本和任务习惯改一改就能用。需要记住的是，重试不是万能药，它只解决服务端的瞬时过载；当任务被持续拒绝时，先停一停，看看是不是自己的运行方式需要调整。