内容阅读

Codex Subagents 深度解析：什么时候拆成多个专业代理，什么时候不要拆

TL;DR

Subagents 适合读多写少、可并行、需要多视角覆盖的工程任务。官方 Codex Subagents 概念页说明，Codex 可以通过启动专业代理并行探索、处理或分析工作，再把摘要返回主线程；但它不会自动生成 subagents，用户需要显式要求并行代理工作。官方还提示，subagent workflow 会消耗更多 token，因为每个子代理都会独立做模型和工具工作。起点应是探索、测试、triage、日志分析、summarization 等读密集任务；写密集并行工作更容易产生冲突和协调成本。

判断是否拆分，不看任务“听起来大不大”，而看子任务是否能独立收集证据、是否需要不同视角或模型、合并结果是否比单线程更可靠。主 agent 不能把最终判断外包给 subagents；它仍要负责分工、去重、冲突裁决、验证和最终输出。

读者定位

本文面向需要用 Codex 处理大型仓库调研、PR review、迁移评估、发布风险、日志分析、方案评审的中高级开发者和技术负责人。你应该熟悉 Codex 会话、沙箱、文件读取、工具调用和基本成本控制。本文不把 subagents 当成“多开几个模型就更聪明”的技巧，而把它当作并行工程组织方式来分析。

如果你的任务是一个线性 bug 修复，前一步结果决定下一步方向，或者主要工作是写同一批文件，先不要拆。并行代理在这类任务里往往会增加冲突、重复读取和合并成本。

问题：单线程 Codex 会话在大任务里会遇到什么瓶颈

一个 Codex 会话处理小任务很高效：读相关文件、做修改、跑测试、总结结果。但任务范围扩大后，单线程会话会出现三个问题。

第一是上下文污染。大型调研会产生大量中间输出：搜索结果、测试日志、堆栈、失败命令、候选文件、未采用方案。官方文档把这类问题称为 context pollution 和 context rot：主会话里混入太多低价值中间信息后，关键需求、约束和决策容易被埋掉，后续判断变差。

第二是视角单一。比如审查支付系统改造，需要 API 兼容、数据库迁移、幂等、权限、审计、测试、部署和回滚多个视角。一个 agent 串行处理时，容易把前一个视角的假设带到后一个视角，也容易在长任务后期疲劳式总结。

第三是等待时间长。读多个模块、跑多组测试、分析多份日志本来可以并行。如果全部串行，用户等待时间增加，主线程也会装进大量中间过程。

Subagents 的价值是把噪声和探索分流：让专门代理在独立线程里做读密集工作，返回压缩后的证据和结论，主 agent 保持在需求、决策、合并和最终输出上。

心智模型：主 agent 是负责人，subagents 是调查员

把 subagent workflow 想成一次工程评审会。主 agent 是负责人，负责定义问题、划分领域、设置输出格式、等待结果、识别冲突、决定下一步。Subagents 是调查员，负责在自己的范围内收集证据、运行检查、给出有限结论。

这个分工有两个原则。

第一，子代理拿到的是窄任务，不是“全面审查”。例如不要启动三个代理都说“全面检查这个 PR”。更好的分工是：一个代理只看 API 兼容性，一个代理只看数据迁移和回滚，一个代理只看测试覆盖和 CI。范围越窄，结果越可比较。

第二，子代理返回摘要，不返回大量原始日志。官方文档强调 subagents 帮助把 noisy work 移出主线程，返回 summaries 而不是原始中间输出。主 agent 需要证据文件、关键行、命令和不确定项，但不需要每个 grep 输出和完整日志。

主 agent 不能把责任推给“多数代理意见”。如果 API agent 说可合，Data agent 发现迁移无回滚，Test agent 说覆盖不足，主 agent 要合并成明确风险，而不是简单列出三段报告。冲突是 subagent workflow 的正常产物，裁决才是主 agent 的工作。

官方机制：显式触发、线程可见性、模型和 reasoning

官方 Subagents 概念页给出几个关键点。第一，Codex 可以启动专业代理并行探索、处理或分析工作。第二，subagent workflow、subagent、agent thread 是相关术语；CLI 中 agent thread 可通过 /agent 检查和切换。第三，Codex 不会自动启动 subagents，应在用户明确要求 subagents 或 parallel agent work 时使用。第四，好的 subagent prompt 应说明怎样拆分、是否等待所有代理、返回什么摘要。第五，不同代理可使用不同模型和 reasoning effort；官方建议大多数任务从 gpt-5.5 开始，轻量子代理可用 gpt-5.4-mini，model_reasoning_effort 可按 high、medium、low 调整。

