跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/concepts/subagents

Subagents

Subagent 工作流如何让 Codex 保持专注，以及如何为不同 agent 选择模型

Codex 可以通过并行生成专门的 agent 来运行 Subagent 工作流，这样它们就能同时进行探索、处理或分析工作。

本页解释核心概念和权衡取舍。有关设置、agent 配置和示例，请参阅 Subagents。

为什么 Subagent 工作流有帮助​

即使拥有很大的上下文窗口，模型也有局限。如果你用嘈杂的中间输出（例如探索笔记、测试日志、堆栈跟踪和命令输出）淹没主对话（你在其中定义需求、约束和决策的地方），随着时间推移，会话的可靠性可能会降低。

这通常被描述为：

  • 上下文污染：有用信息被嘈杂的中间输出掩盖。
  • 上下文腐化：随着对话被不太相关的细节填满，性能会下降。

有关背景信息，请参阅 Chroma 关于 context rot 的文章。

Subagent 工作流通过将嘈杂工作移出主线程来提供帮助：

  • 让 main agent 专注于需求、决策和最终输出。
  • 并行运行专门的 subagents 来进行探索、测试或日志分析。
  • 从 subagents 返回摘要，而不是原始中间输出。

当工作可以独立并行运行时，它们也能节省时间；并且通过把更大形态的任务拆分为有边界的片段，它们让大型任务更易处理。例如，Codex 可以将对一个数百万 token 文档的分析拆分成较小的问题，并将提炼后的要点返回到主线程。

作为起点，可将并行 agent 用于以读取为主的任务，例如探索、测试、分诊和总结。对于以写入为主的并行工作流要更加谨慎，因为多个 agent 同时编辑代码可能会造成冲突并增加协调开销。

核心术语​

Codex 在 Subagent 工作流中使用了几个相关术语：

  • Subagent workflow：Codex 运行并行 agent 并组合其结果的工作流。
  • Subagent：Codex 启动来处理特定任务的委派 agent。
  • Agent thread：某个 agent 的 CLI 线程，你可以使用 /agent 查看并在线程之间切换。

触发 Subagent 工作流​

Codex 不会自动生成 subagents，并且只有在你明确要求使用 subagents 或并行 agent 工作时，才应该使用 subagents。

在实践中，手动触发意味着使用直接指令，例如“生成两个 agent”、“并行委派这项工作”或“每个点使用一个 agent”。与可比较的单 agent 运行相比，Subagent 工作流会消耗更多 token，因为每个 subagent 都会执行自己的模型和工具工作。

一个好的 Subagent 提示应说明如何划分工作、Codex 是否应在继续之前等待所有 agent 完成，以及应返回什么摘要或输出。

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

选择模型和推理​

不同的 agent 需要不同的模型和推理设置。

如果你没有固定模型或 model_reasoning_effort，Codex 可以为任务选择一种在智能、速度和价格之间取得平衡的配置。对于快速扫描，它可能偏向 gpt-5.4-mini；对于要求更高的推理，则可能选择更高 effort 的 gpt-5.5 配置。当你想要更精细的控制时，可以在提示中引导该选择，或直接在 agent 文件中设置 model 和 model_reasoning_effort。

对于 Codex 中的大多数任务，从 gpt-5.5 开始。若你希望 为较轻量的 Subagent 工作使用更快、成本更低的选项，请使用 gpt-5.4-mini。如果你有 ChatGPT Pro， 并且希望进行几乎即时的纯文本迭代，gpt-5.3-codex-spark 仍可作为研究预览使用。

模型选择​

  • gpt-5.5：对于要求较高的 agent，从这里开始。它最擅长处理需要规划、工具使用、验证以及在更大上下文中持续推进的模糊、多步骤工作。
  • gpt-5.4：当某个工作流固定到 GPT-5.4 时使用。它结合了强大的编码、推理、工具使用和更广泛的工作流能力。
  • gpt-5.4-mini：用于更看重速度和效率而非深度的 agent，例如探索、以读取为主的扫描、大文件审查或处理支持文档。它很适合作为并行工作者，将提炼后的结果返回给 main agent。
  • gpt-5.3-codex-spark：如果你有 ChatGPT Pro，当延迟比更广泛的能力更重要时，可使用这个研究预览模型进行几乎即时的纯文本迭代。

推理 effort（model_reasoning_effort）​

  • high：当 agent 需要追踪复杂逻辑、检查假设或处理边界情况时使用（例如 reviewer 或以安全为重点的 agent）。
  • medium：适用于大多数 agent 的平衡默认值。
  • low：当任务很直接且速度最重要时使用。

更高的推理 effort 会增加响应时间和 token 使用量，但它可以提升复杂工作的质量。有关详细信息，请参阅 Models、Config basics 和 Configuration Reference。