Codex 可以通过 parallel spawning specialized agents 来运行 subagent workflows，并把它们的 results 汇总到一个 response 中。对于高度 parallel 的复杂 tasks，例如 codebase exploration 或实施 multi-step feature plan，这尤其有用。
借助 subagent workflows，你还可以按 task 定义自己的 custom agents，为它们设置不同的 model configurations 和 instructions。
关于 subagent workflows 背后的 concepts 和 tradeoffs，包括 context pollution、context rot 与 model-selection guidance，请参见 Subagent concepts 。
Availability
当前 Codex releases 默认启用 subagent workflows。
Subagent activity 目前会在 Codex app 和 CLI 中 surfaced。IDE Extension 中的 visibility 即将推出。
Codex 只会在你明确要求时 spawn subagents。由于每个 subagent 都会执行自己的 model 和 tool work，subagent workflows 会比可比的 single-agent runs 消耗更多 tokens。
Typical workflow
Codex 会处理 agents 之间的 orchestration，包括 spawning new subagents、routing follow-up instructions、等待 results，以及关闭 agent threads。
当许多 agents 正在运行时，Codex 会等到所有 requested results 都可用，然后返回 consolidated response。
Codex 只会在你明确要求它这样做时 spawn new agent。
要看它实际如何工作，可以在你的 project 中尝试下面的 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 codeManaging subagents
在 CLI 中使用 /agent 在 active agent threads 之间切换，并 inspect ongoing thread。
直接请求 Codex steer running subagent、stop it，或 close completed agent threads。
Approvals 和 sandbox controls
Subagents 会继承你当前的 sandbox policy。
在 interactive CLI sessions 中，即使你正在查看 main thread，approval requests 也可能从 inactive agent threads surfaced。Approval overlay 会显示 source thread label，你可以在 approve、reject 或 answer 该 request 前按 o 打开该 thread。
在 non-interactive flows 中，或 run 无法 surfaced fresh approval 时，需要 new approval 的 action 会失败，Codex 会把 error surfaced 回 parent workflow。
Codex spawn child 时也会重新应用 parent turn 的 live runtime overrides。这包括你在 session 中 interactively 设置的 sandbox 和 approval choices，例如 /permissions changes 或 --yolo，即使 selected custom agent file 设置了不同 defaults。
你也可以为 individual custom agents override sandbox configuration，例如显式标记某个 agent 使用 read-only mode。
Custom agents
Codex 随附 built-in agents：
default：general-purpose fallback agent。
worker：execution-focused agent，用于 implementation 和 fixes。
explorer：read-heavy codebase exploration agent。
要定义自己的 custom agents，请在 ~/.codex/agents/ 下添加 standalone TOML files 作为 personal agents，或在 .codex/agents/ 下添加 project-scoped agents。
每个 file 定义一个 custom agent。Codex 会把这些 files 作为 spawned sessions 的 configuration layers 加载，因此 custom agents 可以 override normal Codex session config 中的相同 settings。这可能比 dedicated agent manifest 更重，随着 authoring 和 sharing 成熟，format 也可能演进。
每个 standalone custom agent file 都必须定义：
name
description
developer_instructions
当你 omit optional fields 时，例如 nickname_candidates、model、model_reasoning_effort、sandbox_mode、mcp_servers 和 skills.config，它们会从 parent session 继承。
Global settings
Global subagent settings 仍位于你的 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 | spawn_agents_on_csv jobs 的 default timeout per worker。 |
Notes：
未设置时，agents.max_threads 默认为 6。
agents.max_depth 默认为 1，允许 direct child agent spawn，但会阻止更深层 nesting。除非你明确需要 recursive delegation，否则请保留默认值。提高这个值可能把 broad delegation instructions 变成 repeated fan-out，从而增加 token usage、latency 和 local resource consumption。agents.max_threads 仍会限制 concurrent open threads，但不会移除更深 recursion 带来的 cost 和 predictability risks。
agents.job_max_runtime_seconds 是 optional。未设置时，spawn_agents_on_csv 会 fallback 到每次调用的 per-call default timeout，即每个 worker 1800 seconds。
如果 custom agent name 匹配 built-in agent（例如 explorer），你的 custom agent 优先。
Custom agent file schema
| Field | Type | Required | Purpose |
|---|---|---|---|
| name | string | Yes | Codex spawning 或 referring to this agent 时使用的 agent name。 |
| description | string | Yes | 面向 human 的 guidance，说明 Codex 何时应使用该 agent。 |
| developer_instructions | string | Yes | 定义 agent behavior 的 core instructions。 |
| nickname_candidates | string[] | No | spawned agents 的 optional display nicknames pool。 |
你也可以在 custom agent file 中包含其他 supported config.toml keys，例如 model、model_reasoning_effort、sandbox_mode、mcp_servers 和 skills.config。
Codex 通过 name field 识别 custom agent。让 filename 匹配 agent name 是最简单的 convention，但 name field 才是 source of truth。
Display nicknames
当你希望 Codex 为 spawned agents 分配更 readable display names 时，使用 nickname_candidates。运行同一 custom agent 的多个 instances 时，这尤其有用，可以让 UI 显示 distinct labels，而不是重复同一个 agent name。
Nicknames 仅用于 presentation。Codex 仍通过 name 识别并 spawn 该 agent。
Nickname candidates 必须是 non-empty list of unique names。每个 nickname 可以使用 ASCII letters、digits、spaces、hyphens 和 underscores。
Example：
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 activity 的地方展示 nicknames，而底层 agent type 仍保持 reviewer。
Example custom agents
最好的 custom agents 是 narrow 且 opinionated 的。为每个 agent 指定清晰 job、与 job 匹配的 tool surface，以及防止它漂移到 adjacent work 的 instructions。
Example 1：PR review
这个 pattern 会把 review 拆给三个 focused custom agents：
pr_explorer 会 map codebase 并 gather evidence。
reviewer 查找 correctness、security 和 test risks。
docs_researcher 通过 dedicated MCP server 检查 framework 或 API documentation。
Project config（.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"这个 setup 适合这样的 prompts：
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 batches（experimental）
这个 workflow 是 experimental，可能会随着 subagent support 演进而变化。当你有许多 similar tasks，并且每个 work item 可以 map 到 CSV 的一行时，使用 spawn_agents_on_csv。Codex 会读取 CSV，为每一行 spawn 一个 worker subagent，等待 full batch 完成，并把 combined results export 到 CSV。
它适合 repeated audits，例如：
每行 review 一个 file、package 或 service。
检查 incidents、PRs 或 migration targets 的列表。
为许多 similar inputs 生成 structured summaries。
该 tool 接受：
csv_path，用于 source CSV。
instruction，用于 worker prompt template，并使用 {column_name} placeholders。
id_column，当你希望从 specific column 获取 stable item ids 时使用。
output_schema，当每个 worker 应返回固定 shape 的 JSON object 时使用。
output_csv_path、max_concurrency 和 max_runtime_seconds，用于 job control。
每个 worker 必须且只能调用 report_agent_job_result 一次。如果 worker 退出但没有 report result，Codex 会在 exported CSV 中把该 row 标记为 error。
Example 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 会在 batch 运行期间在 stderr 上显示 single-line progress update。Exported CSV 包含 original row data，以及 job_id、item_id、status、last_error 和 result_json 等 metadata。
Related runtime settings：
agents.max_threads 限制可以 concurrent 保持 open 的 agent threads 数量。
agents.job_max_runtime_seconds 设置 CSV fan-out jobs 的 default per-worker timeout。per-call max_runtime_seconds override 优先。
sqlite_home 控制 Codex 存放 agent jobs 及其 exported results 所用 SQLite-backed state 的位置。
Example 2：Frontend integration debugging
这个 pattern 适合 UI regressions、flaky browser flows，或跨 application code 与 running product 的 integration bugs。
Project config（.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这个 setup 适合这样的 prompts：
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.