跳至主要內容

05. 消息平台接入指南

Mr.Over2026/5/1大约 13 分钟aiaiopenclaw

05. 消息平台接入指南

概述

OpenClaw 的核心卖点之一：一个 Gateway 连接所有消息平台。你在 WhatsApp 上给 AI 发消息，它能帮你在 Telegram 上回复别人。不管你的用户分散在哪些平台，OpenClaw 都能把它们统一到一个入口。

这篇指南会带你从零开始，把各个消息平台接入 OpenClaw。从概念理解到实际配置，从主流平台到小众渠道，从基础接入到高级玩法，全部覆盖。

1. Channel（消息平台）概念详解

1.1 什么是 Channel

在 OpenClaw 里，Channel 就是"消息平台"的抽象。每个 Channel 代表一个消息来源和目的地：

  • 一个 WhatsApp 账号 = 一个 Channel
  • 一个 Telegram Bot = 一个 Channel
  • 一个 Discord Bot = 一个 Channel
  • 一个 Slack App = 一个 Channel
  • 一个飞书应用 = 一个 Channel（通过 extension）
  • 一个 Signal 账号 = 一个 Channel
  • 一个 Web Chat 组件 = 一个 Channel

Channel 是 OpenClaw 消息系统的基本单元。所有消息都通过 Channel 进出。你可以把它理解成一个"双向管道"——外部平台的消息从这里流入 OpenClaw，OpenClaw 的回复也从这里流出到对应平台。

1.2 Channel 的生命周期

添加 Channel（配置凭证）→ 登录/链接账号 → 接收/发送消息 → （可选）移除

Channel 的管理主要通过配置文件 ~/.openclaw/openclaw.json（JSON5 格式）和 CLI 命令完成。可以用 openclaw channels status 查看各频道的当前状态。

1.3 Channel 管理命令

# 查看所有 Channel
openclaw channels list

# 查看频道状态
openclaw channels status

# 添加频道
openclaw channels add <channel>

# 链接频道账号（如 WhatsApp 扫码）
openclaw channels login <channel>

# 登出频道
openclaw channels logout <channel>

# 解析频道/用户名
openclaw channels resolve <channel> <identifier>

# 查看频道日志
openclaw channels logs <channel>

# 移除频道
openclaw channels remove <channel>

1.4 支持的平台一览

平台类型双向消息群组支持接入难度
TelegramgrammY✅✅⭐ 简单
WhatsAppBaileys（非官方）✅✅⭐ 简单（扫码）
Discord@buape/carbon✅✅⭐⭐ 中等
Slack@slack/bolt✅✅⭐⭐ 中等
Signalsignal-cli✅✅⭐⭐ 中等
飞书Extension（@larksuiteoapi/node-sdk）✅✅⭐⭐ 中等
Microsoft Teams内置✅✅⭐⭐ 中等
Google Chat内置✅✅⭐⭐ 中等
Google Meet捆绑参与者插件（v2026.4.24+）✅（语音）✅⭐⭐ 中等
QQ Bot内置（v2026.3.31+）✅✅⭐⭐ 中等
LINE@line/bot-sdk✅✅⭐⭐ 中等
Matrix内置✅✅⭐⭐ 中等
BlueBubblesiMessage（推荐）✅✅⭐⭐ 中等
iMessageLegacy（macOS only）✅❌⭐⭐⭐ 较难
Zalo / Zalo Personal内置✅✅⭐⭐ 中等
Web ChatGateway WebSocket✅❌⭐ 简单

2. Telegram 接入

📋 开始之前你需要： 一个 Telegram 账号、通过 @BotFather 创建的 Bot Token

Telegram 是最容易接入的平台，5 分钟就能搞定。

2.1 创建 Telegram Bot

  1. 在 Telegram 中搜索 @BotFather
  2. 发送 /newbot
  3. 按提示输入 Bot 名称和用户名
  4. 获得 Bot Token（机器人的身份凭证，类似于登录密码）（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）
BotFather: Done! Congratulations on your new bot.
Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz

2.2 配置 OpenClaw

在 ~/.openclaw/openclaw.json（JSON5 格式）中添加 Telegram 配置：

