Skip to main content

​
WhatsApp（网页渠道）

仅支持通过 Baileys 的 WhatsApp Web。Gateway 网关拥有会话。

​
快速设置

重要： 建议使用单独的手机号码运行 OpenClaw，而不是你的个人 WhatsApp 账号。
1

准备手机号码

WhatsApp 需要真实手机号码进行验证。两种选项：方案 1：专用号码（推荐）
  • 使用单独的手机号码
  • 最佳：备用 Android 手机 + eSIM
  • 可以使用 WhatsApp Business在同一设备上
方案 2：个人号码（备选）
  • 在你自己的号码上运行
  • 必须启用 selfChatMode
  • 给自己发消息进行测试
2

配置 OpenClaw

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"]
    }
  }
}
如果使用个人号码：
{
  "channels": {
    "whatsapp": {
      "selfChatMode": true,
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"]
    }
  }
}
3

扫描二维码登录

openclaw channels login
使用 WhatsApp 扫描二维码： WhatsApp → 设置 → 关联设备
4

启动 Gateway 网关

openclaw gateway run
检查状态：
openclaw channels status

​
获取手机号码

从你所在国家的移动运营商获取：
避免使用 TextNow、Google Voice 等虚拟号码服务 - WhatsApp 会积极封锁这些号码。
  • 便宜的选项
  • 只需接收一条验证短信
  • 之后 WhatsApp Web 会话通过 creds.json 持久化
Twilio 的 WhatsApp Business 集成不适合个人助手：
  • Meta 强制执行 24 小时回复窗口
  • 高频使用会触发封锁
  • 投递不可靠且频繁被封锁
早期 OpenClaw 支持 Twilio，但由于这些问题已移除。

​
配置选项

​
专用号码模式

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"],
      "groupPolicy": "allowlist",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

​
个人号码模式

{
  "channels": {
    "whatsapp": {
      "selfChatMode": true,
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"]
    }
  }
}
selfChatMode 防止出站私信触发配对回复，避免打扰联系人。
如果你想使用配对而不是允许列表：
{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    }
  }
}
批准方式：
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​
已读回执

默认情况下，Gateway 网关在接受入站 WhatsApp 消息后将其标记为已读（蓝色勾号）。 
{
  "channels": {
    "whatsapp": {
      "sendReadReceipts": false  // 禁用已读回执
    }
  }
}
按账户禁用： 
{
  "channels": {
    "whatsapp": {
      "accounts": {
        "personal": {
          "sendReadReceipts": false
        }
      }
    }
  }
}

​
WhatsApp 常见问题

不会。 默认私信策略是 配对，因此未知发送者只会收到配对码，他们的消息不会被处理。OpenClaw 只会回复它收到的聊天，或你显式触发的发送。
配对是未知发送者的私信门控：
  1. 来自新发送者的第一条私信返回一个短码
  2. 消息不会被处理
  3. 使用 openclaw pairing approve whatsapp <CODE> 批准
  4. 码在 1 小时后过期
可以。 通过 bindings 将每个发送者路由到不同的智能体（peer kind: "dm"，发送者 E.164 如 +15551234567）。回复仍然来自同一个 WhatsApp 账号。私信访问控制（dmPolicy/allowFrom）是每个 WhatsApp 账号全局的。

​
群组功能

​
配置群组

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groups": {
        "*": { "requireMention": true },
        "[email protected]": {
          "requireMention": false,
          "allowFrom": ["+15551234567"],
          "skills": ["search"],
          "systemPrompt": "群组专用提示"
        }
      }
    }
  }
}

​
激活模式

通过命令临时更改（仅限所有者）： 
/activation mention  # 需要提及（默认）
/activation always   # 始终响应

​
历史上下文

最近未处理的消息（默认 50 条）会插入为上下文： 
{
  "channels": {
    "whatsapp": {
      "historyLimit": 50  // 0 禁用
    }
  }
}

​
确认表情

在收到传入消息时立即自动发送表情反应： 
{
  "channels": {
    "whatsapp": {
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": "mentions"  // always | mentions | never
      }
    }
  }
}
选项：
  • emoji - 表情符号（例如 ”👀”、”✅”、”📨”）
  • direct - 在私聊中发送（默认：true）
  • group - 群聊行为：always | mentions | never
按账户覆盖： 
{
  "channels": {
    "whatsapp": {
      "accounts": {
        "work": {
          "ackReaction": {
            "emoji": "✅",
            "direct": false,
            "group": "always"
          }
        }
      }
    }
  }
}

​
媒体处理

​
支持的类型

  • 图片（JPEG、PNG、WebP）
  • 视频（MP4、WEBM）
  • 音频/语音消息（OGG/Opus）
  • 文档

​
限制

{
  "channels": {
    "whatsapp": {
      "textChunkLimit": 4000,
      "mediaMaxMb": 50,  // 入站
      "chunkMode": "length"  // length | newline
    }
  },
  "agents": {
    "defaults": {
      "mediaMaxMb": 5  // 出站
    }
  }
}

​
语音消息（PTT）

WhatsApp 将音频作为语音消息（PTT 气泡）发送。
  • 最佳效果： OGG/Opus
  • OpenClaw 将 audio/ogg 重写为 audio/ogg; codecs=opus
  • WhatsApp 忽略 [[audio_as_voice]] 标签

​
GIF 播放

动画 GIF 需要特殊处理： 
openclaw message send --media video.mp4 --gif-playback
WhatsApp 期望带有 gifPlayback: true 的 MP4 以实现内联循环。

​
登录管理

​
登录

openclaw channels login
多账户登录： 
openclaw channels login --account <accountId>

​
登出

openclaw channels logout
或按账户： 
openclaw channels logout --account <accountId>

​
凭据存储

  • 位置： ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • 备份： creds.json.bak
  • 重要： 将这些文件视为敏感信息

​
故障排除

症状： channels status 显示 linked: false修复：
openclaw channels login
扫描二维码：WhatsApp → 设置 → 关联设备
症状： channels status 显示 running, disconnected修复：
openclaw doctor
或重启 Gateway 网关。如果问题持续，通过 channels login 重新关联。
不推荐使用 Bun。 WhatsApp（Baileys）和 Telegram 在 Bun 上不可靠。请使用 Node 运行 Gateway 网关。
检查项：
  1. dmPolicy 设为 "pairing"
  2. 批准配对码： 
    openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​
多账户支持

运行多个 WhatsApp 账号： 
{
  "channels": {
    "whatsapp": {
      "accounts": {
        "personal": {
          "name": "个人",
          "dmPolicy": "pairing",
          "sendReadReceipts": false
        },
        "work": {
          "name": "工作",
          "dmPolicy": "allowlist",
          "allowFrom": ["+15559876543"],
          "ackReaction": {
            "emoji": "✅",
            "direct": true
          }
        }
      }
    }
  }
}

​
相关资源

配对系统

了解如何批准新用户

配置参考

完整的 WhatsApp 配置选项

故障排除

解决常见问题

Gateway 故障排除

Gateway 网关故障排除