我来分享下 codex cli 中 multi agent 功能的用法吧。

1. 首先，有什么用？

1. 加速 token 消耗
2. agent 是独立上下文，主 agent（就是你命令行中与其对话的那一个）会自动与其他 agent 沟通，传递输入、读取输出，能让每个 agent 在其任务范围内更加精确（LLM上下文越长，性能及准确性可能越差）
3. 如果多 agent 编排得当，可以：
   • 加快实现速度（主 agent 判定任务可并行，可能会同时分配多个子 agent 一起执行）
   • 提高实现质量（例如编码、审核分步进行，审核 agent会指出编码过程产生的问题）
   • 其他的我也暂时不清楚了

2. 开启方式

• 方式 1：命令行中输入 /experimental 然后勾选

  

  Multi-Agent开启选项1043×277 17.1 KB

• 方式 2：修改 config.toml

  # features中开启选项
  [features]
  multi_agent = true
  

3. 使用方式

开启之后，可以先按正常对话方式问一句：现在有哪些agents可以用

不出意外可以看到类似回复（我的版本是0.114.0，版本太老可以更新下）：

可用Agent列表1042×393 19.1 KB

这就表示 agents 可以使用了。

默认带有 default / explorer / worker 三个 agent，后续你要做什么功能的话，直接对话里指明要用 agent 完成，例如：使用agent分析当前项目结构，帮我实现xxxx。

之后的对话过程中，如果你看到以下类似输出（Spawned 人名[agent]），就是 agent 开始工作了：

07ab7e99-0f14-451b-9ecf-4d77db76a2f71045×229 108 KB

如果你想看子 agent 在做什么，依然是使用斜杠命令 /agent，会出现以下类似选项（main 就是当前主窗口，其他的就是生成的 agent）：

image756×132 6.22 KB

通过选项切换即可（切换后，也可以通过 /status 看到，各个 agent 都是独立上下文）

以上就是最基础的用法啦！

4. 如何自定义 Agent

除了默认的三种 agent 之外，可以通过 config.toml 自定义你想要的任何 agent，以我自己定义的三个 Agent (我是搞游戏的) 为例：

[agents]
max_threads = 6
max_depth = 1

[agents.solution_architect]
description = "方案架构师。负责复杂系统边界收敛、依赖梳理、切片设计与高层取舍，侧重高性能多线程架构与战斗框架设计。"
config_file = "agents/solution_architect.toml"

[agents.systems_implementer]
description = "系统实现者。负责按既定切片实现、重构与修复，侧重高性能 C#、Unity 系统集成与复杂战斗逻辑落地。"
config_file = "agents/systems_implementer.toml"

[agents.implementation_reviewer]
description = "实现审查者。负责需求一致性、架构一致性、坏味道与性能稳定性审计，侧重 Burst 兼容性、内存安全与大规模模拟风险。"
config_file = "agents/implementation_reviewer.toml"

config_file 指向你的 agent 定义文件（路径为相对路径，与 config.toml 同级)，示例内容如下：

model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
你是一名实现一致性与质量门禁审计者。你的职责不是重新设计系统，也不是顺手实现代码，而是确认实现没有偏离用户需求、没有偏离既定架构，并且没有引入临时逻辑、补丁逻辑或其他会持续腐化系统的坏味道。

1. **输入前提**：
   - 审计时优先对照三类证据：用户需求、架构设计结论、实现代码。
   - 如果缺少需求或架构结论，必须明确指出“当前审计依据不足”，并写明你使用的假设。
   - 若已有 \`solution_architect\` 的结论，必须把它视为主要架构约束来源，而不是重新发明一套方案。

2. **核心职责**：
   - **需求一致性审计**：检查实现是否真正满足用户目标，是否遗漏关键约束，是否偷偷扩 scope 或偷换问题。
   - **架构一致性审计**：检查实现是否偏离既定边界、切片顺序、依赖约束、禁止改动项。
   - **坏味道审计**：重点识别临时逻辑、补丁逻辑、兼容兜底、双轨分支、为绕过问题而加的特殊 case、复制粘贴扩散、难回收的 workaround。
   - **正确性与稳定性审计**：检查结构漏洞、逻辑缺陷、隐藏前提、边界条件失真。
   - **性能与底层约束审计**：严格检查 Burst 兼容、Job 中非法 API/托管引用、NativeCollection 竞态、生命周期错误、GC Alloc、缓存与数据布局问题。

3. **明确禁止事项**：
   - 禁止把审计变成重新设计架构；只有在发现阻塞级错误时，才允许指出必须回退的设计问题。
   - 禁止直接改代码或代替实现者给出大段实现代码。
   - 禁止输出“感觉不太好”这类空泛评价；每个问题都要说明影响、触发条件与证据。
   - 禁止为了凑数罗列低价值建议；只保留真正影响需求、架构、稳定性、性能或维护性的点。

4. **标准输出格式**：
   - 默认输出一份 \`一致性审计结果\`，并且**问题必须优先于总结**。
   - 审计卡至少包含以下部分：
     - \`高优先级问题\`：按严重度排序，直接列出问题、影响与证据。
     - \`需求偏差\`：实现与用户目标是否一致。
     - \`架构偏差\`：实现与既定设计/切片是否一致。
     - \`坏味道问题\`：临时逻辑、补丁逻辑、兜底、双轨、重复分支等。
     - \`性能与稳定性风险\`：Burst Job / Native 容器 / 并发 / GC / 缓存等风险。
     - \`验收结论\`：是否建议通过、回退、补充修改或补充验证。
   - 引用代码时必须给出文件与行号，结论必须能追溯到证据。
"""

按以上步骤定义好之后，就可以像之前那样使用你自己的 Agent 了。

有了第一份配置之后，后续修改、新增都可以让 codex 直接来帮你做。

5. 如何让多个 Agent 配合工作

这一块我也只是初步尝试，抛砖引玉。

我现在用 codex cli 的 $skill creator 技能，创建了一个 skill 用来约束三类 agent 角色（设计、实现、审核）一起工作。假设创建的 skill 名为 agents-dev，后续需要使用 agent 工作时，就直接调用 skill: $agents-dev 再输入需求，然后就会按 skill 里的约束来驱动不同 agents执行了。

6. 目前遇到的问题及解决办法

6.1. 提示 spawn failed

问题原因：生成的 agents 太多，数量超过了配置里的限制（例如上面的配置里限制了最大数量为 6）。这个可能是 codex 自己的 bug？毕竟还是试验功能。

解决办法：skill 里加约束，优先复用空闲 agents 而不是每次都重新 spawn agent。

6.2. 主 Agent 中断其他 Agent 的运行然后自己接手任务

问题原因：猜测可能是模型的默认行为，如果子 agent 执行的任务比较复杂，可能耗时比较长，然后主 agent 等待几轮时间后就会打断其执行自己来做

解决办法：skill 里加约束，让其尽可能等待其他 agent 执行完成（5.4 还是比较智能，等太久就会主动询问其他 agent 具体啥情况了，会按照子 agent 的回复来决定做什么）