子代理

身份非官方简体中文镜像

翻译状态 AI 翻译

来源版本官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

ChatGPT Work 和 Codex 可以通过并行生成专门的代理来运行子代理工作流，然后在一个响应中收集它们的结果。这对于高度并行的复杂任务尤其有用，例如代码库探索或实现多步骤功能计划。

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

可用性

ChatGPT Work 向符合条件的账户开放子代理工作流和活动。

当前 Codex 版本默认启用子代理工作流。子代理活动会显示在 ChatGPT 桌面应用、 Codex CLI，以及 IDE 扩展中。

由于每个子代理都会执行自己的模型和工具工作，子代理工作流会比类似的单代理运行消耗更多 token。

在 ChatGPT Work中，请 ChatGPT 将独立工作委派给子代理。这些代理在 ChatGPT的托管环境中运行，聊天会显示它们的活动和结果。在大多数智能级别下，需要明确请求委派。使用 Ultra 时， ChatGPT 可以在并行代理能显著提升速度或质量时主动委派工作。

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

在交互式 Codex 会话中请求 CLI 使用子代理。 Codex 也可以遵循适用的 AGENTS.md 或技能指令来请求委派。使用 /agent 在代理线程运行时检查并切换它们。主线程会将子代理结果收集到最终响应中。

在 Codex 聊天中请求 IDE 将工作的独立部分委派给子代理。 Codex 也可以遵循适用的 AGENTS.md 或技能指令来请求委派。当后台代理 UI 可用时，活跃的子代理会显示在输入框上方。展开面板可查看其状态、停止所有活跃的子代理，或打开单个子代理线程。

子代理工作流的帮助

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

这通常被描述为：

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

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

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

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

当工作可以独立并行运行时，它们也能节省时间，并且它们通过将更大规模的任务拆分为有边界的部分，让任务更易处理。例如， Codex 可以将对数百万 token 文档的分析拆分为更小的问题，并将提炼后的要点返回给主线程。

作为起点，可将并行代理用于以读取为主的任务，例如探索、测试、分诊和总结。对于以写入为主的并行工作流要更加谨慎，因为代理同时编辑代码可能会产生冲突并增加协调开销。

核心术语

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

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

触发子代理工作流

在大多数智能级别下，需要直接请求子代理或并行代理工作。Ultra 支持主动委派，因此 ChatGPT 可以在无需单独请求的情况下委派合适的独立工作。

直接请求子代理或并行代理工作。 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.

选择模型和推理

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

在 ChatGPT Work中，从输入框选择模型和智能级别。可用的智能级别可能包括 Light、 Medium、 High、 Extra High，以及 Max，具体取决于所选模型。 Ultra 仅面向符合条件的账户和受支持模型提供。它使用最大推理，并让 ChatGPT 主动将合适的工作委派给子代理。

在其他智能级别下，如果你希望并行委派工作，请明确请求子代理。

如果你没有固定模型或 model_reasoning_effort， Codex 可以选择一种设置在智能、速度和价格之间为任务取得平衡。它可能会偏向 gpt-5.6-terra 用于快速扫描，或偏向更高强度的 gpt-5.6 配置，用于要求更高的推理。当你想要更精细的控制时，可在提示词中引导该选择，或直接在 agent 文件中设置 model 和 model_reasoning_effort 。

对于 Codex中的大多数任务，从 gpt-5.6开始。使用 gpt-5.6-terra 当你想要一个更快、成本更低的选项来处理较轻量的 subagent 工作时。

模型选择

gpt-5.6：对要求较高的 agent 从这里开始。它最适合需要规划、工具使用、验证，以及在更大上下文中跟进完成的模糊、多步骤工作。
gpt-5.6-terra：用于偏重速度和效率而非深度的 agent，例如探索、以读取为主的扫描、大文件审查，或处理辅助文档。它很适合作为并行工作器，将提炼后的结果返回给主 agent。
gpt-5.6-luna：用于处理清晰、可重复或高容量工作的快速、范围较窄的 agent。

推理强度（`model_reasoning_effort`）

ultra：当所选模型支持时，用于最深度的推理。
max 和 xhigh：当所选模型支持这些级别时，用于特别 demanding 的推理。。
high：当 agent 需要追踪复杂逻辑、检查假设，或推演边缘情况时使用（例如审查员或侧重安全的 agent）。
medium：适用于大多数 agent 的平衡默认值。
low：当任务很直接且速度最重要时使用。

更高的推理强度会增加响应时间和 token 用量，但可以提升复杂工作的质量。详情请参阅模型、配置基础和配置参考。

编排和线程控制

ChatGPT 或 Codex 处理跨代理编排，包括生成新的子代理、路由后续指令、等待结果，以及关闭代理线程。

当许多代理正在运行时， Codex 会等到所有请求的结果可用后，返回整合后的响应。

