8.2 WhatsApp集成

概述

WhatsApp 渠道使 OpenClaw 能够通过 WhatsApp Web（使用 Baileys 库）作为个人助手运行。Gateway 管理会话，支持在一个进程中运行多个账户，并使用确定性路由将回复返回到 WhatsApp，无需基于模型的路由。

设置要求

快速初始化步骤：

1. 在 ~/.openclaw/openclaw.json 中配置 WhatsApp
2. 运行登录命令扫描二维码
3. 启动 Gateway

最小配置需要设置私信策略和允许列表。

手机号码选项

专用号码（推荐）

为 OpenClaw 使用单独的手机，最好是带有 eSIM 的旧 Android 设备并保持 Wi-Fi 连接。WhatsApp Business 可以与个人 WhatsApp 在同一设备上并行运行。

个人号码（备选）

在您自己的号码上运行 OpenClaw，但需启用自聊模式并向自己发送消息进行测试，以避免骚扰联系人。

访问控制

私信策略选项包括：

• 配对（Pairing）：未知发送者会收到一个需要通过 openclaw pairing approve whatsapp <code> 批准的验证码（1小时过期）
• 允许列表（Allowlist）：限制为指定的 E.164 格式电话号码
• 开放（Open）：接受所有发送者

已关联的 WhatsApp 账户会隐式绕过这些检查。

多账户支持

多个账户可在一个 Gateway 进程中运行。登录语法：openclaw channels login --account <id>。凭证存储在 ~/.openclaw/credentials/whatsapp/<accountId>/creds.json，并自动备份。

群组聊天功能

群组通过提及（默认）或始终模式激活。系统会注入最近未处理的消息作为上下文，受可配置的历史记录设置限制。所有者控制仅限于允许列表中的成员。

消息处理

• 引用回复会附加完整上下文和元数据（ReplyToId、ReplyToBody、ReplyToSender）
• 纯媒体消息显示占位符如 <media:image|video|audio|document|sticker>
• 出站文本默认按 4,000 字符分块；可选的基于换行的分块会在段落边界处分割

确认功能

自动表情回应提供即时收据反馈。配置包括表情选择、私信行为和群组特定设置（"mentions"、"always"或"never"）。

媒体处理

• 支持的格式：图片、视频、音频和文档
• 音频以语音便签（PTT）形式发送
• 动态 GIF 需要带有 gifPlayback: true 的 MP4
• 默认出站限制：每项 5 MB；入站：总计 50 MB
• 图片自动优化为 JPEG

配置示例

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"],
      "sendReadReceipts": false,
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": "mentions"
      }
    }
  }
}

监控与故障排除

Gateway 心跳记录连接健康状态（默认 60 秒）。重连使用指数退避和可配置参数。关键故障排除检查包括验证二维码关联、检查断连循环以及确认 Node.js 运行时（不支持 Bun）。