Claude Code 的 Task 模式（子 Agent）用得多了，你早晚会遇到 Rate Limit。我这次跑一个跨仓库的框架迁移，顺手翻了下运行日志，发现被限额杀掉的子 Agent 有 449 个，其中 438 个被系统从头重做了一遍。说实话，第一眼看到这个数字我以为是日志统计脚本写错了——重做比例接近 98%，意味着基本每次触发限额，之前那个子 Agent 的工作就全部作废。
这个现象本身并不罕见，罕见的是它居然被完整记录了下来。我本来只是想把失败的日志打包删掉，结果职业病犯了，花了半个下午把所有 kill 记录和 retry 记录拉出来做了个交叉比对。越看越觉得这里面有个特别有意思的问题：为什么 Claude Code 的重试逻辑是"从头再来"，而不是"接着干"？以及，为什么在这么多重试的情况下，最终任务还是跑完了？
这篇文章就把这次翻日志的过程、我看到的机制、以及最后怎么把重做率压下来的经验完整写出来。全程没有玄学，都是我实测过的东西，适合正在大规模使用 Claude Code 跑批处理任务、或者对子 Agent 机制好奇的朋友。
1. 一次大迁移任务：449 个子 Agent 是如何堆出来的
1.1 项目背景：为什么我会同时开 449 个子任务
事情是这样的。我有一个祖传的老仓库，大概 120 万行代码，分散在 40 多个子项目里。这次要做的是从旧框架的 API 调用方式整体迁移到新框架的调用方式，涉及几百个文件的改动，而且很多文件的调用关系是跨模块的，不能简单全局替换。
这类活儿如果全靠主对话一个个改，上下文窗口很快就会被塞满，改到后面模型会开始"忘事"。我当时的做法是：把任务按模块边界拆成一个个独立的子任务，用 Claude Code 的 Task 工具派发给子 Agent 去执行。每个子 Agent 拿到的是一个相对独立的模块、一份明确的改动说明、以及"改完跑测试并汇报"的指令。
这个项目的核心思路就是：让每个子 Agent 拥有独立的上下文，各自处理一个模块，彼此不干扰。主 Agent 只负责拆任务、收结果、合并汇总。
我前前后后派发了 449 个子 Agent。这个数字不是一次性发出去的，是分批跑的。第一批我试着并行开了 30 个，后面逐渐加码，最后峰值的时候大概有 90 个在同时跑。整个迁移过程从开始到收尾大概花了三天的真实时间。
1.2 我是在哪里翻到这些子 Agent 的日志的
Claude Code 会把每次会话的日志写在本地的项目目录下，具体位置在你的项目根目录下的.claude/projects里面，按项目路径的编码建目录。每个会话对应一个 JSONL 文件，文件名是一长串会话 ID，里面记录了你和模型之间的每一条消息，包括工具调用、结果返回、错误信息。
翻日志的时候我用的是一堆再简单不过的命令。先按文件大小排序，找到那些异常大的会话文件，因为失败的子 Agent 往往会反复重试，日志文件体积会膨胀得特别厉害：
du -ah ~/.claude/projects/your_project | sort -rh | head -50然后在这些 JSONL 文件里搜关键字rate_limit、subagent、retry、Killed，把对应的会话 ID 和错误片段拎出来。449 这个数字就是这么来的——我在日志里统计到有 rate limit 相关报错的子 Agent 会话，同时把"被系统关闭并重新拉起"的子 Agent 记录单独筛了出来，最后用会话 ID 做了一次去重匹配。
这个统计过程本身是一次性脚本干的活，但我还是建议手动抽查了二十多个日志文件确认脚本的判断逻辑没错。因为日志里同一个子 Agent 的报错记录可能出现多次，不去重的话数字会虚高。
1.3 子 Agent 的工作方式：独立上下文的小团队
要理解后面的一切，必须先把子 Agent 的机制说清楚。
Claude Code 的 Task 工具创建的子 Agent，本质上是一个全新的、独立的模型对话。它的特点是：
- 拥有独立的上下文窗口，不继承主 Agent 的历史消息（只会带着你传给它的任务描述和必要的参考文件）。
- 可以自主调用工具：读文件、写文件、执行命令。
- 在完成一个 Task 后，会把最终结果返回给主 Agent，然后这个子会话就结束了。
这个设计很像公司里"老板拆活给员工，员工各自带电脑办公"。每个员工都是从头开始理解任务的，他们之间没有共享的记忆，也不知道彼此做了些什么。老板要做的就是派活的时候把话说明白，收结果的时候把逻辑合并起来。
这个机制在大规模任务上是真好用，真能并行、真能隔离上下文。但它的隐患也恰恰在于"独立"二字——一旦任务执行到一半被外力打断，比如 API 限额，那这个员工之前的劳动成果就全都锁在了那个废弃的会话里，下一个被拉起来的新员工，必须从零开始理解任务。
2. 被"限额"杀掉：Rate Limit 到底长什么样
2.1 先分清几种不同的"限额"
我们平时说的"被限额杀掉"，其实藏着好几种完全不同的限制。我在翻日志的时候发现，很多人把 429 错误、上下文超限、还有并发数限制混为一谈，这样排查问题的时候会很痛苦。
以主流的 Claude API 为例，常见的限额有这几类：
- TPM（Tokens Per Minute）：每分钟消耗的 token 总数上限。这是最容易触发的。
- RPM（Requests Per Minute）：每分钟请求次数上限。子 Agent 多了以后，这个也容易爆。
- IPM（Input Tokens Per Minute）：某些模型会单独限制输入 token 的每分钟用量。
- 每日用量上限（Daily Usage Limit）：账号级别的累计限制，一般发生在账号本身的配额上。
- 并发连接数限制：同时建立的请求数量上限，不是 API 层面的，也可能出现在你使用的中间层或本地代理上。
- 上下文窗口超限：这个不算 Rate Limit，但表现和"被杀掉"很像，子 Agent 的上下文塞满了之后就无法继续执行，同样会导致会话终止。
我这次遇到的绝大多数是 TPM 触顶。因为迁移任务里有大量的文件读取和代码写入，输入 token 消耗极快。尤其是让子 Agent 读一个大文件再改 10 个小文件这种组合操作，每次工具调用都会把文件内容塞进上下文，TPM 嗖嗖地涨。
2.2 日志里被限流到底长什么样
打开 Claude Code 的日志文件，你会看到类似的错误片段：
{ "type": "assistant", "message": { "content": [ { "type": "tool_use", "name": "Task", "input": { "description": "迁移 order-service 模块的 HTTP 客户端调用", "subagent_type": "general-purpose" } } ] } }紧接着，在子 Agent 的执行过程中，日志里会出现这样的报错：
Error: 429 - Rate limit reached for claude-sonnet-4-xxx Please retry after: 3 seconds或者是：
[ERROR] The service is temporarily unable to process your request (529) Waiting 30s before next attempt...还有一个我特别熟悉的日志特征：子 Agent 的会话里反复出现同一个文件的读写操作，因为每次重试它都会重新读一遍文件。所以如果你看到某个会话里同一个文件路径出现了 8 次甚至 10 次以上的 read 记录，那基本可以断定这个子 Agent 被重做过好多次了。
2.3 被"杀"的两种典型路径
我在日志里总结了两种最常见的死亡路径，表现形式不一样，但结果都是"从头再来"。
路径 A：请求被拒，子 Agent 直接抛错退出。这种最干脆。子 Agent 正在执行任务，发起了一次 API 请求，然后收到 429，代码直接抛异常退出。主 Agent 发现子 Agent 没有正常返回，就把它标记为失败，然后启动重试逻辑。
路径 B：不是被 API 拒绝，而是上下文耗尽或者连续重试导致状态错乱。比如子 Agent 正在循环执行某个操作，重复了几十次之后上下文被撑爆，模型开始胡言乱语，最后系统强制终止。这种死亡方式更隐蔽，因为日志里可能根本没有 429，你只能从行为异常和时间线里推断出来。
两种路径里，路径 A 占了绝对大头，大概 80% 以上。路径 B 更多出现在我并发开得太猛的那段时间里。
3. 438 次从头重做：Claude Code 的重试逻辑与隐藏成本
3.1 为什么重试是"从头做"而不是"接着做"
这是整个事件里最值得琢磨的点。
我当时第一反应是：既然子 Agent 挂了，那我的主 Agent 应该知道它做到哪一步了吧？毕竟日志都记录了啊。结果翻代码和日志之后我发现，Claude Code 默认的重试逻辑根本不关心之前的子 Agent 做到哪了。
当一个子 Agent 因为 429 被终结时，主 Agent 收到的信息其实就是：这个 Task 执行失败，没有返回最终结果。然后主 Agent 会重新发起一个全新的 Task，把原来的任务描述原样再传一遍，拉一个新子 Agent 起来跑。
为什么不能接着做？因为子 Agent 的上下文是封闭的，它的中间过程都消耗在那个已经死掉的会话里了。新子 Agent 启动时，没有魔法可以继承旧会话里的思考过程、中间结论、已修改文件清单。它唯一知道的就是主 Agent 给它的那段任务描述。
你可能会问：那让主 Agent 在任务描述里写清楚"这个文件已经改了一半"不就行了？问题是主 Agent 并不知道中途的状态。子 Agent 在执行过程中没有主动向主 Agent 汇报进度的机制，它只在最后返回一个总结。所以在主 Agent 眼里，一个中途死掉的子 Agent 和一颗刚发射就爆炸的火箭没有区别——都没有返回结果。
这个设计在模型层面是合理的，但在工程层面确实很浪费。特别是长任务，跑了一半被杀，重做成本几乎翻倍。
3.2 一次重做的完整生命线
我把一个倒霉的子 Agent 的完整生命线拉出来看了一遍，时间线大概长这样：
- 主 Agent 派发任务，子 Agent A 启动，开始读文件、分析代码。
- 子 Agent A 进行了大约 15 轮工具调用，已经改完了 3 个文件，正在改第 4 个。
- 第 16 轮请求，触发 TPM 限额，返回 429。
- 子 Agent A 重试了 2 次，每次都等了几秒，但限额窗口还没过。
- 子 Agent A 抛错退出，主 Agent 收到"任务失败"信号。
- 主 Agent 启动重试逻辑，创建子 Agent B。
- 子 Agent B 完全不知道 A 做过什么，重新读文件列表、重新分析、重新改代码。
- 子 Agent B 这次运气好，一次跑完，返回结果。
如果第 4 个文件恰好是 A 改到一半的状态——比如只替换了一半的 API 调用就中断了——那么这个文件的状态在仓库里是脏的。B 重新分析的时候，看到的是一个半改状态的代码，反而可能被误导。这是重做机制里最恶心的隐藏问题：不仅是重复劳动，还有脏状态干扰。
3.3 这笔账到底有多贵
我把这 438 次重做的 token 消耗粗算了一下。
一个子 Agent 平均每次执行要消耗 3 万到 5 万 token（包括输入和输出），重做一次的成本接近翻倍，也就是额外多花 3 万到 5 万 token。438 次重做，意味着光是无谓消耗的 token 就在 1300 万到 2200 万之间。
| 指标 | 数量 |
|---|---|
| 被杀掉的子 Agent | 449 个 |
| 被从头重做的子 Agent | 438 个 |
| 重做比例 | 约 97.6% |
| 每次重做额外消耗 | 约 4 万 token |
| 总额外消耗估算 | 约 1700 万 token |
这还不算时间成本。每次重做从拉新 Agent 到读完全部文件再开始动手，至少要多花 3 到 5 分钟。438 次重做，累计多花了差不多 20 多个小时的等待时间。对于我这种分批跑任务的人，这意味着整体完成时间直接翻倍。
更扎心的是，这些被重做的任务里有相当一部分并不是必须成功的。有些模块的迁移我后面发现方案要调整，本来就是要回滚重启的，那它之前的重做就更是白做了。
4. 这组数据背后的三个信号：问题比数字更扎眼
4.1 信号一：我的任务切分粒度太粗了
449 个被杀的子 Agent 里，执行时长分布非常不均衡。有一批任务特别"长命"，能连续跑上四五百行代码的修改；还有一批任务特别"短命"，刚读了两三个文件就被杀了。
我后来复盘，发现短命任务的共同特征是：任务描述里塞的东西太多，导致子 Agent 前期需要大量读取文件来建立全局认知。读取阶段恰恰是输入 token 消耗最猛的时候，也是最容易触发 TPM 限额的阶段。
也就是说，我把大量任务都设计成了"先读一堆文件，然后动手改"。结果就是大家挤在前几轮疯狂读文件，直接把限额打爆，然后集体被杀。这不叫运气差，这叫任务粒度设计有问题。
正确的做法应该是：把"读文件-建立索引-修改代码-跑测试"这个链路拆开。预先在主 Agent 阶段就把需要读的文件都读好、把关键代码片段直接贴到任务描述里，子 Agent 只需要基于给定的信息直接动手改，而不是自己去大海捞针。
4.2 信号二：我完全没有给并发加保险丝
第二个信号更明显：我的并发策略是"傻冲"。
第一批 30 个并行，第二批 60 个，峰值 90 个。所有子 Agent 启动之后，前几分钟几乎同时进入读文件阶段，对 API 的请求量呈脉冲式爆发。这种请求曲线是最容易触达 TPM 和 RPM 上限的。
正确的方式应该参考限流算法里的"令牌桶"思想：控制启动节奏、限制同时在跑的 Agent 数量、甚至主动在子 Agent 的任务描述里加入"每次工具调用之间间隔 2 秒"这样的指令约束。
我当时也试过在 Prompt 里让子 Agent"执行节奏放慢一点"，但效果不理想，因为模型对这种指令的执行并不严格。真正有效的是从外部控制并发度，shell 脚本里直接限制同时在跑的最大进程数：
# 用 xargs -P 控制并行数 cat tasks.txt | xargs -P 15 -I {} sh -c 'claude-code task "{}"'把并行数从 90 降到 15 之后，429 的出现频率肉眼可见地下降。
4.3 信号三：第三方 API 和本地模型的限额表现完全不同
我中间还试过把一部分任务切换到其它模型的兼容 API 上跑，这带来了一类新的问题。第三方兼容层往往不会如实映射 Claude API 的限额语义，有些中间层会静默地吞掉请求，或者返回一些我以前没见过的错误码。这类错误在日志里搜429是搜不到的，搜error才能看见。本地跑模型（比如通过 LM Studio 接本地模型）又是另一套逻辑——本地模型没有 TPM 的概念，但显存不够或者推理排队太久时，表现和限流很像：请求被挂着，响应超时，子 Agent 被中断。
所以如果你和我一样，混合用了官方 API、第三方兼容 API 和本地模型跑混合任务，那你翻日志的时候必须留个心眼：很多失败的根因根本不是同一类问题，别拿一种错误码去套所有现象。
这一点对实践很重要：平时最好在任务描述里显式标注当前任务使用的模型通道，或者在不同环境跑完后把日志按会话 ID 打上不同的项目标签，否则事后想复盘，你根本对不上号。
5. 实测优化：我是怎么把子 Agent 重做率压下去的
5.1 第一个动作：把任务颗粒度打碎
前面说了，重做率高的直接原因是子 Agent 在前期读文件阶段被打爆。我第一个动作就是把所有任务重新切分，从"整个模块迁移"改成"文件级迁移"。
原来的任务描述是这样的：
请将 order-service 模块下所有 HTTP 客户端调用从旧框架迁移到新框架，包括 controller、service、repository 层的所有相关代码。
这种描述看着清晰，但子 Agent 需要自己去探索整个模块的文件结构，读一堆无关文件。我改成这样：
请将文件 src/main/java/com/example/order/OrderClient.java 中的 HTTP 调用从旧框架迁移到新框架。参考文件 src/main/java/com/example/common/ApiClient.java 中已迁移的写法。该文件共 312 行，需要修改的位置我已经在任务描述里给你标出。只改这个文件，不要碰其它文件。
这种文件级任务有几个好处：
- 子 Agent 不需要探索，直接动手。
- 前置的读文件量大幅缩减，TPM 压力骤减。
- 即使被杀掉重做，重做时间也很短，浪费很小。
事实也证明了这个方向是对的：文件级任务的重做率比模块级任务低得多，因为执行时间短、单位时间内的输入消耗更平稳。
5.2 第二个动作：把限流信息直接写进任务描述
这个动作是我后来加上的，效果出乎意料的好。我在每个子 Agent 的任务描述末尾追加了一段：
如果遇到 Rate limit（HTTP 429 或 529 错误），请等待 15 秒后重试当前操作。如果连续重试 3 次仍然失败，请立即结束任务，并返回一条简短说明：任务因限流中断，未完成任何修改。
为什么要在描述里写这个？因为 Claude Code 自带的错误处理在面对 429 时，有时会进入"无限重试循环"的僵局——子 Agent 不停重发同一个请求，把上下文填满，然后被自己的重试行为拖死。显式告诉它"等 15 秒、最多 3 次、不行就走人"，等于给子 Agent 设置了一个安全边界。
当然，这个策略也有一个代价：如果任务真的因为限流被放弃了，我不会自动得到结果，需要后面的扫描脚本去发现这些"未完成"的任务。这总比让它耗到天荒地老强。
5.3 第三个动作：用幂等设计消除重做的副作用
这个是我认为最有价值的一个动作，值得单独说。
子 Agent 被杀不可怕，可怕的是被杀的时候，已经把代码改到一半，留下一个脏文件。后面新拉起来的子 Agent 看到这个脏文件，要么困惑，要么被误导。
解决办法是让每个子任务都是幂等的：不管执行多少次、从什么状态开始，最终结果都一样。
具体怎么做？以迁移任务为例，我的做法是：让子 Agent 在执行前先对目标文件做一次快照备份（cp file file.bak），然后在任务描述里要求子 Agent 在开始修改前检查该文件是否有.bak文件。如果有——说明这个任务可能已经被执行过半——立即从.bak恢复干净状态再开始。任务成功后统一删除.bak文件。
这个思路的本质是：把"从零开始改"变成"从干净状态开始改"，即使任务被杀了无数次，只要你每次都从备份文件恢复，就不会有脏状态累积。这个技巧其实在很多运维场景里都通用，不只是 Claude Code 子 Agent 的专利。
5.4 第四个动作：减少不必要的自动重试
最后，我把 Claude Code 侧自动重试的次数也调低了。
在配置层面，你可以通过环境变量或配置文件来影响重试行为。比如某些场景下，你可以让单个请求最多只重试 1 次，而不是默认的 3 次甚至更多。重试越多，限流窗口越难恢复，反而容易触发雪崩。
调低自动重试次数之后，表面上看失败率好像会上升，但实际效果是：任务的失败更快、失败更干脆，不会拖泥带水地消耗 token。重试的重任交给外面这层幂等逻辑扛着，不容易被拖死。
当然，如果你用的是官方 CLI 的默认配置，可能没法直接调整重试次数，这种情况下风险更可控的办法依然是自己写外层封装：一次任务的执行脚本、超时控制和重试逻辑都由自己掌控，而不是依赖模型侧对 429 的自由发挥。
6. 几条用真金白银换来的经验建议
6.1 建议一：别指望子 Agent 有记忆，该写状态就写状态
子 Agent 被限额杀掉之后，它是真的"死无全尸"。中间过程、临时结论、改到一半的文件，全部留在那个废弃的会话里。你唯一能把控的，就是让工作成果落在项目文件里，而不是落在模型的心里。
我后来所有的任务设计都遵循一个原则：子 Agent 改的任何一个文件，改动必须立刻落盘，绝不能等到最后一次性写入。这样即使任务被杀，盘面上的进度是真实存在的，重做时可以以盘面状态为准，而不是从零开始。这就像写文档随时按 Ctrl+S，别等到快下班才想起来保存。
6.2 建议二：日志要定期翻，别等出事了才看
Claude Code 的本地日志说实话挺难读的，JSONL 固执又啰嗦，但你如果真的在大规模使用它，我强烈建议写一个简单的日志巡检脚本。哪怕只是每周跑一下，统计一下失败率、重试次数、常见错误码，都能提前发现很多问题。
我这次要不是正好翻了日志，根本不知道自己的并发策略一直在制造"无意义的重复劳动"。日志里的数字不会骗人——重做率 97% 的时候，意味着你的大部分算力都花在了同一个任务的第 N 次尝试上，这是最隐蔽的成本黑洞。
6.3 建议三：数据库式思维，别在无限重试里硬耗
很多人在遇到 429 时的第一反应是"再试一次，万一下次过了呢"。但说实话，在并发峰值期，这种"下次碰运气"的思维害处极大。每一次重试都在给限流窗口添柴火，越重试越容易触发新的限流。
更靠谱的做法是学习数据库的事务思维：有限的重试次数、明确的退避时间、失败之后的降级处理。甚至可以考虑把失败的子 Agent 任务放进"死信队列"，等人少的时候再集中拉起来跑。我最后就是为了躲开白天的限流高峰，把重跑任务的时段全部挪到凌晨三四点，效果立竿见影。
6.4 建议四：重做不是世界末日，反而是一次改错机会
说句公道话，子 Agent 被重做也不是完全没有价值。
我翻日志的时候发现，有好几次重做出来的结果比第一次还好。原因很简单：新子 Agent 没有旧子 Agent 的思维定势，面对同一个任务，它可能换了一个更简洁的实现思路。再加上第一次执行过程中留下的半成品代码其实提供了很多隐含信息（比如文件结构、可能的坑），新 Agent 站在"半成品废墟"上反而更容易看清全局。
所以 438 次重做确实浪费了资源，但也阴差阳错地纠正了不少第一次跑偏的方案。这个角度说，Claude Code 的"从头重做"机制虽然粗鲁，但也不全是坏事。只是你最好自己主动控制重做的时机和代价，而不是让它被动发生。
这次翻日志折腾了一下午，最大的收获其实不是数字本身，而是让我对子 Agent 这个工具有了更冷静的认识。它确实能干重活，但它不是一个可靠的持久化执行单元——它更像是那种"接了任务就埋头干、中途断电就彻底失忆"的临时工。你要想用好它，必须自己把状态管理、幂等恢复、失败兜底这些工程基础设施搭好，让它只负责干活，不负责记事儿。
后面我打算把这次日志分析脚本整理一下，做成一个通用的 Claude Code 会话诊断小工具，谁有需要可以直接拿去统计自己项目的失败率、Token 消耗分布和重试热区。工具整理好了之后，我再写一篇具体的实现说明，到时候见。
