Home

深色模式

Codex Multi-Agent ​

概述 ​

Codex Multi-Agent 指 Codex 在一个主任务中创建多个 subagent，让它们在独立 agent thread 中并行工作，再由主 agent 收集和汇总结果。OpenAI 当前文档将这套能力称为 subagent workflow，界面和配置中也主要使用 subagent、agent thread 与 custom agent 等术语。

截至 2026 年 8 月 19 日，当前 Codex 版本默认启用 subagent workflow，ChatGPT desktop app、Codex CLI 和 IDE extension 都可以显示 subagent 活动。它主要解决两类问题：并行处理互不依赖的工作，以及把搜索结果、日志和中间分析移出主上下文。

工作方式 ​

主 agent 负责拆分任务、创建 subagent、补充指令、等待结果和关闭线程。subagent 在自己的 thread 中使用模型与工具，只把整理后的结果返回主线程。

独立上下文能减少两类常见问题：

  • context pollution：大量日志和搜索结果淹没需求、约束与关键决策
  • context rot：对话持续变长后，不相关信息逐渐影响后续判断

subagent 只返回摘要也有代价。主 agent 看不到全部推理过程，因此任务描述必须要求它保留文件位置、命令结果和结论依据，不能只返回“检查完成”。

触发方式 ​

当前本地 Codex 会在两种情况下委派工作：用户直接要求使用 subagent，或适用的 AGENTS.md、skill 指令明确要求委派。普通任务不会因为看起来可以并行就必然自动创建 agent。

直接说明角色、数量和汇总方式：

text
使用并行 subagent 审查当前分支：

- 一个 agent 检查安全风险
- 一个 agent 检查行为回归
- 一个 agent 检查测试缺口和可维护性

等待三者全部完成后再汇总。每条发现按严重程度排序，
附带文件位置、触发条件和修复方向，不要修改代码。

下面几种表述也能明确触发委派：

  • “spawn two agents”
  • “delegate this work in parallel”
  • “use one agent per point”

在项目级 AGENTS.md 中加入常驻规则时，应限定触发场景，避免小任务也付出并行成本：

md
## Multi-Agent

- 仅当任务能拆成至少两个互不依赖的工作流时使用 subagent。
- 代码审查按安全性、正确性和测试覆盖拆分并行检查。
- 多个 agent 不得同时修改同一文件。
- 主 agent 必须等待所有结果并统一验证。

客户端操作 ​

在 Codex CLI 交互会话中，使用 /agent 查看和切换 agent thread。运行中的 subagent 即使不在当前界面，也可能弹出带 thread 标签的权限请求。

ChatGPT desktop app 会展示每个 subagent thread，可以打开线程检查过程和返回主会话的摘要。IDE extension 提供 background-agent panel 时，可以查看状态、打开单个线程或停止所有活跃 subagent。

还可以直接要求主 agent 执行这些操作：

  • 给运行中的 subagent 追加说明
  • 中断指定 subagent 当前工作
  • 让空闲 agent 继续处理后续任务
  • 关闭已经完成的 agent thread

内置 Agent ​

Codex 当前提供三个内置 agent：

Agent用途
default未指定专门角色时使用的通用 agent
worker面向实现和修复的执行 agent
explorer面向代码库探索的只读工作

prompt 可以按工作类型指定角色。例如先让 explorer 定位调用链，再让 worker 修改已经确认的文件。存在严格顺序依赖时，这两个步骤应串行执行，不应为了“多 Agent”硬塞进并行流程。

全局配置 ​

subagent 的全局设置位于 Codex 配置文件的 [agents] 表中。项目可以在 .codex/config.toml 中共享配置，个人默认值则放在用户级 Codex 配置中。

