OpenAI Codex 的 Subagents 适合把代码库探索、PR review、修复排查这类复杂任务拆成多个专业 Agent 并行处理，再汇总成一个结果。当前版本默认启用子代理；在 Codex app 和 CLI 可见活动记录，IDE Extension 还在补充中。自定义 Agent 通过 .codex/agents/ 或 ~/.codex/agents/ 的 TOML 文件配置，max_depth 默认是 1，max_threads 默认是 6。

OpenAI Codex 子代理配置与并行工作流

Codex 可以并行启动多个子代理（Subagents），让不同 Agent 分别处理不同子任务，然后把结果汇总成一条回复。这个模式特别适合复杂且高度并行的任务，比如代码库探索、分步骤功能实现、PR review、调试并修复问题和批量重复检查。

你也可以为不同任务定义自己的自定义 Agent，并分别指定模型、指令和沙箱策略。

子代理只会在你明确要求时启动。每个子代理都会做自己的模型调用和工具操作，所以子代理工作流的 token 消耗通常比单 Agent 运行更高。

可用性

当前 Codex 版本默认启用子代理工作流。

子代理活动目前会在 Codex app 和 CLI 中显示。IDE Extension 里显示子代理活动的能力即将上线。

常见工作流

Codex 负责多个 Agent 之间的编排，包括启动新的子代理、转发后续指令、等待结果，以及关闭 agent 线程。

当同时运行很多 Agent 时，Codex 会等到所有请求结果都可用后，再返回一个汇总响应。

Codex 只有在你明确要求时才会生成新 Agent。

可以在自己的项目里试试下面这段 prompt：

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

如何管理子代理

在 CLI 中使用 /agent 切换当前活动的 agent thread，并查看正在进行中的线程。
也可以直接让 Codex 去调整正在运行的子代理、停止它，或者关闭已经完成的 agent thread。

审批与沙箱控制

子代理会继承当前的 sandbox policy。

在交互式 CLI 会话里，即使你正在看主线程，非活动 agent thread 也可能弹出审批请求。审批覆盖层会显示来源线程标签，你可以按 o 打开对应线程，然后再执行 approve、reject 或答复请求。

在非交互流程里，或者任何无法展示新审批的运行中，需要新审批的动作都会失败，Codex 会把错误回传给父工作流。

Codex 在生成子代理时，也会重新应用父 turn 当前生效的运行时覆盖项，包括你在会话中交互式设置的 sandbox 和 approval 选项，例如 /permissions 变更或 --yolo，即使选中的自定义 agent 文件里写了不同默认值也是如此。

你也可以为单个 custom agents 覆盖 sandbox 配置，例如显式指定某个 agent 以 read-only 模式运行。

自定义 Agent

Codex 自带以下内置 Agent：

default：通用兜底 agent。
worker：偏执行，适合实现和修复。
explorer：偏只读，适合代码库探索。

要定义自己的自定义 Agent，可以在 ~/.codex/agents/ 下放置独立的 TOML 文件作为个人 agent，或者在 .codex/agents/ 下放置项目级 agent 文件。

每个文件定义一个自定义 Agent。Codex 会把这些文件当作 spawned session 的配置层，因此自定义 agent 可以覆盖普通 Codex session config 里的相同设置。相比专门的 agent manifest，这种格式会更重一些，而且随着编写和共享流程成熟，格式也可能继续演进。

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

name
description
developer_instructions

像 nickname_candidates、model、model_reasoning_effort、sandbox_mode、mcp_servers 和 skills.config 这类可选字段，如果不写，会从父会话继承。

全局设置

全局子代理设置仍然放在 configuration 的 [agents] 下。

Field	Type	Required	Purpose
`agents.max_threads`	number	No	Concurrent open agent thread cap.
`agents.max_depth`	number	No	Spawned agent nesting depth (root session starts at 0).
`agents.job_max_runtime_seconds`	number	No	Default timeout per worker for `spawn_agents_on_csv` jobs.

Notes:

