Skip to Content
👋 欢迎来到 HowToUseMoltbot 快速入门
频道WhatsApp

WhatsApp（Web 频道）

约 30 秒连接：moltbot channels login，扫 QR，完成。状态：仅支持经 Baileys 的 WhatsApp Web。网关持有会话。

快速设置（入门）

  1. 如可能请使用独立手机号（推荐）。
  2. 在 ~/.clawdbot/moltbot.json 中配置 WhatsApp。
  3. 运行 moltbot channels login 扫描二维码（已链接设备）。
  4. 启动网关。

最小配置：

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

目标

  • 单网关进程中支持多个 WhatsApp 账号（多账号）。
  • 确定性路由：回复回到 WhatsApp，不由模型选频道。
  • 模型能看到足够上下文以理解引用回复。

配置写入

默认允许 WhatsApp 写入由 /config set|unset 触发的配置更新（需 commands.config: true）。禁用方式：

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

架构（谁管什么）

  • 网关持有 Baileys 连接与收件循环。
  • CLI / macOS 应用与网关通信；不直接使用 Baileys。
  • 出站发送需活跃监听；否则发送会快速失败。

获取手机号（两种方式）

WhatsApp 需要真实手机号做验证。VoIP 和虚拟号通常会被拦截。Moltbot 在 WhatsApp 上支持两种运行方式：

专用号码（推荐）

为 Moltbot 使用独立手机号。体验最好、路由清晰、无自聊异常。理想做法：备用/旧 Android 机 + eSIM，连 Wi‑Fi 和电源，通过 QR 链接。WhatsApp Business： 可在同一设备用不同号码使用 WhatsApp Business，便于与个人 WhatsApp 分离——安装 WhatsApp Business 并用 Moltbot 号码注册。示例配置（专用号、单用户白名单）：

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

配对模式（可选）： 若希望用配对而非白名单，将 channels.whatsapp.dmPolicy 设为 pairing。未知发件人会收到配对码；批准：moltbot pairing approve whatsapp <code>。

个人号码（回退）

快速回退：在你自己的号码上运行 Moltbot。测试时给自己发消息（WhatsApp「给自己发消息」）以免打扰联系人。设置与调试时需在主手机上收验证码。必须启用自聊模式。 向导询问你的个人 WhatsApp 号码时，填的是你将用来发消息的手机号（机主/发件人），不是助理号码。示例配置（个人号、自聊）：

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

自聊回复默认前缀为 [{identity.name}]（若已设置），否则为 [moltbot]（当 messages.responsePrefix 未设置时）。可显式设置以自定义或关闭前缀（用 "" 去掉）。

号码获取建议

  • 本地 eSIM（本国运营商，最稳）：奥地利 hot.at 、英国 giffgaff （免 SIM、无合约）。
  • 预付费 SIM — 便宜，只需收一条验证短信。

避免： TextNow、Google Voice、多数「免费短信」服务——WhatsApp 会严格拦截。提示： 号码只需收一次验证短信，之后 WhatsApp Web 会话通过 creds.json 持久化。

为何不用 Twilio？

  • 早期 Moltbot 曾支持 Twilio WhatsApp Business 集成。
  • WhatsApp Business 号码不适合个人助理场景。
  • Meta 强制 24 小时回复窗口；若过去 24 小时未回复，商业号无法主动发新消息。
  • 高频或「话多」使用会触发严格封禁，因商业账号并非为大量个人助理消息设计。
  • 结果：投递不可靠、频繁封号，故已移除支持。

登录与凭据

  • 登录命令：moltbot channels login（通过已链接设备扫 QR）。
  • 多账号登录：moltbot channels login --account <id>（<id> = accountId）。
  • 默认账号（未指定 --account 时）：若存在则为 default，否则为配置中的第一个账号 ID（按排序）。
  • 凭据存储在 ~/.clawdbot/credentials/whatsapp/<accountId>/creds.json。
  • 备份文件 creds.json.bak（损坏时恢复）。
  • 旧版兼容：早期安装将 Baileys 文件直接放在 ~/.clawdbot/credentials/。
  • 登出：moltbot channels logout（或 --account <id>）会删除 WhatsApp 鉴权状态（但保留共享的 oauth.json）。
  • 已登出的连接会报错并提示重新链接。

