Codex 可以通过生成专门化代理并行运行子代理工作流，然后在一个响应中收集它们的结果。这对于高度并行的复杂任务特别有用，例如代码库探索，或实现一个多步骤功能计划。
通过子代理工作流，你还可以根据任务定义自己的自定义代理，并为它们设置不同的模型配置和指令。
关于子代理工作流背后的概念和权衡，包括上下文污染、上下文腐烂和模型选择指导，请参见 Subagent concepts。
当前 Codex 版本默认启用子代理工作流。
Codex 只有在你明确要求时才会生成子代理。由于每个子代理都会执行自己的模型和工具工作，因此与类似的单代理运行相比，子代理工作流会消耗更多 token。
Codex 会处理代理之间的编排，包括生成新的子代理、路由后续指令、等待结果，以及关闭代理线程。
当许多代理正在运行时，Codex 会等到所有请求的结果都可用，然后返回一个整合后的响应。
Codex 只有在你明确要求时才会生成新代理。
要查看实际效果，可以在你的项目中尝试以下提示词：
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 issue2. Code quality3. Bugs4. Race5. Test flakiness6. Maintainability of the code- 在 CLI 中使用
/agent在活跃代理线程之间切换，并检查正在进行的线程。 - 直接要求 Codex 引导正在运行的子代理、停止它，或关闭已完成的代理线程。
审批和沙盒控制
Section titled “审批和沙盒控制”子代理会继承你当前的沙盒策略。
在交互式 CLI 会话中，即使你正在查看主线程，审批请求也可能从非活跃代理线程中显示出来。审批覆盖层会显示来源线程标签，你可以按 o 打开该线程，然后再批准、拒绝或回答请求。
在非交互式流程中，或者当某次运行无法显示新的审批请求时，需要新审批的操作会失败，Codex 会把错误返回给父工作流。
当 Codex 生成子代理时，也会重新应用父轮次的实时运行时覆盖设置。这包括你在会话期间交互式设置的沙盒和审批选择，例如 /permissions 变更或 --yolo，即使所选的自定义代理文件设置了不同的默认值。
你也可以为单个 自定义代理 覆盖沙盒配置，例如明确标记某个代理以只读模式工作。
Codex 随附内置代理：
default：通用兜底代理。worker：专注执行的代理，用于实现和修复。explorer：偏重读取的代码库探索代理。
要定义自己的自定义代理，请在 ~/.codex/agents/ 下添加独立 TOML 文件作为个人代理，或在 .codex/agents/ 下添加项目作用域代理。
每个文件定义一个自定义代理。Codex 会把这些文件作为生成会话的配置层加载，因此自定义代理可以覆盖普通 Codex 会话配置中的相同设置。这可能会比专用代理清单显得更重，并且随着编写和共享能力逐渐成熟，该格式可能会演进。
每个独立自定义代理文件都必须定义：
namedescriptiondeveloper_instructions
可选字段，例如 nickname_candidates、model、model_reasoning_effort、sandbox_mode、mcp_servers 和 skills.config，如果省略，则会从父会话继承。
全局子代理设置仍然位于你的 配置 中的 [agents] 下。
| 字段 | 类型 | 必需 | 用途 |
|---|---|---|---|
agents.max_threads | number | 否 | 并发打开的代理线程上限。 |
agents.max_depth | number | 否 | 生成代理的嵌套深度，根会话从 0 开始。 |
agents.job_max_runtime_seconds | number | 否 | spawn_agents_on_csv 作业中每个 worker 的默认超时时间。 |
说明：
- 当你未设置
agents.max_threads时，它默认是6。 agents.max_depth默认是1，这允许直接子代理生成，但会阻止更深层嵌套。除非你确实需要递归委派，否则请保持默认值。提高该值可能会把宽泛的委派指令变成重复扇出，从而增加 token 使用量、延迟和本地资源消耗。agents.max_threads仍然会限制并发打开的线程数量，但它不会消除更深递归带来的成本和可预测性风险。agents.job_max_runtime_seconds是可选项。当你未设置它时，spawn_agents_on_csv会回退到其每次调用的默认超时时间，即每个 worker 1800 秒。- 如果自定义代理名称与内置代理名称匹配，例如
explorer，你的自定义代理会优先。
自定义代理文件 schema
Section titled “自定义代理文件 schema”| 字段 | 类型 | 必需 | 用途 |
|---|---|---|---|
name | string | 是 | Codex 在生成或引用该代理时使用的代理名称。 |
description | string | 是 | 面向人的指导，用于说明 Codex 何时应该使用该代理。 |
developer_instructions | string | 是 | 定义代理行为的核心指令。 |
nickname_candidates | string[] | 否 | 生成代理时可选的显示昵称池。 |
你也可以在自定义代理文件中包含其他受支持的 config.toml 键，例如 model、model_reasoning_effort、sandbox_mode、mcp_servers 和 skills.config。
Codex 会通过 name 字段识别自定义代理。让文件名与代理名称匹配是最简单的约定，但 name 字段才是真正的来源。
当你希望 Codex 为生成的代理分配更易读的显示名称时，可以使用 nickname_candidates。当你运行同一个自定义代理的多个实例，并希望 UI 显示不同标签而不是重复同一个代理名称时，这尤其有用。
昵称只用于展示。Codex 仍然通过代理的 name 来识别和生成该代理。
昵称候选必须是非空的唯一名称列表。每个昵称可以使用 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 应用和 CLI 可以在显示代理活动的位置展示这些昵称，而底层代理类型仍然保持为 reviewer。
自定义代理示例
Section titled “自定义代理示例”最好的自定义代理是范围狭窄且观点明确的。给每个代理一个清晰的工作、与该工作匹配的工具范围，以及能防止它漂移到相邻工作的指令。
示例 1：PR 审查
Section titled “示例 1：PR 审查”这个模式会把审查拆分到三个聚焦的自定义代理中：
pr_explorer映射代码库并收集证据。reviewer查找正确性、安全性和测试风险。docs_researcher通过专用 MCP 服务器检查框架或 API 文档。
项目配置（.codex/config.toml）：
[agents]max_threads = 6max_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.使用子代理处理 CSV 批量任务（实验性）
Section titled “使用子代理处理 CSV 批量任务（实验性）”该工作流是实验性的，可能会随着子代理支持的演进而变化。
当你有许多类似任务，并且每个工作项都对应 CSV 中的一行时，可以使用 spawn_agents_on_csv。Codex 会读取 CSV，为每一行生成一个 worker 子代理，等待整个批次完成，并将合并后的结果导出为 CSV。
这非常适合重复性审计，例如：
- 每行审查一个文件、包或服务
- 检查一组事件、PR 或迁移目标
- 为许多相似输入生成结构化摘要
该工具接受：
csv_path：源 CSVinstruction：worker 提示词模板，使用{column_name}占位符id_column：当你希望从特定列获取稳定 item 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限制可以同时保持打开的代理线程数量。agents.job_max_runtime_seconds设置 CSV 扇出作业中每个 worker 的默认超时时间。每次调用的max_runtime_seconds覆盖值优先。sqlite_home控制 Codex 存储 SQLite 状态的位置，该状态用于代理作业及其导出的结果。
示例 2：前端集成调试
Section titled “示例 2：前端集成调试”这个模式适用于 UI 回归、浏览器流程不稳定，或跨应用代码与运行中产品的集成 bug。
项目配置（.codex/config.toml）：
[agents]max_threads = 6max_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.