🕸️ OpenClaw 主代理与子代理：AI 如何学会"找帮手"？

你有没有遇到过这种情况：让 AI 做一件事，它说"好的"，然后卡住了——因为任务太复杂，一个 AI 搞不定。

OpenClaw 的解决方案很聪明：一个 AI 搞不定？那就派一群 AI 去干！

---

一、先讲个故事：当 AI 遇到搞不定的任务

场景： 你对 OpenClaw 说：“帮我审查一下这个项目里所有的代码，找出潜在的内存泄漏。”

这个项目有 500 个文件，分布在 20 个目录中。如果让一个 AI 从头读到尾：

1. 它会读得很慢——一个文件一个文件地读
2. 它会忘记前面看了什么——上下文窗口有限
3. 你会等很久——可能半小时后才收到回复

OpenClaw 的做法完全不同：

你："帮我审查所有代码，找内存泄漏"
        │
        ▼
主 AI（项目经理模式）：
  "这个任务太大了，我一个人干太慢。
   我把项目拆成 5 块，派 5 个子 AI 去并行审查。"
        │
        ▼
子 AI-1 → 审查 src/gateway/ → 发现 2 处泄漏
子 AI-2 → 审查 src/agents/ → 发现 1 处泄漏
子 AI-3 → 审查 src/channels/ → 发现 0 处泄漏
子 AI-4 → 审查 src/providers/ → 发现 3 处泄漏
子 AI-5 → 审查 src/cli/ → 发现 1 处泄漏
        │
        ▼
5 个子 AI 并行工作，互不干扰
        │
        ▼
结果自动汇总到主 AI
        │
        ▼
主 AI 整合成一份完整报告发给你
（整个过程只用了 2 分钟）

这就是 OpenClaw 多代理系统的核心价值：把大任务拆成小任务，并行执行，自动汇总。

---

二、核心概念：Session 和 Agent 到底是什么？

在深入之前，先搞清楚两个基础概念。

Session（会话）= 办公室

Session 是一个对话空间。你在微信上打开一个聊天窗口，那就是一个 Session。

特点：

• 一个 Session 同一时间只能有一个活跃的 Agent
• Session 有独立的上下文窗口（Token 空间）
• Session 可以持久化保存和恢复

Agent（代理）= 员工

Agent 是真正干活的人。每个 Agent 有自己的：

• 身份（IDENTITY.md）— 叫什么名字、用什么头像
• 性格（SOUL.md）— 说话风格、行为边界
• 操作手册（AGENTS.md）— 怎么干活、有什么经验教训
• 工具集（Tool Profile）— 能用什么工具

用公司来理解

Session = 办公室（物理空间）
Agent = 员工（在办公室里干活的人）

一个办公室同一时间只有一名员工接待客户。
但这位员工可以：
  - 打电话给其他办公室的专家请教问题（sessions_send）
  - 派实习生去新办公室完成专项任务（sessions_spawn）
  - 换一个员工来接待（Agent Swapping）

---

三、三种协作模式

OpenClaw 的多代理系统支持三种协作模式，适用于不同的场景。

模式 A：父子协作（Parent-Child Spawn）⭐ 最常用

核心工具： sessions_spawn

这是最常用的模式。主 Agent 把复杂任务外包给子 Agent，子 Agent 在隔离的 Session 中独立执行。

工作流程：

主 Agent 的 Session（你正在聊天的窗口）
        │
        ▼
主 Agent 判断："这个任务太复杂了，我需要派子 Agent 去干"
        │
        ▼
调用 sessions_spawn 工具
  ├── 创建新的子 Session（独立的办公室）
  ├── 给子 Agent 分配任务指令
  ├── 指定 PromptMode: minimal（省 Token）
  └── 指定清理策略（delete 或 keep）
        │
        ▼
子 Agent 在隔离环境中独立工作
主 Agent 可以同时处理其他事情
        │
        ▼
子 Agent 完成任务 → 结果自动通报给主 Agent
        │
        ▼
主 Agent 收到结果 → 整合后回复你

真实场景举例：

你："帮我分析一下这个 GitHub 仓库的代码质量"

主 AI 的思考过程：
  "这个仓库有 200 个文件，我一个人读太慢了。
  我派 4 个子 AI 去并行分析，每个负责 50 个文件。"

主 AI 执行：
  sessions_spawn({
    task: "分析 src/api/ 目录下的代码质量",
    promptMode: "minimal"
  })
  sessions_spawn({
    task: "分析 src/db/ 目录下的代码质量",
    promptMode: "minimal"
  })
  sessions_spawn({
    task: "分析 src/ui/ 目录下的代码质量",
    promptMode: "minimal"
  })
  sessions_spawn({
    task: "分析 src/utils/ 目录下的代码质量",
    promptMode: "minimal"
  })

4 个子 AI 并行工作...
5 分钟后，所有结果自动返回。

主 AI 汇总：
  "分析完成！发现以下问题：
   - api/ 目录：2 处 SQL 注入风险
   - db/ 目录：1 处连接未关闭
   - ui/ 目录：代码风格不一致
   - utils/ 目录：✅ 质量良好"

模式 B：跨会话通信（Cross-Session Messaging）

核心工具： sessions_send

不同 Session 之间的 Agent 可以互相"发消息"。适合需要专家协作的场景。

真实场景举例：

你在微信上问个人助理 AI：
  "帮我问一下服务器监控 AI，最近服务器状态怎么样？"

个人助理 AI（微信 Session）：
  调用 sessions_send → 发给服务器监控 AI（监控 Session）

服务器监控 AI：
  查询监控数据 → 回复："最近一周一切正常，CPU 平均 30%"

个人助理 AI：
  转达给你："服务器监控说一切正常 👍"

和父子协作的区别：

	父子协作（sessions_spawn）	跨会话通信（sessions_send）
关系	上下级（主→子）	平级（同事之间）
新 Session	创建新的子 Session	使用已有的 Session
典型场景	派实习生去干活	请教其他领域的专家
结果处理	自动通报给主 Agent	对方回复后自己处理

模式 C：动态身份切换（Agent Swapping）

核心工具： 管理指令 /agent

不改变聊天窗口，直接"换人"。

真实场景举例：

你在微信上和"个人助理"聊天：
  你："今天有什么安排？"
  个人助理："下午 2 点有会议，晚上 7 点有饭局。"

你输入：/agent coder

微信窗口没变，但 AI 已经换人了：
  你："帮我 review 一下这个 PR"
  Coder AI："好的，我来审查代码..."
  （它现在是一个专业的代码审查助手，性格和工具集都变了）

你再输入：/agent personal

又切回个人助理：
  你："刚才的会议改到 3 点了"
  个人助理："好的，已更新日程。"

---

四、子代理的完整生命周期

子代理从创建到销毁，经历 5 个阶段：

① 注册 (Register)
   ├── 记录 runId（唯一标识）
   ├── 记录会话键（属于哪个主 Session）
   ├── 记录任务描述
   └── 实时持久化到磁盘（防止丢失）
        │
        ▼
② 异步执行 (Execute)
   ├── 子 Agent 在独立 Session 中运行
   ├── 使用 PromptMode: minimal（省 Token）
   ├── 主 Agent 可以同时处理其他事务
   └── 主 Agent 可通过 agent.wait 挂起等待
        │
        ▼
③ 事件监听 (Monitor)
   ├── 子代理注册表订阅全局 lifecycle 事件
   ├── 毫秒级感知子 Agent 状态变化
   └── 支持指数退避重试（网络波动自动重试）
        │
        ▼
④ 结果冻结 (Freeze)
   ├── freezeRunResultAtCompletion 捕获最终结果
   ├── 只保留有效文本，过滤掉内部推理过程
   └── 结果与 runId 绑定，可追溯
        │
        ▼
⑤ 自动通报 (Announce)
   ├── 系统主动将结果推送给主 Agent
   ├── 主 Agent 不需要主动轮询
   └── 通报失败 → 指数退避重试
        │
        ▼
⑥ 清理 (Cleanup)
   ├── delete 模式：任务完成立即销毁子 Session
   └── keep 模式：保留会话历史供后续审计

韧性设计：系统重启也不怕

如果 Gateway 在子代理执行过程中重启了怎么办？

// Gateway 重启时自动执行
restoreSubagentRunsOnce()
// → 扫描磁盘上持久化的子代理注册信息
// → 自动恢复对未完成任务的追踪
// → 任务不因系统中断而丢失

---

五、子代理的 System Prompt：为什么用 minimal 模式？

子代理和主代理最大的区别之一：子代理的 System Prompt 更精简。

对比一下

主代理的 System Prompt（full 模式，约 5000-8000 字）：

┌─ 你是谁（身份 + 性格）
├─ 用户是谁（偏好 + 习惯）
├─ 你在哪运行（OS、Shell、时间）
├─ 你该怎么做（操作规范 + 历史教训）
├─ 你能用什么（工具列表）
└─ 现在什么情况（今日待办 + 最近对话）

