Subagents 是什么

Subagents 是什么

Subagents 可以理解成：

让 Codex 临时启动几个职责明确的子代理，并行完成不同方向的分析，然后把结果汇总回主会话。

它不是“让 Codex 自动变聪明”的按钮。 更准确地说，它是一种并行工作流：

• 主会话负责目标、范围、决策和最终交付。
• 子代理负责某个独立方向的探索、检查或总结。
• 子代理完成后，把精简结论交回主会话。

前置教程：第一个低风险 Hook
如果你还没有理解 Codex 的高阶扩展为什么要先控制风险，先完成前置教程。

依据来源：OpenAI Codex 官方手册中 Subagents、Subagent concepts、/agent、sandbox controls、custom agents、[agents] 配置等章节。

核心结论

Subagents 适合并行分析，不适合新手第一时间并行改代码。

操作判断：

能拆成多个互不影响的“读、查、总结、评审”任务，才适合 Subagents。
多个代理同时改同一批文件，通常会增加冲突和返工。

它解决什么问题

你和 Codex 对话越久，主会话里会堆积越多信息：

• 项目结构。
• 需求讨论。
• 错误日志。
• 测试输出。
• diff 总结。
• 你临时补充的限制。
• Codex 中间探索时产生的大量输出。

其中一部分用于决策，另一部分只是过程输出。 当过程输出太多时，主会话容易被无关细节淹没。

Subagents 的价值是：

• 把嘈杂的探索过程移出主会话。
• 让不同代理并行查不同方向。
• 让主会话只拿到总结后的关键结论。
• 在复杂任务里节省等待时间。

比如你要审查一个比较大的分支，不一定要让主会话从头查完所有东西。 你可以让 Codex：

派 3 个子代理并行审查：
1. 一个只看安全风险。
2. 一个只看测试缺口。
3. 一个只看可维护性。
等三个都完成后，再把结论按严重程度汇总给我。

这是 Subagents 的典型用法。

它不解决什么问题

Subagents 不是下面这些东西：

误解	实际情况
Subagents 会自动启动	不会，Codex 只会在你明确要求时启动
Subagents 免费提升质量	不一定，它会消耗更多 token 和时间
Subagents 适合所有任务	不适合小任务和强依赖任务
Subagents 能自动避免冲突	不能，并行写代码反而容易冲突
Subagents 替代 AGENTS.md	不能，AGENTS.md 仍然负责项目规则
Subagents 替代验收	不能，主会话仍要汇总、判断、验收

如果一个任务本来 5 分钟就能让一个 Codex 会话做完，不要上 Subagents。

什么时候适合用 Subagents

适合的任务通常有 4 个特征：

1. 任务比较大。
2. 可以拆成多个独立方向。
3. 每个方向主要是读、查、分析、总结。
4. 最终只需要主会话汇总结论。

场景 1：大分支评审

适合这样拆：

请用 Subagents 并行评审当前分支。

拆分方式：
1. 一个子代理只看安全风险。
2. 一个子代理只看潜在 Bug。
3. 一个子代理只看测试缺口。
4. 一个子代理只看可维护性。

要求：
1. 每个子代理只读代码和 diff，不修改文件。
2. 等所有子代理完成后再汇总。
3. 汇总时按“高 / 中 / 低”列出问题。
4. 每个问题必须带文件路径和理由。
5. 如果某个方向没有发现问题，也要明确说“未发现”。

场景 2：大型项目快速摸底

适合这样拆：

请用 Subagents 并行了解这个项目。

拆分方式：
1. 一个子代理分析前端入口、路由和页面结构。
2. 一个子代理分析后端入口、接口和服务结构。
3. 一个子代理分析构建、测试、部署脚本。
4. 一个子代理分析配置文件和环境变量说明。

要求：
1. 只读分析，不修改文件。
2. 每个子代理输出 10 条以内结论。
3. 主会话最后汇总成“项目地图”。
4. 不要猜测没有证据的内容。

场景 3：多个失败方向并行排查

比如构建失败原因不明确，可以拆：

请用 Subagents 并行排查这次构建失败。

拆分方式：
1. 一个子代理只看依赖和版本。
2. 一个子代理只看配置文件。
3. 一个子代理只看最近 diff。
4. 一个子代理只看错误日志和堆栈。

要求：
1. 先只读排查，不修改文件。
2. 每个子代理给出最可能原因和证据。
3. 主会话汇总后，只提出一个最小修复方案。

场景 4：文档或规范大规模整理

适合让不同子代理读不同部分，再汇总。

请用 Subagents 并行整理 docs 目录。

拆分方式：
1. 一个子代理检查安装类文档。
2. 一个子代理检查配置类文档。
3. 一个子代理检查实战案例文档。
4. 一个子代理检查排障文档。

要求：
1. 只读，不修改。
2. 每个子代理找出过期、重复、缺步骤的地方。
3. 主会话最后给出一份整理计划，不直接改文件。

什么时候不要用 Subagents

下面这些场景不建议用：

1. 小任务

比如：

• 改一个按钮文案。
• 修一个 CSS 间距。
• 补一段 README。
• 改一个简单接口字段。

这些交给一个 Codex 会话就好。 Subagents 会把简单任务复杂化。

2. 强依赖顺序的任务

比如：