agents.max_threads 不设置时默认是 6。
agents.max_depth 默认是 1，这允许直接子代理再生成，但会阻止更深层嵌套。除非你确实需要递归式委派，否则建议保留默认值。提高这个值会让宽泛的委派指令反复分叉，增加 token 用量、延迟和本地资源消耗。agents.max_threads 仍然会限制并发打开的线程数，但它不能消除更深递归带来的成本和可预测性风险。
agents.job_max_runtime_seconds 是可选项。留空时，spawn_agents_on_csv 会回退到每个 worker 默认 1800 秒超时。
如果自定义 agent 名称与内置 agent（例如 explorer）重名，自定义 agent 会优先生效。

自定义 Agent 文件 schema

Field	Type	Required	Purpose
`name`	string	Yes	Agent name Codex uses when spawning or referring to this agent.
`description`	string	Yes	Human-facing guidance for when Codex should use this agent.
`developer_instructions`	string	Yes	Core instructions that define the agent’s behavior.
`nickname_candidates`	string[]	No	Optional pool of display nicknames for spawned agents.

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

Codex 通过 name 字段识别自定义 agent。文件名和 agent 名称保持一致是最简单的约定，但真正生效的是 name 字段。

显示昵称

当你希望 Codex 给 spawned agents 分配更易读的显示名时，可以使用 nickname_candidates。这在你同时运行很多个相同自定义 agent、又希望 UI 里显示不同标签时尤其有用，而不是一遍遍重复同一个 agent 名称。

昵称只影响展示。Codex 仍然通过 name 识别和生成 agent。

nickname_candidates 必须是一个非空且不重复的名称列表。每个昵称可以包含 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 review

这个模式把 review 拆成三个聚焦的自定义 agent：

pr_explorer 负责映射代码库并收集证据。
reviewer 负责寻找 correctness、security 和测试风险。
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"

这套配置适合下面这种 prompt：

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.

使用子代理处理 CSV 批量任务（实验性）

这个工作流仍然是实验性的，随着 subagent support 演进，可能会继续变化。spawn_agents_on_csv 适合把很多相似任务按“一行一个工作项”来处理。Codex 会读取 CSV，为每一行启动一个 worker 子代理，等待整批完成，然后把合并结果导出为 CSV。

这适合重复性审计任务，例如：

每行审查一个文件、包或 service
检查一组 incident、PR 或 migration target
为大量相似输入生成结构化摘要

这个工具接受：

csv_path：源 CSV 路径
instruction：worker prompt 模板，使用 {column_name} 占位符
id_column：如果你希望从特定列获取稳定 item id
output_schema：当每个 worker 都应该返回固定形状的 JSON object 时使用
output_csv_path、max_concurrency 和 max_runtime_seconds：用于作业控制

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

示例 prompt：

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。

示例 2：前端集成调试

这个模式适合 UI regression、flaky browser flow，或者跨应用代码和运行中产品的 integration bug。

项目配置 (.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

这套配置适合下面这种 prompt：

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.

常见问题

OpenAI Codex 子代理会额外消耗多少 token？

每个子代理都有自己独立的模型调用，所以 token 消耗会明显高于单 Agent 运行。粗略上可以理解为，子代理越多，消耗就越高；如果只是探索型任务，优先给它们配更省成本的模型会更稳妥。

`max_depth = 1` 是什么意思？子代理可以再生子代理吗？

max_depth = 1 表示根会话（depth=0）可以生成子代理（depth=1），但 depth=1 的 Agent 不能再生成 depth=2 的 Agent。默认建议保留这个值，因为更深层的递归会快速放大 token、延迟和不确定性。

自定义 Agent 的 `name` 和文件名必须一致吗？

不需要，但最好保持一致，减少混淆。Codex 用 name 字段识别 Agent；如果你的自定义 Agent 和内置 Agent（比如 explorer）同名，自定义版本会优先。

OpenAI Codex 子代理配置与并行工作流 #

可用性 #

常见工作流 #

如何管理子代理 #

审批与沙箱控制 #

自定义 Agent #

全局设置 #

自定义 Agent 文件 schema #

显示昵称 #

自定义 Agent 示例 #

示例 1：PR review #

使用子代理处理 CSV 批量任务（实验性） #

示例 2：前端集成调试 #

常见问题 #

OpenAI Codex 子代理会额外消耗多少 token？ #

max_depth = 1 是什么意思？子代理可以再生子代理吗？ #

自定义 Agent 的 name 和文件名必须一致吗？ #