子智能体

Codex 可以运行子智能体工作流：并行生成专门的智能体，然后在一次回复里收集它们的结果。这对高度并行的复杂任务特别有用，如代码库探索或实现多步骤的功能计划。在本地 Codex 客户端里，还可以定义带有不同模型配置和指令的自定义智能体。当前的 Codex 版本默认启用子智能体工作流，子智能体的活动显示在桌面应用、Codex CLI 和 IDE 扩展里。因为每个子智能体都做自己的模型和工具工作，子智能体工作流比同等的单智能体运行消耗更多 token。

为什么子智能体工作流有帮助

即使上下文窗口很大，模型也有限度。如果你让主对话（你在那里定义需求、约束和决定）被探索笔记、测试日志、堆栈跟踪、命令输出等嘈杂的中间输出淹没，会话会随时间变得不那么可靠，官方称为：

• 上下文污染：有用的信息被嘈杂的中间输出埋没
• 上下文腐烂：随着对话塞满不那么相关的细节，性能下降

子智能体工作流通过把嘈杂的工作移出主线程来帮忙：让主智能体专注于需求、决定和最终输出；并行运行专门的子智能体做探索、测试或日志分析；让子智能体返回摘要而不是原始中间输出。它们也能在工作可以独立并行时节省时间，并把较大的任务拆成有界的小块。作为起点，把并行智能体用在读多的任务（探索、测试、分诊、摘要）上；对并行的写多工作流要更小心，因为多个智能体同时编辑代码会产生冲突并增加协调开销。

触发子智能体

直接要求使用子智能体或并行智能体工作。当前的本地 Codex 版本在你直接要求，或适用的 AGENTS.md 或 skill 指令要求委派时才会委派。手动触发就是用「spawn two agents」「delegate this work in parallel」「use one agent per point」这样的直接指令。好的子智能体提示词应说明如何划分工作、Codex 是否应等待所有智能体再继续、以及要返回什么摘要或输出：

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

在交互式 CLI 会话里用 /agent 检查和切换智能体线程。主线程把子智能体的结果汇总成最终回复。在 IDE 里，有后台智能体界面时，活动的子智能体显示在输入框上方，展开面板可以查看状态、停止所有活动子智能体、或打开单个子智能体线程。想引导运行中的子智能体、停止它、或关闭已完成的线程，直接让 Codex 去做。

模型与推理设置

不同的智能体需要不同的模型和推理设置。如果你没有配置子智能体的模型或 model_reasoning_effort，子智能体继承父智能体的模型和推理强度；显式的 spawn 请求或 [agents] 默认值选择了模型却没有显式或已配置的推理强度时，子智能体用该模型的默认推理强度。要为每个任务平衡智能、速度和价格，可以在提示里请求特定的模型或推理强度、在 config.toml 里配置 [agents] 默认值，或直接在自定义智能体文件里设置 model 和 model_reasoning_effort。推理强度的选择思路：high 适合需要追踪复杂逻辑、检查假设或处理边缘情况的智能体（如评审或安全方向的智能体）；medium 平衡速度和深度；low 适合直接了当且速度最重要的任务；xhigh、max、ultra 用于特别苛刻的推理，取决于所选模型是否支持。更高的推理强度增加响应时间和 token 用量，但能提高复杂工作的质量。

审批与沙箱控制

子智能体继承你当前的沙箱策略和输入框下方选择的权限模式，所以在要求 Codex 委派工作前先为父回合选好权限模式。在交互式 CLI 会话里，来自非活动智能体线程的审批请求即使你在看主线程也会冒出来，审批浮层显示来源线程标签，你可以按 o 先打开那个线程再批准、拒绝或回答。在非交互流程里，或运行无法弹出新审批时，需要新审批的动作会失败，Codex 把错误返回给父工作流。Codex 在生成子智能体时还会重新应用父回合的实时运行时覆盖，包括你在会话期间交互式设置的沙箱和审批选择（如 /permissions 的更改或 --yolo），即使选中的自定义智能体文件设置了不同的默认值。你也可以为单个自定义智能体覆盖沙箱配置，例如明确标记某个只读工作。

自定义智能体

Codex 自带内置智能体：default（通用回退智能体）、worker（专注执行、实现和修复）、explorer（读多的代码库探索）。要定义自己的，把独立的 TOML 文件放在 ~/.codex/agents/（个人智能体）或 .codex/agents/（项目范围的智能体）下。每个文件定义一个自定义智能体；Codex 把这些文件作为生成会话的配置层加载，所以自定义智能体可以覆盖普通 Codex 会话配置能覆盖的相同设置（格式可能随着编写和共享的成熟而演进）。每个独立自定义智能体文件必须定义：

• name：Codex 生成或引用该智能体时使用的名字
• description：关于 Codex 何时应使用该智能体的面向人的指引
• developer_instructions：定义智能体行为的核心指令

也可以包含其他受支持的 config.toml 键，如 model、model_reasoning_effort、sandbox_mode、mcp_servers 和 skills.config；文件省略 sandbox_mode、mcp_servers、skills.config 等会话设置时从父会话继承。Codex 按 name 字段识别自定义智能体（让文件名与智能体名一致是最简单的约定，但 name 字段才是依据）。自定义智能体名字与内置智能体（如 explorer）相同时，你的自定义智能体优先。最好的自定义智能体窄而有主见：给每个一个明确的任务、与该任务匹配的工具面，以及防止它漂移到相邻工作的指令。

全局设置

全局子智能体设置仍在配置的 [agents] 下：

显式的 spawn 值覆盖 agents.default_subagent_model 和 agents.default_subagent_reasoning_effort。

示例：PR 评审

官方示例把评审拆给三个聚焦的自定义智能体：pr_explorer 梳理代码库并收集证据；reviewer 查找正确性、安全和测试风险；docs_researcher 通过专用 MCP 服务器检查框架或 API 文档。项目配置（.codex/config.toml）：

[agents]
max_concurrent_threads_per_session = 8

.codex/agents/pr-explorer.toml（只读的代码库探索者，描述、模型用你账号可用的，沙箱设为只读）：

description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model_reasoning_effort = "high"
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.
"""

（model 请换成你的账号或工作区可用的模型；官方示例里是具体的模型名，会随版本变化。）