Appearance
Codex 的子代理（Subagents）机制让你把一个复杂任务拆给多个专业 Agent 并行处理，再汇总结果。内置三种 Agent 类型：default（通用）、worker（执行实现）、explorer（只读探索）。也可以自定义 Agent——指定不同的模型、推理强度、MCP 服务器和沙箱策略。本文覆盖子代理的配置格式、管理命令、CSV 批量任务和两个完整的多 Agent 工作流示例。
Codex 子代理：多 Agent 并行工作流
Codex 可以并行启动多个子代理（Subagents）处理复杂任务，特别适合：代码库探索、多维度 PR Review、多功能并行开发、批量重复性工作。
你也可以定义自己的自定义 Agent，为不同的工作配不同的模型和指令。
子代理只在你明确要求时才会启动，Codex 不会自动拆分任务。每个子代理都有独立的模型调用和工具消耗，Token 用量会增加。
可用性
- 当前 Codex 版本默认开启子代理功能
- App 和 CLI 里都可以看到子代理活动
- IDE 扩展的子代理可见性即将上线
快速体验
在你的项目上试试这个 Prompt：
text
Review this PR (compare this branch vs main).
Spawn one agent per point, wait for all results, then summarize:
1. Security issues
2. Code quality
3. Bugs
4. Race conditions
5. Test flakiness
6. MaintainabilityCodex 会为每个维度启动一个独立子代理，并行工作，最后整合输出。
管理子代理
在 CLI 的 TUI 里：
/agent # 切换查看各个 Agent 线程也可以直接问 Codex：
"Stop the security review agent""Close all completed agent threads""Steer the explorer agent to focus on the auth module"
内置 Agent 类型
| Agent | 定位 |
|---|---|
default | 通用兜底 Agent |
worker | 专注代码实现和 Bug 修复 |
explorer | 只读代码库探索，不做修改 |
自定义 Agent
存放位置
- 个人 Agent：
~/.codex/agents/下的.toml文件 - 项目级 Agent：
.codex/agents/下（推荐加入版本控制）
每个文件定义一个 Agent，文件名建议和 name 字段保持一致。
必填字段
| 字段 | 说明 |
|---|---|
name | Agent 名称（Codex 按这个字段识别，不是文件名） |
description | 说明什么时候该用这个 Agent |
developer_instructions | Agent 的核心行为指令 |
可选字段
model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config、nickname_candidates 均可覆盖，不填时继承父会话的配置。
示例：PR Reviewer Agent
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.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]nickname_candidates 只影响界面显示，不影响 Agent 识别逻辑。
全局子代理配置
在 config.toml 的 [agents] 块里：
| 字段 | 默认值 | 说明 |
|---|---|---|
max_threads | 6 | 最大并发 Agent 线程数 |
max_depth | 1 | 嵌套深度（0=根会话，1=允许子代理，但子代理不能再生子代理） |
job_max_runtime_seconds | 1800 | CSV 批量任务每个 Worker 的默认超时 |
max_depth 保持默认 1，除非你明确需要多层嵌套——深度递归会指数级增加 Token 消耗和不确定性。
实战示例一：PR 三代理并行 Review
场景：用三个专业 Agent 分别探索代码、审查风险、核实文档
项目配置 .codex/config.toml：
toml
[agents]
max_threads = 6
max_depth = 1.codex/agents/pr-explorer.toml：
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, avoid proposing fixes.
""".codex/agents/reviewer.toml：
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.
""".codex/agents/docs-researcher.toml：
toml
name = "docs_researcher"
description = "Documentation specialist for verifying 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. Do not make code changes.
"""
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"触发 Prompt：
text
Review this branch against main.
Have pr_explorer map the affected code paths,
reviewer find real risks,
docs_researcher verify the framework APIs the patch relies on.实战示例二：前端 UI Bug 调试三代理
场景：分工 → 代码定位 + 浏览器复现 + 最小化修复
.codex/agents/code-mapper.toml：
toml
name = "code_mapper"
description = "Read-only explorer for locating the relevant frontend and backend code paths."
model = "gpt-5.4-mini"
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 edits.
""".codex/agents/browser-debugger.toml（需要 Chrome DevTools MCP）：
toml
name = "browser_debugger"
description = "UI debugger using browser tooling to reproduce issues."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, 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：
toml
name = "ui_fixer"
description = "Implementation agent for small, targeted fixes after the issue is understood."
model = "gpt-5.3-codex-spark"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, validate only the behavior you changed.
"""触发 Prompt：
text
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.CSV 批量任务（实验性）
用 spawn_agents_on_csv 让 Codex 读取 CSV，为每一行启动一个 Worker Agent，适合大批量重复任务：
text
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 via report_agent_job_result."
- output_csv_path: /tmp/components-review.csv
- output_schema: { path, risk, summary, follow_up }每个 Worker 必须调用 report_agent_job_result 一次；不调用的行在输出 CSV 里标记为错误。
审批与沙箱继承
- 子代理继承父会话的沙箱策略
- 交互模式下，子代理的审批请求会在主线程显示，按
o可以跳转到该子代理线程后再审批 - 非交互模式下，需要新审批的操作会直接失败并上报给父工作流
常见问题
Q: 子代理会消耗多少额外 Token？
A: 每个子代理有独立的模型调用，Token 消耗大约是单 Agent 的 N 倍（N = 子代理数量）。使用高性价比模型（如 gpt-5.3-codex-spark）做探索型子代理可以显著控制成本。
Q: max_depth = 1 是什么意思？子代理可以再生子代理吗？
A: max_depth = 1 表示根会话（depth=0）可以生成子代理（depth=1），但 depth=1 的 Agent 不能再生 depth=2 的 Agent。推荐保持这个默认值，深层递归会指数级放大 Token 和不确定性。
Q: 自定义 Agent 的 name 和文件名必须一样吗？
A: 不需要，但推荐保持一致以减少混淆。Codex 用 name 字段识别 Agent，如果你的自定义 Agent 和内置 Agent（如 explorer）同名，自定义版本优先。