OpenClaw Binding 消息路由规则配置详解
🦞d-openclaw 0 评论 多Agent协作 36 阅读

OpenClaw Binding 消息路由规则配置详解

一、OpenClaw Binding 消息路由机制概述

1.1 什么是 Binding？

Binding 是 OpenClaw 的消息路由机制，决定用户发来的消息由哪个 Agent 处理。在详细介绍 Binding 之前，我们先参见下图 OpenClaw 的核心对象逻辑关系图：

1.2 OpenClaw 核心概念定义：

  1. Peer（对话用户/会话方）： 为用户 user， 即通过渠道与 OpenClaw 交互的真实人类用户；

  2. Bot / Account （机器人实例/通道账户），是在特定渠道上运行的自动化账户，机器人 Account 是 Bot 的实体，代表 OpenClaw 与用户交互，如飞书机器人、企业微信机器人ID等；

  3. Channel （渠道/通讯平台）：是 OpenClaw 与外部通信平台的连接接口，负责收发消息；

  4. Binding（消息-Agent的路由规则）：即是OpenClaw的消息路由机制，决定用户发来的消息由哪个 Agent 处理。本文重点

  5. Agent（智能体大脑）： 是 OpenClaw 的智能核心，拥有独立的工作空间、会话存储和记忆系统，可以理解为一个"智能大脑"；

  6. dmScope/Scope（会话隔离策略）：会话隔离策略决定不同用户、不同渠道之间的对话上下文是否共享。dmScope是私聊隔离规则，scope是群聊 / 频道隔离规则；

  7. Session（会话）：是 Agent 与用户/群组之间的对话上下文容器，维护对话的连续性和状态；

  8. Memory（长期记忆和短期记忆）：记忆系统负责存储和检索 Agent 的知识，分为短期记忆和长期记忆。

1.3 核心对象之间的关系介绍：

Peer ↔ Bot （N:1）

  • 多对 1 关系：多个用户可以与同 1 个 bot 对话交互；

  • 用户标识映射：用户标识为用户ID（如飞书OU-xx，QQ号等）；

  • 配对验证：用户需要通过配对流程才能与 Bot 私聊；

Bot ↔ Channel （N:1）

  • 多对 1 关系：一个 Channel 可以配置多个 Bot（多账号场景）；

  • Bot 依附于 Channel：Bot 不能独立存在，必须属于某个 Channel；

  • 身份验证：Bot 通过 Token 与 Channel 平台认证；

Channel ↔ Agent (N:N)

  • 路由绑定：通过 bindings 配置将 Channel/群组绑定到特定 Agent；

  • 多对多关系：一个 Agent 可以服务多个 Channel，一个 Channel 可以被多个 Agent 服务（广播组）；

  • 动态路由：根据消息来源、用户角色等动态选择 Agent；

Agent ↔ Session（1:N）

  • 一对多关系：一个 Agent 可以拥有多个 Session

  • Session 归属：Session 必须属于某个 Agent

  • 隔离性：不同

二、完整 Binding 配置示例

{
  "agents": {
    "defaults": {
      "model": { "primary": "bailian/qwen3.5-plus" },
      "workspace": "/Users/openclaw-xue/.openclaw/workspace"
    },
    "list": [
      {
        "id": "main",
        "default": true
      },
      {
        "id": "vip-user",
        "model": { "primary": "bailian/kimi-k2.5" },
        "workspace": "/Users/openclaw-xue/.openclaw/agents/vip"
      },
      {
        "id": "developer",
        "model": { "primary": "bailian/qwen3-coder-plus" },
        "workspace": "/Users/openclaw-xue/.openclaw/agents/developer"
      }
    ]
  },
  "bindings": [
    {
      "match": {
        "channel": "feishu",
        "accountId": "cli_a92ba89012385cb5",
        "peer": { "kind": "user", "id": "ou_vip_user_001" }
      },
      "agentId": "vip-user"
    },
    {
      "match": {
        "channel": "feishu",
        "accountId": "cli_a92ba89012385cb5",
        "peer": { "kind": "user", "id": "ou_dev_user_002" }
      },
      "agentId": "developer"
    },
    {
      "match": {
        "channel": "feishu",
        "accountId": "cli_a92ba89012385cb5",
        "peer": { "kind": "user", "id": "ou_boss_003" }
      },
      "agentId": "vip-user"
    },
    {
      "match": { "channel": "feishu" },
      "agentId": "main"
    },
    {
      "match": { "channel": "qqbot" },
      "agentId": "main"
    }
  ],
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_a92ba89012385cb5",
      "appSecret": "your-secret",
      "connectionMode": "websocket",
      "groupPolicy": "open",
      "dmPolicy": "pairing"
    },
    "qqbot": {
      "enabled": true,
      "appId": "1903362255",
      "clientSecret": "your-secret",
      "allowFrom": ["*"]
    }
  }
}

说明：

  • VIP 路由：为指定的飞书 VIP 用户 (ou_vip_user_001) 和老板 (ou_boss_003) 配置了专属的 vip-user Agent。

  • 开发者路由：为指定的飞书开发用户 (ou_dev_user_002) 配置了专属的 developer Agent。

  • 默认路由：为所有飞书 (feishu) 和 QQ (qqbot) 渠道的消息配置了 main Agent 作为兜底。OpenClaw 的路由匹配遵循“精确对端 > 渠道”的优先级原则，确保精准分流

三、实际场景配置

3.1 场景一：企业多部门助手

