OpenClaw 多 Agent 路由与绑定：Bindings 机制与广播组

在多租户 AI 网关架构中，"消息该由哪个 Agent 处理"是核心路由问题。OpenClaw 通过八级优先级的决策链与显式绑定配置，实现了从精确匹配到默认回退的完整路由体系。本文深度拆解其路由算法、隔离边界与广播组并行计算模式。

一、路由决策链：八级优先级匹配算法

OpenClaw 的路由系统采用确定性层级匹配策略，当消息进入 Gateway 时，按以下八级优先级逐层匹配，一旦命中即停止遍历。

1.1 优先级层级结构

+------------------------------------------------------------------+
|                    路由决策链（高→低优先级）                       |
+------------------------------------------------------------------+
|  T1  |  Exact peer        |  binding.peer 精确匹配（DM/群组/话题ID）  |
|  T2  |  Parent-peer       |  父级上下文继承（Thread → Channel）       |
|  T3  |  Guild + Roles     |  Discord 服务器+角色双重匹配              |
|  T4  |  Guild only        |  Discord 服务器单维度匹配                 |
|  T5  |  Team              |  Slack Workspace 匹配                    |
|  T6  |  Account           |  渠道账户维度匹配（如不同WhatsApp号码）    |
|  T7  |  Channel           |  全局渠道匹配（accountId: "*"）            |
|  T8  |  Default           |  agents.list[].default 或首个Agent        |
+------------------------------------------------------------------+

核心原则：最精确匹配胜出（Most-Specific-Wins）。高优先级绑定可覆盖低优先级配置，例如 T1 的 peer 级绑定可覆盖 T6 的 account 级绑定。

1.2 匹配算法执行流程

+-------------------+        +-------------------+        +-------------------+
|   消息进入 Gateway |        |  绑定列表预过滤    |        |  八级层级匹配      |
|  (携带元数据)      |   -->  | (Channel+Account)  |   -->  |  (逐层遍历)       |
+-------------------+        +-------------------+        +-------------------+
         |                             |                            |
         v                             v                            v
+--------+----------+        +---------+---------+        +---------+---------+
| 元数据提取         |        | 排除不相关绑定     |        | 返回首个匹配Agent  |
| - channel         |        | 仅保留可能匹配项   |        | 生成 Session Key  |
| - accountId       |        |                   |        | 标记 matchedBy    |
| - peer (DM/Group) |        |                   |        |                   |
| - guildId/roles   |        |                   |        |                   |
| - teamId          |        |                   |        |                   |
+-------------------+        +-------------------+        +-------------------+

关键约束：若绑定包含多个匹配字段（如同时指定 peer 和 guildId），所有字段必须同时匹配该绑定才生效。

1.3 实战：Mattermost 多账户路由陷阱

在 Mattermost/Discord 等多账户场景中，常见需求是"让 Agent Lumi 处理特定频道，无论哪个 Bot 账户收到消息"。此时需利用 T1 覆盖 T6 的特性：

{
  bindings: [
    // T6: Housie 账户的默认路由（低优先级）
    { agentId: "home", match: { channel: "mattermost", accountId: "housie" } },
    
    // T6: Lumi 账户的默认路由
    { agentId: "lumi", match: { channel: "mattermost", accountId: "lumi" } },
    
    // T1: 关键！当 Jack/Housie 的 WebSocket 收到该频道消息时，
    // 强制路由到 Lumi（peer 匹配优先级高于 account）
    { 
      agentId: "lumi", 
      match: { 
        channel: "mattermost", 
        accountId: "default",  // Jack 的账户
        peer: { kind: "group", id: "<lumi-channel-id>" } 
      } 
    },
    { 
      agentId: "lumi", 
      match: { 
        channel: "mattermost", 
        accountId: "housie",
        peer: { kind: "group", id: "<lumi-channel-id>" } 
      } 
    }
  ]
}

此配置确保无论哪个 Bot 账户收到该频道消息，都路由到 lumi Agent，实现跨账户的频道级 Agent 绑定。

