子代理

身份非官方简体中文镜像

翻译状态 AI 翻译 / AI 审校

来源版本官方未提供

同步日期 2026-07-26

官方原文 learn.chatgpt.com

ChatGPT Work 和 Codex 可以通过并行生成专用代理，然后在一条响应中汇总结果，来运行子代理工作流。对于高度适合并行处理的复杂任务（例如探索代码库或实施多步骤功能计划），这尤其有帮助。

在本地 Codex 客户端中，你还可以为不同任务定义具有不同模型配置和指令的自定义代理。

可用性

当前的 Codex 版本默认启用子代理工作流。子代理活动会显示在 ChatGPT 桌面应用、Codex CLI 和 Codex IDE extension 中。

由于每个子代理都会独立执行模型和工具工作，子代理工作流消耗的 token 多于相近的单代理运行。

在应用聊天中要求 Codex 将工作的独立部分委派给子代理。当前的本地 Codex 版本会在你直接提出请求，或适用的 AGENTS.md 或技能指令要求时进行委派。应用会展示每个子代理线程，以便你检查其工作以及返回主聊天的摘要。

子代理工作流的帮助

即使上下文窗口很大，模型仍然存在限制。如果将探索笔记、测试日志、堆栈跟踪和命令输出等嘈杂的中间输出灌入主聊天（你在其中定义需求、约束和决策），随着时间推移，会话的可靠性可能下降。

这通常被描述为：

上下文污染：有用信息被埋没在嘈杂的中间输出之下。
上下文腐化：随着聊天中填入越来越多不相关的细节，性能会下降。

如需了解背景信息，请参阅 Chroma 关于上下文腐化的文章。

子代理工作流通过将嘈杂的工作移出主线程来提供帮助：

让主代理专注于需求、决策和最终输出。
并行运行专用子代理，处理探索、测试或日志分析。
返回子代理的摘要，而不是原始中间输出。

当工作可以独立并行运行时，它们还可以节省时间；通过将大型任务拆分为范围明确的部分，也能让任务更易于处理。例如，Codex 可以将对一份数百万 token 文档的分析拆分为更小的问题，然后向主线程返回提炼后的要点。

作为起点，对于探索、测试、分流和摘要等以读取为主的任务，可以使用并行代理。对于以写入为主的并行工作则应更加谨慎，因为多个代理同时编辑代码可能造成冲突，并增加协调开销。

核心术语

Codex 在子代理工作流中使用几个相关术语：

子代理工作流：Codex 运行并行代理并合并其结果的工作流。
子代理：Codex 启动来处理特定任务的委派代理。
代理线程：子代理执行工作的线程。受支持的客户端允许你打开这些线程，以检查进度或结果。

触发子代理工作流

直接要求使用子代理或并行代理工作。适用的项目或技能指令也可能要求 Codex 进行委派。

在实践中，手动触发意味着使用诸如“生成两个代理”“并行委派这项工作”或“每个要点使用一个代理”等直接指令。由于每个子代理都会独立执行模型和工具工作，子代理工作流消耗的 token 多于相近的单代理运行。

良好的子代理提示词应说明如何划分工作、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.

选择模型和推理

不同代理需要不同的模型和推理设置。

如果不固定模型或 model_reasoning_effort，Codex 可以选择在智能程度、速度和价格之间取得平衡的配置。对于快速扫描，它可能倾向于使用 gpt-5.6-terra；对于要求更高的推理，则可能使用更高投入的 gpt-5.6 配置。如果需要更精细的控制，可以在提示词中引导这一选择，或直接在代理文件中设置 model 和 model_reasoning_effort。

对于 Codex 中的大多数任务，请从 gpt-5.6 开始。如果希望为较轻量的子代理工作选择更快、成本更低的选项，请使用 gpt-5.6-terra。

模型选择

gpt-5.6：从这里开始，用于要求较高的代理。它最适合需要规划、工具使用、验证，以及在更大上下文中持续跟进的模糊多步骤工作。
gpt-5.4：当工作流固定使用 GPT-5.4 时使用。它结合了出色的编码、推理、工具使用和更广泛的工作流能力。
gpt-5.6-terra：用于优先考虑速度和效率而非深度的代理，例如探索、以读取为主的扫描、大文件审查或处理辅助文档。它非常适合并行工作者向主代理返回提炼后的结果。

推理投入（`model_reasoning_effort`）

ultra：当所选模型支持时，用于最深度的推理。
max 和 xhigh：当所选模型支持时，用于要求特别高的推理。
high：当代理需要追踪复杂逻辑、检查假设或处理边界情况时使用（例如审查代理或专注于安全性的代理）。
medium：大多数代理的平衡默认值。
low：任务简单且速度最重要时使用。

