跳到主要内容

3.4 WhatsApp

WhatsApp 是全球用户最多的即时通讯应用之一。OpenClaw 通过 Baileys 库连接 WhatsApp Web，需要手机扫码配对。

前置要求​

  • WhatsApp 账号
  • 独立的手机号码（推荐使用专门的手机号，避免干扰个人联系人）
  • OpenClaw 已安装并完成初始配置

为什么需要专用号码？​

WhatsApp 与 Telegram/Discord 不同：

  • 需要真实手机号验证
  • VoIP 和虚拟号码会被封锁
  • 在个人号码上运行会打扰联系人

推荐方案：

  • 备用/旧 Android 手机 + eSIM
  • 或 WhatsApp Business（可以同一设备用不同号码）

配置 OpenClaw​

最小配置​

编辑 ~/.openclaw/openclaw.json：

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

配对模式配置​

如果不想用白名单，可以用配对模式：

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    }
  }
}

登录配对​

1. 启动网关​

openclaw gateway

2. 扫码登录​

openclaw channels login

会显示二维码，用 WhatsApp 扫描：

  • WhatsApp → 设置 → 已关联的设备 → 关联设备

3. 验证状态​

openclaw channels status

两种运行模式​

模式一：专用号码（推荐）​

为 OpenClaw 使用单独的手机号码。

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

模式二：个人号码（备选）​

在你的个人 WhatsApp 上运行：

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

⚠️ 警告：这会把消息发给你自己，实验期间会打扰联系人。

获取手机号​

推荐方式​

地区推荐服务商
奥地利hot.at
英国giffgaff（免费 SIM 卡）
中国本地 eSIM 或预付费 SIM

避免使用​

  • TextNow
  • Google Voice
  • 大多数"免费短信"服务

提示：号码只需要接收一条验证短信，之后通过 creds.json 持久化。

访问控制​

私聊策略（dmPolicy）​

值说明
pairing默认。陌生用户收到配对码
allowlist仅 allowFrom 列表中的用户
open允许所有人（设置 allowFrom: ["*"]）
disabled禁用私聊

群组策略​

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",  // open / allowlist / disabled
      "groupAllowFrom": ["+15551234567"]
    }
  }
}

高级配置​

自动确认表情​

收到消息时自动回复表情：

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

选项：

  • direct: 私信中发送确认
  • group: 群组行为（always / mentions / never）

消息分块​

{
  "channels": {
    "whatsapp": {
      "textChunkLimit": 4000,
      "chunkMode": "newline"  // length 或 newline
    }
  }
}

媒体限制​

{
  "channels": {
    "whatsapp": {
      "mediaMaxMb": 50
    }
  }
}

群组配置​

群组策略​

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",  // open / allowlist / disabled
      "groups": {
        "群组JID": {
          "requireMention": true  // 需要 @提及
        }
      }
    }
  }
}

激活模式​

模式说明
mention需要 @提及（默认）
always始终响应

在群组中发送命令切换：

/activation always
/activation mention

凭证管理​

  • 凭证存储在：~/.openclaw/credentials/whatsapp/<account>/creds.json
  • 备份副本：creds.json.bak（损坏时恢复）

登出​

openclaw channels logout whatsapp

常见问题​

需要重新扫码？​

运行：

openclaw channels login

机器人给陌生人发消息？​

不会。默认配对模式会阻止未知发送者。

配对码过期？​

配对码 1 小时后过期。重新运行：

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <新码>

多个人可以用同一个 WhatsApp 吗？​

可以，通过 bindings 将不同用户路由到不同的 Agent。