二、Bindings 配置语法与 Agent 定义

Bindings 是连接"外部消息渠道"与"内部 Agent 实例"的桥梁，通过声明式配置实现灵活的路由策略。

2.1 Agent 定义结构（agents.list）

每个 Agent 是完全隔离的大脑，拥有独立的 Workspace、认证凭证与会话存储：

{
  agents: {
    list: [
      {
        id: "personal",           // 唯一标识（小写+连字符）
        name: "Personal Assistant", // 显示名称
        workspace: "~/.openclaw/workspace-personal", // 工作目录
        agentDir: "~/.openclaw/agents/personal/agent", // 状态目录（含 auth）
        model: "anthropic/claude-sonnet-4",
        default: true,            // 默认路由 fallback
        description: "General purpose agent", // 用于 broadcast 选择
        // 工具权限控制（v2026.1.6+）
        tools: {
          allow: ["read", "exec", "memory_search"],
          deny: ["write", "edit", "browser"]
        },
        // 沙箱隔离配置
        sandbox: {
          mode: "all",            // off | all
          scope: "agent",         // global | agent
          docker: {
            setupCommand: "apt-get update && apt-get install -y git"
          }
        }
      },
      {
        id: "support",
        workspace: "~/.openclaw/workspace-support",
        // 未指定 agentDir 时默认使用 ~/.openclaw/agents/support/agent
      }
    ]
  }
}

关键警告：agentDir 包含 auth-profiles.json（OAuth 令牌、API Key）与模型注册信息，绝对禁止多个 Agent 共享同一 agentDir，否则将导致认证冲突与会话串扰。

2.2 绑定匹配规则（bindings）

Bindings 数组定义路由规则，支持多维度匹配：

{
  bindings: [
    // 精确群组匹配（T1）
    {
      agentId: "support",
      match: {
        channel: "telegram",
        peer: { kind: "group", id: "-1001234567890" }
      }
    },
    
    // Discord 服务器+角色匹配（T3）
    {
      agentId: "moderator",
      match: {
        channel: "discord",
        guildId: "123456789",
        roles: ["admin", "moderator"]  // 拥有任一角色即匹配
      }
    },
    
    // Slack Workspace 匹配（T5）
    {
      agentId: "enterprise",
      match: {
        channel: "slack",
        teamId: "T12345678"
      }
    },
    
    // 账户级匹配（T6）
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "business-account-1"
      }
    },
    
    // 渠道通配匹配（T7）
    {
      agentId: "fallback",
      match: {
        channel: "webhook",
        accountId: "*"  // 匹配该渠道所有账户
      }
    }
  ]
}

2.3 快速创建与验证

使用 CLI 向导快速创建多 Agent 环境：

# 创建新 Agent（自动创建目录结构）
openclaw agents add work
openclaw agents add family

# 查看所有 Agent 及其绑定
openclaw agents list --bindings

# 验证路由决策（调试）
openclaw gateway debug-routing --channel telegram --peer "+1234567890"

三、多 Agent 隔离机制：安全边界设计

OpenClaw 的多 Agent 架构通过三层隔离确保数据安全与运行环境独立。

3.1 隔离维度矩阵

隔离维度	单 Agent 模式	多 Agent 模式	共享/隔离说明
Gateway 进程	共享	共享	一个 openclaw gateway 进程托管所有 Agent
Workspace	~/.openclaw/workspace	~/.openclaw/workspace-<agentId>	严格隔离，含 AGENTS.md/SOUL.md/USER.md
agentDir	~/.openclaw/agents/main/agent	~/.openclaw/agents/<agentId>/agent	严格隔离，含 auth 凭证
Session Store	~/.openclaw/agents/main/sessions	~/.openclaw/agents/<agentId>/sessions	严格隔离，会话历史独立
向量记忆	独立索引	独立索引	每个 Agent 拥有独立 Qdrant 集合
Skills	~/.openclaw/skills/ + workspace/skills/	同上	全局 skills 可共享，workspace skills 隔离
工具权限	全局配置	可 per-agent 配置	v2026.1.6+ 支持 per-agent sandbox

