OpenClaw 渠道接入的通用套路：插件安装、配置段落、DM 策略与配对码怎么串起来

2026-08-17

很多人第一次给 OpenClaw 接聊天渠道，是照着某一个渠道页（比如 Telegram 页或 Slack 页）一路复制配置过去的。配置贴完，机器人在群里没反应，或者私聊过去石沉大海，这时候就懵了——因为渠道页只讲了自己那一段，接入流程真正的骨架被拆在三个文档里：channels/index 讲哪些渠道存在、以什么形态分发；channels/pairing 讲访问审批；gateway/config-channels 讲配置键怎么写、策略怎么解析。

这三处拼起来，接一个渠道其实只有四件事：确认这个渠道是随核心装的还是要单独装插件、把 channels.<id> 配置段写出来、重启网关让插件加载、然后处理访问控制（配对或者白名单）。绝大多数”配好了没反应”，卡的都是第四步，而不是前三步。

这篇就按这四步把通用流程说清楚，具体某个渠道的独有配置键（比如 Telegram 的 apiRoot、WhatsApp 的 authDir）不在这里展开，那是各渠道页的事。

第一步：先确认这个渠道是什么形态分发的

官方文档把渠道分了四种分发形态，这个区别直接决定你要不要多跑一条安装命令：

形态	含义	举例
included in core	随核心安装	WebChat
bundled plugin	随核心安装的捆绑插件	Telegram、Reef
official plugin	一条命令安装的官方插件	Discord、Slack、飞书、Signal、QQ Bot、Matrix、Teams 等
external plugin	在 OpenClaw 仓库之外维护	微信、企业微信、元宝、Zalo ClawBot

官方插件的安装命令是：

openclaw plugins install @openclaw/<id>

文档里还有另外两条路：openclaw onboard 引导过程中按需安装，或者 openclaw channels add 加渠道时按需安装。三条路都指向同一句话——装完需要重启网关。这一点在 channels/index 里是明写的，很多”配置贴了但插件没加载”的情况就是漏了这一步。

WhatsApp 是个特例，文档把它描述为 install-on-demand：引导流程可以在插件包还没装的时候就把设置流程显示出来，网关只有在渠道真正激活时才去加载那个外部插件包。

第二步：配置段落存在，渠道就会启动

config-channels 开头有一句很关键的规则：每个渠道在它的配置段存在时自动启动，除非写了 enabled: false。也就是说没有”启用渠道”这个独立开关动作，写了 channels.telegram = {...} 它就要起来；不想要它起来，就得显式关掉。

反过来说，如果某个渠道的配置块整体缺失（channels.<provider> 不存在），运行期的群策略会回落到 allowlist（fail-closed）并在启动时打一条告警。这是个故意设计的保守行为：宁可不回消息，也不默认放开群里的任何人。

跨渠道共享的默认值放在 channels.defaults 里：

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      implicitMentions: {
        replyToBot: true,
        quotedBot: true,
        threadParticipation: true,
      },
      heartbeatVisibility: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

channels.defaults.groupPolicy 只在某个渠道自己没设 groupPolicy 时生效。implicitMentions 三个开关控制哪些”隐式事实”算作被@到：回复机器人、引用机器人、参与线程，默认都是 true。它们的解析顺序是账号 → 渠道 → defaults，每个开关各自独立解析。注意这些名字是正向的，把某个设成 false 是让这个事实不再绕过提及门禁；原生的显式@永远放行。

第三步：访问控制——DM 策略与群策略

这是接入流程里最容易踩的一段。所有渠道共用同一套策略枚举：

DM 策略	行为
`pairing`（默认）	陌生发送者拿到一次性配对码，需要 owner 批准
`allowlist`	只放行 `allowFrom` 里的发送者（或已配对的允许存储）
`open`	放行全部入站私聊，*要求 `allowFrom: [""]`**
`disabled`	忽略全部入站私聊

