8.4 路由配置

---

想象一下这个场景：

公司前台接到一个电话。

“找销售部”——前台转给销售 “找技术支持”——前台转给技术 “找老板”——前台转给总经理办公室

前台就是路由——根据规则，把消息送到正确的地方。

多个 Agent 跑在一个 Gateway 里，消息怎么知道该发给谁？靠路由绑定（bindings）。我们在7.6节已经初步接触过这个概念了。这一节，我们用15分钟，学会配置多Agent的路由规则。

---

路由规则：最具体的优先

Bindings 是确定性的，最具体的优先：

优先级	匹配规则	示例
1（最高）	peer 匹配（精确私信/群组/频道 id）	peer: { kind: "dm", id: "+15551230001" }
2	guildId（Discord 服务器）	guildId: "123456789"
3	teamId（Slack 工作区）	teamId: "T01234567"
4	渠道的 accountId 匹配	accountId: "personal"
5	渠道级匹配	channel: "whatsapp"
6（最低）	回退到默认 Agent	agents.list[].default，否则列表第一个

---

场景一：一个WhatsApp号码，多个人用

同一个 WhatsApp 号码，不同联系人路由到不同 Agent：

{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" },
    ],
  },
  bindings: [
    { agentId: "alex", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
    { agentId: "mia", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } },
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}

不同手机号发来的消息，路由到不同的 Agent。回复都来自同一个 WhatsApp 号码。

+15551230001 发消息 → alex Agent 回复
+15551230002 发消息 → mia Agent 回复

---

场景二：飞书不同群组，不同Agent

一个飞书 Bot，不同群组路由到不同 Agent：

{
  agents: {
    list: [
      { id: "brainstorm", workspace: "~/.openclaw/workspace-brainstorm" },
      { id: "writer", workspace: "~/.openclaw/workspace-writer" },
      { id: "coder", workspace: "~/.openclaw/workspace-coder" },
    ],
  },
  bindings: [
    {
      agentId: "brainstorm",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_d46347c35dd403daad7e5df05d08a890" }
      }
    },
    {
      agentId: "writer",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_598146241198039b8d9149ded5fb390b" }
      }
    },
    {
      agentId: "coder",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_b1c331592eaa36d06a05c64ce4ecb113" }
      }
    },
  ],
}

头脑风暴群走 brainstorm Agent，写作群走 writer Agent，代码群走 coder Agent。

头脑风暴群里 @机器人 → brainstorm Agent 回复
写作群里 @机器人 → writer Agent 回复
代码群里 @机器人 → coder Agent 回复

---

场景三：不同渠道，不同Agent

WhatsApp 走日常 Agent，Telegram 走深度工作 Agent：

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-5",
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

WhatsApp 来消息 → chat Agent（快速日常）
Telegram 来消息 → opus Agent（深度工作）

---

试一试：配置你的路由

步骤1：创建多个Agent

openclaw agents add work --model zai/glm-4.7 --workspace ~/.openclaw/workspace-work
openclaw agents add personal --model zai/glm-4.7 --workspace ~/.openclaw/workspace-personal

步骤2：编辑openclaw.json

{
  agents: {
    list: [
      {
        id: "work",
        name: "Work",
        workspace: "~/.openclaw/workspace-work",
        default: false,
      },
      {
        id: "personal",
        name: "Personal",
        workspace: "~/.openclaw/workspace-personal",
        default: true,  // 默认Agent
      },
    ],
  },
  bindings: [
    // 工作群组走work Agent
    {
      agentId: "work",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "你的工作群ID" }
      }
    },
    // 其他走personal Agent
    {
      agentId: "personal",
      match: { channel: "feishu" }
    },
  ],
}

步骤3：验证配置

openclaw agents list --bindings

步骤4：重启Gateway

openclaw gateway restart

---

获取群组ID

怎么知道群组的 ID？

方法一：查看日志

openclaw logs --follow

在群里发一条消息，日志中会显示 chat_id（格式如 oc_xxx）。

方法二：使用CLI

openclaw sessions list --kinds group

---

群组配置详解

对于群组聊天，你可以设置更细粒度的控制：

{
  agents: {
    list: [
      {
        id: "family",
        name: "Family",
        workspace: "~/.openclaw/workspace-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
        },
        sandbox: {
          mode: "all",
          scope: "agent",
        },
        tools: {
          allow: ["exec", "read", "sessions_list", "sessions_history"],
          deny: ["write", "edit", "browser", "cron"],
        },
      },
    ],
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "120363999999999999@g.us" },
      },
    },
  ],
}

关键配置说明

配置	说明
mentionPatterns	@提及模式，只有被 @ 时才响应
sandbox	沙箱隔离级别
tools.allow/deny	工具权限控制

---

多账户路由

支持多账户的渠道（如 WhatsApp）可以用 accountId 区分：

{
  agents: {
    list: [
      { id: "home", workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* 个人号配置 */ },
        biz: { /* 工作号配置 */ },
      },
    },
  },
}

个人号来的消息走 home Agent，工作号来的消息走 work Agent。

---

故障排查

消息没有路由到预期的Agent

检查项	操作
bindings 顺序	bindings 是顺序匹配的，第一个匹配的生效
peer ID 是否正确	群组 ID、用户 ID 是否写对
accountId 是否匹配	多账户场景下是否指定了正确的 accountId
Gateway 是否重启	配置修改后需要重启 Gateway

调试命令

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

# 查看Gateway日志
openclaw gateway logs

# 检查配置文件语法
openclaw config validate

找不到群组ID

检查项	操作
查看日志	openclaw logs --follow，然后在群里发消息
查看会话列表	openclaw sessions list --kinds group
确认机器人已入群	机器人需要先加入群组

---

这一节，你做了什么

学了什么	核心理解
路由优先级	peer > guildId > teamId > accountId > 渠道级 > 默认
分流方式	按用户、按群组、按渠道、按账户
群组配置	mentionPatterns、沙箱、工具权限
多账户	用 accountId 区分不同号码
排错方法	检查 bindings 顺序、peer ID、重启 Gateway

---

下一节

路由配置学会了。现在来搭建一个真正的 AI 团队！