子智能体

ChatGPT Work 和 Codex 可以并行启动多个专用智能体，再把结果汇总到一份回复中。这种方式尤其适合并行度高的复杂任务，例如代码库探索或多步骤功能实现。

在本地 Codex 客户端中，你还可以按任务类型定义自定义智能体，并为它们设置不同的模型配置和开发者指令。

可用性

当前 Codex 版本默认启用子智能体工作流。ChatGPT 桌面 App、Codex CLI 和 IDE 扩展都会显示子智能体活动。

由于每个子智能体都会独立进行模型调用和工具调用，子智能体工作流会比同类单智能体任务消耗更多 token。

你可以在 App 任务中直接要求 Codex 把互不依赖的工作委派给子智能体。当前本地 Codex 版本会在你明确提出要求，或适用的 AGENTS.md、skill 指令要求委派时启动子智能体。App 会展示每个子智能体对话线程，方便你检查其工作以及返回主任务的摘要。

子智能体工作流为何有帮助

即使上下文窗口很大，模型仍然有极限。如果把探索笔记、测试日志、堆栈追踪和命令输出等带噪中间结果全部放进正在定义需求、约束与决策的主对话，会话会逐渐变得不可靠。

这通常称为：

• 上下文污染（Context pollution）： 有用信息被带噪的中间输出淹没。
• 上下文腐化（Context rot）： 随着对话充满低相关细节，整体表现下降。

背景资料可参阅 Chroma 关于 context rot 的文章。

子智能体工作流把带噪工作移出主对话线程：

• 让主智能体聚焦需求、决策与最终输出。
• 让专用子智能体并行处理探索、测试或日志分析。
• 让子智能体返回摘要，而不是原始中间输出。

当工作可以独立并行时，这种方式还能缩短时间，并把大任务拆成边界清晰的小块。例如，Codex 可以把数百万 token 的文档分析拆成多个较小问题，再把提炼结果交还主对话线程。

建议先把并行智能体用于探索、测试、分诊和总结等读操作较重的任务。并行写操作更容易产生代码冲突和协调开销，应谨慎使用。

核心术语

• 子智能体工作流： Codex 运行并行智能体并汇总结果的工作流。
• 子智能体： Codex 为特定任务启动的委派智能体。
• 智能体对话线程（Agent thread）： 子智能体执行工作的对话线程；受支持的客户端允许你打开它查看进度和结果。

触发子智能体工作流

可以直接要求 Codex 使用子智能体或并行智能体。适用的项目指令或 skill 指令也可以要求委派。

手动触发时，应使用明确指令，例如 “spawn two agents,” “delegate this work in parallel,” 或 “use one agent per point.” 好的提示词要说明如何拆分工作、是否等待全部智能体完成，以及最终需要返回什么摘要或产物。

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.

选择模型与推理强度

不同智能体适合不同的模型和推理设置。如果没有固定 model 或 model_reasoning_effort，Codex 会选择兼顾能力、速度与价格的配置。快速扫描可能使用 gpt-5.6-terra，复杂推理则可能使用更高推理强度的 gpt-5.6。需要精细控制时，可在提示词中引导选择，或在智能体文件中直接设置这两个字段。

模型选择

• gpt-5.6： 适合含糊、多步骤、需要规划、工具调用、验证与跨大上下文持续推进的高要求任务。
• gpt-5.4： 适合已经固定在 GPT-5.4 上的工作流，兼顾编码、推理、工具使用和更广泛任务。
• gpt-5.6-terra： 适合更看重速度和效率的探索、读操作密集型扫描、大文件评审与辅助材料处理。
• gpt-5.3-codex-spark： 面向 ChatGPT Pro 的研究预览模型，适合延迟比通用能力更重要的纯文本迭代。

推理强度（model_reasoning_effort）

• ultra： 所选模型支持时，用于最深层推理。
• max、xhigh： 所选模型支持时，用于特别困难的推理任务。
• high： 用于追踪复杂逻辑、检查假设或处理边界情况，例如 reviewer 或安全智能体。
• medium： 大多数智能体的平衡默认值。
• low： 适合任务直接且速度优先的场景。
• minimal、none： 所选模型支持时，用于几乎不需要推理的低延迟任务。

更高推理强度会增加响应时间和 token 用量，但可能提升复杂任务质量。详情见模型、配置基础和配置参考。

编排与对话线程控制

Codex 负责所有编排工作，包括：

• 生成新的子智能体
• 给不同智能体路由后续指令
• 等待结果
• 关闭子智能体对话线程

当多个智能体并行运行时，Codex 会等待所有要求的结果都返回后，再给出一份汇总答复。当前本地 Codex 版本会在直接请求，或适用的项目与 skill 指令要求时启动智能体。

例如，你可以在当前项目中尝试下面这段提示词：

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 去引导某个正在运行的子智能体、停止它，或关闭已经完成的智能体对话线程。

审批与沙箱控制

子智能体会继承你当前会话的沙箱策略。在 App 中，应先在输入框下方为父会话轮次选择权限模式，再要求 Codex 委派工作。

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

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

Codex 在生成子智能体时，也会重新应用父级会话轮次的实时运行时覆盖项，包括你在当前会话里通过 /permissions 改的设置，或者类似 --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 默认是 6。
• agents.max_depth 默认是 1。根会话可以启动直接子智能体，但这些子智能体不能继续生成更深层后代。除非确实需要递归委派，否则建议保持默认值；提高该值可能让宽泛的委派指令重复扩散，增加 token、延迟和本地资源消耗。agents.max_threads 仍限制并发打开的对话线程，但不会消除深层递归的成本和可预测性风险。
• agents.job_max_runtime_seconds 是可选项。未设置时，spawn_agents_on_csv 会回退到每个 worker 1800 秒的默认超时。
• agents.interrupt_message 默认为 true。设为 false 可不把中断说明写入智能体上下文。
• 如果某个自定义智能体的 name 与内建智能体重名，例如 explorer，则你的自定义智能体会优先生效。

自定义智能体文件结构

你也可以在自定义智能体文件中加入其他 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 server 核对框架或 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：当你希望用某一列作为稳定的内容项 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：前端集成调试

这个模式特别适合 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

这套配置适合如下提示词：

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.