跳到主要内容

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

Subagents

在 Codex 中使用 subagent 和自定义 agent

Codex 可以通过并行生成专门的 agent，然后在一个响应中汇总它们的结果，来运行 subagent 工作流。这对于高度并行的复杂任务尤其有帮助，例如探索代码库或实现多步骤功能计划。

通过 subagent 工作流，你还可以根据任务定义具有不同模型配置和指令的自定义 agent。

有关 subagent 工作流背后的概念和权衡，包括上下文污染、上下文腐坏以及模型选择指导，请参阅 Subagent concepts。

可用性​

当前的 Codex 版本默认启用 subagent 工作流。

subagent 活动目前会显示在 Codex app 和 CLI 中。在 IDE Extension 中的可见性 即将推出。

只有在你明确要求时，Codex 才会生成 subagent。由于每个 subagent 都会执行自己的模型和工具工作，因此与可比的单 agent 运行相比，subagent 工作流会消耗更多 token。

典型工作流​

Codex 负责跨 agent 的编排，包括生成新的 subagent、 路由后续指令、等待结果以及关闭 agent 线程。

当许多 agent 正在运行时，Codex 会等到所有请求的结果都 可用后，再返回一个整合后的响应。

只有在你明确要求 Codex 这样做时，它才会生成新的 agent。

要查看其实际效果，请在你的项目上尝试以下提示词：

I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

管理 subagent​

  • 在 CLI 中使用 /agent 可在活动的 agent 线程之间切换，并检查正在进行的线程。
  • 直接请求 Codex 引导正在运行的 subagent、停止它，或关闭已完成的 agent 线程。

审批与沙箱控制​

subagent 会继承你当前的沙箱策略。

在交互式 CLI 会话中，即使你正在查看主线程，来自非活动 agent 线程的审批请求也可能会显示出来。审批覆盖层会显示来源线程标签，你可以按 o 打开该线程，然后 再批准、拒绝或回复该请求。

在非交互式流程中，或者任何运行无法显示新的审批时，任何 需要新审批的操作都会失败，Codex 会将该错误反馈回父工作流。

当 Codex 生成子级时，它还会重新应用父级回合中的实时运行时覆盖设置。这包括你在会话期间交互式设置的沙箱和审批选择，例如 /permissions 更改或 --yolo，即使所选的 自定义 agent 文件设置了不同的默认值也是如此。

你也可以为单独的 custom agents 覆盖沙箱配置，例如明确将某一个标记为以只读模式工作。

自定义 agent​

Codex 内置以下 agent：

  • default：通用后备 agent。
  • worker：专注执行的 agent，用于实现和修复。
  • explorer：以读取为主的代码库探索 agent。

要定义你自己的自定义 agent，请在 ~/.codex/agents/（个人 agent）或 .codex/agents/（项目范围 agent）下添加独立的 TOML 文件。

每个文件定义一个自定义 agent。Codex 将这些文件作为已生成会话的配置层加载，因此自定义 agent 可以覆盖与普通 Codex 会话配置相同的设置。这可能会比专用的 agent 清单显得更重，并且随着编写和共享方式的成熟，该格式可能会演进。

每个独立的自定义 agent 文件都必须定义：

  • name
  • description
  • developer_instructions

像 nickname_candidates、model、 model_reasoning_effort、sandbox_mode、mcp_servers 和 skills.config 这样的可选字段，如果省略，则会从父会话继承。

全局设置​

全局 subagent 设置仍位于你的 configuration 中的 [agents] 下。

字段类型必填用途
agents.max_threadsnumber否并发打开的 agent 线程上限。
agents.max_depthnumber否生成的 agent 嵌套深度（根会话从 0 开始）。
agents.job_max_runtime_secondsnumber否spawn_agents_on_csv 作业中每个 worker 的默认超时时间。

说明：

  • 如果未设置，agents.max_threads 默认为 6。
  • agents.max_depth 默认为 1，这允许直接子 agent 生成，但会阻止更深层嵌套。除非你确实需要递归委派，否则请保持默认值。提高该值可能会让广泛的委派指令变成重复的扇出，从而增加 token 使用量、延迟和本地资源消耗。agents.max_threads 仍然会限制并发打开的线程数，但它并不能消除更深层递归带来的成本和可预测性风险。
  • agents.job_max_runtime_seconds 是可选项。如果未设置，spawn_agents_on_csv 会回退到其每次调用的默认超时时间，即每个 worker 1800 秒。
  • 如果某个自定义 agent 名称与内置 agent（如 explorer）匹配，则你的自定义 agent 优先。

自定义 agent 文件 schema​

字段类型必填用途
namestring是Codex 在生成或引用此 agent 时使用的 agent 名称。
descriptionstring是面向用户的说明，用于指示 Codex 何时应使用此 agent。
developer_instructionsstring是定义 agent 行为的核心指令。
nickname_candidatesstring[]否为生成的 agent 提供可选的显示昵称池。

你也可以在自定义 agent 文件中包含其他受支持的 config.toml 键，例如 model、model_reasoning_effort、sandbox_mode、mcp_servers 和 skills.config。

Codex 通过其 name 字段识别自定义 agent。让文件名与 agent 名称一致是最简单的约定，但 name 字段才是唯一真实来源。

显示昵称​

