中文 | English

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

借助 subagent 工作流，你还可以根据任务定义自己的自定义 agents，并为其指定不同的模型配置与说明。

关于 subagent 工作流背后的概念与取舍，包括上下文污染、上下文腐化以及模型选择指导，请参阅 Subagent concepts。

可用性

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

目前，Codex app 和 CLI 都会展示 subagent 活动。IDE 扩展中的可见性即将推出。

只有在你明确要求时，Codex 才会生成 subagents。由于每个 subagent 都会执行自己的模型调用和工具操作，subagent 工作流会比同等的单 agent 运行消耗更多 token。

典型工作流

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

当有多个 agents 同时运行时，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

管理 subagents

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

审批与沙箱控制

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

在交互式 CLI 会话中，即使你当前停留在主线程，也可能会看到来自非活动 agent 线程的审批请求。审批覆盖层会显示来源线程标签；在你批准、拒绝或回答请求之前，可以按 o 打开该线程。

在非交互式流程中，或者任何无法弹出新审批的运行里，凡是需要新审批的动作都会失败，Codex 会将错误返回给父工作流。

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

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

自定义 agents

Codex 内置了以下 agents：

• default：通用回退 agent。
• worker：面向执行的 agent，适合实现与修复。
• explorer：偏重读取的代码库探索 agent。

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

每个文件定义一个 custom agent。Codex 会把这些文件作为被生成会话的配置层来加载，因此 custom agents 可以覆盖与普通 Codex session config 相同的设置。与专门的 agent manifest 相比，这种方式可能会显得更重；随着编写与共享方式逐渐成熟，格式也可能继续演化。

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

• name
• description
• developer_instructions

可选字段例如 nickname_candidates、model、model_reasoning_effort、sandbox_mode、mcp_servers 与 skills.config，在省略时会从父 session 继承。

全局设置

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

Field	Type	Required	Purpose
agents.max_threads	number	No	并发打开的 agent 线程上限。
agents.max_depth	number	No	生成的 agent 嵌套深度（根 session 从 0 开始）。
agents.job_max_runtime_seconds	number	No	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 秒的每次调用超时。
• 如果某个 custom agent 的名称与内置 agent（例如 explorer）重名，你的 custom agent 会优先生效。

自定义 agent 文件 schema

Field	Type	Required	Purpose
name	string	Yes	Codex 在生成或引用此 agent 时使用的名称。
description	string	Yes	说明 Codex 何时应使用该 agent 的面向人的指导。
developer_instructions	string	Yes	定义该 agent 行为的核心说明。
nickname_candidates	string[]	No	可选的展示昵称池，用于生成后的 agent。

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

Codex 会通过 name 字段识别 custom agent。让文件名与 agent 名称保持一致，是最简单的约定；但真正的事实来源是 name 字段。

显示昵称

当你希望 Codex 为生成出的 agents 分配更易读的显示名称时，请使用 nickname_candidates。当你运行同一种 custom 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 示例

最好的 custom agents 通常都很窄、且带有明确倾向。给每个 agent 一个清晰的工作职责、一套与职责匹配的工具面，以及一组能避免它漂移到相邻任务上的说明。

示例 1：PR review

这个模式把 review 拆给三个聚焦的 custom agents：

• 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 = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-5.4-mini"
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 when available.
Do not make code changes.
"""

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

这个配置非常适合如下提示：

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.

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

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

这非常适合以下重复性审查：

• 每行审查一个文件、包或服务
• 检查一组 incidents、PRs 或 migration targets
• 为大量相似输入生成结构化摘要

该工具接受以下参数：

• csv_path：源 CSV 的路径
• instruction：worker prompt 模板，可使用 {column_name} 占位符
• id_column：当你希望从某一列获得稳定工作项 id 时使用
• output_schema：当每个 worker 应返回具有固定结构的 JSON 对象时使用
• output_csv_path、max_concurrency 和 max_runtime_seconds：用于任务控制

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

示例提示：

Create /tmp/components.csv with columns path,owner and one row per frontend component.

Then call spawn_agents_on_csv with:
- 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: an object with required string fields path, risk, summary, and 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 fan-out 任务设置每个 worker 的默认超时时间。每次调用传入的 max_runtime_seconds 覆盖项优先级更高。
• sqlite_home 控制 Codex 存放基于 SQLite 的状态的位置，这些状态用于 agent jobs 及其导出结果。

示例 2：前端集成调试

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

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

[agents]
max_threads = 6
max_depth = 1

.codex/agents/code-mapper.toml：

name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Map the code that owns the failing UI flow.
Identify entry points, state transitions, and likely files before the worker starts editing.
"""

.codex/agents/browser-debugger.toml：

name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
"""

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

.codex/agents/ui-fixer.toml：

name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
"""

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

这个配置非常适合如下提示：

Investigate why the settings modal fails to save. Have browser_debugger reproduce it, code_mapper trace the responsible code path, and ui_fixer implement the smallest fix once the failure mode is clear.