WhatsApp（Web 渠道）

状态：生产就绪，通过 WhatsApp Web（Baileys）接入。Gateway 管理连接会话。

推荐：为 OpenClaw 使用独立的手机号，避免与个人 WhatsApp 混用。

快速配置

步骤 1：配置访问策略

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

步骤 2：扫描 QR 码配对 WhatsApp

openclaw channels login --channel whatsapp

指定账户：

openclaw channels login --channel whatsapp --account work

步骤 3：启动 Gateway

openclaw gateway

步骤 4：审批第一条私信（配对模式）

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

配对请求有效期 1 小时，同时最多挂起 3 个配对请求。

部署模式

独立号码（推荐）

使用独立号码是最干净的运行模式：

• 独立的 WhatsApp 身份
• 更清晰的私信白名单和路由边界
• 降低自聊天混淆的风险

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

个人号码（支持但需谨慎）

也支持在个人号码上运行，但需要注意：

• OpenClaw 会接管 WhatsApp Web 会话（与手机 App 共存）
• 为避免自发消息意外触发 Agent，配置好 dmPolicy 和 allowFrom

访问控制

私信策略（dmPolicy）

策略值	行为
"pairing"（默认）	未知发送者收到配对码
"allowlist"	只允许 allowFrom 中的号码
"open"	允许所有人（需 allowFrom: ["*"]）
"disabled"	禁用私信

allowFrom 接受完整国际格式号码（如 +15551234567）。

群组策略

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",        // open | allowlist | disabled
      groupAllowFrom: ["+15551234567"], // 允许的群成员号码
      groups: {
        "*": { requireMention: true }, // 所有群都需要 @mention
      },
    },
  },
}

多用户安全模式

如果多个用户可以私信你的 Bot，建议开启安全 DM 模式，让各用户的对话独立：

{
  session: { dmScope: "per-channel-peer" },
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567", "+15551234568"],
    },
  },
}

多账户配置

{
  channels: {
    whatsapp: {
      accounts: {
        personal: {
          dmPolicy: "allowlist",
          allowFrom: ["+15551234567"],
        },
        work: {
          dmPolicy: "allowlist",
          allowFrom: ["+15559876543"],
        },
      },
    },
  },
}

每个账户分别通过 --account 参数扫码配对：

openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account work

运行时说明

• WhatsApp 连接由 Gateway 进程管理（类似 WhatsApp Web）
• 路由是确定性的：WhatsApp 来的消息回复到 WhatsApp
• 会话状态持久化在磁盘上（~/.openclaw/whatsapp/）
• 支持图片、视频、语音等媒体类型的接收和发送

常见问题

QR 码扫描失败：

• 确保手机 WhatsApp 已更新到最新版本
• 在手机 WhatsApp 中进入 已关联的设备 → 关联设备 重新扫码

Bot 被踢出（会话断开）：

• WhatsApp 通常允许最多 5 个关联设备
• 运行 openclaw channels status --probe 检查连接状态

收不到消息：

• 检查 dmPolicy 是否设置正确
• 查看日志：openclaw logs --follow
• 运行 openclaw doctor 检查配置问题