{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      // 或者使用环境变量 TELEGRAM_BOT_TOKEN，此处可省略 botToken

      // 群组配置（可选，按群组 ID 配置）
      // groups: {
      //   "-1001234567890": { ... },  // 以群组 ID 为键
      // },

      // Webhook 模式（可选，默认使用 polling）
      // webhookUrl: "https://your-domain.com/webhook/telegram",
      // webhookSecret: "your-webhook-secret",
    },
  },
}

也可以通过环境变量设置 Bot Token：

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

2.3 Webhook vs Polling

Webhook（消息推送机制，平台主动把新消息发给你的服务器）和 Polling（你的服务器主动去平台拉取新消息）是两种接收消息的方式：

特性WebhookPolling
实时性即时推送有延迟（取决于轮询间隔）
资源消耗低（被动接收）高（持续请求）
网络要求需要公网 HTTPS 地址不需要公网地址
适用场景生产环境开发/测试环境

2.4 高级配置

{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",

      // 群组配置（按群组 ID 配置）
      // groups: {
      //   "-1001234567890": { ... },  // 以群组 ID 为键
      // },

      // Webhook 配置（可选）
      webhookUrl: "https://your-domain.com/webhook/telegram",
      webhookSecret: "your-webhook-secret",
    },
  },
}

2.5 常见问题

Bot 收不到消息？

  • 检查 Token 是否正确
  • Webhook 模式：确认 HTTPS 证书有效，URL 可访问
  • Polling 模式：确认没有其他程序在使用同一个 Token
  • 群组中：确认 Bot 已被添加到群组，且 Privacy Mode 已关闭（/setprivacy → Disable）

3. WhatsApp 接入

📋 开始之前你需要： 一部安装了 WhatsApp 的手机、手机和电脑在同一网络环境下

OpenClaw 使用 Baileys（非官方的 WhatsApp 连接库，通过扫码登录）（包名：@whiskeysockets/baileys）接入 WhatsApp，通过扫码链接设备，无需 Meta Cloud API。

3.1 链接 WhatsApp 设备

接入非常简单，只需一步扫码：

openclaw channels login whatsapp

执行后终端会显示一个二维码，用手机 WhatsApp 扫码即可完成链接（类似 WhatsApp Web 的登录方式）。

凭证会自动存储在 ~/.openclaw/credentials 目录中。

3.2 配置 OpenClaw

在 ~/.openclaw/openclaw.json 中配置 WhatsApp：

{
  channels: {
    whatsapp: {
      // 控制谁可以和 Bot 对话
      // 设置为 ["*"] 表示允许所有人
      allowFrom: ["+8613800138000", "+8613900139000"],

      // 群组配置（按群组 JID 为键配置）
      // groups: {
      //   "120363xxx@g.us": { ... },  // 以群组 JID 为键
      // },
    },
  },
}

3.3 DM 安全策略

WhatsApp 支持 DM Pairing 安全机制（详见第 12 节），可以防止未知用户直接与 Bot 对话。

3.4 常见问题

扫码后连接不上？

  • 确保手机 WhatsApp 版本是最新的
  • 确保手机和运行 OpenClaw 的设备在同一网络环境下
  • 如果凭证过期，删除 ~/.openclaw/credentials 目录后重新扫码

收不到某些人的消息？

  • 检查 allowFrom 配置是否包含了对方的号码
  • 如果需要接收所有人的消息，设置 allowFrom: ["*"]

注意：Baileys 是非官方库，WhatsApp 可能会对自动化使用进行限制。建议仅用于个人或小规模场景。

4. Discord 接入

📋 开始之前你需要： 一个 Discord 账号、一个你有管理权限的 Discord 服务器

4.1 创建 Discord Application

  1. 访问 Discord Developer Portal
  2. 点击 "New Application"，输入名称
  3. 进入 Bot 页面，点击 "Add Bot"
  4. 复制 Bot Token
  5. 开启 "Message Content Intent"（重要！）

4.2 邀请 Bot 到服务器

生成邀请链接：

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=274877975552&scope=bot%20applications.commands

权限说明：

  • Send Messages：发送消息
  • Read Message History：读取历史消息
  • Use Slash Commands：使用斜杠命令
  • Attach Files：发送文件
  • Embed Links：发送嵌入消息

