第9章多 Agent 架构

一句话：一个 Gateway 可以运行多个 Agent，每个 Agent 有独立的人格、记忆和工具——用 Bindings 路由规则决定谁处理哪条消息。

9.1 为什么要多 Agent

单个 Agent 就像一个全能员工——什么都能做，但什么都不够专精。当你的需求变复杂：

工作和生活想用不同的 AI 人格
不同渠道需要不同的专业知识
需要一个专门处理代码审查的 Agent

这时候就需要多 Agent。每个 Agent 有独立的：

Workspace：独立的 Bootstrap 文件和记忆
人格：独立的 SOUL.md 和 AGENTS.md
工具集：独立的 TOOLS.md
Session：互不干扰的对话上下文

9.2 配置多 Agent

在 agents.list 中定义多个 Agent：

{
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v3.2" },
    },
    list: [
      {
        id: "main",
        default: true,  // 默认 Agent，未匹配到 binding 时使用
        workspace: "~/.openclaw/workspace",
      },
      {
        id: "home",
        workspace: "~/.openclaw/workspace-home",
      },
      {
        id: "code-review",
        workspace: "~/.openclaw/workspace-review",
        // 可以覆盖 defaults 中的模型
        model: { primary: "minimax/MiniMax-M2.5" },
      },
    ],
  },
}

9.3 Bindings 路由规则

Bindings 决定了哪些消息路由到哪个 Agent：

{
  bindings: [
    {
      agentId: "home",
      match: { channel: "whatsapp" },
    },
    {
      agentId: "code-review",
      match: {
        channel: "discord",
        peer: { kind: "channel", id: "CHANNEL_ID" },  // 指定频道
      },
    },
    // 未匹配到任何 binding → 路由到 default Agent
  ],
}

匹配规则

match 中的所有条件必须同时满足（AND 逻辑）
多个 binding 按精确度优先匹配：peer > guildId > accountId > 渠道级别；同一级别内按配置顺序，第一个命中的生效
没有命中任何 binding 的消息路由到 default: true 的 Agent

可用的匹配字段

字段	说明	示例
`channel`	渠道类型	`"telegram"`, `"discord"`, `"whatsapp"`
`accountId`	账户 ID	`"personal"`, `"work"`
`peer`	对话对象（对象格式）	`{ kind: "direct", id: "123" }`
`guildId`	Discord 服务器 ID	`"123456789012345678"`
`teamId`	MS Teams 团队 ID	`"team-id"`

实战：工作/生活分离

{
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v3.2" },
    },
    list: [
      { id: "work", default: true, workspace: "~/.openclaw/workspace-work" },
      { id: "life", workspace: "~/.openclaw/workspace-life" },
    ],
  },
  bindings: [
    { agentId: "life", match: { channel: "whatsapp" } },
    { agentId: "life", match: { channel: "telegram", accountId: "personal-bot" } },
    // 其余 → work
  ],
}

9.4 Sub-agent 派生

Agent 可以在运行时通过 sessions_spawn 工具派生子 Agent 来并行处理任务。

聊天命令

/subagents spawn coding "研究 React Server Components 最佳实践"
/subagents list          # 列出当前 session 的子 Agent
/subagents info <id>     # 查看详情
/subagents log <id>      # 查看日志
/subagents kill <id|all> # 终止

子 Agent 模型配置

为子 Agent 配置经济型模型以控制成本：

{
  agents: {
    defaults: {
      subagents: {
        model: "deepseek/deepseek-v3.2",  // 子 Agent 用便宜的模型
        thinking: "low",                   // off | low | medium | high
      },
    },
  },
}

成本提醒：每个子 Agent 有独立的上下文和 token 消耗，多个子 Agent = 叠加成本。主 Agent 用好模型做决策，子 Agent 用便宜模型执行。

9.5 STATE.yaml 协调模式

多个 Agent 之间可以通过 STATE.yaml 文件共享状态：

current_project: "电商后台"
sprint_goal: "完成用户模块 v2"
blockers:
  - "等待设计稿"
  - "数据库迁移未完成"

任何 Agent 都可以读取和更新这个文件，实现松耦合的协调。

9.6 Agent 间通信（sessions_send）

Agent 可以通过 sessions_send 工具向其他 Agent 发送消息：

Agent A → sessions_send("code-review", "请审查 PR #42") → Agent B

这使得 Agent 之间可以协同工作：一个 Agent 收到任务后，可以委派给更专业的 Agent 处理。

9.7 真实案例

4-Agent 虚拟团队

一个独立创业者（Solo Founder）用 4 个 Agent 组建了虚拟公司：

Agent ID	角色	Workspace	渠道
`milo`	策略与产品	workspace-milo	Telegram 群组
`josh`	商务与营销	workspace-josh	Telegram 群组
`angela`	内容与设计	workspace-angela	Telegram 群组
`bob`	编码与 DevOps	workspace-bob	Telegram 群组

四个 Agent 在同一个 Telegram 群组里协调工作，每个 Agent 有不同的人格和专长。通过 Bindings 规则，@milo 的消息路由到策略 Agent，@bob 的消息路由到编码 Agent。

10-Agent 自动化军团

更大规模的案例：10 个 Agent、3 台机器、1 个 Discord 服务器：

邮件清理 Agent（自动清理万封邮件）
广告审查 Agent（审查广告支出和效果）
社交发布 Agent（自动发布内容到 X/Twitter）
报告生成 Agent（每日生成运营报告）
多个领域专家 Agent

通过 Bindings 将 Discord 不同频道路由到不同 Agent，实现大规模自动化。

9.8 小结

概念	说明
多 Agent	`agents.list` 定义多个 Agent，各有独立 workspace
Bindings	按渠道/账户/群组/发送者路由消息到对应 Agent
匹配规则	AND 逻辑，按顺序匹配，未命中走 default
Sub-agent	运行时派生，处理特定任务
STATE.yaml	多 Agent 共享状态文件
sessions_send	Agent 间通信工具

下一章进入自动化——让 Agent 主动做事，而不只是被动回复。

第9章 多 Agent 架构