WhatsApp 是全球用户量最大的即时通讯应用，超过20亿月活用户。能在 WhatsApp 里直接和 OpenClaw 对话，是很多用户选择它的核心理由之一。本文带你完整走一遍 WhatsApp 连接流程，并告诉你哪些坑一定要提前了解。

先了解一件重要的事：WhatsApp 连接的工作原理

OpenClaw 连接 WhatsApp 使用的是 WhatsApp Web 协议（基于 Baileys 库），本质上和你在电脑浏览器上使用 WhatsApp Web 是同一套机制——扫 QR 码，将 OpenClaw 作为一个”关联设备”绑定到你的 WhatsApp 账号。

这意味着：

  • 不需要购买任何额外服务
  • 不需要 WhatsApp Business API 账号
  • 你的个人 WhatsApp 号码就可以直接使用
  • 每次 Gateway 重启后，只要 session 有效，无需重新扫码

但也意味着一个现实限制：这是非官方的协议对接方式，WhatsApp 明令禁止自动化批量消息行为。个人使用、只和自己对话或少数联系人交互，风险较低；如果用于批量发送消息或自动回复大量用户，账号有被封禁的风险。

使用哪个 WhatsApp 号码？两种方案

在开始配置之前，先做一个决定：用哪个号码连接 OpenClaw？

方案 A：用个人主号（给自己发消息）

最简单的方式。OpenClaw 连接你的主号后，你通过”给自己发消息”（WhatsApp 的”Message yourself”功能）与它交互。

优点：零额外成本，立即可用。

风险：如果 OpenClaw 产生异常行为（如发送太频繁），可能影响你的主号。

方案 B：用专用备用号（推荐）

准备一张备用 SIM 卡，注册一个专门用于 OpenClaw 的 WhatsApp 号码。

优点：主号完全安全，即使备用号被封禁也不影响日常使用。两个号互加好友后，像和联系人对话一样与 OpenClaw 交互。

社区中经验丰富的用户普遍推荐方案 B，尤其是打算长期稳定使用的用户。

第一步：安装 WhatsApp 插件

OpenClaw 的 WhatsApp 支持通过插件形式提供，首次使用需要安装。有两种方式触发安装：

方式 A：通过引导向导（推荐新手）

在运行 openclaw onboard 时，选择 WhatsApp 作为通讯平台，系统会自动提示安装 WhatsApp 插件并引导完成配置。

方式 B：手动安装

# 添加 WhatsApp 频道（会自动触发插件安装）
openclaw channels add --channel whatsapp

# 或者直接登录（同样会触发安装）
openclaw channels login --channel whatsapp

第二步：启用 WhatsApp 并重启 Gateway

# 在配置中启用 WhatsApp
openclaw config set channels.whatsapp.enabled true

# 重启 Gateway 使配置生效
openclaw gateway restart

第三步：扫码配对（核心步骤）

这是整个连接过程中最关键的一步。

通过控制面板扫码

打开浏览器访问控制面板（http://127.0.0.1:18789），进入”Channels”→”WhatsApp”，点击”Show QR Code”，屏幕上会显示 QR 码。

通过命令行生成 QR 码

# 在前台运行 Gateway 以显示 QR 码
openclaw gateway

# 或者直接登录触发 QR 码生成
openclaw channels login --channel whatsapp

QR 码出现后，立即用手机扫描。动作要快，QR 码有时效限制，大约60～90秒后会过期，过期后需重新生成。

手机端扫码步骤

  1. 打开 WhatsApp（使用你选定的号码）
  2. 点击右上角菜单（三个点）→ 关联的设备（Linked Devices）
  3. 点击 关联设备（Link a Device）
  4. 扫描屏幕上的 QR 码

扫码成功后，终端或控制面板会显示类似”device linked”和”session saved”的确认信息。WhatsApp 的”关联的设备”列表中也会出现一个新条目。

💡 扫码技巧：如果 QR 码在终端中显示扭曲或模糊，尝试调亮屏幕亮度、缩小终端字体，或改用控制面板中的 QR 码显示方式（图形更清晰）。

第四步：配置消息权限（dmPolicy）

扫码完成后，还需要配置谁有权限给 OpenClaw 发消息。这是最重要的安全设置之一：

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["+8613800138000"],
      "groupPolicy": "allowlist"
    }
  }
}

dmPolicy 三种模式说明

模式 效果 适用场景
pairing（推荐） 首次发消息需配对验证，配对后永久授权 个人使用，安全且灵活
allowlist 只有 allowFrom 列表中的号码可以发消息 严格限制访问，最安全
open 任何人都可以发消息 仅在完全受控的私有环境使用

