用 Subagents 拆分任务

Subagents 用来把复杂任务拆给多个专门 agent 并行处理，再由主 agent 汇总结果。它适合高度并行的探索、审查和事实核验，不适合小任务或强串行任务。

Subagents 不是越多越强。每个 subagent 都会消耗模型和工具资源，也会增加上下文、审批和写入冲突成本。

当前 Codex releases 默认启用 subagent workflows，但 Codex 只会在你明确要求时 spawn subagents。官方文档也强调：每个 subagent 都会独立做模型和工具工作，因此会比单 agent 消耗更多 tokens。

Subagents

查看官方 subagents 配置和使用说明。

Skills vs Subagents

区分流程复用和任务拆分。

Team production

多 agent 进入团队流程前先明确边界和治理。

什么时候该拆

flowchart TD
    Task["任务来了"]
    Independent{"子问题是否独立?"}
    Outputs{"输出是否能汇总?"}
    Write{"是否会写同一批文件?"}
    Use["适合 subagents"]
    Single["保持单 agent"]

    Task --> Independent
    Independent -->|否| Single
    Independent -->|是| Outputs
    Outputs -->|否| Single
    Outputs -->|是| Write
    Write -->|会冲突| Single
    Write -->|不会| Use

适合拆：

PR 同时做安全、测试、文档和架构审查。
大型代码库探索多个模块。
一个 agent 查官方文档，另一个读代码。
多个只读维度可以并行。

不适合拆：

单文件修改。
小 bug。
强依赖同一段上下文的调试。
多个 worker 会改同一文件。
non-interactive 环境无法处理审批。

内置角色怎么用

Codex 内置三类 agents：

agent	用途	推荐边界
`explorer`	read-heavy codebase exploration	只读查证、回答具体代码库问题。
`worker`	implementation and fixes	执行明确修改，必须有文件 ownership。
`default`	general-purpose fallback	无特定角色时兜底。

新手建议先用只读 explorer。需要写文件时，只给一个 worker 明确写入范围。不要让多个 worker 同时改同一批文件。

CLI 中可以用 /agent 切换 active agent thread，查看或继续某个 subagent 的上下文。任务结束后，让主 agent close completed agent threads，避免后台线程长期占用上下文和状态。

写给 subagent 的任务要窄

好的 subagent 任务应该包含：

它负责什么。
它不能碰什么。
输入范围。
输出格式。
是否只读。
是否允许调用外部工具。

示例：

只读检查 PR diff 中的权限和数据泄露风险。
不要修改文件。
输出按严重程度排序的 findings，每条包含文件、证据和建议。

任务越窄，主 agent 越容易汇总。

权限和审批

Subagents 的权限边界不能忽略：

它们可能继承当前 sandbox。
它们可能触发自己的审批请求。
它们可能读取不同上下文。
它们可能产生写入冲突。

建议：

初期全部只读。
写入任务只交给一个 worker。
明确文件 ownership。
非交互任务避免需要审批的 subagent 动作。
结束后汇总每个 subagent 做了什么。

官方行为要记住两点：

Subagents inherit 当前 sandbox policy。
交互式 CLI 中，inactive thread 也可能弹出 approval request；approval overlay 会显示来源 thread。

非交互流程中，如果某个动作需要新的 approval 但无法弹窗，该动作会失败并把错误返回给 parent workflow。因此 CI、批处理、自动化里更适合只读 subagents 或预先收窄权限边界。

自定义 agents

当内置角色不够用时，可以添加 custom agent：

~/.codex/agents/reviewer.toml
.codex/agents/reviewer.toml

每个 standalone TOML 文件定义一个 agent，至少包含：

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""

可以额外设置 model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config 等配置。全局并发和深度放在 [agents]：

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

默认 agents.max_threads 是 6，agents.max_depth 是 1。不要轻易提高 depth，递归拆分会快速增加成本、等待时间和不可预测性。

常见坑

为了并行而并行。
子任务没有明确交付物。
多个 worker 改同一文件。
子结果都是自然语言，无法汇总。
没有说明哪个结果是事实、哪个是推断。
忘记 token 和工具调用成本。
让 subagent 继续无限拆分。

Subagents 的价值来自清晰分工，而不是数量。

验收标准

使用 subagents 后，应能回答：

每个 subagent 负责什么。
哪些只读，哪些可写。
输出如何进入主结论。
是否真的更快或更全面。
是否产生冲突或重复判断。
成本是否值得。

不能回答这些问题，就回到单 agent。