WhatsApp 接入

1. 准备一个手机号码（推荐使用单独号码）。
2. 在配置文件中添加 WhatsApp 渠道。
3. 运行 openclaw channels login 扫码关联。
4. 启动 Gateway。

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

专用号码（推荐）

为 OpenClaw 使用单独的手机号码，路由清晰，体验最佳。理想搭配：备用 Android + eSIM，保持 Wi-Fi 和电源连接。 也可以在同一设备上安装 WhatsApp Business 使用不同号码。

个人号码（备选）

在自己的号码上运行 OpenClaw，启用 selfChatMode 通过"给自己发消息"测试。

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

号码来源建议：本地运营商 eSIM 或预付费 SIM 卡。避免使用 TextNow、Google Voice 等虚拟号码，WhatsApp 会封锁这些。

# 扫码登录（关联设备）
openclaw channels login

# 多账户登录
openclaw channels login --account work

# 登出
openclaw channels logout

• 凭证保存在 ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• 自动备份到 creds.json.bak
• 登出只删除 WhatsApp 认证状态，不影响其他 OAuth 凭证

你关联的 WhatsApp 号码是隐式信任的，跳过 dmPolicy 和 allowFrom 检查。

• groupPolicy：open | allowlist（默认） | disabled
• 激活模式：mention（默认，需 @提及）或 always（始终响应）
• 群组历史上下文自动注入最近未处理的消息（默认 50 条）
• 群组元数据缓存 5 分钟

在群组中发送 /activation always 或 /activation mention 切换（仅会话级别）。

默认情况下，Gateway 接受消息后自动标记为已读（蓝色勾号）。可按全局或账户级别禁用：

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
      accounts: {
        personal: { sendReadReceipts: false }
      }
    }
  }
}

自聊天模式始终跳过已读回执。

收到消息时自动发送表情回应，在机器人生成回复之前给用户即时反馈：

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions"  // always | mentions | never
      }
    }
  }
}

• 支持图片、视频、音频、文档的收发
• 音频以 PTT 语音消息发送（OGG/Opus 格式最佳）
• 图片超出大小限制时自动优化为 JPEG
• 动画 GIF：需以 MP4 格式发送并设置 gifPlayback: true
• 入站媒体上限 mediaMaxMb（默认 50 MB），出站上限 5 MB

一个 Gateway 可同时运行多个 WhatsApp 账户：

{
  channels: {
    whatsapp: {
      accounts: {
        personal: {
          dmPolicy: "allowlist",
          allowFrom: ["+8613800000000"]
        },
        work: {
          dmPolicy: "pairing",
          sendReadReceipts: false
        }
      }
    }
  }
}