WhatsApp

Status: 可通过 WhatsApp Web（Baileys）投入生产使用。Gateway 网关拥有已关联会话。

# 安装（按需）

• 新手引导（openclaw onboard）和 openclaw channels add --channel whatsapp 会在你第一次选择 WhatsApp 插件时提示安装它。
• 当插件尚未存在时，openclaw channels login --channel whatsapp 也会提供安装流程。
• Dev 渠道 + git checkout：默认使用本地插件路径。
• Stable/Beta：在当前官方发布标签上使用 npm 包 @openclaw/whatsapp。

仍可手动安装：

openclaw plugins install @openclaw/whatsapp

使用裸包名会跟随当前官方发布标签。只有在需要可复现安装时，才固定精确版本。

在 Windows 上，WhatsApp 插件在 npm install 期间需要 PATH 中有 Git，因为它的一个 Baileys/libsignal 依赖是从 git URL 获取的。安装 Git for Windows，然后重启 shell 并重新运行安装：

winget install --id Git.Git -e

如果 Portable Git 的 bin 目录在 PATH 中，也可以使用。

# 快速设置

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# 部署模式

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

# 运行时模型

• Gateway 网关拥有 WhatsApp socket 和重连循环。
• 重连看门狗使用 WhatsApp Web 传输活动，而不只是入站应用消息量，因此安静的已关联设备会话不会仅仅因为最近没人发送消息而被重启。如果传输帧持续到达，但在看门狗窗口内没有处理任何应用消息，更长的应用静默上限仍会强制重连；对于最近活跃会话的临时重连，在第一个恢复窗口内，该应用静默检查会使用正常消息超时。
• Baileys socket 时序在 web.whatsapp.* 下显式配置：keepAliveIntervalMs 控制 WhatsApp Web 应用 ping，connectTimeoutMs 控制打开握手超时，defaultQueryTimeoutMs 控制 Baileys 查询超时。
• 出站发送要求目标账号有活跃的 WhatsApp 监听器。
• 当文本和媒体标题中的 @+<digits> 与 @<digits> 令牌匹配当前 WhatsApp 参与者元数据（包括 LID 支持的群组）时，群组发送会附加原生 mention 元数据。
• Status 和广播聊天会被忽略（@status、@broadcast）。
• 重连看门狗遵循 WhatsApp Web 传输活动，而不只是入站应用消息量：只要传输帧持续，安静的已关联设备会话就会保持在线，但传输停滞会在后续远端断开路径之前强制重连。
• 直接聊天使用私信会话规则（session.dmScope；默认 main 会将私信折叠到智能体主会话）。
• 群组会话相互隔离（agent:<agentId>:whatsapp:group:<jid>）。
• WhatsApp Channels/Newsletters 可以用其原生 @newsletter JID 作为显式出站目标。出站 newsletter 发送使用渠道会话元数据（agent:<agentId>:whatsapp:channel:<jid>），而不是私信会话语义。
• WhatsApp Web 传输会遵循 Gateway 网关主机上的标准代理环境变量（HTTPS_PROXY、HTTP_PROXY、NO_PROXY / 小写变体）。优先使用主机级代理配置，而不是 WhatsApp 渠道专用代理设置。
• 启用 messages.removeAckAfterReply 时，OpenClaw 会在可见回复送达后清除 WhatsApp ack 反应。

# 插件钩子和隐私

WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标识符、发送者姓名和会话关联字段。因此，除非你显式选择加入，否则 WhatsApp 不会向插件广播入站 message_received 钩子载荷：

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

你可以将选择加入限定到一个账号：

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

仅对你信任其接收 WhatsApp 入站消息内容和标识符的插件启用此功能。

# 访问控制和激活

# 个人号码和自聊行为

当已关联的自身号码也存在于 allowFrom 中时，WhatsApp 自聊保护会激活：

• 跳过自聊轮次的已读回执
• 忽略否则会 ping 你自己的 mention-JID 自动触发行为
• 如果未设置 messages.responsePrefix，自聊回复默认使用 [{identity.name}] 或 [openclaw]

# 消息规范化和上下文

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

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

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

# 送达、分块和媒体

# 回复引用

WhatsApp 支持原生回复引用，出站回复会明显引用入站消息。使用 channels.whatsapp.replyToMode 控制它。

默认值是 "off"。按账号覆盖使用 channels.whatsapp.accounts.<id>.replyToMode。

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

