跳转到内容
OpenClaw Docs

WhatsApp

WhatsApp (Web 渠道)

Section titled “WhatsApp (Web 渠道)”

状态：通过 WhatsApp Web (Baileys) 已可用于生产环境。Gateway(网关) 拥有已关联的会话。

按需安装

Section titled “按需安装”
  • 新手引导(openclaw onboard)和openclaw channels add --channel whatsapp 会在您首次选择时提示安装WhatsApp插件。
  • openclaw channels login --channel whatsapp也提供安装流程，当 插件尚未存在时。
  • Dev 渠道 + git checkout：默认使用本地插件路径。
  • 稳定版/测试版：默认使用npm包@openclaw/whatsapp。

手动安装仍然可用：

Terminal window
openclaw plugins install @openclaw/whatsapp
配对

针对未知发送者的默认私信策略为配对。

渠道故障排除

跨渠道诊断和修复手册。

Gateway配置

完整的渠道配置模式和示例。

快速设置

Section titled “快速设置”

  1. Configure WhatsApp access policy

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

  2. 链接WhatsApp (QR)

    Terminal window
    openclaw channels login --channel whatsapp
    对于特定账户：
    Terminal window
    openclaw channels login --channel whatsapp --account work

  3. 启动Gateway

    Terminal window
    openclaw gateway

  4. 批准首次配对请求（如果使用配对模式）

    Terminal window
    openclaw pairing list whatsapp
    openclaw pairing approve whatsapp
        配对请求将在1小时后过期。待处理的请求每个渠道上限为3个。

部署模式

Section titled “部署模式”
专用号码（推荐）

这是最干净的操作模式：

  • 为OpenClaw提供独立的WhatsApp身份
  • 更清晰的私信允许列表和路由边界
  • 降低自聊混淆的几率

最小策略模式：

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
个人号码回退

新手引导支持个人号码模式，并写入支持自聊的基线配置：

  • dmPolicy: "allowlist"
  • allowFrom 包含您的个人号码
  • selfChatMode: true

在运行时，自聊保护机制以关联的自身号码和 allowFrom 为基础。

仅 WhatsApp Web 渠道范围

在当前的 WhatsApp 渠道架构中，消息平台渠道是基于 WhatsApp Web 的（Baileys）。

在内置的聊天渠道注册表中，没有单独的 Twilio OpenClaw 消息渠道。

运行时模型

Section titled “运行时模型”
  • Gateway(网关) 拥有 WhatsApp 套接字和重连循环。
  • 出站发送需要目标帐户有活动的 WhatsApp 监听器。
  • 状态和广播聊天会被忽略（@status、@broadcast）。
  • 直接聊天使用私信会话规则（session.dmScope；默认 main 会将私信折叠到座席主会话中）。
  • 群组会话是隔离的（agent:<agentId>:whatsapp:group:<jid>）。

访问控制和激活

Section titled “访问控制和激活”

channels.whatsapp.dmPolicy 控制直接聊天访问权限：

  • pairing（默认）
  • allowlist
  • open（要求 allowFrom 包含 "*"）
  • disabled

allowFrom 接受 E.164 格式的号码（内部进行标准化）。

多账户覆盖：`channels.whatsapp.accounts.

.dmPolicy（和 allowFrom`）优先于该账户的渠道级默认值。

运行时行为详情：


- 配对关系持久化存储在渠道允许存储中，并与配置的 `allowFrom` 合并
- 如果未配置允许列表，关联的自身号码默认被允许
- 出站 `fromMe` 私信永远不会自动配对

个人号码和自聊行为

Section titled “个人号码和自聊行为”

当关联的自有号码也存在于 allowFrom 中时，WhatsApp 自聊天保护机制会激活：

  • 跳过自聊回合的已读回执
  • 忽略提及 JID 自动触发行为，否则这将会 @ 提醒你自己
  • 如果 messages.responsePrefix 未设置，自聊天回复默认为 [{identity.name}] 或 [openclaw]

消息规范化和上下文

Section titled “消息规范化和上下文”
入站信封 + 回复上下文

传入的 WhatsApp 消息被封装在共享的入站信封中。

如果存在引用回复，上下文将按此形式附加：

[Replying to

id:

]

[/Replying]

回复元数据字段在可用时也会被填充（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。
媒体占位符和位置/联系人提取

仅包含媒体的入站消息将使用如下占位符进行标准化：

  • `

-

-

-

-

`

位置和联系人负载会在路由前被标准化为文本上下文。
待处理群组历史注入

对于群组，未处理的消息可以被缓冲，并在机器人最终被触发时作为上下文注入。

  • 默认限制：50
  • 配置：channels.whatsapp.historyLimit
  • 回退：messages.groupChat.historyLimit
  • 0 禁用

注入标记：

  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]
已读回执

对于已接受的入站 WhatsApp 消息，默认启用已读回执。

全局禁用：

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

每个账户覆盖：

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

