05. 消息平台接入指南

课程信息

⠀

• 作者：老金

• GitHub：https://github.com/KimYx0207

• 公众号：老金带你玩AI

• X（Twitter）：老金带你玩AI

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

• 难度等级：🟡 进阶

• 阅读时间：20 分钟

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

⠀

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

⠀

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

⠀

概述

⠀

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

内置

✅

✅

⭐⭐ 中等

Google Meet

捆绑参与者插件（v2026.4.24+）

✅（语音）

✅

⭐⭐ 中等

QQ Bot

内置（v2026.3.31+）

✅

✅

⭐⭐ 中等

LINE

@line/bot-sdk

✅

✅

⭐⭐ 中等

Matrix

内置

✅

✅

⭐⭐ 中等

BlueBubbles

iMessage（推荐）

✅

✅

⭐⭐ 中等

iMessage

Legacy（macOS only）

✅

❌

⭐⭐⭐ 较难

Zalo / Zalo Personal

内置

✅

✅

⭐⭐ 中等

Web Chat

Gateway WebSocket

✅

❌

⭐ 简单

---

2. Telegram 接入

⠀

v2026.5.22 通道口径：官方 Channels 页面列出的平台已不止 Telegram / WhatsApp / Discord / Slack / 飞书。当前应按 WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、IRC、Microsoft Teams、Matrix、飞书、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、Zalo Personal、WeChat、QQ、WebChat、macOS、iOS/Android 等通道理解；具体可用性以你安装的插件和官方文档为准。

⠀

v2026.5.27 新增注意：Telegram 文档补充了 wildcard topic defaults；Slack / Telegram ack reactions、Feishu dynamic agents、Discord voice follow、Meeting Notes 外部插件也都在这一轮更新中出现。v2026.5.26 / v2026.5.27 又补强了 Telegram durable outbound delivery、iMessage 附件 roots / thumb approval reactions、WhatsApp group / media 行为、Signal reaction approvals、Discord voice playback / model picker、Matrix mention inert delivery、Google Chat DM thread suppression 等通道细节。下面各平台章节会按“先接入、再确认新版行为”的顺序讲。

⠀

📋 开始之前你需要： 一个 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（你的服务器主动去平台拉取新消息）是两种接收消息的方式：

⠀

特性

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",
    },
  },
}

⠀

v2026.5.22 起，Telegram 多 topic / group 场景要额外确认默认 topic 行为。团队群里建议记录：

⠀

• 哪些 topic 默认允许触发 Agent。

• 哪些 topic 只允许人工 ack。

• ack reaction 是否会被当作状态反馈。

• 群组 ID、topic ID 和权限 owner 存在哪里。

⠀

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: {
      //   "[email protected]": { ... },  // 以群组 JID 为键
      // },
    },
  },
}

⠀

3.3 DM 安全策略

⠀

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

⠀

3.4 常见问题

⠀

扫码后连接不上？

• 确保手机 WhatsApp 版本是最新的

• 确保手机和运行 OpenClaw 的设备在同一网络环境下

• 如果凭证过期，删除 ~/.openclaw/credentials 目录后重新扫码

• v2026.5.22 后，如果遇到 QR 登录 408 / 超时恢复，先不要反复删配置；等当前登录流程退出，再重新执行 openclaw channels login whatsapp。仍失败时再清理对应 WhatsApp credential，而不是清空所有平台凭证。

⠀

收不到某些人的消息？

• 检查 allowFrom 配置是否包含了对方的号码

• 如果需要接收所有人的消息，设置 allowFrom: ["*"]

⠀

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

---

4. Discord 接入

⠀

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

⠀

v2026.5.22 语音更新：Discord voice 会话可以跟随配置的 Discord 用户进入语音频道，并保留 DAVE recovery；realtime voice session 默认会带有限的 IDENTITY.md、USER.md、SOUL.md profile context，可通过 voice.realtime.bootstrapContextFiles: [] 关闭。Meeting Notes 外部插件也首先支持 Discord voice 作为 live source。

⠀

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 才触发回复

⠀

4.6 Meeting Notes 外部插件

⠀

v2026.5.22 开始，Meeting Notes 外部插件首先支持 Discord voice 作为 live source。它适合会议纪要、访谈记录和语音复盘，不等同于普通 Discord 文本 Bot。

⠀

使用前先确认三件事：

⠀

1. Discord voice follow 已按官方文档配置。

2. live source 所在频道有明确授权，避免无意记录私人语音。

3. 纪要输出是只读生成，提交到文档、PR 或消息平台前仍需要人工确认。

---

5. Slack 接入

⠀

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

⠀

v2026.5.22 状态反馈：Slack ack reaction 相关说明已补进官方通道文档。团队接入时要约定哪些 reaction 表示“已处理 / 需要人工 / 拒绝”，避免把普通表情误当作流程状态。

⠀

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 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。

⠀

v2026.5.22 更新：飞书 dynamic agents 相关说明已进入官方通道文档。多个群、多个 agent 共存时，不要只记录 App ID / Secret，还要记录群 ID、agent 路由规则和默认 owner。

⠀

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 接入

BlueBubbles

iMessage 接入（推荐方式）

iMessage

Legacy 方式，仅 macOS

Microsoft Teams

内置支持

Google Chat

内置支持

Matrix

内置支持（v2026.4.22 新增交叉签名验证）

Zalo / Zalo Personal

内置支持

LINE

通过 @line/bot-sdk 接入

⠀

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

⠀

v2026.5.22 之后，部分平台的配置细节需要额外记录：

⠀

平台

新版配置关注点

Signal

明确 configPath，避免多实例争用同一 signal-cli 配置

Zalo / Zalo Personal

优先使用官方文档列出的环境变量，不要把账号 token 写进仓库

Android

pairing approval 要由 owner 明确确认，避免陌生设备直接绑定

macOS / iMessage

VM auto-login 和 BlueBubbles 凭证要单独备份，重启后先验登录状态

---

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 支持对比

⠀

格式

Telegram

WhatsApp

Discord

Slack

飞书

粗体

✅ text

✅ text

✅ text

✅ text

✅

斜体

✅ text

✅ text

✅ text

✅ text

✅

代码

✅ code

✅ code

✅ code

✅ code

✅

代码块

✅

❌

✅

✅

✅

链接

✅

✅ 自动识别

✅

✅

✅

⠀

13.2 长消息处理

⠀

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

⠀

平台

最大长度

OpenClaw 处理方式

Telegram

4096 字符

自动分段发送

WhatsApp

4096 字符

自动分段发送

Discord

2000 字符

自动分段发送

Slack

40000 字符

通常不需要分段

飞书

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

---

下一步

⠀

下一步

文档

说明

配置技能

06-技能系统指南

让 Agent 具备更多能力

记忆系统

07-记忆系统指南

让 AI 记住用户偏好

安全配置

10-安全配置指南

Webhook 安全、Token 管理