一个网关跑多个 Agent 时，路由必须做成确定性的：用声明式绑定（bindings）描述「什么消息进哪个 Agent」，由宿主配置裁决，而不是让模型猜。OpenClaw 的实现可作参照：路由按最精确匹配优先，第一个命中的绑定生效，优先级从高到低为 peer > parentPeer > guildId+roles > guildId > teamId > accountId > channel > 默认 Agent。下文给出通用的路由设计方法、OpenClaw 的完整优先级规则与可直接复用的配置片段。
一、路由要解决的三类分流
| 分流维度 | 典型场景 | 匹配字段 |
|---|---|---|
| 按渠道 | WhatsApp 日常闲聊、Telegram 深度工作各用不同 Agent | channel |
| 按账号 | 同一渠道接多个 Bot 账号，一号一 Agent | channel + accountId |
| 按对象 | 某个 VIP 用户或某个群单独指派专属 Agent | channel + peer（kind + id） |
设计原则只有一条：规则必须可预测。写规则的人要知道任何一条消息会落在哪个 Agent，排障时能按优先级逐层核对。
二、OpenClaw 的匹配优先级
OpenClaw 采用确定性路由，首个命中的绑定生效。完整优先级如下：
- peer：精确匹配用户或群组（kind + id），最高优先级，永远压过服务器级和渠道级规则；
- parentPeer：匹配父级上下文（如频道的父服务器）；
- guildId + roles：Discord 服务器 + 角色组合；
- guildId：Discord 服务器级匹配；
- teamId：Slack 工作区级匹配；
- accountId：渠道账号级匹配；
- channel：渠道级，命中该渠道全部流量；
- default：兜底 Agent，取标记 default 的条目或列表第一项。
同一优先级内多条规则同时命中时，配置文件里的书写顺序决定胜负——写在前的赢。所以 peer 绑定要放在渠道级规则上面。
三、配置实战
3.1 多 Agent 多账号的基础绑定
{
agents: {
entries: {
home: { default: true, name: "Home", workspace: "/.openclaw/workspace-home" },
work: { name: "Work", workspace: "/.openclaw/workspace-work" }
}
},
bindings: [
// 精确匹配：这个群直接交给 work
{ agentId: "work", match: { channel: "whatsapp", accountId: "personal",
peer: { kind: "group", id: "1203630...@g.us" } } },
// 账号匹配：biz 号全部进 work
{ agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
// 渠道兜底：其余 WhatsApp 流量进 home
{ agentId: "home", match: { channel: "whatsapp", accountId: "personal" } }
]
}多个匹配字段是 AND 关系。{ channel: "discord", guildId: "123456", roles: ["admin"] } 表示只有该服务器内带 admin 角色的消息才命中。
3.2 渠道分流的常见模式
把 WhatsApp 路由给快速日常 Agent，Telegram 路由给高阶模型 Agent，是官方文档给出的典型用法：
bindings: [
{ agentId: "chat", match: { channel: "whatsapp", accountId: "" } },
{ agentId: "opus", match: { channel: "telegram", accountId: "" } }
]accountId: "" 是留空技巧：后续加新账号时绑定依然生效。想让某条私聊单独走 opus，加一条 peer: { kind: "direct", id: "+15551234567" } 绑定并放在最前面即可。
四、落地路由的四步流程
- 盘点渠道与身份标识：收集每个渠道的 peer.id、guildId、teamId、accountId，没有标识就无法写精确规则；
- 从粗到细排规则：先写渠道级骨架，再补账号级，最后加 peer 特例，特例永远置顶；
- 每个 Agent 独立目录：agentDir 严禁复用，共享目录会造成认证配置冲突和会话数据损坏；
- 验证与排障：用
openclaw doctor查配置合法性；发现「Agent 回错了」先核对优先级，再看同层规则的书写顺序。
两个易错点：Agent 间通信默认关闭，需要显式开启并配 allowlist（tools.agentToAgent: { enabled: true, allow: ["home", "work"] }），跨 Agent 记忆访问只读；广播场景（一条消息多个 Agent 都要看到）用 broadcast 配置的 parallel 策略，不要靠复制绑定硬凑。
常见问题（FAQ）
Q1：两条规则都命中时听谁的？
按优先级取最精确的；同层级则看配置顺序，写在前面的绑定生效。
Q2：peer 匹配支持哪些 kind？
常用 direct/user（私聊）、group（群组），Discord 线程等子上下文由 parentPeer 层承接。
Q3：路由配错了怎么快速定位？
先跑 openclaw doctor 查配置，再按 peer → guild/team → account → channel 顺序逐层核对绑定。
