一个人查三遍，不如三路同时查
你让 Codex「把这次改动从安全、性能、测试三个角度审一遍」，它会顺着查三趟，中间翻过的几百个文件全堆进主对话——上下文越塞越满，后面回答开始飘。
子代理（Subagents）解决的就是这件事：Codex 临时派生一批专项 agent，各自在独立线程里干活，干完只交一份摘要回来，翻过的原始资料不倒回主线程。
类比很直白：你是探长，派三路侦探同时出门，回来各递一页结论，而不是把卷宗全搬到你桌上。
关键前提：Codex 默认不会主动拆。 你不明说，它就一个人闷头干。
第一步：先判断这活该不该拆
拆错了不但不快，还烧钱——每个子代理都独立跑模型和工具，token 是叠加的。
| 任务类型 | 该不该拆 | 理由 |
|---|---|---|
| 大代码库探索、多角度 review | 该拆 | 只读、天然并行、互不干扰 |
| 长日志/长文档分块分析 | 该拆 | 分片独立，汇总即可 |
| 批量重复审查（一行一个对象） | 该拆 | 标准流水线 |
| 多个 agent 同时改同一批文件 | 别拆 | 文件冲突 + 协调成本 |
| 一条线性依赖的小改动 | 别拆 | 拆了纯属添堵 |
一句话记法：read-heavy 放心拆，write-heavy 慎重拆。
第二步：把「拆」明确写进提示词
不用记特殊语法，直接说人话就行。下面这个 review 模板可以直接抄：
请用并行 subagent review 当前分支相对 main 的改动。
启动 3 个 subagent，分工如下：
1. 一个只查潜在 bug 和边界情况
2. 一个只查测试覆盖，指出缺哪些用例
3. 一个只查安全风险与可维护性
要求：
- 每个 subagent 只输出明确问题，不要输出大段过程
- 等三个都完成后再汇总，不要拿半成品下结论
- 汇总按「高风险 / 中风险 / 可选优化」分组，每条附文件路径
- 最后告诉我应该优先修哪一个
这段模板有三处是刻意写的：分工不重叠（避免三个人查同一件事）、等全部完成再汇总（避免主代理提前下结论）、指定输出格式（拿到的是清单不是流水账）。
排查报错时换个说法同样好用：
我遇到这个报错：[粘贴完整报错和 stack trace]
请同时做两件事：
1. 用 explorer 追踪完整调用链，找出根本原因，只读不改代码
2. 另一个 agent 对照官方文档核对涉及的 API 用法是否正确
两者都完成后，给我一个最小改动的修复方案，并说明为什么这样改。
比「直接问怎么修」强在哪？explorer 走的是真实执行路径，不是根据代码结构猜的路径。
第三步：认识三个内置 agent
不用配置，开箱就能点名使唤：
default：通用兜底，没特殊要求时用它worker：偏执行，适合实现功能和修 bugexplorer：偏只读探索，适合读代码、收集证据
在提示词里直接说「用 explorer 去追调用链」「让 worker 去改」，Codex 就会按这个角色派活。
CLI 里输入 /agent 可以查看和切换各个 agent 线程，看它们各自跑到哪一步了。
第四步：写一个自己的只读侦察兵
内置 agent 不够用时，往 ~/.codex/agents/（个人级）或 .codex/agents/（项目级）丢一个 TOML 文件，一个文件定义一个 agent。
三个字段必填：name、description、developer_instructions。
.codex/agents/recon.toml：
name = "recon"
description = "只读侦察兵，负责在动手改之前把执行路径和依赖摸清楚。"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
保持在探索模式。追踪真实执行路径，引用具体文件和函数名。
除非主代理明确要求，不要提出修改方案、不要改动任何文件。
优先用精准检索和定点读文件，不要做全库扫描。
"""
可选字段（model、model_reasoning_effort、sandbox_mode、mcp_servers 等）省略时会继承父会话配置。这里有个很实用的搭配：侦察兵用快模型、低成本；审查员用强模型、高推理强度，钱花在刀刃上。
并发上限写在配置的 [agents] 段里：
[agents]
max_threads = 6
max_depth = 1
max_threads 是同时开的线程数上限（不设时默认 6），max_depth 限制子代理再派子代理的嵌套层数。
第五步：验收，确认它没越权
自定义 agent 写完别急着信，派一次小任务专门验三件事：
- 只回摘要——主对话里没有出现它翻过的大段原文
- 没改文件——跑完
git status应该是干净的 - 角色没漂移——它没有顺手给你提修改建议
任何一条不对，回去把 developer_instructions 写得更硬：把「不要做什么」明确列出来，比只写「应该做什么」有效得多。
第六步：批量流水线，一行 CSV 一个任务
当你有几十个同构任务（一个文件一份审查、一个服务一份报告），用 spawn_agents_on_csv 走批处理。这个能力目前仍是实验性的，用法模式是固定的：
准备 CSV（每行 = 一个任务）
↓
Codex 每行启动一个 worker 子代理
↓
全部并行跑完
↓
结果汇总写回输出 CSV
两步就能跑起来。先生成任务清单：
扫描 src/utils/ 下所有 .ts 文件，
生成 utils-list.csv，列：file_path、function_count（该文件导出的函数数量）
再批量派活：
用 spawn_agents_on_csv 读取 utils-list.csv，每行启动一个 agent：
- 读取 {file_path} 中所有导出函数
- 为每个函数生成对应的单元测试
- 测试文件写到 __tests__/ 对应路径下
- 覆盖正常输入、边界值、异常输入三类用例
完成后输出到 test-results.csv，包含：file_path、tests_generated、status
status 这一列别省。跑完一眼就能看出哪几行失败了，单独重跑就行，不用整批推倒重来。每个 worker 必须回报一次结果，中途退出的行会在导出 CSV 里被标成 error。
三个容易踩的坑
一是把并发当免费的。 六个子代理就是六份 token，小项目看不出来，项目一大立刻肉眼可见。拆之前先问一句：省下的时间值不值这个钱。
二是分工写得含糊。 「一个查代码质量、一个查可维护性」——这俩边界在哪？agent 会漂移到相邻工作，输出大量重复噪音。每个角色只给一件事。
三是忘了审批会跳出来。 交互式会话里，非活跃线程的审批请求也会弹到你面前，弹窗上会标来源线程。非交互式流程里则相反：需要新审批的操作会直接失败并把错误抛回父流程，跑自动化脚本前要提前把权限配好。
来源：公众号《Codex：安排小弟干活（子代理）》，以及 Subagents 三场景实战（并行 review、报错排查、CSV 批量）分享内容，本文为原创转写与流程重构。
资料最后核对日期：2026-08-06 · 内容整理自 CodexGuide 社区公开教程