05. 消息平台接入指南

课程信息

作者：老金

GitHub：https://github.com/KimYx0207

公众号：老金带你玩AI

X（Twitter）：老金带你玩AI

个人博客：https://aiking.dev

难度等级：🟡 进阶

阅读时间：20 分钟

前置知识：已完成快速开始（03-快速开始指南）

本篇你将学会： 把 AI 助手接到 WhatsApp、Telegram、Discord 等消息平台，在手机上随时跟 AI 聊天

小白速通： 只看你要用的那个平台的章节就行，不需要全部看完。最简单的是 Telegram（只需要一个 Bot Token）

教程版本基线

稳定版参考 v2026.3.28；另有预发布线见 Releases。约定全文见 00-阅读指南。

概述

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 支持的平台一览

平台	类型	双向消息	群组支持	接入难度
Telegram	grammY	✅	✅	⭐ 简单
WhatsApp	Baileys（非官方）	✅	✅	⭐ 简单（扫码）
Discord	@buape/carbon	✅	✅	⭐⭐ 中等
Slack	@slack/bolt	✅	✅	⭐⭐ 中等
Signal	signal-cli	✅	✅	⭐⭐ 中等
飞书	Extension（@larksuiteoapi/node-sdk）	✅	✅	⭐⭐ 中等
Microsoft Teams	内置	✅	✅	⭐⭐ 中等
Google Chat	内置	✅	✅	⭐⭐ 中等
LINE	@line/bot-sdk	✅	✅	⭐⭐ 中等
Matrix	内置	✅	✅	⭐⭐ 中等
BlueBubbles	iMessage（推荐）	✅	✅	⭐⭐ 中等
iMessage	Legacy（macOS only）	✅	❌	⭐⭐⭐ 较难
Zalo / Zalo Personal	内置	✅	✅	⭐⭐ 中等
Web Chat	Gateway WebSocket	✅	❌	⭐ 简单

2. Telegram 接入

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

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

2.1 创建 Telegram Bot

在 Telegram 中搜索 @BotFather
发送 /newbot
按提示输入 Bot 名称和用户名
获得 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（你的服务器主动去平台拉取新消息）是两种接收消息的方式：

特性	Webhook	Polling
实时性	即时推送	有延迟（取决于轮询间隔）
资源消耗	低（被动接收）	高（持续请求）
网络要求	需要公网 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 安全机制（详见第 10 节），可以防止未知用户直接与 Bot 对话。

3.4 常见问题

扫码后连接不上？

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

收不到某些人的消息？

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

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

4. Discord 接入

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

4.1 创建 Discord Application

访问 Discord Developer Portal
点击 "New Application"，输入名称
进入 Bot 页面，点击 "Add Bot"
复制 Bot Token
开启 "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

访问 Slack API
点击 "Create New App" → "From scratch"
输入 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

在 "Event Subscriptions" 中开启 Events
设置 Request URL：https://your-domain.com/webhook/slack
订阅以下 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 Mode	Events 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 创建飞书应用

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

6.2 配置权限

在应用权限中开启：

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

6.3 配置事件订阅

在"事件订阅"中设置请求地址：https://your-domain.com/webhook/feishu
添加事件：
- 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. 其他支持的平台

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

平台	说明
Signal	通过 signal-cli 接入
BlueBubbles	iMessage 接入（推荐方式）
iMessage	Legacy 方式，仅 macOS
Microsoft Teams	内置支持
Google Chat	内置支持
Matrix	内置支持
Zalo / Zalo Personal	内置支持
LINE	通过 @line/bot-sdk 接入

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

9. 自定义 Channel 开发

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

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

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

9.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>;
}

9.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>;
}

10. DM 安全策略（Pairing）

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

10.1 Pairing 模式

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

openclaw pairing approve <channel> <code>

10.2 Open 模式

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

10.3 使用建议

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

11. 消息格式适配

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

11.1 Markdown 支持对比

格式	Telegram	WhatsApp	Discord	Slack	飞书
粗体	✅ `text`	✅ `text`	✅ `text`	✅ `text`	✅
斜体	✅ `_text_`	✅ `_text_`	✅ `text`	✅ `_text_`	✅
`代码`	✅ `code`	✅ `code`	✅ `code`	✅ `code`	✅
代码块	✅	❌	✅	✅	✅
链接	✅	✅ 自动识别	✅	✅	✅

11.2 长消息处理

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

平台	最大长度	OpenClaw 处理方式
Telegram	4096 字符	自动分段发送
WhatsApp	4096 字符	自动分段发送
Discord	2000 字符	自动分段发送
Slack	40000 字符	通常不需要分段
飞书	30000 字符	通常不需要分段

11.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",
    ],
  },
}

12. 常见问题排查

12.1 通用问题

Channel 连接有问题？

# 查看频道状态
openclaw channels status

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

消息延迟很高？

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

12.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

12.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 是否完整

下一步

下一步	文档	说明
配置技能	06-技能系统指南	让 Agent 具备更多能力
记忆系统	07-记忆系统指南	让 AI 记住用户偏好
安全配置	10-安全配置指南	Webhook 安全、Token 管理

FilesExpand file tree

05-消息平台接入指南.md

Latest commit

History