在 AI 辅助开发工作流中，将"探索代码""执行改动""代码审查"等职责拆分给不同子代理（Sub-Agent），是提升任务质量和效率的关键策略。本文记录多代理协作的配置方法论，包括角色划分原则、权限模型设计、推理强度分配，以及从项目级验证到全局推广的落地路径。
多代理配置的核心目标：
| 子代理 | 推理强度 | 权限模式 | 主要职责 |
|---|---|---|---|
| default | medium | workspace-write | 通用任务承接、常规分析与实现 |
| explorer | low | read-only | 代码探索、入口定位、调用链梳理 |
| worker | medium | workspace-write | 定点实现、问题修复、局部验证 |
| reviewer | high | read-only | 正确性审查、回归风险识别、测试缺口提示 |
核心约束：
explorer 专注"读"和"找"，不直接改代码 → read-onlyworker 专注落地实现，不做无关重构 → workspace-writereviewer 专注"判断"和"质疑"，不直接修改 → read-onlydefault 承接通用任务，保持范围收敛 → workspace-write| 强度 | 适用场景 | 选择理由 |
|---|---|---|
| low | 代码检索、结构梳理、结论归纳 | 探索类任务不需要深度推理 |
| medium | 日常实现、定点修改、通用分析 | 效率与稳定性的平衡点 |
| high | 回归风险识别、逻辑严谨性审查 | 审查需要更深的推理和质疑能力 |
.codex/
├── config.toml # 总配置（并发限制、层级限制）
└── agents/
├── default.toml # 通用代理
├── explorer.toml # 探索代理
├── worker.toml # 执行代理
└── reviewer.toml # 审查代理[agents]
max_threads = 6 # 最多并行 6 个子代理任务
max_depth = 1 # 单层委派，避免递归创建导致上下文失控max_depth = 1 是偏稳妥的起步方案，适合文档类、前端类和中等规模代码修改任务。
explorer.toml（探索代理）：
name = "explorer"
model = "gpt-5.4"
model_reasoning_effort = "low"
sandbox_mode = "read-only"reviewer.toml（审查代理）：
name = "reviewer"
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"| 配置层级 | 路径 | 作用 |
|---|---|---|
| 全局配置 | ~/.codex/ | 所有项目共享的基础代理体系 |
| 项目配置 | 项目根/.codex/ | 项目级覆盖或扩展 |
执行优先级：项目配置 > 全局配置
采用"先局部验证，再推广全局"的策略：
除模型与强度外，每个子代理应配置专门的 developer_instructions，固化职责边界：
| 角色 | 行为约束要点 |
|---|---|
| explorer | 专注探索，输出结构化结论，不修改任何文件 |
| worker | 按指令定点修改，不顺手做无关重构 |
| reviewer | 优先关注真实缺陷和回归风险，而非风格问题 |
| default | 承接通用任务时保持范围收敛，不扩散 |
子代理通常不会自动无条件触发，建议在任务提示中明确委派意图：
开两个 subagents 并行：
1. explorer 先定位主题设置抽屉的状态流和入口文件
2. reviewer 审查这次改动的回归风险和测试缺口或按流水线顺序：
先用 explorer 梳理通信链路，
再让 worker 做定点修改，
最后让 reviewer 做一次回归审查。修改配置后建议重开会话，确保新配置从启动阶段被读取。
当项目出现大量固定类型任务时，可继续拆出新角色：
doc-writer：文档编写frontend-refactor：前端重构test-auditor：测试审计初期建议保持 4 角色体系，复杂度更可控。
| 问题 | 解决方案 |
|---|---|
| 子代理输出风格不一致 | 统一模型基座，仅调整推理强度 |
| explorer 修改了文件 | 设置 sandbox_mode = "read-only" |
| reviewer 直接改代码 | 权限隔离 + 行为约束明确"只审不改" |
| 子代理递归创建子代理 | 设置 max_depth = 1 限制层级 |
| 配置不生效 | 重开会话，确保启动时读取新配置 |