WhatsApp（Web 频道）

状态：通过 WhatsApp Web（Baileys）生产就绪。网关拥有链接的会话。

默认 DM 策略为对未知发件人进行配对。 跨频道诊断和修复手册。 完整频道配置模式和示例。

快速设置

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}
 
openclaw channels login --channel whatsapp
对于特定账户：
openclaw channels login --channel whatsapp --account work
 
openclaw gateway
 
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
配对请求在 1 小时后过期。每个频道的待处理请求上限为 3 个。
 OpenClaw 建议在可能的情况下在单独号码上运行 WhatsApp。（频道元数据和入职流程针对该设置进行了优化，但也支持个人号码设置。）

部署模式

这是最清晰的操作模式： 
- OpenClaw 的独立 WhatsApp 身份
- 更清晰的 DM 白名单和路由边界
- 减少自聊混淆的可能性

最小策略模式：

```json5
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
```
 入职支持个人号码模式并写入自聊友好的基线： 
- `dmPolicy: "allowlist"`
- `allowFrom` 包含您的个人号码
- `selfChatMode: true`

在运行时，自聊保护链接自号码和 `allowFrom` 的密钥。
 当前 OpenClaw 频道架构中的消息平台频道是基于 WhatsApp Web 的（`Baileys`）。 
内置聊天频道注册表中没有单独的 Twilio WhatsApp 消息频道。

运行时模型

  • 网关拥有 WhatsApp 套接字和重连循环。
  • 出站发送需要目标账户的活动 WhatsApp 监听器。
  • 状态和广播聊天被忽略（@status、@broadcast）。
  • 直接聊天使用 DM 会话规则（session.dmScope；默认 main 将 DM 折叠到代理主会话）。
  • 群组会话是独立的（agent:<agentId>:whatsapp:group:<jid>）。

访问控制和激活

`channels.whatsapp.dmPolicy` 控制直接聊天访问： 
- `pairing`（默认）
- `allowlist`
- `open`（需要 `allowFrom` 包含 `"*"`）
- `disabled`

`allowFrom` 接受 E.164 格式号码（内部规范化）。

多账户覆盖：`channels.whatsapp.accounts.<id>.dmPolicy`（和 `allowFrom`）优先于该账户的频道级默认设置。

运行时行为详情：

- 配对持久化在频道允许存储中，并与配置的 `allowFrom` 合并
- 如果未配置白名单，则默认允许链接的自号码
- 出站 `fromMe` DM 从不自动配对
 群组访问有两层： 
1. **群组成员白名单**（`channels.whatsapp.groups`）
   - 如果省略 `groups`，所有群组都符合条件
   - 如果存在 `groups`，它充当群组白名单（允许 `"*"`）

2. **群组发件人策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`）
   - `open`：发件人白名单绕过
   - `allowlist`：发件人必须匹配 `groupAllowFrom`（或 `*`）
   - `disabled`：阻止所有群组入站

发件人白名单回退：

- 如果未设置 `groupAllowFrom`，运行时回退到可用的 `allowFrom`
- 发件人白名单在提及/回复激活之前评估

注意：如果根本不存在 `channels.whatsapp` 块，即使设置了 `channels.defaults.groupPolicy`，运行时群组策略回退也是 `allowlist`（带警告日志）。
 默认情况下，群组回复需要提及。 
提及检测包括：

- 明确提及机器人身份
- 配置的提及正则表达式模式（`agents.list[].groupChat.mentionPatterns`，回退 `messages.groupChat.mentionPatterns`）
- 隐式回复机器人检测（回复发件人匹配机器人身份）

安全说明：

- 引用/回复仅满足提及门控；它**不会**授予发件人授权
- 对于 `groupPolicy: "allowlist"`，非白名单发件人即使回复白名单用户的消息仍会被阻止

会话级激活命令：

- `/activation mention`
- `/activation always`

`activation` 更新会话状态（不是全局配置）。它是所有者控制的。

消息处理

消息通过 Baileys WebSocket 发送。速率限制： 
- 单个消息：~15000 字符
- 媒体消息：直接发送，Baileys 处理上传
- 链接预览：WhatsApp 不支持自定义链接预览

失败处理：

- 发送失败时，错误会返回给代理
- 代理可以决定重试或报告错误
 已读回执配置： 
- `channels.whatsapp.readReceipts`：启用/禁用已读回执
- 默认：启用

注意：WhatsApp Web 不总是可靠地发送已读回执。
 WhatsApp 反应支持： 
- 代理可以发送反应（emoji）
- 反应显示在消息下方
- 频道配置：`channels.whatsapp.reactions`

故障排除

常见问题

无法连接 WhatsApp

  • 确保手机已连接互联网
  • 重新扫描二维码
  • 检查防火墙设置

消息未发送

  • 检查账户是否仍链接
  • 验证目标用户不在黑名单中
  • 检查速率限制

收不到消息

  • 检查 dmPolicy 设置
  • 确保发件人在白名单中（如果使用 allowlist）
  • 检查群组策略设置

命令

# 检查 WhatsApp 状态
openclaw channels status whatsapp

# 查看配对请求
openclaw pairing list whatsapp

# 重新链接 WhatsApp
openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp

# 查看消息日志
openclaw logs --channel whatsapp

配置示例

最小配置

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
    },
  },
}

白名单模式

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

群组配置

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: {
        allow: ["[email protected]"],
      },
    },
  },
}

多账户

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

安全性

  • 始终使用强 hooks.token 保护 webhook 端点
  • 定期审查允许列表
  • 使用 dmPolicy: "pairing" 限制未知发件人
  • 监控配对请求

相关链接