更高的推理投入会增加响应时间和 token 使用量，但可以提升复杂任务的质量。详情请参阅 Models、Config basics 和 Configuration Reference。

编排和线程控制

ChatGPT 或 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

管理子代理

从主线程中显示的活动信息打开子代理线程，以检查其工作。
直接要求 Codex 引导正在运行的子代理、停止子代理或关闭已完成的子代理线程。

插图：Codex 桌面聊天显示两个子代理并行工作。

插图：Codex 桌面子代理面板显示没有活动子代理以及三个已完成的审计。

审批和沙箱控制

子代理会继承你当前的沙箱策略。

子代理会继承编辑器下方所选的权限模式。在要求 Codex 委派工作之前，为父级回合选择权限模式。

你也可以为单个自定义代理覆盖沙箱配置，例如明确将其标记为以只读模式工作。

自定义代理

Codex 自带以下内置代理：

default：通用备用代理。
worker：专注于执行的代理，用于实施和修复。
explorer：以读取为主的代码库探索代理。

要定义自己的自定义代理，请在个人代理目录 ~/.codex/agents/ 或项目范围代理目录 .codex/agents/ 下添加独立的 TOML 文件。

每个文件定义一个自定义代理。Codex 会将这些文件作为生成会话的配置层加载，因此自定义代理可以覆盖普通 Codex 会话配置中的相同设置。这种方式可能比专用代理清单更繁琐，并且随着编写和共享方式的成熟，格式也可能发生变化。

每个独立的自定义代理文件都必须定义：

name
description
developer_instructions

如果自定义代理文件设置了 model 或 model_reasoning_effort，文件中的值会优先使用。否则，Codex 会独立解析每项设置：显式的生成值，然后是相应的 [agents] 默认值，最后是父级的值。如果生成时选择了不同模型，且既没有显式指定也没有配置推理投入，Codex 会使用该模型的默认推理投入。其他会话设置（例如 sandbox_mode、mcp_servers 和 skills.config）在自定义代理文件省略这些设置时，会从父级继承。

全局设置

全局子代理设置仍位于 configuration 中的 [agents] 下。

字段	类型	必填	用途
`agents.enabled`	boolean	否	启用或禁用多代理工具。
`agents.max_concurrent_threads_per_session`	number	否	限制同时打开的已生成代理线程数，不包括主代理。
`agents.default_subagent_model`	string	否	设置已生成代理的默认模型。
`agents.default_subagent_reasoning_effort`	string	否	设置已生成代理的默认推理投入。
`agents.interrupt_message`	boolean	否	代理回合被中断时，记录一条模型可见的消息。

注意：

agents.enabled 默认为 true。将其设置为 false 可禁用多代理工具。
如果未设置 agents.max_concurrent_threads_per_session，Codex 会选择默认值。现有配置可以继续使用 agents.max_threads 这一旧版别名。
显式的生成参数会覆盖 agents.default_subagent_model 和 agents.default_subagent_reasoning_effort。
agents.interrupt_message 默认为 true。将其设置为 false 可从代理上下文中省略模型可见的中断消息。
如果自定义代理名称与内置代理（例如 explorer）匹配，则优先使用自定义代理。

自定义代理文件架构

字段	类型	必填	用途
`name`	string	是	Codex 生成或引用此代理时使用的代理名称。
`description`	string	是	面向用户的说明，用于指导 Codex 何时使用此代理。
`developer_instructions`	string	是	定义代理行为的核心指令。

你还可以在自定义代理文件中加入其他受支持的 config.toml 键，例如 model、model_reasoning_effort、sandbox_mode、mcp_servers 和 skills.config。

Codex 通过其 name 字段识别自定义代理。将文件名与代理名称保持一致是最简单的约定，但实际以 name 字段为准。

自定义代理示例

最好的自定义代理通常职责专一且有明确倾向。为每个代理指定清晰的工作内容、与该工作匹配的工具范围，以及防止其偏离到相邻任务的指令。

示例 1：PR 审查

此模式将审查工作拆分给三个职责明确的自定义代理：

pr_explorer 梳理代码库并收集证据。
reviewer 查找正确性、安全性和测试风险。
docs_researcher 通过专用 MCP 服务器检查框架或 API 文档。

项目配置（.codex/config.toml）：

[agents]
max_concurrent_threads_per_session = 8

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

示例 2：前端集成调试

此模式适用于 UI 回归、不稳定的浏览器流程，或横跨应用代码与运行中产品的集成错误。