入站流程（私信 + 群组）

  • WhatsApp 事件来自 messages.upsert（Baileys）。
  • 关闭时会分离收件监听器，避免测试/重启时事件处理函数堆积。
  • 状态/广播会话被忽略。
  • 私聊使用 E.164；群组使用 group JID。
  • 私信策略：channels.whatsapp.dmPolicy 控制私聊访问（默认 pairing）。
    • Pairing：未知发件人收到配对码（通过 moltbot pairing approve whatsapp <code> 批准；1 小时后过期）。
    • Open：需在 channels.whatsapp.allowFrom 中包含 "*"。
    • 你链接的 WhatsApp 号码默认受信任，故自己发的消息会跳过 channels.whatsapp.dmPolicy 和 channels.whatsapp.allowFrom 检查。

个人号码模式（回退）

若在个人 WhatsApp 号码上运行 Moltbot，请启用 channels.whatsapp.selfChatMode（见上示例）。行为：出站私信不会触发配对回复（避免骚扰联系人）；入站未知发件人仍遵循 channels.whatsapp.dmPolicy；自聊模式（allowFrom 包含你的号码）下不自动发已读回执并忽略提及 JID；非自聊私信会发已读回执。

已读回执

默认网关在接收 WhatsApp 消息后将其标为已读（蓝勾）。全局关闭：

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

按账号关闭：

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

说明：自聊模式始终不发已读回执。

WhatsApp 常见问题：发消息与配对

链接 WhatsApp 后 Moltbot 会随便给联系人发消息吗？ 不会。默认私信策略是 pairing，未知发件人只会收到配对码，消息不会被处理。Moltbot 只回复它收到的会话，或你通过 agent/CLI 显式触发的发送。WhatsApp 上配对怎么用？ 配对是面向未知发件人的私信门控：新发件人首次私信会收到短码（消息不处理）；批准：moltbot pairing approve whatsapp <code>（列表：moltbot pairing list whatsapp）；码 1 小时后过期；每频道待处理请求上限 3 个。一个 WhatsApp 号能让多人用不同的 Moltbot 吗？ 可以，通过 bindings 将不同发件人路由到不同 agent（peer kind: "dm"，发件人 E.164 如 +15551234567）。回复仍来自同一 WhatsApp 账号，私聊会合到各 agent 的主会话，因此请每人一个 agent。私信访问控制（dmPolicy/allowFrom）按 WhatsApp 账号全局生效。见 多 Agent 路由。向导为什么问我的手机号？ 向导用它设置你的白名单/机主，以便你自己的私信被允许。不用于自动发送。若在个人 WhatsApp 号上运行，填同一号码并启用 channels.whatsapp.selfChatMode。

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

  • Body 为当前消息正文及信封。
  • 引用回复上下文始终追加：
[Replying to +1555 id:ABC123]
<quoted text or <media:...>>
[/Replying]
  • 回复元数据也会设置：ReplyToId = stanzaId；ReplyToBody = 引用正文或媒体占位符；ReplyToSender = 已知时的 E.164。
  • 仅媒体的入站消息使用占位符：<media:image|video|audio|document|sticker>。

群组

  • 群组对应会话 agent:<agentId>:whatsapp:group:<jid>。
  • 群组策略：channels.whatsapp.groupPolicy = open|disabled|allowlist（默认 allowlist）。
  • 激活模式：mention（默认）需 @ 提及或正则匹配；always 始终触发。
  • /activation mention|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 Web 发送标准消息（当前网关不支持引用回复线程）。
  • 本频道忽略回复标签。

确认表态（收到即自动表态）

WhatsApp 可在收到消息后、机器人生成回复前自动发送表情表态，让用户立刻知道消息已收到。配置：

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

选项： emoji（字符串）：确认用表情（如 ”👀”、”✅”、”📨”）。空或省略则关闭该功能。direct（布尔，默认 true）：在私信中发送表态。group（字符串，默认 "mentions"）：群聊行为——"always" 对所有群消息表态（即使未 @）；"mentions" 仅在被 @ 时表态；"never" 群内从不表态。按账号覆盖： 在 channels.whatsapp.accounts.<id>.ackReaction 中配置。行为说明： 表态在收到消息后立即发送，早于打字指示或机器人回复；在 requireMention: false（activation: always）的群组中，group: "mentions" 仍会对所有消息表态；表态失败只记日志，不阻止回复；群组表态会自动包含参与者 JID；WhatsApp 不使用 messages.ackReaction，请用 channels.whatsapp.ackReaction。

