WhatsApp

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

安装（按需）

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

openclaw plugins install @openclaw/whatsapp

​

快速设置

{
  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 的群组。
• 状态和广播聊天会被忽略（@status、@broadcast）。
• 重连看门狗跟随 WhatsApp Web 传输活动，而不只是入站应用消息量：在传输帧持续时，安静的已链接设备会话会保持在线，但传输停滞会在后续远程断开路径之前很早触发重连。
• 直接聊天使用 DM 会话规则（session.dmScope；默认 main 会将 DM 折叠到代理主会话）。
• 群组会话彼此隔离（agent:<agentId>:whatsapp:group:<jid>）。
• WhatsApp Channels/Newsletters 可以作为显式出站目标，并使用其原生 @newsletter JID。出站 newsletter 发送使用频道会话元数据（agent:<agentId>:whatsapp:channel:<jid>），而不是 DM 会话语义。
• WhatsApp Web 传输会在 gateway 主机上遵循标准代理环境变量（HTTPS_PROXY、HTTP_PROXY、NO_PROXY / 小写变体）。优先使用主机级代理配置，而不是频道特定的 WhatsApp 代理设置。
• 当启用 messages.removeAckAfterReply 时，OpenClaw 会在可见回复送达后清除 WhatsApp 的 ack 反应。

​

插件钩子与隐私

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

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

​

访问控制与激活

​

个人号码与自聊行为

• 跳过自聊轮次的已读回执
• 忽略原本会 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,
        },
      },
    },
  },
}

​

投递、分块与媒体

​

回复引用

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

​

反应级别

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

​

确认反应

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // 始终 | 提及 | 从不
      },
    },
  },
}

• 在入站被接受后立即发送（回复前）
• 失败会被记录，但不会阻止正常回复投递
• 组模式 mentions 会在提及触发的轮次上进行反应；组激活 always 作为此检查的绕过条件
• WhatsApp 使用 channels.whatsapp.ackReaction（此处不使用旧的 messages.ackReaction）

​

多账号与凭据

​

工具、动作与配置写入

• Agent 工具支持包括 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

​

系统提示词

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

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

• channels.whatsapp.groups 既是按群组的配置映射，也是聊天级群组白名单。无论是在根作用域还是账号作用域，groups["*"] 都表示该作用域内“允许所有群组”。
• 只有在你本来就希望该作用域接收所有群组时，才添加带通配符的群组 systemPrompt。如果你仍然只想让固定的一组群组 ID 有资格被处理，就不要把 groups["*"] 用作提示词默认值。相反，请在每个显式加入白名单的群组条目上重复该提示词。
• 群组接纳与发送者授权是两个独立的检查。groups["*"] 会扩大可进入群组处理的群组集合，但它本身并不会授权这些群组中的每个发送者。发送者访问仍由 channels.whatsapp.groupPolicy 和 channels.whatsapp.groupAllowFrom 单独控制。
• channels.whatsapp.direct 对 DM 没有同样的副作用。direct["*"] 只是在 DM 已通过 dmPolicy 加上 allowFrom 或配对存储规则被接纳之后，提供一个默认的私聊配置。

{
  channels: {
    whatsapp: {
      groups: {
        // 仅在你希望根作用域接纳所有群组时使用。
        // 适用于所有未定义自己 groups 映射的账号。
        "*": { systemPrompt: "所有群组的默认提示词。" },
      },
      direct: {
        // 适用于所有未定义自己 direct 映射的账号。
        "*": { systemPrompt: "所有私聊的默认提示词。" },
      },
      accounts: {
        work: {
          groups: {
            // 该账号定义了自己的 groups，因此根级 groups 会被完全
            // 替换。若要保留通配符，也请在此显式定义 "*"。
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "专注于项目管理。",
            },
            // 仅在你希望该账号接纳所有群组时使用。
            "*": { systemPrompt: "工作群组的默认提示词。" },
          },
          direct: {
            // 该账号定义了自己的 direct 映射，因此根级 direct 条目会被
            // 完全替换。若要保留通配符，也请在此显式定义 "*"。
            "+15551234567": { systemPrompt: "某个特定工作私聊的提示词。" },
            "*": { systemPrompt: "工作私聊的默认提示词。" },
          },
        },
      },
    },
  },
}

​

配置参考指针

• 配置参考 - WhatsApp

• access: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• delivery: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multi-account: accounts.<id>.enabled, accounts.<id>.authDir, account-level overrides
• operations: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• session behavior: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompts: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

​

相关内容

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