4.3 配置 OpenClaw

在 ~/.openclaw/openclaw.json 中配置 Discord：

{
  channels: {
    discord: {
      token: "YOUR_DISCORD_BOT_TOKEN",
      // 或者使用环境变量 DISCORD_BOT_TOKEN，此处可省略 token

      // 命令配置
      commands: {
        native: true,       // 启用原生 Slash Commands
        // nativeSkills: true, // 将技能注册为 Slash Commands
      },

      // 允许的用户（可选）
      // allowFrom: ["user-id-1", "user-id-2"],

      // 服务器白名单（可选）
      // guilds: ["guild-id-1"],

      // 媒体大小限制（MB）
      // mediaMaxMb: 25,
    },
  },
}

4.4 Slash Commands

OpenClaw 会在连接时自动注册 Slash Commands（需要 commands.native: true）。

4.5 常见问题

Bot 在线但不回复？

  • 确认 "Message Content Intent" 已开启
  • 确认 Bot 有对应频道的读写权限
  • 在群组配置中，确认是否需要 @bot 才触发回复

5. Slack 接入

📋 开始之前你需要： 一个 Slack 工作区的管理员权限、能访问 Slack API 的浏览器

5.1 创建 Slack App

  1. 访问 Slack API
  2. 点击 "Create New App" → "From scratch"
  3. 输入 App 名称，选择 Workspace

5.2 配置权限

在 "OAuth & Permissions" 中添加以下 Bot Token Scopes：

  • chat:write - 发送消息
  • channels:history - 读取公共频道消息
  • groups:history - 读取私有频道消息
  • im:history - 读取私聊消息
  • app_mentions:read - 读取 @提及
  • files:read - 读取文件
  • files:write - 上传文件

5.3 配置 Event Subscriptions

  1. 在 "Event Subscriptions" 中开启 Events
  2. 设置 Request URL：https://your-domain.com/webhook/slack
  3. 订阅以下 Bot Events：
    • message.channels - 公共频道消息
    • message.groups - 私有频道消息
    • message.im - 私聊消息
    • app_mention - @提及

5.4 配置 OpenClaw

在 ~/.openclaw/openclaw.json 中配置 Slack：

{
  channels: {
    slack: {
      botToken: "xoxb-xxx",   // 或环境变量 SLACK_BOT_TOKEN
      appToken: "xapp-xxx",   // 或环境变量 SLACK_APP_TOKEN（Socket Mode 必需）
    },
  },
}

也可以通过环境变量设置：

export SLACK_BOT_TOKEN="xoxb-xxx"
export SLACK_APP_TOKEN="xapp-xxx"

5.5 Socket Mode vs Events API

特性Socket ModeEvents API
网络要求不需要公网地址需要公网 HTTPS
实时性WebSocket 实时HTTP 推送
适用场景开发/内部工具生产环境
配置复杂度简单需要配置 Webhook

5.6 常见问题

Bot 不响应消息？

  • 确认 Bot 已被邀请到频道（/invite @your-bot）
  • 确认 Event Subscriptions 已正确配置
  • 检查 Signing Secret 是否正确

6. 飞书接入（Extension）

📋 开始之前你需要： 飞书企业管理员权限、能访问 飞书开放平台 的浏览器

注意：飞书是通过 OpenClaw 的 extension 机制支持的（extensions/feishu/），使用 @larksuiteoapi/node-sdk。详细配置请参考 OpenClaw 官方文档 docs/channels/feishu.md。

6.1 创建飞书应用

  1. 访问 飞书开放平台
  2. 创建企业自建应用
  3. 添加"机器人"能力
  4. 获取 App ID 和 App Secret

6.2 配置权限

在应用权限中开启：

  • im:message - 获取与发送单聊、群组消息
  • im:message.group_at_msg - 接收群聊中 @机器人消息
  • im:resource - 获取与上传图片或文件资源

6.3 配置事件订阅

  1. 在"事件订阅"中设置请求地址：https://your-domain.com/webhook/feishu
  2. 添加事件：
    • im.message.receive_v1 - 接收消息

6.4 配置 OpenClaw

