OpenClaw 中文文档 — 渠道总览与配对机制

本文覆盖 OpenClaw 渠道系统的整体架构和安全配对机制。作为渠道篇的第一篇，重点在于建立对渠道体系的全局认知，后续文章会逐一展开各渠道的具体配置。

渠道体系概览

OpenClaw 当前支持 22 个聊天平台，按集成方式分为两类：

内置渠道

内置渠道随 OpenClaw 一起安装，开箱即用：

渠道	集成方式	协议/框架	备注
WhatsApp	Web 协议	Baileys	最受欢迎，需 QR 配对
Telegram	Bot API	grammY	上手最快
Discord	Bot API + Gateway	discord.js	服务器/频道/私信
Signal	CLI 桥接	signal-cli	隐私导向
BlueBubbles	REST API	自有服务端	iMessage 推荐方案
iMessage（旧版）	本地 CLI	imsg	已弃用
Google Chat	HTTP webhook	Google API	需服务账号
WebChat	WebSocket	内置	Gateway Web 聊天界面

插件渠道

插件渠道需要单独安装，通过 OpenClaw 的插件机制接入：

渠道	接入方式	适用场景
飞书/Lark	WebSocket 机器人	国内企业
Microsoft Teams	Bot Framework	企业级
Slack	Bolt SDK	团队协作
Mattermost	Bot API + WebSocket	自托管团队
Matrix	Matrix 协议	开放联邦
IRC	IRC 协议	技术社区
LINE	Messaging API	日本/台湾
Nextcloud Talk	自托管	隐私优先企业
Nostr	NIP-04	去中心化
Synology Chat	Webhook	NAS 用户
Tlon	Urbit 协议	去中心化
Twitch	IRC 连接	直播场景
Zalo	Bot API / QR 登录	越南市场

渠道选择的考量

从工程角度，各渠道的选择涉及以下权衡：

• 上手成本：Telegram 最低（一个 bot token），WhatsApp 中等（QR 配对 + 本地状态），企业渠道最高（服务账号/审批流程）
• 本地状态：WhatsApp 在本地存储较多会话状态，Telegram 几乎无本地状态
• 并行运行：多个渠道可同时运行，Gateway 按会话自动路由
• Agent 逻辑共享：所有渠道共享同一套 Agent 逻辑，渠道只是入口

配对机制

配对是 OpenClaw 的显式所有者审批环节，用于两个场景：私信访问控制和节点设备接入。

私信配对

当渠道的私信策略为 pairing 时，未知发送者的消息不会被 Agent 处理，而是触发配对流程：

1. 发送者收到一个 8 字符配对码
2. 所有者通过 CLI 批准

openclaw pairing list telegram
openclaw pairing approve telegram ABCDEFGH

配对码的设计考量：

属性	值	原因
长度	8 字符	安全性与易用性的平衡
字符集	大写字母，排除 O/0/I/1	避免跨字体混淆
有效期	1 小时	限制暴力破解窗口
并发上限	每渠道 3 个	防止滥用

白名单模式

白名单是配对的替代方案，适合已知用户群的场景：

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123", "+15555550456"],
    },
  },
}

白名单外的消息直接忽略，不触发配对流程。

配对状态存储

配对状态存储在 ~/.openclaw/credentials/ 下：

• 待处理请求：<channel>-pairing.json
• 已批准白名单：<channel>-allowFrom.json（默认账户）或 <channel>-<accountId>-allowFrom.json（非默认账户）

这些文件应视为敏感数据——它们控制着对 Agent 的访问权限。

节点设备配对

设备（iOS/Android/macOS/无头节点）以 role: node 连接 Gateway，需经配对审批：

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

值得注意的是，OpenClaw 支持通过 Telegram 完成 iOS 设备配对：

1. Telegram 给机器人发 /pair
2. 收到包含 Gateway 地址和引导令牌的设置码（base64 JSON）
3. iOS 应用中粘贴设置码
4. Telegram 发 /pair approve

这个设计将设备配对的复杂度降到了最低——不需要手动输入 Gateway 地址和 Token。

多渠道并行的技术细节

• 多个渠道同时运行时，Gateway 按会话维度自动路由
• 同一 Agent 处理所有渠道的消息，但会话按渠道隔离
• 群组行为因渠道而异，通用建议是设置 requireMention: true
• 媒体支持程度因渠道不同，文本消息所有渠道均支持

小结

OpenClaw 的渠道体系采用了"内置 + 插件"的分层架构，覆盖了主流聊天平台。配对机制作为安全的第一道防线，在易用性和安全性之间取得了较好的平衡。

本文是渠道篇的第一篇。下一篇详细展开 WhatsApp 和 Telegram 的接入配置。

---

完整中文文档：OpenClaw 中文文档

GitHub 仓库：openclaw/openclaw