群策略	行为
`allowlist`（默认）	只放行匹配白名单的群
`open`	绕过群白名单（提及门禁仍然生效）
`disabled`	屏蔽全部群/房间消息

open 这一条有个坑值得单独讲。文档写得很直白：dmPolicy: "open" 只有在生效的 DM 白名单包含 "*" 时才是真正公开的。如果你的既有状态里是 open 但 allowFrom 写的是具体条目，运行期仍然只放行那些具体发送者；而且配对存储里的批准结果不会把 open 的访问面撑大。也就是说光把策略改成 open 而不加通配符，行为跟白名单没区别。

第四步：配对码怎么发、怎么批

当渠道的 DM 策略是 pairing 时，陌生发送者的消息不会被处理，他会先拿到一个短码。这几个数字最好记住：

配对码 8 个字符，全大写，剔除了容易混的 0O1I；
1 小时过期。机器人只在新请求被创建时才发那条配对消息，大致是每个发送者每小时一次；
每个渠道账号的待处理请求上限是 3 个，超出的会被直接忽略，直到有一个过期或被批准。

第三条解释了一类奇怪现象：某个群/某个账号突然”谁申请都没反应”，很可能是三个待批名额被占满了。

批准有两条路。CLI 这条最直接：

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

加 --notify 会在同一渠道上通知申请人；多账号渠道用 --account <id> 指定。另一条是 Control UI，官方文档给的路径是 Settings → Channels → DM access requests，那个队列会把所有 DM 策略为 pairing 的渠道账号的待批请求合并在一起。

两条路有个不对称，值得留意：CLI 在还没有配置命令 owner 时会自动引导写入 commands.ownerAllowFrom（条目形如 telegram:123456789），而 Control UI 是把它做成一个显式勾选项（“把这个发送者设为第一个命令 owner”，且只在没有 owner、且当前会话具备 operator.admin 时才显示）。一旦 owner 已存在，后续的配对批准就只给 DM 访问权，不会再加 owner。

还有一句必须记牢：批准 DM 配对不等于给了群里的权限。文档专门加了注记——配对允许存储管的是私聊访问；群授权是另一套，走渠道自己的群白名单（groupAllowFrom、groups，或者按群/按话题的覆盖配置）。

支持配对的渠道，文档列了这些：discord、feishu、googlechat、imessage、irc、line、matrix、mattermost、msteams、nextcloud-talk、nostr、signal、slack、sms、synology-chat、telegram、twitch、whatsapp、zalo、zalouser。外部插件（例如 openclaw-weixin）只要声明了配对能力也能加进来，具体要看各渠道的配置页，可以顺着微信渠道怎么配那一篇往下看。

同一批人要在多个渠道复用，用 accessGroups

如果同一组可信发送者要同时用在多个渠道，或者同时用在 DM 和群的白名单上，官方给的做法是顶层 accessGroups，静态组用 type: "message.senders"，在渠道白名单里用 accessGroup:<name> 引用：

{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
  channels: {
    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },
    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },
  },
}

这样改一处，两个渠道、两类白名单一起生效，比在每个渠道里各抄一份人名单要好维护。

配对状态存在哪：SQLite，不是散落的 JSON

这一条排查时很有用。配对状态统一落在共享状态库 ~/.openclaw/state/openclaw.sqlite：

待处理请求在 channel_pairing_requests
已批准的发送者在 channel_pairing_allow_entries

每条请求和每个已批准发送者都按渠道 + 账号做键。运行期只读这些规范化的 SQLite 行，不会去合并遗留文件。老版本网关写在 ~/.openclaw/credentials/ 下的 <channel>-pairing.json 和 <channel>-<accountId>-allowFrom.json，是靠启动迁移和 openclaw doctor --fix 导进 SQLite 的，导入成功后源文件会被删掉。所以如果你手工去改那些 JSON 文件想临时放行某个人，不会有任何效果。

这个库要当敏感数据对待——里面的行直接决定谁能跟你的助手说话。

