本教程共 32 篇 · 第 22 篇 · 更新于 2026-07-26 · 约 11 分钟阅读

22. 子代理与多智能体V2

本节目标：理解子代理是什么、解决什么问题、什么时候该用什么时候别用，学会配置自定义 agent、分配模型和管理并行任务。

子代理是什么

子代理（Subagent）是 Codex 临时派生出来的一批专项 agent。它们各自在独立的线程里干活，干完不把原始资料倒回来，由 Codex 统一收成一份结论交给你。

打个比方：你是探长（主线对话），手上一个复杂案子—「把这次改动从安全、性能、测试三个角度审一遍」。你派出三路侦探同时出门、各查各的。查完了，他们不把翻过的几百页卷宗全堆回你桌上，而是各递一份摘要：「安全这块有两处风险，在 X 和 Y」。你最后拿到的是一份按角度归好类的汇总。

当前 Codex 版本默认启用子代理工作流。ChatGPT 桌面 App、Codex CLI 和 IDE 扩展都会显示子代理活动。

Note

自 v0.145 起，多智能体 V2 稳定可用。每个子代理都会独立进行模型调用和工具调用，所以子代理工作流比同类单智能体任务消耗更多 token。

它解决什么问题

上下文污染

你的主对话本来摊着正事—需求、约束、决策。结果你让它跑个测试套件，哗啦刷出几百行测试日志全糊在桌上。有用的那几句「哪几个挂了」被埋在没用的中间输出底下。这就是上下文污染（Context Pollution）：噪声把信号盖住了。

上下文腐烂

对话越填越满、越填越杂，模型的表现会随着不相关细节越积越多而慢慢变差。这就是上下文腐烂（Context Rot）。就像一场会开太久，人就开始走神。

子代理的药方是同一个：把吵闹的活搬出主线，扔给子代理并行干，让它们只把提炼过的摘要交回来。

什么时候该用，什么时候别用

子代理不是免费的。每个子代理都要自己跑模型、调工具，比单 agent 跑法更烧 token。拆得越多，烧得越多。

这类活	该不该拆	为什么
探路 / 跑测试 / 翻日志 / 做摘要（偏读）	值得拆	把噪声搬出主线，正是它的主场
几块互不依赖的调研	值得并行	同时跑，串行三趟变并行一趟
一句话能说清的小修改	别拆	烧 token，得不偿失
几个 agent 同时改同一片代码	慎用	并行写容易撞车
步骤间强依赖	拆了也快不了	并行的前提是互不依赖

Tip

| 建议先把并行 agent 用于探索、测试、分诊和总结等读操作较重的任务。并行写操作更容易产生代码冲突和协调开销，应谨慎使用。

触发子代理

关键一条：Codex 不会自动拆，必须你在话里明说要并行。 你不喊「开几个 agent 并行」，它就老老实实一个人干到底。

好的提示词要说清三件事：怎么分工、要不要等齐所有 agent、最后回什么摘要。

用并行子代理审一下这个分支（当前分支 vs main）。
开一个 agent 专盯安全风险、一个专盯测试缺口、一个专盯可维护性。
三个都等齐，再按类别把发现汇总，带上文件位置。

Codex 负责所有编排工作：生成子代理、路由后续指令、等待结果、关闭子代理线程。多个 agent 并行运行时，它会等到所有要求的结果都返回后，再给出一份汇总答复。

内置三种 agent

Codex 自带三种内置 agent，开箱即用，不用写配置：

内置 agent	定位	适合派去干
`default`	通用兜底	没特别要求时的默认人选
`worker`	偏执行	写代码、改 bug 这类动手的活
`explorer`	偏只读	大范围读代码、定位、调研

Note

这三种是类型（角色），不是「同时只能开三个」。你可以同时开多个同类型的实例—比如让三个 worker 各干一块。总并发上限由全局设置控制。

管理在跑的 agent

用 /agent 切换和查看

/agent

用它在活跃的 agent 线程之间切换，查看某条线程当前在干嘛。注意是单数 /agent，不是 /agents。

直接喊话指挥

也可以直接跟 Codex 说：「把那个还在跑的探路 agent 停了」「关闭已经干完的 agent 线程」。不用记子命令，大白话指挥就行。

Warning

在交互式 CLI 中，审批请求可能来自一个你没在看的 agent 线程。弹窗会标出来源线程，你可以按 o 先跳进那条线程看上下文，再决定批不批。在非交互流程中，需要审批的操作会直接失败。

自定义 agent

内置三种能应付不少场景，但如果你老在重复同一类活—每次审查都强调「像 owner 那样审、盯正确性和安全」—就该把它固化成自定义 agent。

放在哪

位置	谁能用
`~/.codex/agents/`	你的所有项目
`.codex/agents/`	仅当前项目，可提交进 Git

