渠道路由 - 消息分发规则

Channel Routing（渠道路由）是 OpenClaw 的消息分发系统，负责将来自不同渠道的消息准确路由到对应的 Agent Session（智能体会话）。

路由工作原理

当一条消息到达 OpenClaw 时，路由系统按以下流程处理：

消息到达
   │
   ▼
┌──────────────────┐
│  1. 识别渠道来源   │  ← 从哪个 Channel 来的？
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  2. 判断消息类型   │  ← DM（私信）还是 Group（群组）？
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  3. 生成会话键     │  ← 构造唯一的 Session Key
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  4. 匹配路由规则   │  ← 发送到哪个 Agent？
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  5. 分发到会话     │  ← 找到或创建对应的 Session
└──────────────────┘

步骤详解

识别渠道来源：通过 Webhook 端点或消息元数据确定消息来自哪个 Channel（渠道）
判断消息类型：区分 DM（Direct Message，私信）和 Group Message（群组消息）
生成会话键：根据消息类型构造唯一的 Session Key（会话键）
匹配路由规则：根据配置的路由规则确定目标 Agent
分发到会话：将消息发送到对应的 Agent Session

Session Key（会话键）格式

Session Key 是 OpenClaw 用来唯一标识一个会话的字符串。不同消息类型的格式不同：

DM 会话键

agent:::dm:channel:userId

部分	说明	示例
`agent`	Agent 名称	`main`、`support`、`sales`
`dm`	会话类型标识	固定值
`channel`	渠道标识	`telegram`、`slack`、`feishu`
`userId`	用户唯一 ID	`user_12345`、`U0ABC`

示例：

main:::dm:telegram:user_12345
support:::dm:slack:U0123ABCDE
main:::dm:feishu:ou_a1b2c3d4

Group 会话键

agent:::group:channel:groupId

部分	说明	示例
`agent`	Agent 名称	`main`、`support`
`group`	会话类型标识	固定值
`channel`	渠道标识	`telegram`、`discord`
`groupId`	群组唯一 ID	`group_789`、`C04ABCDEF`

示例：

main:::group:telegram:group_789
main:::group:discord:1234567890
support:::group:feishu:oc_a1b2c3d4

会话隔离

DM 会话和 Group 会话是完全隔离的。即使同一个用户在私信和群组中与同一个 Agent 对话，上下文也不会共享。这是有意设计的安全特性。

多 Agent 路由

OpenClaw 支持运行多个 Agent，你可以将不同的渠道或用户路由到不同的 Agent。

基础路由配置

单 Agent（默认）多 Agent 路由

yaml

# 所有渠道的消息都路由到 main agent
routing:
  default: main

yaml

routing:
  default: main                # 默认路由到 main agent
  rules:
    - match:
        channel: slack         # Slack 渠道
      agent: support           # 路由到 support agent

    - match:
        channel: telegram      # Telegram 渠道
        chatType: dm           # 仅私信
      agent: personal          # 路由到 personal agent

    - match:
        channel: feishu        # 飞书渠道
        chatType: group        # 仅群组
      agent: team              # 路由到 team agent

路由匹配条件

路由规则支持以下匹配条件：

yaml

routing:
  rules:
    - match:
        channel: "telegram"          # 渠道名称（精确匹配）
        chatType: "dm"               # 消息类型：dm 或 group
        userId: "user_*"             # 用户 ID（支持通配符 Glob Pattern）
        groupId: "group_internal_*"  # 群组 ID（支持通配符）
        metadata:                    # 自定义元数据匹配
          department: "engineering"
      agent: dev-assistant
      priority: 10                   # 优先级，数字越大越优先

条件	类型	说明
`channel`	`string`	渠道标识符，精确匹配
`chatType`	`string`	`dm` 或 `group`
`userId`	`string`	用户 ID，支持 Glob 通配符
`groupId`	`string`	群组 ID，支持 Glob 通配符
`metadata`	`object`	自定义键值对匹配
`priority`	`number`	优先级（默认 0）

Priority（优先级）与 Fallback（回退）规则

当多条路由规则匹配同一条消息时，OpenClaw 按以下顺序决定最终路由：

优先级排序

yaml

routing:
  default: main
  rules:
    # 优先级 20：最高优先级 — VIP 用户专属 Agent
    - match:
        channel: telegram
        userId: "vip_*"
      agent: vip-assistant
      priority: 20

    # 优先级 10：Telegram 群组路由到 team agent
    - match:
        channel: telegram
        chatType: group
      agent: team
      priority: 10

    # 优先级 0（默认）：Telegram 渠道通用规则
    - match:
        channel: telegram
      agent: general
      priority: 0

路由匹配规则：

优先级从高到低：priority 值越大越优先
同优先级按配置顺序：相同优先级时，配置文件中靠前的规则优先
Fallback 到默认 Agent：如果没有任何规则匹配，使用 default 指定的 Agent

Fallback 链

yaml

routing:
  default: main
  fallback:
    # 当目标 Agent 不可用时的降级策略
    strategy: "next"        # next（下一条规则）/ default（直接回退默认）/ reject（拒绝消息）
    retries: 2              # 重试次数
    retryDelay: "1s"        # 重试间隔
    onReject:
      message: "服务暂时不可用，请稍后再试。"

避免路由循环