3.2 隔离架构图

+-------------------------------------------------------------+
|                     Gateway Process                         |
|  (Single Node.js Process, Event Loop)                       |
+--------+----------------+----------------+------------------+
         |                |                |
         v                v                v
+--------+----+   +-------+----+   +------+-----+
|   Agent A   |   |   Agent B  |   |  Agent C   |
|  (personal) |   |   (work)   |   |  (family)  |
+-------------+   +------------+   +------------+
|  Workspace  |   |  Workspace |   |  Workspace |
|  /workspace-|   |  /workspace-|   |  /workspace-|
|  personal   |   |  work      |   |  family    |
+-------------+   +------------+   +------------+
|   agentDir  |   |   agentDir |   |   agentDir |
|  /agents/   |   |  /agents/  |   |  /agents/  |
|  personal/  |   |  work/     |   |  family/   |
|  agent/     |   |  agent/    |   |  agent/    |
+-------------+   +------------+   +------------+
|    Auth     |   |    Auth    |   |    Auth    |
|   Profiles  |   |   Profiles |   |   Profiles |
| (isolated)  |   | (isolated) |   | (isolated) |
+-------------+   +------------+   +------------+
|   Sessions  |   |   Sessions |   |   Sessions |
|   (isolated)|   |  (isolated)|   |  (isolated)|
+-------------+   +------------+   +------------+

安全风险警示：

• Workspace 是默认工作目录而非强制沙箱，绝对路径仍可访问主机其他位置，除非启用 sandbox.mode: “all”
• 若需共享凭证，必须手动复制 auth-profiles.json 到目标 agentDir，而非共享目录

3.3 沙箱隔离实战

针对不同 Agent 实施差异化安全策略：

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },  // 完全信任，无限制
        tools: { allow: ["*"] }
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",
          scope: "agent",          // 仅影响此 Agent
          docker: {
            setupCommand: "apt-get update && apt-get install -y curl"
          }
        },
        tools: {
          allow: ["read", "exec"],
          deny: ["write", "edit", "apply_patch", "browser"]  // 禁止文件修改与浏览器
        }
      }
    ]
  }
}

四、广播组（Broadcast Groups）：并行多 Agent 计算

广播组是 OpenClaw 的高级特性，允许单个消息触发多个 Agent 并行处理，适用于需要多视角分析或冗余验证的场景。

4.1 广播组触发条件

广播组仅在特定条件下激活：

• 正常路由决策后，检查是否匹配广播组配置
• 常见于 WhatsApp 群组（提及触发后）、Discord 频道等
• 不影响常规一对一绑定路由

4.2 配置语法与策略

{
  broadcast: {
    strategy: "parallel",  // parallel | sequential（目前主要支持 parallel）
    
    // Key: peer ID（群组ID或用户ID）
    // Value: 要并行运行的 Agent ID 列表
    "120363403215116621@g.us": ["alfred", "baerbel"],  // WhatsApp 群组
    "+15555550123": ["support", "logger"],              // 特定手机号
    "discord:guild:123:channel:456": ["analyst", "critic"] // Discord 频道
  }
}

执行流程：

+-------------------+        +-------------------+        +-------------------+
|   消息命中常规绑定  |        |   检查广播组配置    |        |   并行执行 Agent   |
|  (Agent X 已确定)  |   -->  |   (peer ID 匹配)   |   -->  |  [A, B, C] 同时运行|
+-------------------+        +-------------------+        +-------------------+
         |                            |                            |
         v                            v                            v
+--------+----------+        +---------+---------+        +---------+---------+
| 正常单 Agent 处理  |        | 若匹配广播组       |        | 结果聚合策略       |
| (无广播组时)       |        | 覆盖为并行多 Agent  |        | - 合并输出        |
|                   |        |                   |        | - 投票机制        |
|                   |        |                   |        | - 主次 Agent      |
+-------------------+        +-------------------+        +-------------------+

