用子代理把大任务拆开跑，读密集的活最划算
子代理是把独立的子任务丢到后台并行跑，好处不只是快，更重要的是把大量中间输出挡在主线程之外，避免上下文被噪声填满。定义放在 agents 目录下，用 TOML 写清楚名字、用途和行为指令，权限和沙箱从父代理继承而不会被放大。适合探索、分类、总结这类读密集的活；并行写操作要谨慎，而且每个子代理都各自烧 token，成本要算进去。
先讲结论：拆的是噪声，不只是时间
子代理最容易被理解成「并行跑得快」。快是结果之一，但不是最重要的那个。
真正的价值在上下文。
举个跨境的例子：你要分析 20 个竞品的差评，找出共同的产品问题。如果在一个会话里做，那 20 份评论原文全部会进入上下文——几万字的噪声，把真正重要的判断挤到角落。到第 15 个竞品的时候，它可能已经忘了前面几个的结论。
用子代理的做法是：每个竞品派一个子代理去读、去归纳，只把结论带回主线程。原文留在各自的分支里，主线程手上是 20 条干净的结论，然后做汇总判断。
所以子代理解决的是「中间输出污染主线程」这个问题。并行带来的速度提升，是顺带的。
怎么定义一个子代理
定义文件放在两个位置之一：
- 个人级：
~/.codex/agents/ - 项目级：
.codex/agents/
一个文件定义一个代理，用 TOML 格式。
三个必填字段：
name = "review-miner"
description = "从竞品评论里提炼产品问题，用于选品和产品改进判断"
developer_instructions = """
读取指定的评论数据，按问题类型聚类。
分类维度：耐久性、功能不达标、尺寸与兼容、使用门槛、品质一致性、包装运输、服务。
每类输出：提及条数、占抽样比例、3 条原文片段作为证据。
只返回结论和证据片段，不要把原文全部带回。
抽样量不足 50 条时，明确标注「样本不足」。
"""
三个字段各管一件事：
name：名字description：什么时候该用它。这条决定了主代理会不会在合适的时候想到它developer_instructions：它的行为指令，也就是这个子代理的工作说明书
最后那句「只返回结论，不要把原文带回」很关键——这正是用子代理的意义。如果它把原文全带回来，那和不拆没区别。
可选字段：按任务调档
子代理可以覆盖几项从父代理继承来的设置：
model = "..."
model_reasoning_effort = "high"
sandbox_mode = "read-only"
mcp_servers = ["..."]
实务上最有用的是后两个。
sandbox_mode：给子代理更小的权限。比如主会话是 workspace-write，但负责读评论的子代理只需要 read-only。权限按需分配，而不是所有分支都拿一样的。
mcp_servers：给不同的子任务配不同的数据通道。调研用的子代理能访问外部数据服务，整理内部报表的只读本地文件，互不干扰。
model_reasoning_effort 也值得按任务调：归纳类的活调高，纯整理的活调低，能省不少成本。
权限是继承的，不会被放大
这一点必须说清楚，否则容易误以为子代理是个提权的口子。
**子代理继承父代理的权限模式、沙箱策略和运行时覆盖。**也就是说，主会话是只读的，子代理不会因为单独定义就获得写权限。
所以前面那个「按需调小」是对的方向——你可以给子代理更小的权限，但不能借它绕过父代理的限制。
有一个细节要注意：**审批请求可能从非活跃的线程冒出来。**你正在看主线程的输出，某个后台子代理需要批准，请求会浮上来。如果它拿不到批准，那个操作会失败。
在非交互场景里这一点尤其要留心——没人批的时候，需要审批的子任务就是会失败。所以要么把子代理的沙箱配到不需要审批的档位，要么接受那部分任务跑不完。
怎么触发
两种方式。
显式说，在对话里直接要求：
- 「每个竞品派一个子代理去分析」
- 「把这些活并行拆开跑」
- 「用子代理处理这批评论」
配默认值，在配置里设置全局行为，让它在合适的场景自己拆。
刚开始建议用显式的方式。原因是你需要先建立一个判断：什么活拆了划算、什么活拆了反而乱。这个判断建立起来之前，让它自己决定容易失控。
并发要限制
有两个配置项管这件事：
agents.enabled：整个多代理功能的开关，默认是开的agents.max_concurrent_threads_per_session：一个会话里最多同时跑几个子代理
第二个建议设一个不大的值。理由有三个：
- 成本：并发数直接等于同时在烧 token 的分支数
- 外部服务：如果子代理要访问外部数据源或抓页面，并发太高等于对人家压测
- 可读性：十几个分支同时输出，你根本看不过来
从小往大调，比一上来就开满稳妥。
跨境场景里哪些活适合拆
判断标准很简单：任务能不能切成互相独立的小块，而且每块的中间过程你并不关心。
适合拆的
- 竞品逐个分析：20 个竞品，一个一个来，只要结论
- 评论和差评分类：几百条评论分批处理，只要聚类结果
- 多站点内容生成：五个站点的 Listing，各生成各的
- 多份文档抽取：一批供应商合同，每份抽关键字段
- 多个 SKU 的独立核算：每个 SKU 算自己的毛利和动销
这几类的共同点：每块之间没有依赖，中间过程是噪声，最后要的是汇总。
不适合拆的
- 有先后依赖的：调研结论要先定，才能写 Listing。这种拆了也得排队
- 需要全局视角的：比如判断整个类目的价格带分布，本来就要看全部数据，拆开每个分支只看到局部
- 并行写同一批文件的：多个分支同时改同一个目录，容易互相覆盖
第三条要特别小心。官方的建议也是优先用于读密集的任务，写操作要谨慎。实务上的做法是：让子代理只负责读和产出结论，写文件统一由主线程做。
成本要算进去
这是最容易被忽略的一条：每个子代理都在做自己的模型调用和工具调用，子代理工作流消耗更多 token。
拆成 20 个分支，不是把一份工作分成 20 份，而是跑了 20 份各自完整的工作。
所以要判断划不划算：
- 值得拆的：单个分支的输入很大（比如每个竞品几百条评论），但输出很小（一条结论）。这种情况下，拆开反而省——因为原文不进主线程
- 不值得拆的：每个分支的活本来就很轻。拆的开销比省下的多
一个粗略的判断：**如果某个子任务的原始材料不拆的话会占掉主上下文的很大一块，那就值得拆。**否则先别拆。
一个实际的组合用法
把前面几篇串起来，一个完整的竞品分析流程可以这样组织：
- 主会话在调研目录里启动，那个目录的配置开了网络
- 主线程读竞品清单，为每个竞品派一个子代理
- 子代理只读，各自抓页面、读评论、归纳问题，只返回结论和证据片段
- 主线程汇总 20 条结论，做跨竞品的共性判断
- 主线程把最终报告写成文件
权限上是分层的：主线程能写文件，子代理只读；网络只在这个目录开着，其他目录不受影响。
这个结构的好处是，每一层的权限都刚好够用，没有一处是多给的。
什么时候先别用
如果你还在摸索阶段，建议先不用子代理。
理由是它增加了一层复杂度：出了问题你要判断是主线程的规则不对，还是某个子代理的指令不对，还是拆的方式不对。在单会话流程都还没跑稳的时候，这层复杂度是负担。
顺序建议：先把单个流程用普通会话跑通、规则写稳，确实遇到上下文被撑满或者任务量大到不拆不行的时候，再引入子代理。
下一步
前面五篇讲的都是怎么用。从下一篇开始进入具体场景，第一个是选品调研——它是跨境活里唯一必须打开网络的一类，所以权限怎么配、边界怎么守，要单独讲清楚。
