OpenClaw WhatsApp 集成完整指南

配对码在 1 小时 后过期，每个通道的待处理请求上限为 3 个。

白名单模式

只有 channels.whatsapp.allowFrom 中列出的电话号码才能发起聊天。

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

开放模式

需要 channels.whatsapp.allowFrom 包含 "*" 。

注意： 您链接的 WhatsApp 号码是隐式信任的 — 自消息会跳过 dmPolicy 和 allowFrom 检查。

已读回执

默认情况下，网关在接受入站 WhatsApp 消息后会将其标记为已读（蓝色对勾）。

全局禁用：

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

按账户禁用：

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

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

群聊支持

群组映射到专用会话。通过以下方式配置群组行为：

• 群组策略： channels.whatsapp.groupPolicy — open 、 disabled 或 allowlist （默认： allowlist ）
• 激活模式：
  • mention （默认）：需要 @提及 或正则匹配
  • always ：始终触发响应

通过仅限所有者的命令切换激活模式（必须作为独立消息发送）：

/activation mention
/activation always

所有者由 channels.whatsapp.allowFrom 确定（如未设置则为您的 E.164 号码）。

群聊历史上下文

最近未处理的消息（默认 50 条）会自动注入作为上下文：

[Chat messages since your last reply - for context]
...
[Current message - respond to this]

每条消息包含发送者后缀： [from: Name (+E164)] 。

群组元数据（主题 + 参与者）缓存 5 分钟。

确认回应

WhatsApp 可以在收到消息时自动发送 emoji 回应，在机器人生成回复之前提供即时反馈。

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

选项：

• emoji ：回应使用的 emoji（如 "👀"、"✅"）。为空或省略则禁用该功能。
• direct （默认： true ）：在 DM 聊天中发送回应。
• group （默认： "mentions" ）：
  • "always" ：对所有群组消息回应
  • "mentions" ：仅在机器人被 @提及 时回应
  • "never" ：从不在群组中回应

按账户覆盖：

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

回应在收到消息后立即发送，在输入指示器或机器人回复之前。失败会被记录但不会阻止机器人回复。

消息处理

入站消息

• 消息通过 Baileys messages.upsert 事件到达
• 状态/广播聊天被忽略
• 直接聊天使用 E.164 格式；群组使用 group JID
• 引用回复上下文始终附加以提供对话上下文
• 纯媒体消息使用占位符： <media:image|video|audio|document|sticker>

出站消息

• 文本默认分块为 4,000 字符 （可通过 channels.whatsapp.textChunkLimit 配置）
• 可选换行分块：设置 channels.whatsapp.chunkMode="newline" 在长度分块前按段落边界分割
• 支持的媒体类型：图片、视频、音频、文档
• 音频作为语音备忘录（PTT）发送。OGG/Opus 格式效果最佳
• 标题仅在第一个媒体项上
• 动态 GIF：WhatsApp 需要带 gifPlayback: true 的 MP4 才能内联循环播放

媒体限制

• 入站 媒体保存上限：50 MB（可通过 channels.whatsapp.mediaMaxMb 配置）
• 出站 媒体上限：每项 5 MB（可通过 agents.defaults.mediaMaxMb 配置）
• 图片在上限内自动优化为 JPEG（调整大小 + 质量扫描）
• 超大媒体会导致错误；媒体回复回退到文本警告

凭证与存储

• 凭证存储在： ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• 自动备份在 creds.json.bak （损坏时恢复）
• 登出： openclaw channels logout （或 --account <id> ）删除 WhatsApp 认证状态但保留共享的 oauth.json

多账户支持

多个 WhatsApp 账户可以在单个网关进程中运行。在配置中使用账户标识符：

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* 按账户设置 */ },
        work: { /* 按账户设置 */ },
      },
    },
  },
}

按账户设置支持覆盖 sendReadReceipts 、 ackReaction 、 mediaMaxMb 、 historyLimit 等。

为什么不用 Twilio / WhatsApp Business API？

早期 OpenClaw 构建支持 Twilio 的 WhatsApp Business 集成，但已被移除，原因是：

• WhatsApp Business 号码不适合个人助手
• Meta 强制执行 24 小时回复窗口 — 如果过去 24 小时内没有响应，商业号码无法发起新消息
• 高频或"聊天式"使用会触发积极封禁，因为商业账户不是为个人助手式消息设计的
• 结果：投递不可靠且频繁被封禁

配置速查参考

| 配置键 | 描述 | |---|---| | channels.whatsapp.dmPolicy | DM 策略： pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | 为个人号码设置启用 | | channels.whatsapp.allowFrom | DM 白名单（E.164 电话号码） | | channels.whatsapp.sendReadReceipts | 自动已读回执（默认：true） | | channels.whatsapp.ackReaction | 消息收到时自动回应 | | channels.whatsapp.groupPolicy | 群组策略： open / disabled / allowlist | | channels.whatsapp.textChunkLimit | 出站文本分块大小（默认：4000） | | channels.whatsapp.mediaMaxMb | 入站媒体上限（默认：50 MB） | | channels.whatsapp.configWrites | 允许通过 /config 命令写入配置 | | agents.defaults.mediaMaxMb | 出站媒体上限（默认：5 MB） |

故障排除

未链接 / 需要 QR 码登录

症状： channels status 显示 linked: false 或警告"Not linked"。

修复： 在网关主机上运行 openclaw channels login 并扫描 QR 码（WhatsApp > 设置 > 关联设备）。

已链接但断开连接 / 重连循环

症状： channels status 显示 running, disconnected 或警告"Linked but disconnected"。

修复： 运行 openclaw doctor 或重启网关。如果问题持续，通过 openclaw channels login 重新链接并检查 openclaw logs --follow 。

Bun 运行时问题

Bun 不建议使用 。WhatsApp（Baileys）和 Telegram 在 Bun 上不稳定。请使用 Node.js 运行网关。

重连行为

网关使用退避策略（ web.reconnect ），可配置 initialMs 、 maxMs 、 factor 、 jitter 和 maxAttempts 。如果达到最大尝试次数，Web 监控停止（降级模式）。已登出的 socket 停止并需要重新链接。

后续步骤

• Telegram 集成指南
• Discord 集成指南
• 官方 WhatsApp 文档