先改数据库字段 -> 再改后端接口 -> 再改前端页面 -> 再改文档

这类任务需要按顺序推进。 并行拆开容易出现前后不一致。

3. 多个代理同时写同一批文件

这是新手最容易踩坑的地方。

不要这样说：

派 4 个子代理同时优化首页样式。

因为 4 个代理可能同时改同一个 CSS、同一个组件、同一个布局。 最后主会话要合并冲突，反而更慢。

更稳的方式是：

先让 3 个子代理只读评审首页问题。
主会话汇总后，只让一个代理执行最终修改。

4. 你还说不清验收标准

如果你自己都不知道最后要什么，不要把任务拆给多个代理。 多个代理会把模糊问题放大。

先让 Codex 在主会话里帮你澄清：

我还不确定这个任务应该怎么拆。
请先不要使用 Subagents。
请帮我把目标、范围、风险和验收标准问清楚。

Subagents 和主会话怎么分工

你可以这样理解：

角色	负责什么
主会话	目标、限制、拆分、最终判断、最终交付
子代理	独立方向的探索、检查、总结
你	批准范围、判断风险、验收结果

不要把最终判断完全交给子代理。 子代理的输出应该回到主会话，由主会话统一汇总。

一个合格的 Subagents 提示词长什么样

最少要写清 6 件事：

1. 是否明确要求使用 Subagents。
2. 拆成几个子代理。
3. 每个子代理负责什么。
4. 每个子代理能不能修改文件。
5. Codex 是否要等所有子代理完成。
6. 最终汇总格式是什么。

模板：

请使用 Subagents 并行处理这个任务。

任务背景：
【说明当前任务是什么】

拆分方式：
1. 子代理 A：只负责【方向 A】。
2. 子代理 B：只负责【方向 B】。
3. 子代理 C：只负责【方向 C】。

限制：
1. 所有子代理先只读分析，不修改文件。
2. 不要提交 Git。
3. 不要安装依赖。
4. 不要联网，除非你先说明原因并请求确认。

汇总要求：
1. 等所有子代理完成后再回复。
2. 每个方向最多输出 5 条结论。
3. 每条结论必须带证据。
4. 最后给出“建议下一步”，但不要直接执行。

第一次学习 Subagents 应该怎么练

第一次不要练“并行改代码”。 先练“并行只读评审”。

推荐练习任务：

请用 Subagents 并行只读评审当前项目。

拆分方式：
1. 一个子代理看项目结构是否清晰。
2. 一个子代理看文档是否缺步骤。
3. 一个子代理看构建和脚本说明是否清楚。

限制：
1. 所有子代理只读，不修改文件。
2. 不运行安装命令。
3. 不提交 Git。
4. 等所有子代理完成后再汇总。

汇总格式：
1. 先给总体判断。
2. 再按三个方向列出发现。
3. 每条发现都带文件路径或证据。
4. 最后给出一个最小改进建议，不要执行。

这个练习的好处是：

• 风险低。
• 不会产生文件冲突。
• 能看到并行分析的价值。
• 能训练你写拆分指令。

如何查看子代理

在 CLI 里，可以使用：

/agent

它用于切换或查看 agent thread。

你第一次用时重点看：

• 子代理有没有按你指定的方向工作。
• 有没有子代理偏题。
• 有没有子代理请求权限。
• 有没有子代理尝试修改文件。
• 主会话最后有没有等待所有结果。

如果某个子代理偏题，你可以让主会话处理：

请停止偏题的子代理，并说明它偏离了哪条限制。
不要让它继续修改或执行命令。

权限和沙盒要注意什么

官方手册里有一个关键点：

Subagents 会继承当前会话的 sandbox policy。

这意味着：

• 如果当前会话是受限的，子代理也会受限。
• 如果当前会话放得很开，子代理也可能继承较宽权限。
• 子代理里的权限请求可能从非当前线程冒出来。

所以新手练习时要写清：

所有子代理只读分析，不修改文件，不提交 Git，不安装依赖。

如果出现权限请求，不要顺手批准。 先问：

这个权限请求来自哪个子代理？
它为什么需要这个权限？
它是否违反了“只读分析”的限制？
如果不批准，会影响最终只读评审吗？

和 AGENTS.md、Skills、Hooks 的区别

能力	适合做什么	不适合做什么
AGENTS.md	写项目长期规则	并行拆任务
Skill	复用一套工作方法	自动插入生命周期
Hook	在生命周期自动检查或提醒	大范围任务拆分
Subagents	并行探索、评审、总结	小任务、并行抢同一批文件

它们不是谁替代谁。 成熟工作流通常是组合使用：

AGENTS.md 写项目规则
Skill 复用任务方法
Hook 做低风险自动提醒
Subagents 并行处理大型只读分析
主会话负责最终决策

本篇验收标准

读完本篇，你应该能回答：

• Subagents 是什么。
• 它为什么能减少主会话噪音。
• 为什么它不会自动启动。
• 为什么它比单会话更消耗 token。
• 哪些任务适合 Subagents。
• 哪些任务不要用 Subagents。
• 第一次练习为什么应该只读评审。
• /agent 是用来干什么的。
• 子代理权限请求为什么不能顺手批准。

如果这些都能说清楚，下一篇就可以正式做第一次 Subagents 只读评审练习。