多账号：一个渠道跑两个机器人

同一渠道跑多个账号，每个账号有自己的 accountId：

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

几条规则容易忘：省略 accountId 时用的是 default；环境变量里的 token 只对 default 账号生效；基础渠道设置对所有账号生效，除非在账号层覆盖；要把不同账号路由到不同 Agent，用 bindings[].match.accountId。

还有一个迁移行为：如果你已经是单账号的顶层配置，然后用 openclaw channels add（或渠道引导流程）加了一个非默认账号，OpenClaw 会先把账号相关的顶层单账号值提升进渠道的账号映射里，好让原来那个账号继续能用——多数渠道搬进 channels.<channel>.accounts.default，Matrix 可以保留已有的匹配命名/默认目标。openclaw doctor --fix 也会用同样的规则修被混用的配置形态。

别把设备配对和 DM 配对搞混

pairing 这个词在 OpenClaw 里管两件事，文档开头就点明了：一是 DM 配对（谁能跟机器人说话），二是节点设备配对（哪些设备/节点能加入网关网络）。两者存储在同一个 SQLite 库里，但流程和命令完全不同，设备侧走的是：

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

而且设备侧的待处理请求5 分钟就过期（DM 配对是 1 小时），差了一个数量级。设备配对默认是纯手工批准，只有在明确配置了可信网段时才可以对全新的 role: node 请求自动放行：

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

而且这个自动放行只对没有请求任何 scope 的全新 node 请求生效——operator、浏览器、Control UI、WebChat 客户端仍然必须手工批准，角色、scope、元数据、公钥有变化的也一样必须手工批准。

WhatsApp 那边还有一层容易混：登录二维码是把一个 WhatsApp 账号链接到 OpenClaw，DM 访问请求是批准给那个账号发消息的人，文档明确说这是两条独立的流程。

这套流程管不到什么

渠道能力差异这套流程不管。channels/index 只保证”文本到处都支持”，媒体和表情回应按渠道各不相同，群行为也按渠道各不相同。所以流程走通不等于功能对齐，具体能不能发图、能不能回应表情，得回到各渠道页看。

接通之后的行为问题也不在这条线上。比如群里@了之后出现输入中然后没下文、多个机器人互相刷屏、消息路由到了错误的 Agent，这些都是接入完成之后的运行期问题。刷屏那一类走的是 bot loop protection 与群消息策略，见机器人互相刷屏怎么办；连不上、报错那一类有官方自己的排查表，见渠道连不上的排查路径。

插件本身的安装与管理也是另一个话题。渠道大多以插件形态存在，插件怎么装、怎么禁用、自己写一个要遵守什么约定，见OpenClaw 插件体系。

最后提醒一句形态上的事：文档说渠道可以同时跑，配了多个 OpenClaw 会按会话路由；它也给了一句自己的判断——最快配起来的通常是 Telegram（一个 bot token，不用装插件），而 WhatsApp 需要扫码配对并且在磁盘上存更多状态。这是官方文档的说法，具体选哪个还得看你的人实际在哪个应用里。

延伸阅读

从头读起：OpenClaw 架构总览：网关、Agent、渠道、节点、插件五层各管什么，出问题该往哪查
本专题共 40 篇，完整分组目录见专题页
OpenClaw 渠道连上了却不回消息：官方排查表按渠道逐条拆解
OpenClaw 接微信：openclaw-weixin 插件的安装、扫码登录与版本对应关系

本文依据 OpenClaw 官方仓库（github.com/openclaw/openclaw）docs/ 下的官方文档整理，核对日 2026-08-17。 我们没有安装或运行过 OpenClaw，因此不涉及界面外观、操作手感与实测耗时的任何描述；文中的默认值、命令与配置项均为文档口径，不构成对实际运行结果的保证。该项目迭代很快，请以仓库最新内容为准。接入即时通讯平台前，请自行确认所在平台的规则与合规要求。