自聊回合会跳过已读回执，即使已全局启用。

发送、分块和媒体

Section titled “发送、分块和媒体”
文本分块
  • 默认分块限制：channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • newline 模式优先考虑段落边界（空行），然后回退到长度安全的分块
出站媒体行为
  • 支持图片、视频、音频（PTT 语音笔记）和文档有效载荷 - 为了兼容语音笔记，audio/ogg 会被重写为 audio/ogg; codecs=opus - 通过在视频发送时使用 gifPlayback: true 来支持动态 GIF 播放 - 发送多媒体回复有效载荷时，字幕将应用于第一个媒体项 - 媒体源可以是 HTTP(S)、file:// 或本地路径
媒体大小限制和回退行为
  • 入站媒体保存上限：channels.whatsapp.mediaMaxMb（默认为 50）
  • 出站媒体发送上限：channels.whatsapp.mediaMaxMb（默认为 50）
  • 每个帐户的覆盖设置使用 `channels.whatsapp.accounts.

.mediaMaxMb` - 图片会自动优化（调整大小/质量扫描）以符合限制 - 媒体发送失败时，第一项回退将发送文本警告，而不是静默放弃响应

反应级别

Section titled “反应级别”

channels.whatsapp.reactionLevel 控制代理在 WhatsApp 上使用表情符号反应的广泛程度：

级别确认反应代理发起的反应描述
"off"否否完全不使用反应
"ack"是否仅确认反应（回复前回执）
"minimal"是是（保守）确认 + 保守指导下的代理反应
"extensive"是是（鼓励）确认 + 鼓励指导下的代理反应

默认值："minimal"。

每个帐户的覆盖设置使用 channels.whatsapp.accounts.<id>.reactionLevel。

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

确认反应

Section titled “确认反应”

WhatsApp 支持通过 channels.whatsapp.ackReaction 对入站消息进行立即确认反应。 确认反应由 reactionLevel 控制——当 reactionLevel 为 "off" 时，它们将被抑制。

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

行为说明：

  • 在接收入站消息后立即发送（回复前）
  • 失败会被记录，但不会阻止正常回复的发送
  • 群组模式 mentions 对提及触发的轮次做出反应；群组激活 always 充当此检查的绕过机制
  • WhatsApp 使用 channels.whatsapp.ackReaction（此处不使用旧版 messages.ackReaction）

多账户和凭据

Section titled “多账户和凭据”
帐户选择和默认值
  • 帐户 ID 来自 channels.whatsapp.accounts
  • 默认帐户选择：如果存在 default 则选择它，否则选择第一个配置的帐户 ID（已排序）
  • 帐户 ID 在内部进行规范化以便查找
Credential paths and legacy compatibility
  • current auth path: `~/.openclaw/credentials/whatsapp/

/creds.json - backup file:creds.json.bak - legacy default auth in~/.openclaw/credentials/` is still recognized/migrated for default-account flows

Logout behavior

`openclaw channels logout —channel whatsapp [—account

]` 清除该帐户的 WhatsApp 身份验证状态。

在旧版身份验证目录中，`oauth.json` 会保留，同时删除 Baileys 身份验证文件。

工具、操作和配置写入

Section titled “工具、操作和配置写入”
  • Agent 工具 支持包括 WhatsApp 反应操作 (react)。
  • 操作门控：
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • 默认情况下已启用通道发起的配置写入（可通过 channels.whatsapp.configWrites=false 禁用）。

故障排除

Section titled “故障排除”
未链接（需要 QR 码）

症状：渠道状态报告未链接。

修复方法：

Terminal window
openclaw channels login --channel whatsapp
openclaw channels status
已链接但断开连接 / 重连循环

症状：已链接的帐户出现反复断开连接或尝试重新连接的情况。

修复方法：

Terminal window
openclaw doctor
openclaw logs --follow

如果需要，请使用 channels login 重新链接。

发送时无活动监听器

当目标帐户不存在活动的网关监听器时，出站发送会快速失败。

请确保网关正在运行且帐户已关联。

Group messages unexpectedly ignored

请按以下顺序检查：

  • groupPolicy
  • groupAllowFrom / allowFrom
  • groups allowlist 条目
  • 提及限制 (requireMention + 提及模式)
  • openclaw.json (JSON5) 中的重复键：后面的条目会覆盖前面的条目，因此请确保每个作用域内只有一个 groupPolicy
Bun 运行时警告

WhatsApp 网关运行时应使用 Node。Bun 被标记为与稳定的 WhatsApp/Telegram 网关操作不兼容。

配置参考指针

Section titled “配置参考指针”

主要参考：

高重要性 WhatsApp 字段：

  • access: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
  • delivery: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
  • 多账号：accounts.<id>.enabled，accounts.<id>.authDir，账号级覆盖
  • operations: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
  • 会话行为：session.dmScope，historyLimit，dmHistoryLimit，dms.<id>.historyLimit

相关

Section titled “相关”