OpenAI Codex 子智能体指南 | 自定义子智能体与任务拆分

Codex 可以通过并行启动多个专用智能体，并在最后汇总各自的结果，来运行子智能体工作流。这种方式尤其适合并行度高的复杂任务，例如大规模代码库探索，或按步骤推进的多阶段功能实现。

借助子智能体工作流，你还可以按任务类型定义自己的自定义智能体，并为它们指定不同的模型配置和开发者指令。

如果你想先了解子智能体的核心概念和权衡取舍，例如上下文污染、上下文退化，以及模型选择建议，可以先阅读子智能体概念。

可用性

当前版本的 Codex 默认启用子智能体工作流。

目前子智能体活动会显示在 Codex App 和 CLI 中；IDE 扩展的可视化支持后续会补上。

Codex 只会在你明确要求时生成子智能体。因为每个子智能体都会独立进行模型调用和工具调用，所以相比单智能体运行，子智能体工作流会消耗更多 token。

典型工作流

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 issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

管理子智能体

在 CLI 中使用 /agent，可以在活跃智能体线程之间切换，并查看正在运行的线程。
你也可以直接要求 Codex 去引导某个正在运行的子智能体、停止它，或关闭已经完成的智能体线程。

审批与沙箱控制

子智能体会继承你当前会话的沙箱策略。

在交互式 CLI 中，即使你当前停留在主线程里，审批请求也可能来自一个暂时不在前台的智能体线程。审批浮层会显示来源线程标签；如果你想先切过去再决定是否批准，可以按 o 打开对应线程。

在非交互流程中，或者任何“无法弹出新的审批”的运行环境里，只要某个动作需要新的批准，这个动作就会失败，错误会被抛回父工作流。

Codex 在生成子智能体时，也会重新应用父 turn 的实时运行时覆盖项，包括你在当前会话里通过 /approvals 改的设置，或者类似 --yolo 这样的全局开关。即使选中的自定义智能体文件里写了不同的默认值，这些父级实时覆盖也仍然优先。

你也可以为单个自定义智能体单独覆盖沙箱配置，例如强制把某个智能体限定在只读模式。

自定义智能体

Codex 自带三种内建智能体：

default：通用回退智能体。
worker：偏执行，适合实现和修复类任务。
explorer：偏只读，适合代码库探索类任务。

如果你要定义自己的智能体，可以在下面两个目录之一中放置独立的 TOML 文件：

个人级：~/.codex/agents/
项目级：.codex/agents/

每个文件定义一个自定义智能体。Codex 会把它作为一个“额外配置层”应用到生成的会话中，所以自定义智能体能覆盖的键，基本与普通 config.toml 可覆盖项一致。

每个自定义智能体文件都必须定义：

name
description
developer_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.job_max_runtime_seconds 是可选项。未设置时，spawn_agents_on_csv 会回退到每个 worker 1800 秒的默认超时。
如果某个自定义智能体的 name 与内建智能体重名，例如 explorer，则你的自定义智能体会优先生效。

自定义智能体文件结构

字段	类型	必需	说明
`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 一致是最省事的做法，但最终还是以 name 为准。

显示昵称

如果你希望 Codex 在界面中给同一类智能体显示更可读的昵称，可以使用 nickname_candidates。这在同时运行很多个同类自定义智能体时特别有用，可以避免界面上出现大量重复名称。

昵称只影响展示层；Codex 在内部识别和生成智能体时，依然使用 name。

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 可以显示这些昵称，而底层智能体类型仍然是 reviewer。

自定义智能体示例

好的自定义智能体应当足够窄、足够明确。每个智能体都应该有清晰职责、匹配其职责的工具面，以及避免它漂移到相邻工作的开发者指令。

示例 1：PR 评审

这种模式会把 PR 评审拆分给三个各自聚焦的自定义智能体：

pr_explorer：负责梳理代码库并收集证据。
reviewer：负责检查正确性、安全性和测试风险。
docs_researcher：通过专用 MCP 服务端核对框架或 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.

用子智能体处理 CSV 批量任务（实验性）

这个工作流仍属实验性能力，后续可能变化。spawn_agents_on_csv 适合“每一行对应一个相似工作项”的批量任务：Codex 会读取 CSV，按行生成 worker 子智能体，等待所有任务完成，然后把结果重新导出成 CSV。

它很适合用于重复性审计类工作，例如：

按行审查文件、包或服务
检查一组事故、PR 或迁移目标
为大量相似输入生成结构化摘要

这个工具接受的核心参数包括：

csv_path：源 CSV 路径
instruction：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 等元数据。

示例 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