确保路由规则不会形成循环（Agent A 转发到 Agent B，Agent B 又转发回 Agent A）。OpenClaw 会检测并阻止循环路由，但建议在配置阶段就避免此类问题。

路由调试

查看当前路由规则

bash

# 列出所有路由规则
openclaw routing list

# 输出示例：
# Priority  Match                              Agent          Status
# 20        channel=telegram, userId=vip_*      vip-assistant  active
# 10        channel=telegram, chatType=group    team           active
# 0         channel=slack                       support        active
# default   *                                   main           active

测试路由匹配

bash

# 模拟消息路由，查看会匹配到哪个 Agent
openclaw routing test --channel telegram --chat-type dm --user-id "vip_001"

# 输出示例：
# Matched rule: priority=20, agent=vip-assistant
# Session key: vip-assistant:::dm:telegram:vip_001

# 测试无匹配情况
openclaw routing test --channel matrix --chat-type dm --user-id "user_999"

# 输出示例：
# No rule matched, using default agent: main
# Session key: main:::dm:matrix:user_999

查看活跃会话

bash

# 查看所有活跃会话及其路由信息
openclaw sessions list

# 输出示例：
# Session Key                              Agent    Channel    Type   Messages   Last Active
# main:::dm:telegram:user_12345            main     telegram   dm     42         2 min ago
# support:::dm:slack:U0123ABCDE            support  slack      dm     15         5 min ago
# team:::group:feishu:oc_a1b2c3d4          team     feishu     group  128        just now

高级路由场景

按时间段路由

yaml

routing:
  rules:
    # 工作时间路由到人工客服 + AI 混合 Agent
    - match:
        channel: webchat
      agent: hybrid-support
      schedule:
        timezone: "Asia/Shanghai"
        hours: "09:00-18:00"
        days: ["mon", "tue", "wed", "thu", "fri"]
      priority: 10

    # 非工作时间路由到纯 AI Agent
    - match:
        channel: webchat
      agent: ai-only-support
      priority: 0

按消息内容路由

yaml

routing:
  rules:
    # 包含关键词的消息路由到专业 Agent
    - match:
        channel: slack
        contentMatch: "(bug|error|crash|故障|报错)"
      agent: incident-bot
      priority: 15

跨渠道会话同步

实验性功能

跨渠道会话同步目前是 Experimental Feature（实验性功能），可能在未来版本中变更。

yaml

routing:
  sessionSync:
    enabled: true
    # 同一用户在不同渠道的会话共享上下文
    identityMapping:
      # 将不同渠道的用户 ID 映射为统一身份
      - userId: "telegram:user_12345"
        unifiedId: "emp_001"
      - userId: "slack:U0123ABCDE"
        unifiedId: "emp_001"

配置示例：完整的多 Agent 路由

yaml

# openclaw.yaml — 完整路由配置示例
agents:
  main:
    model: deepseek-chat
    description: "通用助手"
  support:
    model: qwen-max
    description: "客户支持专员"
  dev:
    model: claude-3-sonnet
    description: "开发助手"

routing:
  default: main
  fallback:
    strategy: default
  rules:
    - match:
        channel: feishu
        chatType: group
        groupId: "oc_dev_*"
      agent: dev
      priority: 10

    - match:
        channel: wecom
      agent: support
      priority: 5

    - match:
        channel: telegram
        chatType: dm
      agent: main
      priority: 0

channels:
  telegram:
    enabled: true
    dmPolicy: pairing
  feishu:
    enabled: true
    dmPolicy: allowlist
  wecom:
    enabled: true
    dmPolicy: pairing

🇨🇳 中国用户须知

多 Agent 路由在国内企业场景中非常实用。 典型配置方案：

飞书群组 → 团队协作 Agent（接入内部知识库、项目管理工具）
企业微信 → 客户支持 Agent（接入 CRM、工单系统）
钉钉 → 运维告警 Agent（接入监控系统、日志分析）
Web Chat → 公共客服 Agent（接入 FAQ、产品文档）

路由规则的时区设置： 使用按时间段路由时，请确保 timezone 设置为 Asia/Shanghai（UTC+8），以匹配国内工作时间。

会话键中的中文字符： Session Key 中不会包含中文字符，所有标识符均为英文/数字，兼容性无需担心。

渠道路由 - 消息分发规则 ​

路由工作原理 ​

步骤详解 ​

Session Key（会话键）格式 ​

DM 会话键 ​

Group 会话键 ​

多 Agent 路由 ​

基础路由配置 ​

路由匹配条件 ​

Priority（优先级）与 Fallback（回退）规则 ​

优先级排序 ​

Fallback 链 ​

路由调试 ​

查看当前路由规则 ​

测试路由匹配 ​

查看活跃会话 ​

高级路由场景 ​

按时间段路由 ​

按消息内容路由 ​

跨渠道会话同步 ​

配置示例：完整的多 Agent 路由 ​

渠道路由 - 消息分发规则

路由工作原理

步骤详解

Session Key（会话键）格式

DM 会话键

Group 会话键

多 Agent 路由

基础路由配置

路由匹配条件

Priority（优先级）与 Fallback（回退）规则

优先级排序

Fallback 链

路由调试

查看当前路由规则

测试路由匹配

查看活跃会话

高级路由场景

按时间段路由

按消息内容路由

跨渠道会话同步

配置示例：完整的多 Agent 路由