Agent 工具（表态）

  • 工具：whatsapp，动作 react（chatJid、messageId、emoji，可选 remove）。
  • 可选参数：participant（群组发件人）、fromMe（对自己消息表态）、accountId（多账号）。
  • 表态移除语义见 表态。
  • 工具门控：channels.whatsapp.actions.reactions（默认启用）。

限制

  • 出站文本按 channels.whatsapp.textChunkLimit 分块（默认 4000）。
  • 可选按换行分块：设 channels.whatsapp.chunkMode="newline" 在按长度分块前按空行拆分。
  • 入站媒体保存受 channels.whatsapp.mediaMaxMb 限制（默认 50 MB）。
  • 出站媒体单条受 agents.defaults.mediaMaxMb 限制（默认 5 MB）。

出站发送（文本 + 媒体）

  • 使用活跃 web 监听；网关未运行时发送会报错。
  • 文本分块：每条最多 4k（可通过 channels.whatsapp.textChunkLimit、可选 channels.whatsapp.chunkMode 配置）。
  • 媒体：支持图片/视频/音频/文档；音频以 PTT 发送；audio/ogg => audio/ogg; codecs=opus；仅首条媒体带 caption；媒体获取支持 HTTP(S) 与本地路径；动图：WhatsApp 期望带 gifPlayback: true 的 MP4 以内联循环——CLI：moltbot message send --media <mp4> --gif-playback；网关：send 参数含 gifPlayback: true。

语音消息（PTT 音频）

WhatsApp 以语音消息（PTT 泡）发送音频。最佳格式：OGG/Opus。Moltbot 会将 audio/ogg 重写为 audio/ogg; codecs=opus。WhatsApp 忽略 [[audio_as_voice]]（音频本就以语音消息发送）。

媒体限制与优化

  • 出站默认单条上限 5 MB。
  • 覆盖：agents.defaults.mediaMaxMb。
  • 图片会在上限内自动优化为 JPEG（缩放 + 质量扫描）。
  • 超限媒体会报错；媒体回复回退为文本提示。

心跳

  • 网关心跳记录连接健康（web.heartbeatSeconds，默认 60 秒）。
  • Agent 心跳可按 agent 配置（agents.list[].heartbeat）或通过 agents.defaults.heartbeat 全局配置（无按 agent 配置时回退）。使用配置的心跳提示与 HEARTBEAT_OK 跳过行为；投递默认到上次使用的频道或配置的目标。

重连行为

  • 退避策略：web.reconnect（initialMs、maxMs、factor、jitter、maxAttempts）。
  • 达到 maxAttempts 后，web 监控停止（降级）。
  • 已登出 => 停止并需重新链接。

配置速查

  • channels.whatsapp.dmPolicy、selfChatMode、allowFrom、mediaMaxMb、ackReaction、accounts.<accountId>.*、groupAllowFrom、groupPolicy、historyLimit/dmHistoryLimit、groups、actions.reactions、messagePrefix 等；以及 agents.list[].groupChat.mentionPatterns、messages.groupChat.historyLimit、messages.responsePrefix、agents.defaults.mediaMaxMb、agents.defaults.heartbeat.*、session.*、web.enabled、web.heartbeatSeconds、web.reconnect.*。完整说明见 配置。

日志与故障排查

  • 子系统：whatsapp/inbound、whatsapp/outbound、web-heartbeat、web-reconnect。
  • 日志文件：/tmp/moltbot/moltbot-YYYY-MM-DD.log（可配置）。
  • 故障排查指南：网关故障排查。

故障排查（速查）

未链接 / 需 QR 登录

  • 现象：channels status 显示 linked: false 或提示「未链接」。
  • 处理：在网关主机运行 moltbot channels login 并扫描 QR（WhatsApp → 设置 → 已链接设备）。

已链接但断开 / 重连循环

  • 现象：channels status 显示 running, disconnected 或提示「已链接但断开」。
  • 处理：执行 moltbot doctor（或重启网关）。若持续，通过 channels login 重新链接并查看 moltbot logs --follow。

Bun 运行时

  • 不推荐使用 Bun。WhatsApp（Baileys）和 Telegram 在 Bun 上不稳定。请用 Node 运行网关。（见入门文档中的运行时说明。）
最后更新于:
TwitchZalo