OpenClaw
渠道集成12 分钟阅读

OpenClaw WhatsApp 集成完整指南

连接 OpenClaw 与 WhatsApp 的分步指南。使用 Baileys 通过 WhatsApp Web 协议与您的 AI 助手聊天。

O

OpenClaw Guides

Tutorial Authors

概述

WhatsApp 集成允许您直接通过 WhatsApp 与 OpenClaw AI 助手聊天。OpenClaw 使用 WhatsApp Web via Baileys — 网关拥有会话并管理所有通信。您将像在浏览器上链接 WhatsApp Web 一样链接您的 WhatsApp 账户。

前提条件

开始之前，请确保您有：

  • 已安装 OpenClaw 且网关正在运行
  • 一个拥有真实手机号码的 WhatsApp 账户（VoIP 和虚拟号码通常会被 WhatsApp 屏蔽）
  • Node.js 运行时（不建议使用 Bun — WhatsApp/Baileys 在 Bun 上运行不稳定）

获取电话号码

WhatsApp 需要真实手机号码进行验证。有两种支持的模式：

专用号码（推荐）

使用独立电话号码运行 OpenClaw。这提供最佳用户体验，路由清晰，没有自聊天问题。理想设置是备用/旧 Android 手机 + eSIM — 保持 Wi-Fi 和电源连接，然后通过 QR 码链接。

号码获取提示：

  • 本地 eSIM — 来自您所在国家的运营商（最可靠）
  • 预付费 SIM 卡 — 便宜，只需接收一条验证短信
  • 避免使用： TextNow、Google Voice 及大多数"免费短信"服务 — WhatsApp 会积极屏蔽这些

号码只需接收一条验证短信。之后，WhatsApp Web 会话通过 creds.json 持久保存。

提示： 您可以在同一设备上使用不同号码运行 WhatsApp Business。非常适合将个人 WhatsApp 分开 — 安装 WhatsApp Business 并用 OpenClaw 号码注册。

个人号码（备选方案）

快速备选：在您自己的号码上运行 OpenClaw。给自己发消息（WhatsApp"给自己发消息"）进行测试，避免打扰联系人。这种情况下必须启用自聊天模式。

步骤 1：配置 WhatsApp

编辑 ~/.openclaw/openclaw.json。

专用号码配置

json5
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

将 +15551234567 替换为您希望允许与助手聊天的电话号码（E.164 格式）。

个人号码配置（自聊天模式）

json
{
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

使用自聊天模式时，输入您发送消息的电话号码（拥有者/发送者），而非助手号码。自聊天回复默认使用 [{identity.name}] 作为前缀（如未设置则为 [openclaw]）。您可以通过 messages.responsePrefix 自定义，或设置为 "" 来移除。

步骤 2：链接您的 WhatsApp 账户

运行登录命令：

bash
openclaw channels login

这将在终端显示二维码。在手机上：

  1. 打开 WhatsApp
  2. 进入 设置 > 关联设备
  3. 点击 关联设备
  4. 扫描终端中显示的二维码

对于多账户设置，指定账户：

bash
openclaw channels login --account <accountId>

省略 --account 时的默认账户：如果存在 default 则使用它，否则使用第一个配置的账户 ID（按排序）。

步骤 3：启动网关

启动 OpenClaw 网关开始接收消息。网关拥有 Baileys socket 和收件循环 — CLI 和 macOS 应用程序与网关通信，不直接使用 Baileys。

重要： 出站发送需要活跃的监听器；否则发送会快速失败。

DM 访问控制

OpenClaw 通过 channels.whatsapp.dmPolicy 提供三种 DM 策略模式：

配对模式（默认）

未知发送者会收到一个有时间限制的配对码。他们的消息在批准前不会被处理。

bash
# 批准配对请求
openclaw pairing approve whatsapp <code>

# 列出待处理的配对请求
openclaw pairing list whatsapp

配对码在 1 小时后过期，每个通道的待处理请求上限为 3 个。

白名单模式

只有 channels.whatsapp.allowFrom 中列出的电话号码才能发起聊天。

json5
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567", "+15559876543"],
    },
  },
}

开放模式

需要 channels.whatsapp.allowFrom 包含 "*"。

注意： 您链接的 WhatsApp 号码是隐式信任的 — 自消息会跳过 dmPolicy 和 allowFrom 检查。

已读回执

默认情况下，网关在接受入站 WhatsApp 消息后会将其标记为已读（蓝色对勾）。

全局禁用：

json5
{
  channels: { whatsapp: { sendReadReceipts: false } },
}

按账户禁用：

json5
{
  channels: {
    whatsapp: {
      accounts: {
        personal: { sendReadReceipts: false },
      },
    },
  },
}

自聊天模式始终跳过已读回执。

群聊支持

群组映射到专用会话。通过以下方式配置群组行为：

  • 群组策略： channels.whatsapp.groupPolicy — open、disabled 或 allowlist（默认：allowlist）
  • 激活模式：
    • mention（默认）：需要 @提及 或正则匹配
    • always：始终触发响应

通过仅限所有者的命令切换激活模式（必须作为独立消息发送）：

/activation mention
/activation always