4.3 结果聚合模式

当前 OpenClaw 广播组主要采用独立响应模式，每个 Agent 独立发送回复。未来版本可能支持：

策略	说明	适用场景
parallel (当前)	各 Agent 独立回复	多专家并行咨询
debate	Agent 间交叉讨论后输出共识	方案评审
primary	指定主 Agent，其他为顾问	质量控制
voting	多数决输出	事实核查

配置实例：WhatsApp 群组双 Agent 响应

{
  agents: {
    list: [
      { id: "alfred", name: "Alfred", description: "Formal butler persona" },
      { id: "baerbel", name: "Baerbel", description: "Casual German aunt persona" }
    ]
  },
  bindings: [
    // 基础路由到 Alfred
    { 
      agentId: "alfred", 
      match: { channel: "whatsapp", peer: { kind: "group", id: "120363403215116621@g.us" } }
    }
  ],
  broadcast: {
    strategy: "parallel",
    "120363403215116621@g.us": ["alfred", "baerbel"]  // 两者同时响应
  }
}

当群组成员提及 Bot 时，Alfred 和 Baerbel 将同时生成回复，提供不同风格视角。

五、Agent 身份文件体系

每个 Agent 的 Workspace 包含四个核心身份定义文件，构成 Agent 的"人格与行为边界"。

5.1 文件职责矩阵

文件	加载时机	核心内容	影响范围
SOUL.md	每次会话启动	人格特质、沟通风格、价值观、情感边界	语气、措辞、态度
AGENTS.md	每次会话启动	操作规则、工具使用规范、响应长度限制、禁止事项	行为模式、工具调用
IDENTITY.md	每次会话启动	角色定义、专业领域、身份背景	知识边界、自信程度
USER.md	每次会话启动	用户画像、项目背景、当前优先级、沟通偏好	个性化程度、上下文理解

加载机制：这些文件通过 on bootstrap hook 在会话启动时注入上下文，不受 Compaction 影响（每次重新从磁盘加载）。

5.2 文件内容规范
SOUL.md 示例（人格定义）：

# SOUL.md - 人格核心

## 人格特质
- 你是经验丰富的技术架构师，说话直接、技术术语准确
- 对模糊需求零容忍，会立即追问澄清
- 幽默感 dry，偶尔 sarcastic 但保持专业边界

## 沟通风格
- 技术讨论：精确、结构化、使用专业术语
- 日常交流：简洁、不寒暄、直奔主题
- 拒绝过度解释：假设用户具备基础技术素养

## 价值观与边界
- 优先可维护性胜过交付速度
- 安全与隐私不可妥协
- 对"临时方案"持怀疑态度

## 反模式（绝对不做）
- 不编造不确定的技术细节
- 不使用"根据我的知识"等 hedging 语言
- 不在代码审查中充当"老好人"

AGENTS.md 示例（操作规则）：

# AGENTS.md - 操作规范

## 工具使用约定
- 文件操作前必须确认路径，禁止假设
- 网络请求必须设置超时（默认 30s）
- 代码编辑使用 apply_patch，禁止直接 write 覆盖

## 响应长度控制
- 技术解释：不超过 3 个要点
- 代码示例：不超过 20 行，除非明确要求完整实现
- 状态汇报：单行 JSON 或 bullet list

## 群聊特殊规则（Group Chat）
- 仅在被 @ 提及、直接提问或有真正有价值信息时响应
- 绝对不响应：闲聊、物流协调、表情包、链接分享
- 不确定时：仅回复 NO_REPLY（整消息仅含此字符串）

## 禁止事项
- 禁止解释"为什么"要做某事，除非被问及
- 禁止在每次回复末尾询问"还需要什么帮助"
- 禁止主动总结对话，除非用户要求

USER.md 示例（用户画像）：

# USER.md - 用户画像

## 基本信息
- 身份：10年经验的全栈工程师，现专注 AI 基础设施
- 沟通偏好：技术细节>高层概括，厌恶"AI 味"的客套话
- 当前项目：开源多 Agent 网关框架

