← 返回目录

WhatsApp（网页渠道）

状态：仅支持通过 Baileys 的 WhatsApp Web。Gateway 网关拥有会话。

快速设置（新手）

  1. 如果可能，使用单独的手机号码（推荐）。
  2. 在 ~/.openclaw/openclaw.json 中配置 WhatsApp。
  3. 运行 openclaw channels login 扫描二维码（关联设备）。
  4. 启动 Gateway 网关。

最小配置：

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

目标

配置写入

默认情况下，WhatsApp 允许写入由 /config set|unset 触发的配置更新（需要 commands.config: true）。

禁用方式：

{
  channels: { whatsapp: { configWrites: false } },
}

架构（谁拥有什么）

获取手机号码（两种模式）

WhatsApp 需要真实手机号码进行验证。VoIP 和虚拟号码通常会被封锁。在 WhatsApp 上运行 OpenClaw 有两种支持的方式：

专用号码（推荐）

为 OpenClaw 使用单独的手机号码。最佳用户体验，清晰的路由，无自聊天怪异问题。理想设置：备用/旧 Android 手机 + eSIM。保持 Wi-Fi 和电源连接，通过二维码关联。

WhatsApp Business： 你可以在同一设备上使用不同号码的 WhatsApp Business。非常适合将个人 WhatsApp 分开——安装 WhatsApp Business 并在那里注册 OpenClaw 号码。

示例配置（专用号码，单用户允许列表）：

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

配对模式（可选）： 如果你想使用配对而不是允许列表，请将 channels.whatsapp.dmPolicy 设置为 pairing。未知发送者会收到配对码；使用以下命令批准： openclaw pairing approve whatsapp <code>

个人号码（备选方案）

快速备选方案：在你自己的号码上运行 OpenClaw。给自己发消息（WhatsApp"给自己发消息"）进行测试，这样就不会打扰联系人。在设置和实验期间需要在主手机上阅读验证码。必须启用自聊天模式。 当向导询问你的个人 WhatsApp 号码时，输入你将用于发送消息的手机（所有者/发送者），而不是助手号码。

示例配置（个人号码，自聊天）：

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

当设置了 identity.name 时，自聊天回复默认为 [{identity.name}]（否则为 [openclaw]）， 前提是 messages.responsePrefix 未设置。明确设置它可以自定义或禁用 前缀（使用 "" 来移除）。

号码获取提示

避免： TextNow、Google Voice、大多数"免费短信"服务——WhatsApp 会积极封锁这些。

提示： 该号码只需要接收一条验证短信。之后，WhatsApp Web 会话通过 creds.json 持久化。

为什么不用 Twilio？

登录 + 凭证

入站流程（私信 + 群组）

个人号码模式（备选方案）

如果你在个人 WhatsApp 号码上运行 OpenClaw，请启用 channels.whatsapp.selfChatMode（见上面的示例）。

行为：

已读回执

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

全局禁用：

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

按账户禁用：

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

注意事项：

WhatsApp 常见问题：发送消息 + 配对

当我关联 WhatsApp 时，OpenClaw 会给随机联系人发消息吗？ 不会。默认私信策略是配对，因此未知发送者只会收到配对码，他们的消息不会被处理。OpenClaw 只会回复它收到的聊天，或你明确触发的发送（智能体/CLI）。

WhatsApp 上的配对是如何工作的？ 配对是未知发送者的私信门控：

多个人可以在一个 WhatsApp 号码上使用不同的 OpenClaw 实例吗？ 可以，通过 bindings 将每个发送者路由到不同的智能体（peer kind: "dm"，发送者 E.164 如 +15551234567）。回复仍然来自同一个 WhatsApp 账户，直接聊天会折叠到每个智能体的主会话，因此每人使用一个智能体。私信访问控制（dmPolicy/allowFrom）是每个 WhatsApp 账户全局的。参见多智能体路由。

为什么向导会询问我的手机号码？ 向导使用它来设置你的允许列表/所有者，以便允许你自己的私信。它不会用于自动发送。如果你在个人 WhatsApp 号码上运行，请使用相同的号码并启用 channels.whatsapp.selfChatMode。

消息规范化（模型看到的内容）

群组

回复投递（线程）

确认表情（收到时自动回应）

WhatsApp 可以在收到传入消息时立即自动发送表情回应，在机器人生成回复之前。这为用户提供即时反馈，表明他们的消息已收到。

配置：

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

选项：

按账户覆盖：

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

行为说明：

智能体工具（表情回应）

限制

出站发送（文本 + 媒体）

语音消息（PTT 音频）

WhatsApp 将音频作为语音消息（PTT 气泡）发送。

媒体限制 + 优化

心跳

重连行为

配置快速映射

日志 + 故障排除

故障排除（快速）

未关联 / 需要二维码登录

已关联但断开连接 / 重连循环

Bun 运行时