OpenClaw 通过 WhatsApp Web（Baileys 库）接入 WhatsApp，Gateway 持有链接 Session，支持私信、群组、多账号和语音消息。
快速接入（4步）
第一步：配置访问策略
{
"channels": {
"whatsapp": {
"dmPolicy": "pairing",
"allowFrom": ["+8613800138000"],
"groupPolicy": "allowlist",
"groupAllowFrom": ["+8613800138000"]
}
}
}第二步：QR 扫码链接
# 默认账号
openclaw channels login --channel whatsapp
# 指定账号名
openclaw channels login --channel whatsapp --account work用手机 WhatsApp 扫描终端中显示的 QR 码完成链接。
第三步：启动 Gateway
openclaw gateway第四步：审批配对请求（pairing 模式）
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>配对码有效期 1 小时，最多 3 个待审批请求。
推荐：使用独立手机号运行 OpenClaw，避免与个人 WhatsApp 混用。
两种部署模式
专用号码（推荐）
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": ["+8613800138000"]
}
}
}好处：路由边界清晰，不会产生自聊天混淆。
个人号码
引导向导会自动配置：
{
"channels": {
"whatsapp": {
"dmPolicy": "allowlist",
"allowFrom": ["+8613800138000"],
"selfChatMode": true
}
}
}selfChatMode: true 开启自聊天保护，避免误触发。
访问控制详解
DM 策略（dmPolicy）
| 策略 | 说明 |
|---|---|
pairing（默认） | 未知用户需要配对审批 |
allowlist | 仅 allowFrom 列表中的号码 |
open | allowFrom 包含 "*" 时开放 |
disabled | 拒绝所有私信 |
号码使用 E.164 格式（如 +8613800138000）。
群组策略
两层控制：
哪些群组可以访问（groups 配置）：
{
"channels": {
"whatsapp": {
"groups": {
"120363999999999999@g.us": { "enabled": true }
}
}
}
}群组内谁可以发言（groupPolicy + groupAllowFrom）：
{
"channels": {
"whatsapp": {
"groupPolicy": "allowlist",
"groupAllowFrom": ["+8613800138000"]
}
}
}注意：引用/回复满足提及检测，但不绕过发送者白名单验证。
消息与媒体处理
引用回复格式
[Replying to +8613800138000 id:xxx]
被引用的内容
[/Replying]
媒体占位符
纯媒体消息显示为：<media:image>、<media:video>、<media:audio>、<media:document>
文本分块
{
"channels": {
"whatsapp": {
"textChunkLimit": 4000,
"chunkMode": "newline"
}
}
}newline 模式在段落边界分割，更自然。
即时回执反应
{
"channels": {
"whatsapp": {
"ackReaction": {
"emoji": "👀",
"direct": true,
"group": "mentions"
}
}
}
}消息收到后立即发送 emoji 回应，表示已收到正在处理。
多账号配置
两个号码对应两个 Agent：
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account work{
"channels": {
"whatsapp": {
"accounts": {
"personal": { "dmPolicy": "allowlist", "allowFrom": ["+8613800000001"] },
"work": { "dmPolicy": "allowlist", "allowFrom": ["+8613800000002"] }
}
}
},
"bindings": [
{ "agentId": "home", "match": { "channel": "whatsapp", "accountId": "personal" } },
{ "agentId": "work", "match": { "channel": "whatsapp", "accountId": "work" } }
]
}认证文件路径：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
注销与重新登录
openclaw channels logout --channel whatsapp
openclaw channels logout --channel whatsapp --account work
openclaw channels login --channel whatsapp # 重新扫码故障排查
未链接（需要扫码）：
openclaw channels login --channel whatsapp
openclaw channels status已链接但频繁断线：
openclaw doctor
openclaw logs --follow群组消息被忽略：依次检查 groupPolicy、groupAllowFrom、groups 白名单、requireMention 和 mention patterns。
警告：WhatsApp Gateway 必须使用 Node.js 运行，Bun 运行时会导致不稳定。
原文：WhatsApp - OpenClaw | 来源：OpenClaw 官方文档