Codex 子代理（Subagents）
子代理（Subagents）是 Codex 的多智能体编排能力。主代理（Main Agent）在处理大型复杂任务时，可派生多个独立的辅助代理，把整体任务拆分为若干独立子任务，交由子代理并行或串行执行；子代理完成任务后将结果返回主代理，由主代理统一汇总、校验、合并输出。子代理适合大型项目重构、多模块并行开发、批量代码审计等复杂工程场景。
一、子代理基础概念
子代理是由主代理派生的专用工作智能体，拥有独立会话上下文、独立工具权限，可单独配置模型、推理档位、沙箱策略。默认继承主会话的审批策略与安全沙箱，也可单独覆盖配置。
主代理与子代理关系
- 主代理：任务总调度者，负责需求拆解、任务分发、结果汇总、冲突校验、最终输出。
- 子代理：专项执行者，只负责分配给自己的子任务，任务范围受限，不擅自扩大工作边界。
执行流程：主代理拆解任务 → 分发任务给子代理 → 多个子代理并行执行 → 子代理返回结果 → 主代理合并、校验、生成最终成果。
子代理适用场景
✅ 推荐使用
- 大型项目多模块并行开发（前端、后端、测试分开处理）
- 全项目批量代码迁移、框架升级
- 全仓库安全审计、大规模代码评审
- 多文件、多目录独立并行查询分析
❌ 不推荐使用
- 简单单行代码生成、单文件小修改
- 强依赖顺序执行、前后步骤高度耦合的任务
- 简单Bug修复、代码格式化等轻量化任务（会产生额外Token开销）
二、启用与全局配置
子代理功能默认关闭，需要在项目配置文件 config.toml 开启多代理能力。
# config.toml
[features]
multi_agent = true
[agents]
max_threads = 4 # 最大并行子代理数量
max_depth = 1 # 最大嵌套层级，默认禁止子代理再创建子代理
job_max_runtime_seconds = 1800配置说明：
max_threads：控制同时运行的子代理数量，建议日常开发设置2~4，防止并发过多消耗大量Token。max_depth：控制嵌套深度，推荐固定为1，避免无限递归创建代理。job_max_runtime_seconds：子代理任务超时时间，超时自动终止。
配置文件存放位置：
- 项目级：
./.codex/config.toml（团队共享，提交Git）- 用户全局：
~/.codex/config.toml（本机所有项目生效）
三、自定义子代理角色定义
自定义子代理定义文件使用 TOML 格式，存放于 .codex/agents/ 目录，提交代码仓库即可团队共享。
每个子代理文件包含必填项：name、description、developer_instructions；可选配置：模型、推理档位、沙箱权限、MCP服务、技能覆盖。
示例：.codex/agents/code-reviewer.toml
name = "code-reviewer"
description = "代码评审子代理，负责扫描代码规范、漏洞、逻辑缺陷"
developer_instructions = """
仅执行分配给你的代码评审任务，输出结构化评审报告，只列出真实可复现问题，不要擅自修改代码。
输出格式：【级别】文件路径 - 问题描述 + 修改建议。
"""
model = "gpt-5.1-codex-max"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
内置子代理角色（开箱即用，无需编写文件）
| 角色名称 | 定位 | 默认权限 |
|---|---|---|
| worker | 通用开发工人，编写、修改代码 | workspace-write |
| explorer | 代码库检索、文件阅读、依赖分析 | read-only |
| reviewer | 代码评审与静态检查 | read-only |
| monitor | 执行校验、结果自检、任务验收 | read-only |
四、子代理调用方式
1. 隐式自动调用
开启 multi_agent=true 后，当主代理识别到任务可拆分为多个独立并行子任务，自动派生对应子代理执行。适合大型重构、全项目审计。
2. 显式手动调用（推荐，可控性更强）
通过指令直接指定使用哪一类子代理，示例：
# 派生reviewer子代理，审查src目录全部代码 spawn agent code-reviewer 任务：审查 src 目录所有文件，输出安全与规范报告派生worker子代理，开发后端接口spawn agent worker
任务：实现用户登录接口，使用Pydantic校验参数
斜杆命令快速查看子代理列表：
/agents list # 列出当前项目全部可用子代理
/agents info worker # 查看子代理详细配置
五、权限、沙箱与安全管控
子代理的安全策略可继承主代理，也可单独配置沙箱模式：
read-only：仅读取文件，禁止修改、执行命令（推荐给审计、检索类子代理）workspace-write：允许读写项目文件，禁止高危系统命令（开发子代理使用）danger-full-access：完整读写与命令执行权限，高风险，企业环境严格审批
安全管控要点：
- 子代理默认不允许继续派生新子代理，由
max_depth限制，防止递归扩散。 - 所有子代理操作日志独立记录，可审计每个子代理的文件读写、命令执行记录。
- 高危操作（批量删除、全量替换），无论主代理还是子代理，都会触发人工审批。
- 企业管理员可通过
requirements.toml限制允许启用的子代理角色，禁用高危角色。
六、子代理与 Agent Skills 的区别
很多场景容易混淆子代理和Agent Skills，二者定位完全不同：
| 项目 | 子代理 Subagents | Agent Skills |
|---|---|---|
| 本质 | 独立运行的智能体工作实例 | 封装好的标准化任务流程包 |
| 作用 | 任务拆分、并行分工，多智能体协同 | 固化一套固定执行步骤与输出规范 |
| 生效方式 | 派生独立会话，多线程并行执行 | 在当前代理会话内加载规则，单线程执行 |
| 存放路径 | .codex/agents/*.toml | .codex/skills/*.md |
| 适用场景 | 大规模、多模块并行任务 | 单一领域标准化任务（评审、测试、重构） |
两者可以组合使用：子代理在执行任务时，可加载对应的Skill，让每个专项代理遵循固定工作流。
七、最佳实践
- 控制并发数量：并发线程不要设置过大，2~4个足够，过多并行会快速消耗Token，同时增加结果合并冲突。
- 角色职责单一：一个子代理只承担一类任务，不要把前端开发、安全审计、测试全部塞进同一个子代理。
- 最小权限原则：检索、审计类子代理一律使用
read-only沙箱，仅开发worker开放写权限。 - 优先显式调用：重要工程任务手动指定子代理，避免主代理自动拆分任务出现范围偏差。
- 禁止多层嵌套：保持
max_depth=1，不开启子代理再派生子代理，降低不可控风险。 - 结果必须校验：主代理合并所有子代理输出后，统一做完整性校验，修复子代理之间的代码冲突。
八、常见问题
Q：子代理会不会额外消耗Token？
A：会。每一个子代理都拥有独立上下文，会占用额外Token；简单任务不建议启用子代理。
Q：子代理之间能否直接互相通信？
A：不能。子代理之间互相隔离，所有信息交互必须经过主代理中转，保证上下文隔离、便于审计。
Q：子代理的模型可以和主代理不一样吗？
A：可以。自定义子代理配置中可单独指定model与推理档位，例如：主代理使用高推理档位做规划，explorer子代理使用轻量模型做代码检索，节约成本。
Q：子代理文件如何团队共享？
A：.codex/agents/目录提交到Git仓库，团队成员拉取代码后，自动加载全部自定义子代理。
九、总结
子代理（Subagents）是 Codex 面向大型工程任务的多智能体编排能力。主代理负责任务规划与结果汇总，派生多个角色化子代理并行处理独立子任务，支持自定义角色、独立模型配置、细粒度沙箱权限控制。子代理适合大型项目重构、多模块并行开发、全仓库安全审计等复杂场景；同时要注意控制并发数量、遵循最小权限原则，平衡开发效率与Token成本。子代理与Agent Skills可以配合使用，子代理负责分工，Skill负责标准化任务流程，共同构建团队AI开发流水线。
0 条笔记