通过 CLI 快速设置：

# 设置为配对模式（推荐）
openclaw config set channels.whatsapp.dmPolicy "pairing"

# 添加允许的号码（E.164 格式）
openclaw config set channels.whatsapp.allowFrom '["+8613800138000"]'

# 设置自动回应表情（可选，收到消息时自动点赞）
openclaw config set channels.whatsapp.ackReaction.emoji "👀"
openclaw config set channels.whatsapp.ackReaction.direct true

修改配置后重启 Gateway：

openclaw gateway restart

第五步：发送第一条消息测试

使用个人主号的用户

打开 WhatsApp，点击”给自己发消息”（Message yourself），发送”你好”。

使用备用号的用户

用主号给备用号（OpenClaw 使用的号码）发一条消息。

如果是 pairing 模式，第一次发消息会收到一个配对码，在服务器上运行：

openclaw pairing approve whatsapp 配对码

配对完成后，OpenClaw 会响应你的消息。收到 AI 回复，说明连接成功！

Session 管理：避免频繁断线

WhatsApp 连接最常见的问题是 session 失效导致断线，通常需要重新扫码。以下是保持连接稳定的关键：

Session 存储在哪里？

OpenClaw 将 WhatsApp 的 session 凭证存储在本地 ~/.openclaw/credentials/ 目录中。Gateway 每次重启时会自动读取并重连，正常情况下不需要重新扫码。

哪些情况会导致需要重新扫码？

  • 在手机端手动解除了 OpenClaw 的关联设备
  • session 凭证文件被删除或损坏
  • WhatsApp 账号因异常行为被系统主动断开关联
  • 长时间（通常超过14天）未发送任何消息导致 session 超时

服务器时钟同步（VPS 用户必做）

WhatsApp 的认证握手对服务器时钟精度有要求，时钟漂移会导致频繁断线：

# Ubuntu/Debian 安装时钟同步服务
sudo apt install -y ntp
sudo systemctl enable ntp
sudo systemctl start ntp

# 检查时钟同步状态
timedatectl status

群组消息配置

如果你想让 OpenClaw 在 WhatsApp 群组中也能响应，需要额外配置：

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+8613800138000"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

requireMention: true 要求在群组中必须 @提及 OpenClaw 才会触发回复，避免它响应所有群消息。

常见问题排查

Q：QR 码扫完后没有反应，终端没有”linked”提示怎么办？
QR 码可能在扫描前已过期。重新运行 openclaw channels login --channel whatsapp 生成新的 QR 码，扫完后等待5～10秒再确认。

Q：连接成功但发消息没有回复怎么办？

# 检查 WhatsApp 频道状态
openclaw channels status --probe

# 查看实时日志
openclaw logs --follow
# 发一条消息，观察日志中是否有消息接收记录

Q：每次重启 Gateway 都要重新扫码怎么办？
检查 session 文件是否存在：

ls -la ~/.openclaw/credentials/

如果每次重启后 session 文件消失，可能是 Gateway 以非预期的用户身份运行，导致无权写入该目录。确认文件所有者和权限：

ls -la ~/.openclaw/
# 应该全部属于你的用户，权限 700

Q：WhatsApp 账号收到警告或被暂时限制怎么办？
立即停止 OpenClaw 的 WhatsApp 连接，让账号休息24～48小时再重新连接。同时检查你的使用场景是否触发了 WhatsApp 的反自动化检测（如频繁发消息、发向大量不同号码等）。强烈建议切换到备用号码继续使用。

Q：如何断开 WhatsApp 连接？

# 断开当前 WhatsApp 会话
openclaw channels logout --channel whatsapp

# 同时在手机端解除关联：WhatsApp → 关联的设备 → 点击对应设备 → 退出登录

WhatsApp vs Telegram：该选哪个？

很多用户在选择通讯平台时会纠结。简单说：

  • WhatsApp：如果你的日常主力通讯工具是 WhatsApp，或者国际联系人主要在 WhatsApp，选它。但要做好使用备用号的准备。
  • Telegram：配置更简单（无需 QR 码，通过 Bot Token 直接接入），稳定性更好（官方 Bot API，不存在封号风险），功能更完整（支持 Bot 内联命令等）。如果没有特别理由坚持 WhatsApp，Telegram 是更推荐的第一选择。

当然，两者可以同时连接，各司其职。

更多配置细节，访问 OpenClaw官网中文版（通过浏览器翻译访问 openclaw.ai）或官方 WhatsApp 频道文档 docs.openclaw.ai/channels/whatsapp。

本文内容基于 OpenClaw 官方文档、lumadock.com、marktechpost.com 等公开资料整理，信息截至2026年3月28日。