为什么这篇值得先看
很多人搜索 OpenClaw WhatsApp，是因为已经完成安装，想把助手放进每天都会打开的消息入口。这里最容易犯的错误，是把“QR 能扫上”当成接入完成。官方文档里的 WhatsApp 页面实际覆盖了更多事情：插件安装、WhatsApp Web / Baileys 会话、Gateway 重连、私信 pairing、群聊准入、插件钩子隐私、多账号和媒体投递。
所以这篇不只讲登录命令，而是把 WhatsApp 接入拆成四个判断：用专用号码还是个人号码、私信走 pairing 还是 allowlist、群聊是否允许进入、插件是否可以接收入站消息内容。只有这四件事都清楚，后面的自动化、客服通知、多渠道助手才不会变成一堆临时补丁。
先抓住这 3 个关键点
- WhatsApp 当前基于 WhatsApp Web / Baileys 运行，Gateway 拥有 socket、认证目录和重连循环。
- 官方建议可行时使用 dedicated number；个人号码模式要特别处理
allowFrom和selfChatMode。 - 私信准入、群组准入、mention 门控和插件钩子是四层不同边界，不能混在一个“能不能回消息”的问题里。
官方资料依据
本页核验于 2026-06-16，主要依据官方 WhatsApp channel、channels pairing、channel config reference 和 channel routing 页面。需要特别记住几个官方边界：
| 官方信息 | 对你的影响 |
|---|---|
| WhatsApp 可通过 WhatsApp Web / Baileys 用于生产，Gateway 拥有已关联会话 | 接入后要重点看 Gateway 进程、认证目录和重连日志，而不是只看 CLI 登录是否成功 |
openclaw channels login --channel whatsapp 负责 QR 登录，pairing approval 是私信访问审批 | QR 登录和私信准入是两件事，不能用“扫过码”替代访问控制 |
| pairing code 约 1 小时过期，每个渠道待处理请求有上限 | 审批动作要短链路完成，不要让用户截图旧 code 后反复复用 |
| WhatsApp 入站消息包含个人内容、电话号码、群组 ID 和发送者信息 | pluginHooks.messageReceived 只应给真正可信的插件开启 |
先选号码模式
| 模式 | 适合谁 | 建议策略 | 风险边界 |
|---|---|---|---|
| Dedicated number | 团队、客服、业务通知、长期自动化 | dmPolicy: "allowlist"，只允许 owner 或固定操作员 | 最清晰，但需要单独维护号码和 WhatsApp Web 会话 |
| Personal-number fallback | 个人试用、临时验证、没有专用号码 | allowFrom 放自己的号码，并启用 selfChatMode | 容易把个人聊天和助手行为混在一起，不适合无边界开放 |
| Group workflow | 群里只在被 @ 或指定人触发时工作 | groupPolicy: "allowlist"，配合 groups 和 groupAllowFrom | 群组 ID、成员授权、mention 三者都要正确，否则会漏回或误回 |
如果你还没有明确业务场景，先用 dedicated number 的心智模型写配置。即使你现在用的是个人号码，也应该把“谁能私信、哪个群能进、哪些人能触发”写成显式规则。
实操步骤：从最小闭环开始
- 确认 WhatsApp 插件已安装。新手引导、
openclaw channels add --channel whatsapp或openclaw channels login --channel whatsapp都可能触发安装流程；需要可复现安装时再固定版本。 - 先写最小访问策略，不要一开始打开所有群组。至少先定下
dmPolicy、allowFrom、groupPolicy、groups。 - 执行 QR 登录：
openclaw channels login --channel whatsapp。如果是多账号，使用--account work并明确认证目录。 - 启动 gateway 后，如果私信策略是 pairing，立即运行
openclaw pairing list whatsapp和openclaw pairing approve whatsapp <CODE>。 - 用一条私信、一条群聊 mention、一条不该触发的普通群聊消息分别测试。不要只测成功路径。
- 回到日志、Control UI 或 Dashboard 看实际投递状态，确认“模型生成了回复”和“WhatsApp 真正收到可见消息”不是被混为一谈。
配置或命令示例
专用号码起步配置
{
channels: {
whatsapp: {
enabled: true,
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
groups: {
"*": { requireMention: true }
}
}
}
}openclaw channels login --channel whatsapp
openclaw gateway
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>多账号或已有认证目录
openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work这类配置适合把个人入口和工作入口拆开。多账号后，要额外确认默认账号、账号级 allowFrom、账号级认证目录是否和你的出站目标一致。
仅在可信插件上打开入站钩子
{
channels: {
whatsapp: {
pluginHooks: {
messageReceived: true
}
}
}
}WhatsApp 入站载荷可能包含电话号码、群组标识符和消息正文。除非你确定插件需要读取这些内容，并且你信任它的存储和转发行为，否则不要因为“后面也许会用到”就打开。
群聊准入怎么设计
群聊至少有三层判断：
groups决定哪些群组可以进入处理范围。配置了groups后，它就是群组允许列表；"*"表示允许所有群组。groupPolicy和groupAllowFrom决定群里哪些发送者可以触发。没有groupAllowFrom时，运行时可能回退到allowFrom。requireMention和 mention pattern 决定已授权消息是否需要显式叫醒机器人。授权检查在 mention / reply 激活之前发生。
一个稳妥的起步策略是：允许少数群组，允许少数发送者，默认需要 mention。确认噪声和权限都可控后，再为特定群组放宽 requireMention。
常见排错路径
- 未关联或需要重新扫码：运行
openclaw channels login --channel whatsapp，再看openclaw channels status。 - 反复断连或 watchdog 重连：先看 Gateway 是否持续运行，再看 WhatsApp Web 传输和
web.whatsapp.keepAliveIntervalMs、connectTimeoutMs等时序配置。 - 代理环境下 QR 登录超时：确认 Gateway 进程继承了
HTTPS_PROXY、HTTP_PROXY和NO_PROXY等标准代理环境变量。 - 群组消息被忽略：按
groupPolicy、groupAllowFrom/allowFrom、groups、mention 门控、重复配置键这个顺序查。 - 日志里有回复但 WhatsApp 没收到：模型转录和平台送达不是一回事，要找
auto-reply delivery failed或 provider accepted 相关日志。
风险边界
- 不要把个人 WhatsApp 号码暴露给公开机器人场景；个人号码模式更适合私用或低风险测试。
dmPolicy: "open"应只用于明确的公开机器人，并配合严格工具权限。普通个人助手不要这么起步。allowFrom限制的是私信发送者，不会自动限制显式出站发送到群组 JID 或 newsletter JID。- 群聊默认应需要 mention。把
requireMention: false当成特例，而不是默认。 - 插件入站钩子默认不开是有原因的。WhatsApp 消息内容和联系人信息不应被无关插件旁路读取。
常见坑
- 把“能扫码”当成接入完成，忽略 session 持久化和策略治理。
- 既想用 dedicated number，又开 personal-number selfChatMode，最后行为边界变混乱。
- 群聊场景不设 mention 或 allowlist，助手会在错误的上下文里被频繁触发。
- 把私信 pairing 当成群组授权，结果 DM 已能访问，群里仍被 groupPolicy 拦住。
- 忽略多账号默认路由，导致出站消息从意外账号发出。
完成检查
openclaw channels login --channel whatsapp已完成，Gateway 运行后状态正常。- 你明确选择 dedicated number、personal fallback 或 group workflow，而不是混用所有模式。
- 私信策略可解释：
pairing、allowlist、open、disabled当前是哪一个，为什么。 - 群聊策略可预测：哪个群能进、谁能触发、是否需要 mention。
- 至少测试过一条应该回复的消息和一条应该被拒绝的消息。
- 插件钩子、媒体上限、已读回执和多账号默认值都没有被默认值“顺手带过”。
下一步内链
- 如果你还在纠结号码选择，继续看 OpenClaw WhatsApp 方案怎么选。
- 如果卡在审批或配对码，继续看 OpenClaw pairing 教程。
- 如果准备把 WhatsApp 和 Telegram 一起用，继续看 OpenClaw channel routing 实战。
为什么建议把这篇收藏起来
- WhatsApp 是 OpenClaw 最常见的入口之一，值得有一篇真正讲清策略边界的教程。
- 这篇能帮你避免“先接上，后治理”的反复返工。