Codex 多 Agent 与子代理(Subagents)怎么用:并行委派、自定义角色与配置详解

Codex 支持多 Agent 并行干活吗?按官方《Subagents》文档整理:默认已开启子代理工作流,内置 explorer 与 worker 角色、用 /subagents 切换线程、在 .codex/agents/ 自定义 TOML 角色,以及权限继承与额度注意事项。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Plus 账号

结论先说

  1. 当前版本的 Codex 默认已开启多代理(Subagents)功能(agents.enabled 默认为 true),支持同时拉起多个专职子代理并行干活,再由主线程汇总结果。
  2. 核心价值是防「上下文污染(Context pollution)」:把翻代码、跑单测、读长堆栈这类吵闹的中间过程剥离到子线程,只把精炼结论传回主对话。
  3. 内置三种角色:explorer(偏只读搜索)、worker(偏动手实现与修复)、default(通用兜底);还可在 ~/.codex/agents/ 或项目 .codex/agents/ 下写独立 .toml 文件定义专属角色。
  4. 怎么触发与查看:在提示词里直接写明并行拆分要求(或开启 Ultra 推理档让系统主动委派);CLI 里输 /subagents 随时查看和切换活动线程。
  5. 沙箱与审批严格继承父会话:自定义子代理可以单独换模型或关掉 Shell 工具,但不能绕开父会话当前的沙箱和审批策略。

Codex 内置与自定义子代理分工对比

图:本站根据 Codex 官方文档:Subagents 整理的示意图

本文根据 Codex 官方文档《Subagents》《Sample Configuration》《Slash commands in Codex CLI》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。Claude Code 的同类机制可对比 Claude Code Subagents(子代理)怎么用。

适用于谁

  • 在大仓库里让单个会话既搜代码、又看几千行测试日志、又改逻辑,结果聊到后面主线上下文越来越糊涂的人;
  • 想让 Codex 同时派出三个子代理分别查安全漏洞、缺测分支和可维护性,最后汇总成一份报告的人;
  • 想给扫描探索子代理单独配便宜快速的 gpt-6-luna,而主代理保持强模型的开发者。

一、怎么触发子代理并行工作、在哪看进度

官方文档建议:读多写少的任务(如代码库探索、PR 多维度审查、故障分流、长文档分块摘要)最适合上并行子代理;而多个代理同时改同一批文件的「写密集」任务容易产生代码冲突,要谨慎拆分。

触发方式有两种:

  • 常规档位显式点名:直接在提示词(或仓库 AGENTS.md、技能文件)里交代清楚「拆几个子代理、各自查什么、要不要等齐再汇总」。例如官方推荐的分支审查写法:
text
请用并行子代理审查当前分支:派一个子代理查安全风险,一个查测试缺口,一个查代码可维护性。等三个全部完成后,按类别汇总问题并附上文件路径与行号。
  • Ultra 档位主动委派:在支持 Ultra 档位的账号与模型上,无需每次手写拆分指令,系统判断并行能明显提速或提质时会自动派发子代理。

运行过程中各端查看入口不同:

  • 命令行 CLI:输入 /subagents 回车,即可在活动线程选择器里切换查看某个子代理正在干什么;如果某个后台子线程触发了命令审批弹窗,遮罩层会标明来源线程名,按键盘 o 键就能先打开那个子线程看清上下文再决定放行或拒绝。
  • 桌面端与 IDE 扩展:桌面端直接在主对话活动流里点开对应子代理线程;IDE 扩展在输入框上方展开后台代理面板查看状态或停止子代理。

二、配置全局并发上限与自定义 .toml 角色

在 Codex 配置并运行子代理的四步

图:本站根据 Codex 官方文档:Subagents 整理的示意图

1. 在 config.toml 的 [agents] 表设全局默认值

不想让所有子代理都跟着父会话用最贵的模型,可以在 ~/.codex/config.toml 或受信任项目的 .codex/config.toml 里配置 [agents] 表(配置优先级见 Codex config.toml 完整详解,模型差异见 Codex 用哪个模型好):

toml
[agents]
enabled = true
max_concurrent_threads_per_session = 6        # 除主线程外的最大并发子线程数
default_subagent_model = "gpt-6.2-sol"        # 子代理默认模型
default_subagent_reasoning_effort = "medium"  # 子代理默认推理强度

2. 在 .codex/agents/ 新建专属角色文件

个人通用角色放 ~/.codex/agents/,项目共享角色放仓库 .codex/agents/。每个 .toml 文件定义一个角色,必填 name、description、developer_instructions 三个字段。例如按官方范例写一个只读搜索员 .codex/agents/pr-explorer.toml:

