OpenClaw 中文文档 — WhatsApp 与 Telegram 接入

本文详细展开 OpenClaw 最常用的两个渠道——Telegram 和 WhatsApp 的完整配置流程，包括访问控制模型、群组策略和运行时行为。

Telegram

接入架构

Telegram 渠道基于 grammY 框架，通过 Bot API 接入。默认使用长轮询模式，也支持 Webhook。Gateway 进程拥有 Telegram 轮询循环，路由是确定性的——Telegram 入站消息始终回复到 Telegram。

配置流程

第 1 步：创建 Bot Token

通过 Telegram 的 @BotFather 创建 Bot，获取 Token。

第 2 步：配置

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABC-DEF...",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

值得注意的是，Telegram 不使用 openclaw channels login 命令。Token 通过配置文件或环境变量（TELEGRAM_BOT_TOKEN）提供，Gateway 启动时自动连接。Token 解析顺序：配置值优先于环境变量，TELEGRAM_BOT_TOKEN 仅适用于默认账户。

第 3 步：启动并配对

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

访问控制模型

私信策略

channels.telegram.dmPolicy 支持四种模式：

策略	行为
pairing（默认）	未知发送者触发配对码
allowlist	仅白名单用户可对话
open	所有人可对话（需 allowFrom: ["*"]）
disabled	禁用私信

allowFrom 接受数字 Telegram 用户 ID。telegram: / tg: 前缀会被规范化。引导向导接受 @username 输入并解析为数字 ID。

获取用户 ID 的推荐方式：给 Bot 发消息后运行 openclaw logs --follow，读取 from.id。

群组策略

群组访问有两层控制：

1. 群组白名单（channels.telegram.groups）：决定哪些群组可以触发 Bot
2. 发送者策略（groupPolicy + groupAllowFrom）：决定允许的群组中谁能触发 Bot

// 示例：允许特定群组中的特定用户
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          allowFrom: ["8734062810"],
        },
      },
    },
  },
}

值得注意的是，groupAllowFrom 存放的是用户 ID（正数），而群组 ID（负数）应放在 groups 中。这是一个常见的配置错误——将群组 ID 放入 groupAllowFrom 会导致所有群组消息被忽略。

安全边界：群组发送者认证不继承私信配对存储审批。配对仅限私信场景。

Telegram 端设置

Telegram Bot 默认启用 Privacy Mode，限制了 Bot 在群组中的消息可见性。如需 Bot 看到所有群组消息：

1. BotFather 中发 /setprivacy → Disable
2. 从群组移除 Bot 再重新添加（Telegram 要求此步骤才能应用更改）

或者将 Bot 设为群组管理员——管理员 Bot 自动接收所有群组消息。

功能特性

流式预览：通过 editMessageText 实时更新回复内容，支持 off/partial/block/progress 四种模式。纯文本回复保持同一消息并就地编辑，不发第二条。

自定义命令：

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
      ],
    },
  },
}

论坛话题：论坛超级群组中，每个话题拥有独立会话（键追加 :topic:<threadId>），可通过配置路由到不同 Agent。

Webhook 模式：

{
  channels: {
    telegram: {
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "your-secret",
    },
  },
}

WhatsApp

接入架构

WhatsApp 渠道基于 Baileys（WhatsApp Web 协议），Gateway 拥有 WhatsApp socket 和重连循环。相比 Telegram，WhatsApp 在本地存储更多状态数据，包括认证凭据和会话信息。

配置流程

第 1 步：配置访问策略

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

第 2 步：QR 码配对

openclaw channels login --channel whatsapp

多账户场景：

openclaw channels login --channel whatsapp --account work

第 3 步：启动 Gateway 并批准配对

openclaw gateway
openclaw pairing approve whatsapp <CODE>

部署模式

独立号码（推荐）：使用独立 WhatsApp 身份，路由边界清晰，自聊混淆概率低。

个人号码：引导向导支持，自动配置 selfChatMode: true 和自聊保护。但运维复杂度更高。

访问控制模型

私信策略与 Telegram 类似，但 allowFrom 使用 E.164 格式电话号码（如 "+15551234567"）。

群组策略同样有两层控制：

1. 群组白名单（channels.whatsapp.groups）
2. 发送者策略（groupPolicy + groupAllowFrom）

发送者白名单回退：如果 groupAllowFrom 未设置，运行时回退到 allowFrom。

运行时行为

• 状态和广播聊天被忽略（@status、@broadcast）
• 私信使用 session.dmScope 控制会话隔离
• 群组会话按 JID 隔离
• 出站发送需要目标账户有活跃的 WhatsApp 监听器

功能特性

确认回应：入站消息接收后立即发送表情回应（回复生成之前）：

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions",
      },
    },
  },
}

已读回执：默认启用，可通过 sendReadReceipts: false 全局或按账户禁用。

文本分块：长回复自动分块，默认 4000 字符。支持 length 和 newline 两种模式，后者优先在段落边界分割。

媒体处理：支持图片、视频、音频（含 PTT 语音备忘录）和文档，上限默认 50 MB。图片支持自动优化。

群组历史注入：对于群组，Bot 被触发时可以注入之前未处理的消息作为上下文（默认最多 50 条，通过 historyLimit 配置）。

凭据存储

认证凭据路径：~/.openclaw/credentials/whatsapp/<accountId>/creds.json

故障排查

症状	处理
需要 QR 码（未关联）	openclaw channels login --channel whatsapp
已关联但反复断连	openclaw doctor + 检查日志
发送时无活跃监听器	确保 Gateway 在运行且账户已关联
群组消息被忽略	检查 groupPolicy → groupAllowFrom → groups → 提及

架构对比

维度	Telegram	WhatsApp
协议	Bot API（HTTP）	Web 协议（Baileys）
认证	Bot Token	QR 码配对
用户标识	数字 ID	E.164 电话号码
本地状态	极少	较多（会话数据）
已读回执	Bot API 不支持	支持
流式预览	支持（消息编辑）	不支持
轮询模式	长轮询 / Webhook	WebSocket
Privacy Mode	需手动关闭	无此概念

从架构层面来看，两个渠道的设计取舍反映了各自平台的特点：Telegram 的 Bot API 是官方支持的，功能丰富但 stateless；WhatsApp 基于逆向工程的 Web 协议，stateful 且需要更多本地维护，但用户覆盖面更广。

本文是渠道篇的第二篇。下一篇覆盖 Discord 和 Slack 的接入配置。

---

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

GitHub 仓库：openclaw/openclaw