飞书作为 extension，配置步骤以 OpenClaw 发行包/官方仓库中与版本同步的文档 docs/channels/feishu.md 为准。一般需在飞书开放平台获取 App ID 和 App Secret，并在 OpenClaw 配置中填写。

7. Web Chat 接入

📋 开始之前你需要： OpenClaw Gateway 已启动运行（默认端口 18789）

OpenClaw 的 Web Chat 通过 Gateway 的 WebSocket 连接实现，不是独立的 HTTP 路径。

7.1 工作原理

Web Chat 客户端通过 WebSocket 连接到 OpenClaw Gateway（默认端口 18789），实现实时双向通信。这不是一个独立的 HTTP 服务，而是 Gateway 的一部分。

7.2 使用方式

Web Chat 的前端可以是任何支持 WebSocket 的客户端。连接到 Gateway 的 WebSocket 端点即可开始对话。

默认 Gateway 地址：ws://localhost:18789

8. Google Meet 接入（v2026.4.24+）

📋 开始之前你需要： Google 账号、Chrome 浏览器或 Twilio 语音通道

v2026.4.24 新增 Google Meet 捆绑参与者插件，支持实时语音循环（realtime voice loop），AI 可以作为参会者加入 Google Meet 会议。

8.1 工作原理

Google Meet 集成通过捆绑的参与者插件实现，支持以下核心能力：

  • 个人 Google 认证：使用你自己的 Google 账号授权
  • Chrome / Twilio 实时会话：支持两种语音通道
  • 配对节点支持：可与远程节点配合使用
  • 会议产物导出：自动导出会议记录和出席信息
  • 标签恢复：对已有 Chrome 标签页的恢复工具

8.2 实时语音循环

Google Meet 支持"实时语音循环"（realtime voice loop），AI 参会者可以在语音对话中调用完整的 OpenClaw Agent 获取工具支持的深度回答。这意味着 AI 不仅能闲聊，还能在会议中查资料、执行命令、访问记忆等。

8.3 配置方式

Google Meet 作为捆绑插件，配置步骤以 OpenClaw 官方文档为准。一般需在 OpenClaw 中完成 Google 认证后即可使用。

具体配置字段和认证流程可能随版本演进，请参考 openclaw 官方文档中的 Google Meet 章节。

9. QQ Bot 接入（v2026.3.31+）

📋 开始之前你需要： QQ 开放平台开发者账号

v2026.3.31 新增 QQ Bot 内置支持，支持多账号配置、斜杠命令、提醒和媒体功能。

9.1 创建 QQ Bot

  1. 访问 QQ 开放平台
  2. 注册开发者账号
  3. 创建机器人应用
  4. 获取 AppID 和 Token

9.2 配置 OpenClaw

QQ Bot 作为内置 Channel，在 ~/.openclaw/openclaw.json 的 channels 中添加对应配置即可。具体配置字段以 OpenClaw 官方文档为准。

9.3 支持的功能

  • 多账号配置
  • 斜杠命令（Slash Commands）
  • 提醒功能
  • 媒体消息（图片、文件等）

10. 其他支持的平台

OpenClaw 还支持以下平台，具体配置请参考各平台对应的官方文档：

平台说明
Signal通过 signal-cli 接入
BlueBubblesiMessage 接入（推荐方式）
iMessageLegacy 方式，仅 macOS
Microsoft Teams内置支持
Google Chat内置支持
Matrix内置支持（v2026.4.22 新增交叉签名验证）
Zalo / Zalo Personal内置支持
LINE通过 @line/bot-sdk 接入

这些平台的配置方式与 Telegram、Discord 等类似，在 ~/.openclaw/openclaw.json 的 channels 中添加对应平台的配置即可。

11. 自定义 Channel 开发

⏭️ 小白可跳过 — 这部分面向开发者，普通用户不需要看

概念性说明：以下 TypeScript 接口是对 Channel 系统的概念性描述，帮助理解其设计思路。实际接口可能与此不完全一致，请以 你所安装 OpenClaw 版本自带的类型定义与官方文档 为准。

如果 OpenClaw 不支持你需要的平台，可以开发自定义 Channel。

11.1 Channel 接口（概念性）

interface Channel {
  name: string;
  platform: string;

  connect(): Promise<void>;
  disconnect(): Promise<void>;