# 反应级别

channels.whatsapp.reactionLevel 控制智能体在 WhatsApp 上使用表情反应的范围：

默认值："minimal"。

按账号覆盖使用 channels.whatsapp.accounts.<id>.reactionLevel。

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

# 确认反应

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）

# 多账号和凭证

# 工具、操作和配置写入

• 智能体工具支持包括 WhatsApp 反应操作（react）。
• 操作门控：
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• 默认启用渠道发起的配置写入（通过 channels.whatsapp.configWrites=false 禁用）。

# 故障排除

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# 系统提示

WhatsApp 通过 groups 和 direct 映射支持适用于群组和直接聊天的 Telegram 风格系统提示。

群组消息的解析层级：

首先确定有效的 groups 映射：如果账号定义了自己的 groups，它会完全替换根 groups 映射（不进行深度合并）。然后在生成的单一映射上执行提示查找：

1. 群组专用系统提示（groups["<groupId>"].systemPrompt）：当映射中存在特定群组条目且定义了其 systemPrompt 键时使用。如果 systemPrompt 为空字符串（""），则会抑制通配符，并且不应用系统提示。
2. 群组通配符系统提示（groups["*"].systemPrompt）：当特定群组条目完全不存在于映射中，或存在但未定义 systemPrompt 键时使用。

直接消息的解析层级：

首先确定有效的 direct 映射：如果账号定义了自己的 direct，它会完全替换根 direct 映射（不进行深度合并）。然后在生成的单一映射上执行提示查找：

1. Direct 专属系统提示词（direct["<peerId>"].systemPrompt）：当映射中存在特定对等方条目且其 systemPrompt 键已定义时使用。如果 systemPrompt 是空字符串（""），则会抑制通配符，并且不会应用系统提示词。
2. Direct 通配符系统提示词（direct["*"].systemPrompt）：当映射中完全不存在特定对等方条目，或条目存在但未定义 systemPrompt 键时使用。

**与 Telegram 多账号行为的区别：**在 Telegram 中，多账号设置会有意抑制根级 groups 对所有账号的继承，即使某些账号没有定义自己的 groups，也是如此，以防止机器人接收它不属于的群组中的群组消息。WhatsApp 不应用此防护：对于没有定义账号级覆盖的账号，无论配置了多少个账号，根级 groups 和根级 direct 都始终会被继承。在多账号 WhatsApp 设置中，如果你想要按账号设置群组或 direct 提示词，请在每个账号下显式定义完整映射，而不是依赖根级默认值。

重要行为：

• channels.whatsapp.groups 既是按群组配置映射，也是聊天级群组允许列表。在根级或账号作用域中，groups["*"] 表示该作用域“允许所有群组”。
• 只有在你已经希望该作用域允许所有群组时，才添加通配符群组 systemPrompt。如果你仍然只希望一组固定的群组 ID 符合条件，请不要使用 groups["*"] 作为提示词默认值。改为在每个显式允许列表中的群组条目上重复该提示词。
• 群组准入和发送者授权是两个独立检查。groups["*"] 会扩大可进入群组处理的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍由 channels.whatsapp.groupPolicy 和 channels.whatsapp.groupAllowFrom 单独控制。
• channels.whatsapp.direct 对私信没有相同的副作用。direct["*"] 只会在私信已通过 dmPolicy 加 allowFrom 或配对存储规则准入后，提供默认 direct 聊天配置。

示例：

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "[email protected]": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

# 配置参考指针

主要参考：

• 配置参考 - WhatsApp

高信号 WhatsApp 字段：

• 访问：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups
• 投递：textChunkLimit、chunkMode、mediaMaxMb、sendReadReceipts、ackReaction、reactionLevel
• 多账号：accounts.<id>.enabled、accounts.<id>.authDir、账号级覆盖
• 运维：configWrites、debounceMs、web.enabled、web.heartbeatSeconds、web.reconnect.*、web.whatsapp.*
• 会话行为：session.dmScope、historyLimit、dmHistoryLimit、dms.<id>.historyLimit
• 提示词：groups.<id>.systemPrompt、groups["*"].systemPrompt、direct.<id>.systemPrompt、direct["*"].systemPrompt

# 相关内容

• 配对
• 群组
• 安全性
• 渠道路由
• 多智能体路由
• 故障排除