这些事实会影响团队用法。不要写模糊 prompt：“多开几个代理看一下”。要写具体分工：“Spawn one subagent for security risks, one for test gaps, one for maintainability. Wait for all three, then summarize findings by category with file references.” 官方文档也提醒，subagents 会消耗更多 token；并行不是免费加速，尤其是多个代理读相同大文件时。

适合拆分的任务类型

第一类是大型 PR review。一个代理看安全和权限，一个看测试缺口，一个看兼容性和迁移，一个看可维护性。主 agent 最后输出按严重程度排序的 findings，并标出各代理之间是否有冲突。

第二类是跨模块迁移评估。比如从旧鉴权库迁到新框架。可以让一个代理看调用点，一个看配置和环境变量，一个看测试与 CI，一个看文档和发布流程。每个代理只读相关路径，减少重复。

第三类是日志和事故 triage。多个代理可以分别分析应用日志、数据库日志、部署事件和最近代码变更。主 agent 合并时间线和根因候选。

第四类是方案评审。一个代理从性能角度评估，一个从安全角度评估，一个从可运维角度评估。注意这类任务要输出证据和假设，不能只写观点。

第五类是大规模文档或代码库索引。多个代理按目录分片阅读，返回结构化摘要。主 agent 合并成地图、风险列表或迁移计划。

不适合拆分的任务包括：单文件修复、需要逐步调试的 bug、多个代理会修改同一文件的实现任务、需求尚不清楚的探索、需要用户频繁确认的设计讨论。这些场景中，单线程更可控。

如何写 subagent prompt

一个可用的 subagent prompt 至少包含六部分。

范围：每个代理看哪些目录、文件、日志或维度。范围不能重叠过多。

权限：默认只读还是允许写文件。调查型代理默认只读，避免并行写冲突。

任务：每个代理要回答什么问题，不要给所有代理同一个宽任务。

证据：要求返回文件路径、关键代码、命令、日志片段或无法验证项。

输出格式：统一字段，方便主 agent 合并。

合并规则：主 agent 是否等待所有代理，怎样处理冲突，最终输出什么。

示例：

请启动 3 个 subagents 并行审查当前分支。所有子代理默认只读，不要修改文件。

1. API agent：只关注 public API、路由、请求/响应兼容性和调用方影响。
2. Data agent：只关注数据库迁移、数据一致性、回滚和后台任务。
3. Test agent：只关注测试覆盖、CI 配置、缺失边界用例和可运行验证。

每个代理返回：检查范围、关键发现、证据文件、无法确认项、建议动作。等待全部完成后，由主 agent 合并成按严重程度排序的 findings，并标出代理结论冲突。

这个 prompt 有几个设计点：明确数量、明确只读、明确范围、统一输出、要求等待和合并。它比“用 subagents 全面检查”可靠得多。

自定义 subagents 和团队模板

如果团队经常做同类拆分，可以把 subagent 分工沉淀成模板或配置。官方 Codex 导航中有 Subagents 配置页面，概念页也提到可按模型和 instructions 选择不同代理。团队可以维护常见角色：security-reviewer、test-gap-reviewer、migration-reviewer、docs-reviewer、log-triage-agent。每个角色都应有窄职责、默认模型、默认 reasoning effort、默认输出格式。

不要把角色做成“万能专家”。比如 senior-engineer 这种名字没有边界。更好的名字是 api-compat-reviewer。职责越窄，主 agent 越容易组合。

模板还应规定默认权限。读密集代理默认 read-only；只有主实现 agent 或经过用户确认的修复 agent 才允许写。并行写入同一仓库很容易冲突，尤其是多个代理同时格式化、修改测试或更新快照时。

模型与 reasoning 分层

官方 Models 页面截至 2026-06-22 推荐 gpt-5.5 作为多数复杂 Codex 任务的起点，gpt-5.4-mini 用于更快、更低成本的轻量任务或 subagents，gpt-5.3-codex-spark 是面向 ChatGPT Pro 用户的文本-only research preview，适合近实时迭代。Subagents 概念页也说明，如果不固定模型或 model_reasoning_effort，Codex 可按任务在智能、速度和价格之间平衡；也可以在 prompt 或 agent 文件里直接指定。

工程上可以这样分层：主 agent 负责需求、计划、合并和裁决，使用更强模型和 medium/high reasoning；探索型子代理负责查文件、列证据、整理日志，可用更快模型和 low/medium reasoning；安全、并发、权限、数据一致性等高风险子代理用 high reasoning；最终修改和验证再回到主 agent。

不要把所有子代理都设成最高配置。并行任务的成本是乘法。也不要把所有代理都设成轻量配置；高风险结论如果错了，后续返工和事故成本更高。模型选择要跟任务风险绑定。

真实工作流案例：支付系统改造评审

一个团队准备合并支付系统回调处理改造。变更涉及 API 路由、幂等表、消息队列、重试策略、审计日志和前端状态展示。单线程 review 容易漏。