当你希望 Codex 为生成的 agent 分配更易读的显示 名称时，请使用 nickname_candidates。当你运行许多 相同自定义 agent 的实例，并希望 UI 显示不同标签而不是重复相同 agent 名称时，这尤其有帮助。

昵称仅用于展示。Codex 仍然通过 其 name 来识别和生成 agent。

昵称候选项必须是一个非空且名称唯一的列表。每个昵称都可以 使用 ASCII 字母、数字、空格、连字符和下划线。

示例：

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.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]

在实际使用中，Codex app 和 CLI 可以在显示 agent 活动的位置显示这些昵称，而底层的 agent 类型仍然是 reviewer。

自定义 agent 示例​

最好的自定义 agent 应该是范围狭窄且有明确倾向的。为每个 agent 赋予清晰的职责、与职责匹配的工具范围，以及防止它偏离到相邻工作的指令。

示例 1：PR 评审​

这种模式将评审拆分给三个聚焦的自定义 agent：

  • pr_explorer：映射代码库并收集证据。
  • reviewer：查找正确性、安全性和测试风险。
  • docs_researcher：通过专用 MCP server 检查框架或 API 文档。

项目配置（.codex/config.toml）：

[agents]
max_threads = 6
max_depth = 1

.codex/agents/pr-explorer.toml：

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
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 for them.
Prefer fast search and targeted file reads over broad scans.
"""

.codex/agents/reviewer.toml：

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.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""

.codex/agents/docs-researcher.toml：

name = "docs_researcher"
description = "文档专家，使用 docs MCP 服务器验证 API 和框架行为。"
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
使用 docs MCP 服务器确认 API、选项以及特定版本的行为。
在可用时返回带链接或精确引用的简明答案。
不要进行代码修改。
"""

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

此设置很适合如下提示：

根据 main 审查这个分支。让 pr_explorer 梳理受影响的代码路径，让 reviewer 找出真实风险，并让 docs_researcher 验证补丁所依赖的框架 API。

使用 subagents 处理 CSV 批次（实验性）​

此工作流是实验性的，可能会随着 subagent 支持的演进而变化。 当你有许多相似任务，并且每个工作项可映射为 CSV 中的一行时，请使用 spawn_agents_on_csv。Codex 会读取 CSV，为每一行生成一个 worker subagent，等待整个批次完成，并将合并后的结果导出为 CSV。

这很适合以下重复性审查场景：

  • 每行审查一个文件、包或服务
  • 检查一组事件、PR 或迁移目标
  • 为大量相似输入生成结构化摘要

该工具接受以下参数：

  • csv_path：源 CSV 的路径
  • instruction：worker 提示模板，使用 {column_name} 占位符
  • id_column：当你想从特定列获取稳定的条目标识时使用
  • output_schema：当每个 worker 应返回固定结构的 JSON 对象时使用
  • output_csv_path、max_concurrency 和 max_runtime_seconds：用于作业控制

每个 worker 必须且只能调用一次 report_agent_job_result。如果 worker 在未报告结果的情况下退出，Codex 会在导出的 CSV 中将该行标记为错误。

提示示例：

创建 /tmp/components.csv，包含列 path,owner，并为每个前端组件写入一行。

然后调用 spawn_agents_on_csv，并传入：
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."
- output_csv_path: /tmp/components-review.csv
- output_schema: 一个对象，必需的字符串字段包括 path、risk、summary 和 follow_up

当你通过 codex exec 运行它时，Codex 会在批处理运行期间在 stderr 上显示单行进度更新。导出的 CSV 包含原始行数据，以及诸如 job_id、item_id、status、last_error 和 result_json 之类的元数据。

相关运行时设置：

  • agents.max_threads 限制可同时保持打开状态的 agent 线程数量。
  • agents.job_max_runtime_seconds 设置 CSV 扇出作业中每个 worker 的默认超时时间。每次调用的 max_runtime_seconds 覆盖会优先生效。
  • sqlite_home 控制 Codex 存储基于 SQLite 的状态的位置，该状态用于 agent 作业及其导出结果。

示例 2：前端集成调试​

这种模式适用于 UI 回归、不稳定的浏览器流程，或跨越应用代码与运行中产品的集成缺陷。

项目配置（.codex/config.toml）：

[agents]
max_threads = 6
max_depth = 1

.codex/agents/code-mapper.toml：

name = "code_mapper"
description = "只读代码库探查器，用于定位相关的前端和后端代码路径。"
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
梳理负责出错 UI 流程的代码。
在 worker 开始编辑之前，识别入口点、状态转换和可能相关的文件。
"""

.codex/agents/browser-debugger.toml：

name = "browser_debugger"
description = "使用浏览器工具复现问题并收集证据的 UI 调试 agent。"
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
在浏览器中复现问题，记录精确步骤，并报告 UI 实际表现。
使用浏览器工具获取截图、控制台输出和网络证据。
不要编辑应用代码。
"""

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20

.codex/agents/ui-fixer.toml：

name = "ui_fixer"
description = "在问题明确后，专注于小范围、针对性修复的实现型 agent。"
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
developer_instructions = """
一旦问题被复现，就负责修复。
进行最小且合理的修改，保持无关文件不变，并且只验证你修改过的行为。
"""

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

此设置很适合如下提示：

调查设置模态框为何保存失败。让 browser_debugger 复现问题，让 code_mapper 追踪负责的代码路径，并在故障模式明确后让 ui_fixer 实施最小修复。