子智能体

Codex 可以通过并行生成专门的智能体，然后将其结果汇总到一次响应中，从而运行子智能体工作流。这对于高度并行的复杂任务（例如代码库探索或实施多步骤功能计划）尤其有用。

通过子智能体工作流，您还可以根据任务定义具有不同模型配置和指令的自定义智能体。

有关子智能体工作流背后的概念与权衡（包括上下文污染、上下文腐化和模型选择指南），请参阅 子代理概念.

可用性

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

管理子智能体

• 使用 /agent 在 CLI 中切换活动的智能体线程并检查正在进行的线程。
• 直接要求 Codex 来操控正在运行的子智能体、停止它，或关闭已完成的智能体线程。

批准与沙盒控制

子智能体将继承您当前的沙盒策略。

在交互式 CLI 会话中，即使您正在查看主线程，非活动智能体线程也可能弹出批准请求。批准覆盖层会显示来源线程标签，您可以按 o 以在该线程中打开，然后再批准、拒绝或回复该请求。

在非交互式流程中，或运行无法弹出全新批准提示时，需要新批准的操作将会失败，并且 Codex 会将错误返回给父工作流。

Codex 在生成子级时，还会重新应用父轮次的实时运行时覆盖配置。这包括您在会话期间以交互方式设置的沙盒和批准选项，例如 /permissions 更改或 --yolo，即使所选的自定义 Agent 文件设置了不同的默认值。

您还可以覆盖单个 的沙盒配置，例如明确将其标记为只读模式。

自定义智能体

Codex 附带了内置智能体：

• default: 通用型备用 Agent。
• worker: 侧重于执行的 Agent，用于实现和修复。
• explorer: 侧重于读取的代码库探索 Agent。

要定义您自己的自定义智能体，请将独立的 TOML 文件添加到 ~/.codex/agents/ for personal agents or .codex/agents/ for project-scoped agents.

每个文件定义一个自定义智能体。Codex 会将这些文件作为生成会话的配置层进行加载，因此自定义智能体可以覆盖与普通 Codex 会话配置相同的设置。这可能比专用的智能体清单显得更繁重，并且随着编写和分享功能的成熟，其格式可能会不断演进。

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

• name
• description
• developer_instructions

可选字段，例如 nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers，且 skills.config 省略时会从父会话继承。

全局设置

全局子代理设置仍位于 [agents] in your 配置.

Notes:

• agents.max_threads 默认值同样因模型而异，而非通用。 6 当你未设置时。
• agents.max_depth 默认值同样因模型而异，而非通用。 1，这允许直接子 Agent 生成，但会阻止更深层次的嵌套。除非您特别需要递归委托，否则请保持默认值。提高此值可能会将宽泛的委托指令转化为重复的扇出，从而增加 Token 用量、延迟和本地资源消耗。 agents.max_threads 仍会限制并发线程数，但无法消除更深递归带来的成本和可预测性风险。
• agents.job_max_runtime_seconds 是可选的。当你未设置时， spawn_agents_on_csv 将回退到每个 worker 单次调用 1800 秒的默认超时时间。
• 如果自定义代理名称与内置代理匹配，例如 explorer，您的自定义 Agent 优先。

自定义代理文件 schema

你还可以在自定义智能体文件中包含其他支持的 config.toml 键，例如 model, model_reasoning_effort, sandbox_mode, mcp_servers，且 skills.config.

Codex 通过其 name 字段识别自定义智能体。将文件名与智能体名称相匹配是最简单的约定，但 name 字段才是真实来源。

显示昵称

使用 nickname_candidates 用于当你希望 Codex 为生成的智能体分配更具可读性的显示名称时。当你运行同一自定义智能体的多个实例，并希望 UI 显示不同的标签而不是重复相同的智能体名称时，这尤其有用。

昵称仅用于展示。Codex 仍然通过其 name.

识别和生成智能体。昵称候选项必须是包含唯一名称的非空列表。每个昵称可以使用 ASCII 字母、数字、空格、连字符和下划线。

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 应用和 CLI 可以在显示智能体活动的地方展示昵称，而底层智能体类型保持不变 reviewer.

自定义智能体示例

最好的自定义智能体应当聚焦且明确。赋予每个智能体明确的职责、与该职责匹配的工具集，以及能防止其偏离核心任务的指令。

示例 1：PR 审查

此模式将审查工作拆分给三个专注的自定义 Agent：

• 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.

使用子 Agent 处理 CSV 批次（实验性）

此工作流是实验性的，可能会随着子 Agent 支持的演进而改变。当你 spawn_agents_on_csv 有许多类似任务（每项任务对应一行）时，请使用此工作流。Codex 会读取 CSV，为每一行生成一个工作子 Agent，等待整批任务完成，并将合并后的结果导出为 CSV。

这非常适合以下重复性审计任务：

• 每行审查一个文件、包或服务
• 检查事件、PR 或迁移目标列表
• 为许多类似输入生成结构化摘要

The tool accepts:

• csv_path for the source CSV
• instruction 作为工作提示模板，使用 {column_name} 占位符
• id_column 当你希望特定列的条目 ID 保持稳定时
• output_schema 当每个 worker 应返回一个具有固定结构的 JSON 对象时
• output_csv_path, max_concurrency，且 max_runtime_seconds for job control

每个 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：前端集成调试

这种模式适用于 UI 回归测试、不稳定的浏览器流程，或跨越应用程序代码与正在运行的产品的集成 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

此配置非常适合以下提示：

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.