在大多数智能级别下， ChatGPT 会在收到直接请求后生成代理。使用 Ultra 时， ChatGPT 也可以在并行工作有用时主动委派。

当前本地 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 引导正在运行的子代理、停止它，或关闭已完成的子代理线程。

交互内容： SubagentWorkflowIllustration 的动态演示请参阅页面顶部的官方原文链接。

使用 /agent 在 CLI 中切换活跃代理线程并检查正在进行的线程。
直接请求 Codex 引导正在运行的子代理、停止它，或关闭已完成的代理线程。
当后台代理面板可用时，展开它以检查状态、停止活跃的子代理，或打开子代理线程。
直接请求 Codex 引导正在运行的子代理、停止它，或关闭已完成的子代理线程。

审批和沙箱控制

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

ChatGPT Work 在其托管环境中运行子代理，并且不公开本地 Codex 沙箱或审批模式控制。子代理会使用父聊天可用的工具。网站和连接器权限仍然是特定于工具的。

子代理会继承输入框下方选择的权限模式。请在请求委派工作之前，为父回合选择 Codex 权限模式。

在交互式 CLI 会话中，即使你正在查看主线程，审批请求也可能从非活跃代理线程中浮现。审批覆盖层会显示来源线程标签，你可以按 o 在批准、拒绝或回答请求之前打开该线程。

在非交互式流程中，或在运行无法显示新的审批请求时，任何需要新审批的操作都会失败，并将 Codex 错误返回到父工作流。

Codex 在生成子项时，也会重新应用父回合的实时运行时覆盖项。这包括你在会话期间交互式设置的沙箱和审批选择，例如更改或 /permissions ， --yolo即使所选自定义代理文件设置了不同默认值。

子代理会继承输入框下方选择的权限模式。请在请求委派工作之前，为父回合选择 Codex 权限模式。

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

自定义 agent

Codex 随附内置 agent：

default：通用的后备 agent。
worker：面向执行的 agent，用于实现和修复。
explorer：偏重阅读的代码库探索 agent。

要定义自己的自定义 agent，请添加独立的 TOML 文件到 ~/.codex/agents/ 用于个人 agent，或添加到 .codex/agents/ 用于项目范围的 agent。

每个文件定义一个自定义 agent。 Codex 会将这些文件作为配置层加载到派生会话中，因此自定义 agent 可以覆盖与普通 Codex 会话配置相同的设置。这可能会显得比专用 agent 清单更重，而且随着创作和共享能力成熟，该格式可能会演进。

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

name
description
developer_instructions

如果自定义 agent 文件设置了 model 或 model_reasoning_effort，则文件中的值优先。否则， Codex 会独立解析每项设置：显式派生值，然后是对应的 [agents] 默认值，然后是父级的值。如果一次派生选择了不同的模型，并且既没有显式也没有已配置的 effort， Codex 会使用该模型的默认 effort。其他会话设置，例如 sandbox_mode、 mcp_servers和 skills.config，在自定义 agent 文件省略它们时，会从父级继承。

全局设置

全局 subagent 设置仍位于 [agents] 你的配置中。

字段	类型	必需	用途
`agents.enabled`	布尔值	否	启用或禁用多 agent 工具。
`agents.max_concurrent_threads_per_session`	数字	否	限制并发打开的派生 agent 线程数，不包括主线程。
`agents.default_subagent_model`	字符串	否	设置派生 agent 的默认模型。
`agents.default_subagent_reasoning_effort`	字符串	否	设置派生 agent 的默认 reasoning effort。
`agents.interrupt_message`	布尔值	否	当 agent 回合被中断时，记录一条模型可见的消息。

注意：

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

自定义 agent 文件架构

字段	类型	必需	用途
`name`	字符串	是	agent 名称 Codex 在派生或引用此 agent 时使用。
`description`	字符串	是	面向人的指引，用于说明 Codex 何时应使用此 agent。
`developer_instructions`	字符串	是	定义 agent 行为的核心指令。

你也可以在自定义 agent 文件中包含其他受支持的 config.toml 键，例如 model、 model_reasoning_effort、 sandbox_mode、 mcp_servers和 skills.config。

Codex 通过其 name 字段识别自定义 agent。让文件名匹配 agent 名称是最简单的约定，但 name 字段才是事实来源。

自定义 agent 示例

最好的自定义 agent 范围窄且立场明确。给每个 agent 一个清晰的职责、一个与该职责匹配的工具表面，以及能防止它偏移到相邻工作的指令。

示例 1： PR review

此模式将评审拆分到三个聚焦的自定义 agent：

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

项目配置（.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.6-terra"
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.6-luna"
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 回归问题、不稳定的浏览器流程，或跨应用程序代码和运行中产品的集成 bug。