主 agent prompt：

请用 subagents 并行评审当前支付回调改造。所有子代理只读。等待全部完成后输出阻塞项、非阻塞风险和需要人工确认的问题。

API agent：检查路由、请求校验、响应兼容和调用方影响。
Data agent：检查幂等表、迁移、事务边界、回滚和数据一致性。
Reliability agent：检查重试、队列、超时、告警和重复消息。
Test agent：检查单测、集成测试、回归用例和 CI 覆盖。

子代理返回后，主 agent 可能得到这些结果：API agent 没发现兼容性问题；Data agent 发现迁移缺少回滚；Reliability agent 发现重复消息测试缺失；Test agent 发现 CI 没跑集成测试。最终输出不能写“四个代理报告如下”，而应合并：

阻塞：迁移缺少回滚路径，影响发布恢复能力。
阻塞或高风险：重复消息路径缺测试，支付回调可能重复入账。
未确认：CI 未运行集成测试，需要指定命令或手动验证。
可接受：API 兼容性未见直接问题，但建议调用方抽样验证。

这才体现主 agent 的裁决价值。

操作清单

任务是否能拆成相互独立的调查范围。
每个 subagent 是否有不同视角，而不是重复“全面检查”。
调查型 subagents 是否默认只读。
prompt 是否写明等待全部代理还是允许先返回。
每个代理是否返回统一字段：范围、发现、证据、未确认项、建议。
主 agent 是否负责合并、去重、冲突裁决和最终排序。
是否预估并行 token 成本和重复读取成本。
高风险代理是否使用更合适的模型和 reasoning effort。
写密集任务是否避免多个代理同时改同一文件。
常见分工是否沉淀为团队模板或 Skill。

权衡与风险

Subagents 提升的是并行探索、覆盖面和主线程清洁度，不保证结论更正确。多个代理可能同时漏掉同一类问题，也可能给出互相矛盾的建议。主 agent 必须以证据为准，而不是以代理数量投票。

并行会增加成本。每个子代理都可能读取文件、调用工具、产生推理 token。对于小任务，启动 subagents 的开销可能超过收益。

并行写入风险高。即使每个代理都做得对，合并改动也可能冲突。写密集工作应先分支或分阶段，必要时让一个代理生成计划，主 agent 串行实施。

可见性也要考虑。CLI 中可以检查和切换 agent thread；不同界面的 subagent 可见性和成熟度应以当前官方文档为准。团队流程不要依赖未确认的界面行为。

常见误区

误区一：为了“更认真”启动 subagents。拆分必须服务于独立调查和多视角覆盖。

误区二：给每个代理同一个任务。这样只会得到重复报告。

误区三：主 agent 不合并。让用户自己读多个报告不是有效代理协作。

误区四：忽略只读默认。调查型代理不需要写权限。

误区五：所有代理都用最高模型。并行成本会快速上升。

误区六：把 subagents 当自动触发机制。官方文档说明需要显式要求 subagents 或 parallel agent work。

合并阶段：主 agent 应怎样处理子代理结果

Subagents 的成败很大程度取决于合并阶段。很多失败的并行流程不是子代理没工作，而是主 agent 把多个结果原样贴给用户，没有完成裁决。

合并第一步是去重。多个代理可能发现同一问题，只是表达不同。比如 API agent 说“字段缺少兼容处理”，Test agent 说“旧字段测试缺失”，Data agent 说“旧数据回填未覆盖”。主 agent 要判断它们是不是同一风险链路。如果是，应合并成一个更完整的 finding，而不是输出三条重复问题。

合并第二步是分级。子代理可能按自己的领域判断严重程度，主 agent 要从整体影响重新排序。一个测试缺口在普通页面可能是中风险，在支付回调或权限变更中可能是高风险。严重程度不能只看代理标签，要结合业务影响、可恢复性和验证状态。

合并第三步是冲突裁决。一个代理说无风险，另一个代理说有风险，主 agent 不能用“存在不同意见”结束。它应引用双方证据，说明哪一边更可信，或标为未确认并提出下一步验证。冲突本身就是有价值信号。

合并第四步是补验证。子代理多为读密集调查，最终建议仍应落到验证命令或人工检查点。比如“运行迁移回滚测试”“抽样调用旧 API”“用旧 fixture 跑集成测试”。没有验证路径的并行报告难以转化为行动。

合并第五步是控制输出长度。子代理可能各自返回很多细节，主 agent 应保留关键证据，把完整中间内容压缩。用户需要最终判断、证据和下一步，不需要所有探索过程。

并行写入的替代方案

有些团队希望让多个 subagents 同时修不同模块。这个想法有时可行，但要非常谨慎。更稳的替代方案有三种。