所有者由 channels.whatsapp.allowFrom 确定（如未设置则为您的 E.164 号码）。

群聊历史上下文

最近未处理的消息（默认 50 条）会自动注入作为上下文：

[Chat messages since your last reply - for context]
...
[Current message - respond to this]

每条消息包含发送者后缀：[from: Name (+E164)]。

群组元数据（主题 + 参与者）缓存 5 分钟。

确认回应

WhatsApp 可以在收到消息时自动发送 emoji 回应，在机器人生成回复之前提供即时反馈。

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

选项：

  • emoji：回应使用的 emoji（如 "👀"、"✅"）。为空或省略则禁用该功能。
  • direct（默认：true）：在 DM 聊天中发送回应。
  • group（默认："mentions"）：
    • "always"：对所有群组消息回应
    • "mentions"：仅在机器人被 @提及 时回应
    • "never"：从不在群组中回应

按账户覆盖：

json
{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

回应在收到消息后立即发送，在输入指示器或机器人回复之前。失败会被记录但不会阻止机器人回复。

消息处理

入站消息

  • 消息通过 Baileys messages.upsert 事件到达
  • 状态/广播聊天被忽略
  • 直接聊天使用 E.164 格式；群组使用 group JID
  • 引用回复上下文始终附加以提供对话上下文
  • 纯媒体消息使用占位符：<media:image|video|audio|document|sticker>

出站消息

  • 文本默认分块为 4,000 字符（可通过 channels.whatsapp.textChunkLimit 配置）
  • 可选换行分块：设置 channels.whatsapp.chunkMode="newline" 在长度分块前按段落边界分割
  • 支持的媒体类型：图片、视频、音频、文档
  • 音频作为语音备忘录（PTT）发送。OGG/Opus 格式效果最佳
  • 标题仅在第一个媒体项上
  • 动态 GIF：WhatsApp 需要带 gifPlayback: true 的 MP4 才能内联循环播放

媒体限制

  • 入站媒体保存上限：50 MB（可通过 channels.whatsapp.mediaMaxMb 配置）
  • 出站媒体上限：每项 5 MB（可通过 agents.defaults.mediaMaxMb 配置）
  • 图片在上限内自动优化为 JPEG（调整大小 + 质量扫描）
  • 超大媒体会导致错误；媒体回复回退到文本警告

凭证与存储

  • 凭证存储在：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • 自动备份在 creds.json.bak（损坏时恢复）
  • 登出：openclaw channels logout（或 --account <id>）删除 WhatsApp 认证状态但保留共享的 oauth.json

多账户支持

多个 WhatsApp 账户可以在单个网关进程中运行。在配置中使用账户标识符：

json5
{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* 按账户设置 */ },
        work: { /* 按账户设置 */ },
      },
    },
  },
}

按账户设置支持覆盖 sendReadReceipts、ackReaction、mediaMaxMb、historyLimit 等。

为什么不用 Twilio / WhatsApp Business API？

早期 OpenClaw 构建支持 Twilio 的 WhatsApp Business 集成，但已被移除，原因是：

  • WhatsApp Business 号码不适合个人助手
  • Meta 强制执行 24 小时回复窗口 — 如果过去 24 小时内没有响应，商业号码无法发起新消息
  • 高频或"聊天式"使用会触发积极封禁，因为商业账户不是为个人助手式消息设计的
  • 结果：投递不可靠且频繁被封禁

配置速查参考

| 配置键 | 描述 | |---|---| | channels.whatsapp.dmPolicy | DM 策略：pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | 为个人号码设置启用 | | channels.whatsapp.allowFrom | DM 白名单（E.164 电话号码） | | channels.whatsapp.sendReadReceipts | 自动已读回执（默认：true） | | channels.whatsapp.ackReaction | 消息收到时自动回应 | | channels.whatsapp.groupPolicy | 群组策略：open / disabled / allowlist | | channels.whatsapp.textChunkLimit | 出站文本分块大小（默认：4000） | | channels.whatsapp.mediaMaxMb | 入站媒体上限（默认：50 MB） | | channels.whatsapp.configWrites | 允许通过 /config 命令写入配置 | | agents.defaults.mediaMaxMb | 出站媒体上限（默认：5 MB） |

故障排除

未链接 / 需要 QR 码登录

症状： channels status 显示 linked: false 或警告"Not linked"。

修复： 在网关主机上运行 openclaw channels login 并扫描 QR 码（WhatsApp > 设置 > 关联设备）。

已链接但断开连接 / 重连循环

症状： channels status 显示 running, disconnected 或警告"Linked but disconnected"。

修复： 运行 openclaw doctor 或重启网关。如果问题持续，通过 openclaw channels login 重新链接并检查 openclaw logs --follow。

Bun 运行时问题

Bun 不建议使用。WhatsApp（Baileys）和 Telegram 在 Bun 上不稳定。请使用 Node.js 运行网关。

重连行为

网关使用退避策略（web.reconnect），可配置 initialMs、maxMs、factor、jitter 和 maxAttempts。如果达到最大尝试次数，Web 监控停止（降级模式）。已登出的 socket 停止并需要重新链接。

后续步骤