必填三个字段

每个自定义 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.
Lead with concrete findings, include reproduction steps when possible.
"""

字段	必填	说明
`name`	是	Codex 派生和指代这个 agent 用的名字
`description`	是	给 Codex 的人类可读说明，提示何时该选它
`developer_instructions`	是	定义这个 agent 行为的核心指令

Note

Codex 识别自定义 agent 靠的是 name 字段，不是文件名。通常让文件名和 name 一致最省事，但最终以 name 为准。如果自定义 agent 和内建 agent 重名（比如也叫 explorer），你写的盖过内置的。

模型与推理强度分配

这是自定义 agent 最香的地方—让每路 agent 用最匹配的脑子。

模型选择

模型	适合
`gpt-5.6`	含糊、多步骤、需要规划和跨大上下文的高要求任务
`gpt-5.4`	兼顾编码、推理、工具使用的广泛任务
`gpt-5.6-terra`	更看重速度和效率的探索、读操作密集型扫描

推理强度（model_reasoning_effort）

强度	用在
`ultra`	所选模型支持时，最深层推理
`max` / `xhigh`	特别困难的推理任务
`high`	追复杂逻辑、查假设、抠边界情况（审查 / 安全类 agent）
`medium`	大多数 agent 的平衡默认值
`low`	任务直白、速度优先

Tip

分配思路很简单：侦察用快脑、攻坚用强脑。偏读、扫大文件的活用更快更省的模型（如 gpt-5.6-terra）；要审查、啃复杂逻辑的用更强的模型（如 gpt-5.6），推理强度开 high。

自定义 agent 示例

只读侦察兵：

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes."
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks.
"""

审查员：

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""

文档核对员：

name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs."
model = "gpt-5.4"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references.
Do not make code changes.
"""

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

审批与沙箱控制

子代理继承你当前会话的沙箱策略。在 App 中，先在输入框下方为父会话选择权限模式，再要求 Codex 委派工作。

你也可以为单个自定义 agent 单独覆盖沙箱配置，比如强制 read-only：

sandbox_mode = "read-only"

Warning

你在会话里临时改的运行时设置（比如 /permissions 调整、--yolo），会被重新套用到派生出的子代理身上—哪怕那个 agent 文件里写了不同的默认值。会话里的实时选择，盖过 agent 文件里的静态默认。

全局设置

全局子代理设置写在主配置的 [agents] 下：

[agents]
max_concurrent_threads_per_session = 8

字段	说明	默认值
`agents.enabled`	启用或停用多智能体工具	`true`
`agents.max_concurrent_threads_per_session`	同时打开的子代理线程上限	Codex 选择
`agents.default_subagent_model`	子代理的默认模型	继承父会话
`agents.default_subagent_reasoning_effort`	子代理的默认推理强度	继承父会话
`agents.interrupt_message`	智能体轮次被中断时是否记录模型可见消息	`true`

Note

生成智能体时显式提供的值优先于 agents.default_subagent_model 和 agents.default_subagent_reasoning_effort。已有配置可以继续使用 agents.max_threads 这一旧别名。

编排与对话线程控制

Codex 负责所有编排工作：

生成新的子代理
给不同智能体路由后续指令
等待结果
关闭子代理对话线程

当多个智能体并行运行时，Codex 会等待所有要求的结果都返回后，再给出一份汇总答复。

一个完整的并行评审提示词：

Review this branch against main. Have pr_explorer map the affected code paths,
reviewer find real risks, and docs_researcher verify the framework APIs
that the patch relies on.

小结

你想干啥	怎么做
触发子代理	在话里明说要并行，说清分工、等齐、回什么
管理在跑的 agent	`/agent` 切换查看，或直接喊话指挥
写自定义 agent	`~/.codex/agents/` 或 `.codex/agents/` 下放 TOML 文件
必填字段	`name` + `description` + `developer_instructions`
分配模型	`model` + `model_reasoning_effort`，侦察用快、攻坚用强
锁权限	`sandbox_mode = "read-only"`
控制并发上限	`[agents] max_concurrent_threads_per_session`

子代理的核心价值是「把吵闹的中间产物搬出主对话」。它治的是上下文污染和上下文腐烂两个病。但拆得多不等于专业—小修改、强依赖、并行写这三别碰。记住那条反直觉的设定：Codex 默认不自动拆，得你开口它才拆，话语权一直在你手里。干完它只把摘要汇总回来，主线始终清清爽爽。

到这里，你给 Codex 配的「外援」已经基本齐了：AGENTS.md 定规矩、斜杠命令攒快捷、MCP 接外部工具、Skills 沉淀工作流、Plugins 打包分发、Hooks 自动触发、子代理并行干活。接下来是记忆系统—怎么让 Codex 跨会话记住你的偏好和项目上下文。