第一，先并行只读，后串行写入。多个子代理分别调查 API、数据、测试和文档，主 agent 合并计划后，一个实现代理按计划修改。这样能保留并行探索收益，又避免写冲突。

第二，按目录隔离写入。如果确实要并行写，必须严格限制每个代理的文件范围，并在最终阶段统一合并和测试。例如一个代理只能改文档，一个只能改测试，一个只能改生成代码。即便如此，格式化、公共快照和配置文件仍可能冲突。

第三，用 patch 候选而不是直接写。子代理生成建议 patch 或 diff 草案，主 agent 选择和应用。这样可以在合并前 review 冲突和质量，但会增加流程复杂度。

写密集任务的核心不是“能不能并行”，而是“合并成本是否低于串行成本”。如果最终要花大量时间解决冲突、重复测试和回滚，并行就不划算。

成本预算：启动前先估算并行规模

Subagents 的 token 和工具成本通常按代理数量增长。团队可以在 prompt 前做一个简单预算。

小规模：2 到 3 个子代理，每个代理只读少量目录，适合 PR review、日志分类、文档分片。一般收益明显，成本可控。

中规模：4 到 6 个子代理，适合大型迁移评估或多系统事故复盘。需要更严格输出格式和主 agent 合并策略，否则报告会变散。

大规模：超过 6 个子代理，通常需要明确分片、预算和停止条件。否则多个代理会重复搜索、读取同一文件、产出相似结论。大规模并行更像项目管理，不是一次普通 prompt。

估算时要看每个代理的文件范围、是否运行命令、是否需要网络、是否使用高 reasoning。轻量代理读取少量文件的成本不高；高 reasoning 代理读全仓库并运行测试，成本会很快上升。

团队可以要求主 agent 在启动 subagents 前先给出分工和成本预估，用户确认后再执行。对高风险或高成本任务，这个确认步骤很有用。

适合沉淀为模板的 subagent 组合

常用组合可以写进团队 Skill 或 prompt 模板。

PR 综合 review：security agent、test agent、maintainability agent。适合中等到大型 PR。

发布检查：config agent、migration agent、rollback agent、test agent、docs agent。适合 release readiness。

事故复盘：timeline agent、log agent、recent-change agent、dependency agent。适合跨系统故障。

迁移评估：call-site agent、compatibility agent、data agent、test agent、docs agent。适合框架或 SDK 升级。

文档重构：navigation agent、link agent、content-gap agent、style agent。适合大型文档库。

每个组合都应写明默认只读、输出字段和主 agent 合并要求。模板不是为了减少思考，而是为了避免每次临时拆分时漏掉边界。

验证策略：并行结论如何落到工程证据

Subagents 返回的结论必须经过验证设计。并行调查往往能找到更多线索，但线索不等于结论。主 agent 合并后，应把每个重要 finding 转成至少一种验证方式。

代码层验证包括读取实现、调用点、类型定义、迁移脚本和测试。命令层验证包括运行单测、集成测试、lint、类型检查、静态扫描或项目自带脚本。流程层验证包括检查发布说明、回滚步骤、监控告警、owner 确认。无法验证时，要明确写入未确认项。

验证也可以分给 subagents，但最终由主 agent 决定是否足够。比如 Test agent 说测试覆盖不足，主 agent 可以要求它指出具体缺失用例；Data agent 说迁移有风险，主 agent 要求列出回滚证据或缺失证据。不要让“某代理认为有问题”直接变成阻塞结论。

在高风险任务中，主 agent 可以先让子代理只读取证，再请求用户确认是否进入验证命令阶段。这样能避免多个代理同时运行昂贵或有副作用的命令。验证命令本身也要受沙箱和审批控制。

最终报告应把结论和验证状态绑定。例如“已通过单测验证”“仅基于代码阅读，未运行集成测试”“缺少生产配置访问，无法确认”。这种表达比单纯写“风险较低”更有工程价值。

人类协作：何时让用户介入

Subagent workflow 中有几个适合暂停并让用户介入的点。第一是拆分计划。如果任务大、成本高或会触碰高风险目录，主 agent 应先提出代理分工，让用户确认。第二是权限升级。如果从只读调查转向写文件或运行昂贵测试，应请求明确授权。第三是冲突结论。如果代理给出相反证据，主 agent 应说明冲突，并建议验证路径，而不是擅自选择。第四是最终执行。如果输出包含修复方案，用户应决定是否进入实现。

这种介入不是降低自动化效率，而是把人放在决策节点。Subagents 擅长并行收集和压缩信息，人类擅长判断业务优先级、风险承受和组织约束。两者边界清楚，协作才稳定。

延伸阅读

GitHub 原文：35-codex-subagents.md

0 条

登录后可以参与评论和讨论。

去登录

还没有评论

欢迎留下第一条评论，帮助这篇内容更快形成讨论。