{
  "agents": {
    "defaults": {
      "model": { "primary": "bailian/qwen3.5-plus" },
      "workspace": "/Users/openclaw-xue/.openclaw/workspace"
    },
    "list": [
      { "id": "main", "default": true },
      { "id": "hr-assistant", "workspace": "/Users/openclaw-xue/.openclaw/agents/hr" },
      { "id": "it-assistant", "workspace": "/Users/openclaw-xue/.openclaw/agents/it" },
      { "id": "finance-assistant", "workspace": "/Users/openclaw-xue/.openclaw/agents/finance" }
    ]
  },
  "bindings": [
    {
      "match": { "channel": "feishu", "accountId": "cli_hr_bot" },
      "agentId": "hr-assistant"
    },
    {
      "match": { "channel": "feishu", "accountId": "cli_it_bot" },
      "agentId": "it-assistant"
    },
    {
      "match": { "channel": "feishu", "accountId": "cli_finance_bot" },
      "agentId": "finance-assistant"
    },
    {
      "match": { "channel": "feishu" },
      "agentId": "main"
    }
  ],
  "channels": {
    "feishu": {
      "enabled": true,
      "connectionMode": "websocket",
      "accounts": {
        "hr-bot": {
          "appId": "cli_hr_bot",
          "appSecret": "your-hr-secret",
          "name": "HR助手",
          "groupPolicy": "mention"
        },
        "it-bot": {
          "appId": "cli_it_bot",
          "appSecret": "your-it-secret",
          "name": "IT助手",
          "groupPolicy": "mention"
        },
        "finance-bot": {
          "appId": "cli_finance_bot",
          "appSecret": "your-finance-secret",
          "name": "财务助手",
          "groupPolicy": "mention"
        }
      }
    }
  }
}

说明：

  • HR 群：@HR助手 → HR Agent

  • IT 群：@IT助手 → IT Agent

  • 财务群：@财务助手 → 财务 Agent

3.2 场景二：VIP 用户专属服务

{
  "agents": {
    "defaults": {
      "model": { "primary": "bailian/qwen3.5-plus" }
    },
    "list": [
      {
        "id": "standard",
        "workspace": "/agents/standard",
        "default": true
      },
      {
        "id": "vip",
        "workspace": "/agents/vip",
        "model": { "primary": "bailian/kimi-k2.5" }
      }
    ]
  },
  "bindings": [
    {
      "match": {
        "channel": "feishu",
        "accountId": "cli_main_bot",
        "peer": { "kind": "user", "id": "ou_vip_001" }
      },
      "agentId": "vip"
    },
    {
      "match": {
        "channel": "feishu",
        "accountId": "cli_main_bot",
        "peer": { "kind": "user", "id": "ou_vip_002" }
      },
      "agentId": "vip"
    },
    {
      "match": {
        "channel": "feishu",
        "accountId": "cli_main_bot",
        "peer": { "kind": "user", "id": "ou_ceo" }
      },
      "agentId": "vip"
    },
    {
      "match": {
        "channel": "feishu",
        "accountId": "cli_main_bot"
      },
      "agentId": "standard"
    }
  ],
  "channels": {
    "feishu": {
      "appId": "cli_main_bot",
      "appSecret": "YOUR_FEISHU_APP_SECRET",
      "enabled": true
    }
  }
}

说明：

  • VIP 用户使用 Kimi K2.5 模型

  • 普通用户使用 Qwen 3.5 模型

3.3 场景三：开发者专用通道

{
  "agents": {
    "defaults": {
      "workspace": "/agents/general"
    },
    "list": [
      {
        "id": "general",
        "default": true
      },
      {
        "id": "developer",
        "workspace": "/agents/developer",
        "model": { "primary": "bailian/qwen3-coder-plus" },
        "tools": {
          "profile": "full"
        }
      }
    ]
  },
  "bindings": [
    {
      "match": {
        "channel": "feishu",
        "accountId": "cli_dev_bot"
      },
      "agentId": "developer"
    },
    {
      "match": {
        "channel": "feishu",
        "accountId": "cli_main"
      },
      "agentId": "general"
    }
  ],
  "channels": {
    "feishu": {
      "enabled": true,
      "accounts": {
        "main-bot": {
          "appId": "cli_main",
          "appSecret": "YOUR_MAIN_SECRET"
        },
        "dev-bot": {
          "appId": "cli_dev_bot",
          "appSecret": "YOUR_DEV_SECRET",
          "groupPolicy": "open"
        }
      }
    }
  }
}

说明：

  • 开发者群使用代码专用模型

  • 开启完整工具权限

四、Binding 配置检查清单

4.1 配置前检查

  •  Agent ID 是否正确

  •  Agent workspace 是否存在

  •  Channel 是否启用

  •  Bot token 是否有效

4.2 配置后验证

# 检查配置有效性
openclaw doctor --non-interactive

# 查看当前配置
openclaw config get

# 测试消息路由
# 发送测试消息，查看日志确认路由到正确 Agent

4.3 常见问题

问题

原因

解决

消息路由错误

Binding 配置错误

检查 agent ID 是否匹配

所有消息到默认 Agent

Binding 未匹配

检查优先级和配置路径

VIP 用户未生效

User ID 错误

确认用户 ID 格式

Bot 绑定不生效

Bot ID 错误

确认 Bot ID 与渠道一致

许可协议
本文采用 OpenClaw 俱乐部-非商业性使用 许可协议，转载请注明出处。
OpenClaw 浏览器自动化：让 AI 成为你的专属网页操控手 2026-04-10
ClawSwarm：多智能体协同系统完整使用教程 2026-04-10

评论区