toml
[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"
interrupt_message = true

字段作用如下：

字段作用
agents.enabled是否启用 Multi-Agent 工具，默认值为 true
agents.max_concurrent_threads_per_session限制每个主会话同时打开的 subagent thread 数量
agents.default_subagent_model设置 subagent 默认模型
agents.default_subagent_reasoning_effort设置 subagent 默认推理强度
agents.interrupt_message中断 agent turn 时是否在上下文中记录可见消息

并发数不等于越大越快。受前置依赖、共享文件和外部限流影响，过多线程通常只会增加 token 消耗与协调时间。没有设置并发上限时，Codex 会选择默认值；旧配置中的 agents.max_threads 仍可作为兼容别名。

自定义 Agent ​

custom agent 用 TOML 文件定义专门角色：

  • 个人级目录：~/.codex/agents/
  • 项目级目录：.codex/agents/

每个文件必须包含 name、description 和 developer_instructions。例如创建 .codex/agents/security-reviewer.toml：

toml
name = "security_reviewer"
description = "只读检查认证、授权和敏感信息处理。"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
检查真实执行路径，不修改文件。
重点关注身份认证、权限边界、输入校验和敏感信息泄露。
按严重程度输出发现，每条都包含文件位置、触发条件和判断依据。
没有证据时明确说明不确定性。
"""

此后可以直接使用角色名：

text
让 security_reviewer 审查当前分支的认证改动，
同时让 explorer 梳理受影响的入口和调用链。等待两者完成后汇总。

custom agent 还可以覆盖 mcp_servers 和 skills.config 等常规 session 配置。自定义名称与内置名称相同时，自定义定义优先，因此不要随手创建一个行为完全不同的 explorer。

配置优先级 ​

custom agent 的模型和推理强度按层级解析：

  1. custom agent 文件中的 model 或 model_reasoning_effort
  2. 本次 spawn 显式传入的值
  3. [agents] 中的默认值
  4. 主 agent 当前使用的值

模型与推理强度分别解析。custom agent 没有写 sandbox_mode、MCP 或 skills 时，这些设置从主 agent 继承。

模型选择应和任务形状匹配：代码库扫描、资料整理等工作可以使用更快的模型；安全审查、复杂根因分析应保留较高推理强度。具体模型会随账号和 Codex 版本变化，配置前以当前 /model 和官方文档为准。

权限继承 ​

subagent 默认继承主 turn 的 sandbox 和 approval 设置，包括会话中通过 /permissions 修改的实时值。用户应在要求委派之前确认权限模式，因为新 agent 会以当时的设置启动。

custom agent 可以进一步收紧自己的沙箱，例如将审查角色固定为：

toml
sandbox_mode = "read-only"

在交互式 CLI 中，非当前 thread 的权限请求仍会显示，并标注来源。不能展示新审批的非交互流程里，需要额外批准的操作会失败，然后由主 agent 收到错误。Multi-Agent 不会绕过原有权限边界。

任务边界 ​

适合优先并行的工作包括：

  • 代码库探索和调用链梳理
  • 多角度代码审查
  • 测试、构建和日志分析
  • 独立资料的检索与摘要
  • 无文件重叠的模块实现

下面几类情况应保持单 agent 或串行委派：

  • 后一个任务必须读取前一个任务的未完成产物
  • 多个 agent 需要频繁修改同一文件
  • 工作量很小，调度时间已经超过执行时间
  • 需求仍然模糊，尚未形成可验收的子任务

并行写入尤其需要谨慎。多个 agent 在同一工作区修改代码会产生冲突，也可能基于不同时间点的文件做出判断。稳妥做法是先并行读取和分析，再由一个 worker 统一修改；确实要并行实现时，按目录或文件划分所有权，最后由主 agent 检查差异并运行完整验证。

两种 Multi-Agent ​

OpenAI 文档中还有 Responses API 的 Multi-agent beta。它允许 GPT-5.6 通过 API 协调多个 subagent，属于应用开发接口。

本文介绍的是 Codex 产品内的 subagent workflow，包括 CLI、desktop app、IDE extension、AGENTS.md 和 .codex/agents/。两者都使用并行 agent，但配置入口、运行环境和面向对象不同，不应把 Responses API 参数写进 Codex 配置文件。

参考 ​