  onMessage(handler: (message: IncomingMessage) => void): void;
  sendMessage(to: string, message: OutgoingMessage): Promise<void>;
}

11.2 消息格式（概念性）

interface IncomingMessage {
  id: string;
  from: {
    id: string;
    name: string;
    platform: string;
  };
  content: {
    type: 'text' | 'image' | 'audio' | 'video' | 'file';
    text?: string;
    mediaUrl?: string;
    mimeType?: string;
  };
  timestamp: number;
  metadata: Record<string, any>;
}

12. DM 安全策略（Pairing）

OpenClaw 提供 DM Pairing 机制来控制谁可以与 Bot 私聊。

12.1 Pairing 模式

当 dmPolicy 设置为 "pairing" 时，未知发送者给 Bot 发消息会收到一个配对码。管理员需要手动批准：

openclaw pairing approve <channel> <code>

12.2 Open 模式

当 dmPolicy 设置为 "open" 时，任何人都可以直接与 Bot 对话。此时需要配合 allowFrom 包含 "*" 来允许所有用户。

12.3 使用建议

  • 生产环境建议使用 pairing 模式，防止未授权用户滥用
  • 测试环境可以使用 open 模式方便调试
  • 配合各平台的 allowFrom 配置可以实现更细粒度的访问控制

13. 消息格式适配

不同平台的消息格式差异很大，OpenClaw 会自动处理格式转换。

13.1 Markdown 支持对比

格式TelegramWhatsAppDiscordSlack飞书
粗体✅ *text*✅ *text*✅ **text**✅ *text*✅
斜体✅ _text_✅ _text_✅ *text*✅ _text_✅
代码✅ `code`✅ `code`✅ `code`✅ `code`✅
代码块✅❌✅✅✅
链接✅✅ 自动识别✅✅✅

13.2 长消息处理

不同平台有不同的消息长度限制：

平台最大长度OpenClaw 处理方式
Telegram4096 字符自动分段发送
WhatsApp4096 字符自动分段发送
Discord2000 字符自动分段发送
Slack40000 字符通常不需要分段
飞书30000 字符通常不需要分段

13.3 媒体文件处理

注意：以下为概念性配置示例，实际配置格式请以 OpenClaw 文档为准。

// 全局媒体配置（概念性示例）
{
  media: {
    autoDownload: true,
    storagePath: "./media",
    maxFileSize: 20971520,  // 20MB
    supportedTypes: [
      "image/jpeg",
      "image/png",
      "image/gif",
      "audio/ogg",
      "audio/mpeg",
      "video/mp4",
      "application/pdf",
    ],
  },
}

14. 常见问题排查

14.1 通用问题

Channel 连接有问题？

# 查看频道状态
openclaw channels status

# 查看频道日志
openclaw channels logs <channel>

消息延迟很高？

  • Webhook 模式：检查服务器网络延迟
  • 检查 AI 模型响应时间

14.2 Webhook 通用问题

Webhook 验证失败？

  • 确认 URL 是 HTTPS（大多数平台要求）
  • 确认 SSL 证书有效（不能是自签名证书，除非平台允许）
  • 确认 URL 可以从公网访问

本地开发怎么测试 Webhook？

使用 ngrok 或 cloudflared 创建临时隧道：

# 使用 ngrok
ngrok http 18789
# 获得类似 https://abc123.ngrok.io 的地址

# 使用 cloudflared
cloudflared tunnel --url http://localhost:18789

14.3 平台特定问题

Telegram Bot 在群组中不回复？

  • 关闭 Privacy Mode：在 BotFather 中 /setprivacy -> Disable
  • 或者在群组配置中启用 @提及 才回复的选项

WhatsApp 连接断开？

  • 删除 ~/.openclaw/credentials 目录后重新执行 openclaw channels login whatsapp 扫码
  • 确保手机 WhatsApp 保持在线

Discord Bot 没有权限？

  • 重新生成邀请链接，确保包含所需权限
  • 在服务器设置中检查 Bot 角色权限

Slack Bot 收不到消息？

  • 确认 Bot 已被邀请到频道
  • 确认 Event Subscriptions 中的 Request URL 验证通过
  • 检查 Bot Token Scopes 是否完整
最近更新: