03-多Agent · 协作拓扑

预计阅读：10 分钟 适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7 · 最后审核：2026-05-09 本章回答：要分几个 agent？谁负责什么？怎么互相调用？

---

为什么要多 agent

单 agent 能跑，但跑不远。核心痛点：

1. 上下文爆炸：一个 agent 既做协调、又做业务、又做反思，SOUL.md 越写越长，skills 越装越多，最后 context window 撑不住。
2. 职责混乱：business prompt 和 meta prompt（怎么思考 / 怎么记录）混在一起，调 prompt 顾此失彼。
3. 记忆相互污染：民宿业务的数据进了招生 agent 的语义库，召回时噪声极大。
4. 无法并行：一个 agent 只能串行处理消息队列，用户等得久。

多 agent 架构把这些矛盾拆开：每个 agent 一个核心职责，通过 sessions_send / sessions_spawn 协作。

---

拓扑模式

模式一：星型（推荐入门）

              用户（飞书）
                 │
                 ▼
           ┌──────────┐
           │   main   │  ← 唯一入口 + 协调中枢
           └────┬─────┘
                │ sessions_send / sessions_spawn
     ┌──────────┼──────────┬──────────┐
     ▼          ▼          ▼          ▼
 ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
 │planner│ │业务A │ │业务B │ │业务C │
 └───────┘ └───────┘ └───────┘ └───────┘

特点：main 负责路由 + 兜底，业务 agent 专注领域。 适用：个人 + 小团队，业务 3-5 个。 缺点：main 是单点，main 挂了全挂。

模式二：星型 + 专项下挂

main → 业务agent → 专项agent（如浏览器自动化）

业务 agent 不直接做脏活（RPA / 大批量抓取 / 长跑任务），而是派给专项 agent。 这样业务 agent 的上下文干净，专项 agent 的失败不污染业务 agent 的记忆。

模式三：加 reflector（反思 agent）

main/业务 → 正常工作
            │
            ▼（异步）
         reflector ← 周期性审阅、沉淀记忆、写周报

reflector 不参与业务流，只负责把散落信息整理进 shared/MEMORY.md、输出周审卡片。 作者把这个角色单列，是因为”整理记忆”的心智模型和”解决问题”冲突 —— 放一起做总做不好。

---

作者的真实拓扑（可直接参考）

flowchart TB
    user[👤 用户<br/>飞书私聊]
    user --> main

    main[🧠 main · 智能管家<br/>飞书主 bot · 统一入口 · 路由]

    main -->|规划任务| planner[planner<br/>最强大脑]
    main -->|民宿业务| minsu[minsu<br/>民宿助理]
    main -->|招生业务| zhao[zhaosheng<br/>招生助理]
    main -->|内容运营| yying[yying<br/>运营助手]
    main -->|社区学习| molt[moltbook<br/>学习伙伴]

    minsu -->|内部派发| shang[shangfang<br/>途家浏览器自动化]

    refl[🔄 reflector<br/>记忆整理 · 周审卡片<br/>无飞书 bot · 仅 spawn 拉起]
    main -.异步触发.-> refl

    classDef entry fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    classDef biz fill:#f3e5f5,stroke:#7b1fa2
    classDef tool fill:#fff4e6,stroke:#ff9800
    classDef async fill:#e8f5e9,stroke:#388e3c,stroke-dasharray: 5 5
    class main entry
    class planner,minsu,zhao,yying,molt biz
    class shang tool
    class refl async

怎么读：

• 实线 = sessions_send / sessions_spawn 直接派发；虚线 = 异步 spawn（不等回报）
• main 是唯一飞书入口；reflector / shangfang 都没有 bot，必须由别人 spawn 起来
• minsu → shangfang 是「业务 agent → 专项 agent」的下挂模式

主 agent 列表（真实来源：~/.openclaw/openclaw.json 的 agents.list[]，名称以 name 字段为准）：

id	角色	主要职责
main	智能管家	飞书主 bot，路由 + 协调 + 记忆中枢
planner	最强大脑	任务规划、SOP 维护、方法论
minsu	民宿助理	民宿业务问答、房态、收益
zhaosheng	招生助理	小学招生宣传、家长咨询
yying	运营助手	小红书 / 内容制作
moltbook	学习伙伴	社区学习、agent 互动
reflector	记忆回顾	周期性记忆整理（无飞书 bot）
shangfang	上房助手	途家浏览器自动化（minsu 内部派发）

---

委派：sessions_send vs sessions_spawn

这是最常踩坑的地方。选错了轻则冗余、重则死锁。

权威决策表（来自 ~/.openclaw/shared/AGENTS.md 的派发决策树）：

场景	目标有飞书 bot？	需要上下文连续？	持续/一次性？	用哪个
① 继续已有对话	有	需要	持续	sessions_send
② 隔离任务 + 需要持续交互	有	不需要	持续	sessions_spawn(mode="session")
③ 一次性任务	有	不需要	一次性	sessions_spawn(mode="run")
④ 目标无 bot，从零开	无	—	—	sessions_spawn（从零创建）

sessions_send

给已有 session 发消息，等回复。

适合：main 和 planner 有持续对话关系、planner 记得上下文。

main：让 planner 在已有对话里继续推进"小学招生 2026 Q2"这个任务。
→ 调用 sessions_send 到 planner 的现有 session。

sessions_spawn(mode=“session”)

新建一个持续 session（后续还能用 sessions_send 接着聊）。

适合：启动一个长跑业务，比如”复盘第 17 周所有民宿订单”，开始后后续还有迭代。

sessions_spawn(mode=“run”)

新建一个一次性 session，跑完即走，不留上下文。

适合：一次性的工具调用，比如”帮我生成这个月的账单 PDF”，跑完拿结果就完。

具体调用方式

OpenClaw 的工具调用不是 JavaScript 代码，而是 agent 通过 sessions_send / sessions_spawn 工具名 + JSON 参数调起。参数的精确 schema 以 agent 自己的 TOOLS 上下文为准（~/.openclaw/shared/TOOLS.md 有工具总览）。

不要自己拼 curl / HTTP 请求调 gateway —— agent 内部 runtime 会帮你接管参数封装。

---

派发前确认流程（强制）

来源：shared/AGENTS.md 第二节。所有派发都必须走，禁止跳过直接 sessions_send。

触发词：“让 [agent] 去…”、“派发给…”、“多 agent 协作”、“群协作”

步骤

1. 自动诊断（3 个 Y/N 问题）：目标 agent 有 bot？需要上下文连续？持续还是一次性？
2. 匹配场景（见上表 ①/②/③/④）
3. 展示选项（飞书卡片）：让用户选”确认 / 换个方式 / 取消”
4. 用户回复后执行

为什么强制？—— 因为 agent 容易误判场景，发到不合适的 session 会把对方上下文搞脏。

---

拓扑设计原则

原则 1：一个 agent 一个核心职责

反面：main 既做协调、又做民宿、又做招生 → 上下文爆、prompt 难调、记忆互污染。 正面：按业务领域拆分，main 只做路由。

原则 2：sub-agent 不主动路由给同级 sub-agent

来源：shared/AGENTS.md：“Sub-agent 不主动派发给同级 sub-agent；任务完成后直接回报调用方。”

✅ planner → 完成后回报 main，由 main 决定要不要派 minsu
❌ planner → 直接派给 minsu

原因：避免 agent 互相踢皮球、死循环、以及调用链失控。

原则 3：专项能力独立成 agent

判据：

• 技术栈独立（如浏览器自动化需要 CDP）
• 工作流程独立（有自己的状态机）
• 失败会污染主业务上下文（如爬虫 403 了 main 不想看）

作者的 shangfang 就是典型：它是 minsu 的内部助手，minsu 只说”去上房”，不关心 shangfang 内部怎么点按钮。

原则 4：agent 数量上限 ≈ 7

每多一个 agent 带来固定成本：SOUL / IDENTITY / AGENTS / TOOLS / USER 各一份、workspace 目录、记忆库、运维监控。

超过 7 个，拓扑图连自己都记不住，周审卡片排版都排不下。不要追求”每个业务一个 agent”，优先保核心链路。

---

配置结构（主配置 + 每 agent 工作空间）

~/.openclaw/openclaw.json 的 agents 节

真实结构（截自作者的生产配置）：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "智能管家",
        "workspace": "~/.openclaw/workspace",
        "agentDir": "~/.openclaw/agents/main",
        "model": {
          "primary": "aigpt-openai/gpt-5.4",
          "fallbacks": [
            "aigpt-openai/gpt-5.4-mini",
            "aigpt-openai/gpt-5-mini",
            "aigpt-openai/gpt-4.1-mini",
            "aigpt-openai/gpt-4o-mini"
          ]
        },
        "subagents": {
          "allowAgents": ["planner", "moltbook", "yying", "minsu", "zhaosheng", "reflector", "shangfang"]
        },
        "tools": {
          "alsoAllow": [
            "feishu_im_user_message",
            "feishu_bitable_app_table_record",
            "lcm_grep", "lcm_describe", "lcm_expand"
          ]
        },
        "groupChat": {
          "mentionPatterns": ["main", "@main", "智能管家", "@智能管家"]
        },
        "thinkingDefault": "adaptive"
      }
    ]
  }
}

关键字段（真实字段名，MiniMax 版本写错过）：

字段	作用
id	agent 的唯一标识，别人派发给它时用
workspace	该 agent 的工作目录（放 SOUL / MEMORY / proactivity）
agentDir	该 agent 的配置目录（放 IDENTITY / HEARTBEAT）
subagents.allowAgents	允许派发到的下游 agent 白名单
tools.alsoAllow	额外允许的工具（飞书工具、LCM 等）
groupChat.mentionPatterns	群聊 @ 匹配规则
model.primary / fallbacks	模型与兜底模型

⚠️ 权限是白名单制：allowAgents 不写就派发不过去，即使 sessions_send 调用语法对。

每个 agent 的 workspace 文件

文件	作用	启动顺序
SOUL.md	人设 / 核心原则	①
USER.md	对话对象信息（bot 的 open_id 等）	②
IDENTITY.md	agent 名字 / 定位	③
HEARTBEAT.md	心跳 / 运行时元数据	④
TOOLS.md	工具清单（特定于本 agent，通用的在 shared/TOOLS.md）	⑤
AGENTS.md	协作规则（通用的在 shared/AGENTS.md）	⑥
MEMORY.md	稳定规则 / 长期记忆索引（仅直聊加载）	⑦
memory/YYYY/MM/	日期日志	⑧

bootstrap-extra-files 机制：shared/SOUL.md shared/TOOLS.md shared/AGENTS.md 会在 agent:bootstrap 时自动注入所有 agent 的 Project Context，不用每个 agent 自己复制一份。详见 03-多Agent/02-共享规范。

---

常见问题

Q：agent 之间能直接共享内存吗？

不能，也不该。OpenClaw 设计上 agent 之间只通过消息传递通信。sessions_send 发消息，回的也是消息。想要”共享知识”，放在 shared/ 里让 bootstrap-extra-files 注入，而不是让 A 去读 B 的 workspace。

Q：派发失败怎么降级？

三层兜底：

1. 超时配置：sessions_send 带超时参数（具体字段以当前 CLI 为准，详见 openclaw doctor 或官方 docs）
2. 白名单校验：派发前在 main 的提示里检查目标 agent 是否在 allowAgents 内
3. 用户回显：失败时把错误回给用户，而不是沉默丢弃

Q：reflector 怎么不干扰主流程？

两招：

1. 不订阅飞书：reflector 在 openclaw.json 里不配 groupChat，它只被 sessions_spawn 显式拉起
2. 异步调用：用 sessions_spawn(mode="run")，主 agent 不等它，它跑完写到 shared/MEMORY.md / memory/YYYY-MM-DD.md 就结束

Q：什么时候该再加一个 agent？

看三个信号：

1. 现有某个 agent 的 SOUL.md + TOOLS.md 合起来超过 15KB（上下文吃不消）
2. 该 agent 的记忆库里有明显两类互不相关的事实（民宿 + 招生塞一起）
3. 某个业务有独立的失败模式 / 工作节奏（周期任务 vs 实时响应）

否则暂时不加，先优化现有 agent 的 prompt 切分。

---

验证清单

检查项	命令	期望
所有 agent 能被 list	openclaw gateway status	列出所有配置的 agent id
派发链路通	在 main 对话里说”让 planner 规划…“	main 调 sessions_send 到 planner，planner 回复
权限白名单生效	尝试派发给 allowAgents 里没有的 agent	应被拒绝
bootstrap 注入生效	任意 agent 的第一条消息	能引用 shared/AGENTS.md 的派发决策树内容

---

下一步

• 02-配置/00-多Agent架构 —— 从零规划拓扑的问答法
• 03-多Agent/01-委派机制 —— sessions_send / spawn 的细节与陷阱
• 03-多Agent/02-共享规范 —— SOUL.md 继承体系 + bootstrap-extra-files 深度配置

---

本章准确性保证 所有命令、字段名、拓扑模式都基于 ~/.openclaw/openclaw.json、~/.openclaw/shared/AGENTS.md、~/.openclaw/shared/TOOLS.md 交叉验证。sessions_send / sessions_spawn 四种场景矩阵直接引用自 shared/AGENTS.md 第三节。

---

导航：← 飞书深度配置 · 📖 目录 · → 委派机制