toml
name = "pr_explorer"
description = "只读代码库探索员,在提出修改方案前负责收集调用链与文件证据。"
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
保持只读探索模式,不要修改任何文件。
追踪真实执行路径,准确引用文件路径与函数符号;除非父代理明确要求,否则不要自行编写修复代码。
"""

[features]
shell_tool = false

上面这个例子用了两个官方省钱又防乱改的技巧:把高频翻文件的探索员指定为轻量快速的 gpt-6-luna(配 high 推理),同时用 features.shell_tool = false 关掉它的 Shell 执行能力,只让它安心读代码。

三、权限边界与套餐额度消耗说明

  • 安全边界不可越权:官方明确规定,写在自定义代理 .toml 里的 sandbox_mode、approval_policy、model_provider 和 mcp_servers 不会生效,一律严格继承父会话当前的设置(沙箱规则见 Codex 权限与沙箱设置)。想让子代理用某个 MCP 工具,必须在父会话里配好该 MCP 服务。
  • 关注并行额度消耗:一次派 4 个子代理出去,就等于同时跑了 4 轮独立的模型推理和工具读取,消耗套餐限额的速度显著高于单代理。如果团队日常大量使用并行子代理或 Ultra 模式,个人升级可看本站 ChatGPT Plus 充值说明 或无 5 小时窗口限制的 ChatGPT Pro 充值说明。

常见问题

问:自定义角色取名叫 explorer,会和内置的 explorer 冲突报错吗?

答:不会报错。官方文档写明,当你的自定义角色 name 与内置角色(如 explorer、worker)重名时,优先采用你定义的版本。

问:在 codex exec 非交互脚本里跑子代理,中途子代理请求人工审批会怎样?

答:非交互环境无法弹出审批框。官方说明凡是需要新人工审批的动作都会直接失败,并把错误返回给父工作流处理;因此在自动化里请提前给父命令设好合适的 --sandbox。

问:归档主会话时,它派生出来的子代理会话记录还在吗?

答:运行 codex archive 或 /delete 处理父会话时,Codex 会一并归档或删除它所派生的子代理会话及其后代记录。

相关教程

参考资料

  • Codex 官方文档:Subagents — https://learn.chatgpt.com/docs/agent-configuration/subagents
  • Codex 官方文档:Sample Configuration — https://learn.chatgpt.com/docs/config-file/config-sample
  • Codex 官方文档:Slash commands in Codex CLI — https://learn.chatgpt.com/docs/reference/slash-commands

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  2. 02

    多 Agent 的成本为什么翻倍、怎么控制:Token 膨胀根源与五项降本措施

    刚把单智能体拆成多 Agent,用量往往暴涨好几倍。Anthropic 工程报告统计单智能体约为聊天的 4 倍 Token,多智能体可达约 15 倍。本文拆解固定前缀重复加载、历史搬运、工具链定义与缓存失效四大根源,并给出五条实操控费办法。

    ChatGPTClaude0
  3. 03

    多 Agent 协同开发怎么落地:「一个写、一个审」双代理工作流搭建指南

    多 Agent 协同开发里投入产出比最高的模式就是「一个写、一个审」。本文依据 Anthropic 与 OpenAI 官方编码最佳实践,讲清为什么同会话自审容易漏问题,以及用只读子代理、跨模型交叉审查(Claude Code + Codex)和自动化闭环落地的具体方法。

    ClaudeCodex0
  4. 04

    多 Agent 编排模式详解:编排者-工作者、交接(Handoffs)、并行与评估循环怎么选

    搜「multi-agent orchestration 中文」会被各家框架的不同术语绕晕。本文对照 Anthropic《Building effective agents》与 OpenAI 智能体指南,把编排者-工作者、去中心化交接、并行分片投票与生成-评估循环四种标准编排拓扑讲透。

    ChatGPTClaude0
  5. 05

    多智能体(Multi-Agent)是什么、什么时候该用:Anthropic 与 OpenAI 官方判断标准

    多智能体不是代理越多越聪明。本文依据 Anthropic 研究系统架构文章与 OpenAI 官方智能体指南,讲清确定性工作流、单智能体与多智能体的区别,以及哪三类瓶颈才值得上多智能体协同。

    ChatGPTClaude0
  6. 06

    codebase-memory 类 MCP 是什么、怎么用:基于语法树图谱的本地代码索引原理与配置

    codebase-memory-mcp(DeusData/codebase-memory-mcp)是一类本地代码图谱 MCP 服务器:用 Tree-sitter 把仓库解析成函数与调用关系的 SQLite 图库,帮编码助手查调用链并省下读整份文件的额度。

    ClaudeCodex0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~