子代理的 System Prompt（minimal 模式，约 1000-2000 字）：

┌─ 你在哪运行（OS、Shell、时间）
├─ 你该怎么做（只保留核心规则）
└─ 你能用什么（工具列表）
（跳过身份设定、自我更新等章节）

为什么子代理不需要知道这些？

子代理去"审查 100 个文件"时，它不需要知道：

• 用户叫什么名字（USER.md）
• AI 是什么性格（SOUL.md）
• 之前踩过什么坑（AGENTS.md 的教训部分）

它只需要知道：用什么工具、在什么环境、核心规则是什么。

效果： 每次对话省 75% 的 Token。如果子代理要来回对话很多轮，这个节省非常可观。

---

六、记忆隔离：子代理能看到什么？

子代理不是"什么都能看"的。它的记忆访问权限受到严格控制：

记忆组件	独立性	子代理可访问？
AGENTS.md（操作手册）	高度独立	受限子集
SOUL.md（性格定义）	高度独立	受限子集
USER.md（用户档案）	通常共享	✅ 可访问
memory/*.md（历史日志）	可配置	按配置
向量数据库（RAG 索引）	按 Agent 索引	按 agentId 过滤

记忆流转机制

子代理完成任务后，它的"记忆"不会直接消失，而是通过一个筛选流程回流到主代理：

子代理完成任务
        │
        ▼
子代理的发现 → 通过 runSubagentAnnounceFlow 通报给主代理
        │
        ▼
主代理判断：
  ├── 这个发现很重要 → 写入自己的 MEMORY.md / AGENTS.md
  └── 这个发现是临时的 → 忽略
        │
        ▼
本质：子代理的短期记忆 → 主代理筛选 → 转化为主代理的长期经验
就像：员工给老板汇报 → 老板决定哪些值得记入档案

---

七、深度嵌套：子代理还能派子代理

OpenClaw默认子代理深度（maxSpawnDepth: 1）。
若将配置改为 maxSpawnDepth: 2 可启用编排器模式，子代理最多可再向下派发一层 Worker。
最大支持 5 层嵌套（maxSpawnDepth: 1–5）。

你
  │
  ▼
主 Agent A
  │
  ├── sessions_spawn → 子 Agent B
  │     │
  │     └── sessions_spawn → 孙 Agent C
  │           │
  │           └── sessions_spawn → 曾孙 Agent D
  │
  └── sessions_spawn → 子 Agent E

系统通过 countActiveDescendantRuns 实时统计整个任务树中的活跃后代数量。

真实场景：

你："帮我分析这个大型项目，生成一份完整的优化报告"

主 AI（项目经理）：
  "我先派 3 个子 AI 去分别分析前端、后端、数据库"

子 AI-1（前端分析）：
  "前端代码太多了，我再派 2 个孙 AI 去分别分析 Vue 组件和 CSS"

孙 AI-1（Vue 组件分析）：
  "好的，我开始审查 Vue 组件..."
孙 AI-2（CSS 分析）：
  "好的，我开始审查 CSS 文件..."

子 AI-1 汇总孙 AI 的结果 → 报告给主 AI
子 AI-2（后端分析）→ 直接报告给主 AI
子 AI-3（数据库分析）→ 直接报告给主 AI

主 AI 汇总所有结果 → 生成完整优化报告 → 回复你

---

八、动态航向修正：任务做到一半，方向变了怎么办？

有时候，子代理正在执行任务，但情况变了。比如：

你派子 AI 去"分析项目性能问题"
子 AI 分析到一半，你发现：
  "等等，我说的不是这个项目，是另一个项目"

传统做法：取消子 AI，重新派一个，从头开始
OpenClaw 的做法：航向修正

航向修正（Steer Restart）：

// 主代理在子代理执行途中调用
markSubagentRunForSteerRestart({
  runId: "sub-001",
  newInstructions: "目标项目已变更，请分析 /projects/new-app/ 目录"
})
// → 子代理收到新指令，重新开始
// → 但之前的上下文不会完全丢失

---

九、两种清理策略：delete vs keep

子代理任务完成后，它的 Session 怎么处理？

策略	行为	适用场景
delete（默认）	任务完成后立即销毁子 Session，释放资源	一次性任务，不需要回头看
keep	保留子 Session 的历史记录，供后续审计	需要追溯的任务、合规要求

建议： 大部分场景用 delete 就够了。只有当你觉得"以后可能需要查这个子 AI 当时是怎么干的"时，才用 keep。

---

十、核心约束：1 Session = 1 活跃 Agent

这是 OpenClaw 多代理系统的一个硬性约束：

每一个会话（无论是 WhatsApp 窗口、Telegram 私聊还是 Web Tab）在同一时间都唯一绑定一个 agentId。

为什么这样设计？

防止多个 AI 在同一上下文内相互干扰，导致：

• Prompt 污染：Agent A 的指令混入 Agent B 的上下文
• Token 爆炸：多个 Agent 的上下文叠加，迅速撑满窗口
• 逻辑混乱：用户分不清当前在跟谁说话

怎么实现多代理？

不是让多个 Agent 挤在一个 Session 里，而是：

• 每个子 Agent 有自己的独立 Session（新办公室）
• 通过 sessions_spawn 创建新 Session
• 通过 sessions_send 跨 Session 通信
• 通过 agent.wait 等待结果

---

十一、配置多代理：两种记忆隔离模式

在 config.json 中，你可以配置多个 Agent：

{
  "agents": [
    {
      "agentId": "personal",
      "workspaceDir": "~/.openclaw/workspace/"
    },
    {
      "agentId": "coder",
      "workspaceDir": "~/.openclaw/workspace/"
    },
    {
      "agentId": "assistant",
      "workspaceDir": "~/my-custom-workspace/"
    }
  ]
}

完全隔离模式

每个 Agent 配置独立的 workspaceDir 路径：

Agent A 的 workspace/          Agent B 的 workspace/
├── AGENTS.md                  ├── AGENTS.md
├── SOUL.md                    ├── SOUL.md
├── USER.md                    ├── USER.md
└── memory/                    └── memory/

效果： Agent A 积累的实战教训，Agent B 完全无法感知。它们是互不相识的独立个体。

适用场景： 工作 Agent 与个人 Agent 需要完全隔离。

根目录共享模式（默认）

多个 Agent 共享同一根目录，通过文件名后缀区分：

~/.openclaw/workspace/
├── USER.md                    ← 全局共享
├── AGENTS.md                  ← personal 的手册
├── AGENTS.coder.md            ← coder 专属手册
├── SOUL.md                    ← personal 的灵魂
├── SOUL.coder.md              ← coder 的灵魂（更偏工程师气质）
└── memory/
    ├── 2026-03-11.md
    └── ...

效果： 所有 Agent 读取同一份 USER.md，确保对主人的认知一致。但各自拥有独立的操作手册和性格定义。

适用场景： 多个专项 Agent 协同服务同一用户。

---

十二、总结：一张图看懂主代理和子代理

你（微信 / Telegram / 任何渠道）
        │
        ▼
┌─────────────────────────────────────────────────┐
│  Session（你的聊天窗口）                          │
│  ┌───────────────────────────────────────────┐  │
│  │  主 Agent（项目经理）                      │  │
│  │  - 身份：personal / coder / life          │  │
│  │  - PromptMode: full                       │  │
│  │  - 工具集：完整权限                        │  │
│  │  - 记忆：完整工作区                        │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
        │
        ├── sessions_spawn ──────────────────────┐
        │                                         │
        ▼                                         ▼
┌──────────────────────┐          ┌──────────────────────┐
│ 子 Session（隔离空间） │          │ 子 Session（隔离空间） │
│ ┌──────────────────┐ │          │ ┌──────────────────┐ │
│ │ 子 Agent（实习生）│ │          │ │ 子 Agent（实习生）│ │
│ │ - PromptMode:    │ │          │ │ - PromptMode:    │ │
│ │   minimal        │ │          │ │   minimal        │ │
│ │ - 工具集：受限    │ │          │ │ - 工具集：受限    │ │
│ │ - 记忆：临时工作区│ │          │ │ - 记忆：临时工作区│ │
│ └──────────────────┘ │          │ └──────────────────┘ │
└──────────────────────┘          └──────────────────────┘
        │                                   │
        └────────── 自动通报 ────────────────┘
                        │
                        ▼
                主 Agent 汇总结果 → 回复你

核心价值

能力	说明
并行执行	多个子 Agent 同时工作，大幅缩短任务时间
隔离安全	子 Agent 在独立 Session 中运行，互不干扰
自动通报	任务完成后结果自动返回，无需轮询
韧性设计	网络波动自动重试，系统重启自动恢复
航向修正	任务执行中可以动态调整方向
记忆流转	子 Agent 的发现可沉淀为主 Agent 的长期经验
深度嵌套	子 Agent 还能派自己的子 Agent，任意层级
灵活清理	delete 释放资源，keep 保留审计痕迹

---

本文由 代码牧星人 原创