## 技术栈
- 语言：TypeScript, Rust, Python
- 基础设施：K8s, Terraform, AWS
- AI：熟悉 LLM 原理，无需解释基础概念

## 当前优先级
1. 多 Agent 路由性能优化（P0）
2. 向量记忆压缩策略（P1）
3. 沙箱安全边界加固（P2）

## 相关人员
- 技术合伙人：Alex（后端专家，关注高可用）
- PM：Sarah（业务导向，需要技术翻译）

5.3 身份文件隔离的重要性

多 Agent 场景下的关键原则：

• 子 Agent 仅加载 AGENTS.md 和 TOOLS.md，SOUL.md/USER.md 被过滤
• 若发现子 Agent 缺乏人格或用户上下文，需显式在 AGENTS.md 中定义
• 身份文件变更后，新会话立即生效，无需重启 Gateway

六、生产环境配置模板

基于以上机制，提供生产级多 Agent 配置模板：

{
  agents: {
    defaults: {
      model: "anthropic/claude-sonnet-4",
      dmScope: "per-channel-peer",  // 安全隔离
      tools: {
        allow: ["read", "exec", "memory_search", "sessions_list"],
        deny: ["write", "edit", "browser"]  // 默认禁止危险操作
      }
    },
    list: [
      {
        id: "main",
        name: "General",
        default: true,  // T8 fallback
        workspace: "~/.openclaw/workspace",
        tools: { allow: ["*"] }  // 主 Agent 拥有完整权限
      },
      {
        id: "support",
        name: "Customer Support",
        workspace: "~/.openclaw/workspace-support",
        description: "Handles customer inquiries",
        tools: {
          allow: ["read", "memory_search", "zendesk_query"],
          deny: ["exec", "write", "edit"]
        }
      },
      {
        id: "code-reviewer",
        name: "Code Reviewer",
        workspace: "~/.openclaw/workspace-coder",
        model: "anthropic/claude-opus-4",
        sandbox: { mode: "all", scope: "agent" }
      }
    ]
  },
  
  bindings: [
    // T1: 精确群组路由
    { 
      agentId: "support", 
      match: { 
        channel: "telegram", 
        peer: { kind: "group", id: "-1001234567890" } 
      } 
    },
    
    // T3: Discord 角色路由
    { 
      agentId: "code-reviewer", 
      match: { 
        channel: "discord", 
        guildId: "987654321", 
        roles: ["developer", "maintainer"] 
      } 
    },
    
    // T6: 业务账户路由
    { 
      agentId: "support", 
      match: { 
        channel: "whatsapp", 
        accountId: "business-number" 
      } 
    },
    
    // T7: 通配渠道路由
    { 
      agentId: "main", 
      match: { 
        channel: "slack", 
        accountId: "*" 
      } 
    }
  ],
  
  broadcast: {
    strategy: "parallel",
    // 关键群组双 Agent 响应
    "discord:guild:987654321:channel:111": ["support", "main"]
  }
}

七、总结

OpenClaw 的多 Agent 路由体系通过八级优先级决策链实现了从精确匹配到默认回退的完整覆盖，配合三层隔离机制（Workspace/agentDir/Session）确保了多租户环境下的数据安全与运行独立。
核心设计哲学：

• 显式优于隐式：Bindings 必须显式声明，无自动路由猜测
• 最精确匹配胜出：T1 的 peer 绑定可覆盖任意低优先级配置
• 安全默认：agentDir 严格隔离，凭证不跨 Agent 共享
• 渐进式权限：通过工具白名单/黑名单实现细粒度能力控制
  对于架构师而言，理解 bindings 的矩阵匹配（Channel × Account × Peer × Guild/Roles）与 agents.list 的隔离边界，是设计可扩展、可维护的多 Agent 系统的关键。

本文章基于OpenClaw官方文档学习撰写。仅供学习参考，请勿用于商业用途。