介绍
# WhatsApp Ultimate
> **您的 WhatsApp AI 助手——不仅仅是聊天机器人，而是一个真实的存在。**
发送消息、语音笔记、投票、贴纸和反应。即时搜索数年的聊天记录。管理群组，转录语音消息，并精确控制谁可以与您的助手交谈以及何时交谈。原生 Baileys 集成——**零 Docker，零外部服务，零月费。**
这不是对 REST API 的封装。这是您的助手作为首要参与者存在于 WhatsApp 内部。
---
## 为什么我们要开发这个技能
我们发现的其他 WhatsApp 集成要么是：
- **一个 Webhook 中继**，只能发送文本，仅此而已 - **一个 Docker 容器**，需要您时刻照看 - **一个 Business API 封装**，需要 Meta 审批和独立的电话号码 - **一个 CLI 工具**，无法搜索历史记录或管理群组
我们构建了真正需要的东西：一个能够执行人类在 WhatsApp 上能做的*所有事情*的助手——从发送点赞反应到将 3 年的聊天记录提取到可搜索的数据库中。我们将其做得足够安全，可以与家人共享一个电话号码。
---
## 您将获得什么
### 24 种独特的操作
| 类别 | 您的助手能做什么 | |---|---| | **消息传递** | 文本、图片、视频、文档、语音笔记、GIF、投票、贴纸 | | **互动** | 使用任何表情符号反应、回复/引用、编辑已发送消息、撤回/删除 | | **群组** | 创建、重命名、设置图标/描述、添加/移除/晋升/降级成员、邀请链接 | | **历史记录** | 全文搜索 (SQLite + FTS5)、日期筛选、发送者筛选、批量导入 | | **语音** | 转录传入的语音笔记，发送金属质感的 TTS 回复 | | **安全性** | 3 规则群组门控、DM 前缀门控、按会话访问控制 |
### 与众不同之处
**🔒 严格的 3 规则群组门控** —— AI 助手在 WhatsApp 群组中的首要问题：它们对所有内容都有反应。有人分享照片？助手插嘴。家庭成员发送表情包？助手进行分析。我们通过三条规则解决了这个问题，在您的助手开口之前必须通过**所有**规则：
1. **这是允许的群组吗？** — 您将助手响应的群组聊天列入白名单。助手可以看到所有聊天（用于历史搜索、上下文和感知），但仅在批准的群组中触发响应。 2. **此人是否已授权？** — 即使在允许的群组中，也只有特定的电话号码可以触发助手。您表弟的随机消息？忽略。 3. **他们说了口令吗？** — 消息必须以您的触发前缀开头（例如 "Jarvis"）。没有前缀，就没有响应。照片、贴纸、表情包、转发链——全部静默忽略。
没有绕过，没有例外，没有“但是所有者发送了媒体所以放行”。您的助手保持沉默，直到在您批准的聊天中，由您信任的人通过名字明确地呼叫它。
**🤔↔🧐 思想心跳** —— WhatsApp 的关联设备 API 无法在群组中显示“正在输入...” ([Baileys #866](https://github.com/WhiskeySockets/Baileys/issues/866))。我们解决了这个问题：助手立即用 🤔 反应，每秒交替为 🧐，并在回复准备好时移除反应。您的用户始终知道助手正在工作。没有其他 WhatsApp 技能能做到这一点。
**🎤 语音优先设计** —— 语音笔记会在前缀检查*之前*被转录。在语音笔记中说“Jarvis，天气怎么样？”，它的效果与文本完全一样。转录内容会根据 `triggerPrefix` 进行检查，助手使用本地 TTS 以金属质感的语音回复。零云成本。搭配 [sherpa-onnx-tts](https://clawhub.com/skills/sherpa-onnx-tts) 技能可获得完整的 JARVIS 效果，或使用 [jarvis-voice](https://clawhub.com/skills/jarvis-voice) 获得现成的金属语音流水线。
**📚 可搜索的历史记录** —— 每条消息都存储在 SQLite 中，支持 FTS5 全文搜索。从 WhatsApp 导出中导入多年的旧聊天记录。询问您的助手*“上个月 Sarah 关于截止日期说了什么？”*并立即获得答案。结合 [agent-memory-ultimate](https://clawhub.com/skills/agent-memory-ultimate) 可获得跨越 WhatsApp、电子邮件、日历等的认知回忆。
**🔄 完整历史记录重新同步** —— 通过一次重新链接，将您的整个 WhatsApp 历史记录（3 年以上，17K+ 条消息）拉取到本地数据库中。无需手动导出。
---
## 快速开始
### 先决条件
- 配置了 WhatsApp 频道的 [OpenClaw](https://docs.openclaw.ai) - 通过二维码链接的 WhatsApp 账户 (`openclaw whatsapp login`)
### 最小配置
```json { "channels": { "whatsapp": { "dmPolicy": "allowlist", "allowFrom": ["+1234567890"], "triggerPrefix": "jarvis", "messagePrefix": "🤖", "responsePrefix": "🤖" } } } ```
就这样。您的助手现在仅响应您的消息，仅在您说“Jarvis”时响应，并且每条回复都标有 🤖，这样您始终知道是谁在说话。
---
## 消息传递
### 发送文本
``` message action=send channel=whatsapp to="+34612345678" message="Hello!" ```
### 发送媒体（图片/视频/文档）
``` message action=send channel=whatsapp to="+34612345678" message="Check this out" filePath=/path/to/image.jpg ```
支持：JPG、PNG、GIF、MP4、PDF、DOC 等。
### 发送投票
``` message action=poll channel=whatsapp to="+34612345678" pollQuestion="What time?" pollOption=["3pm", "4pm", "5pm"] ```
### 发送贴纸
``` message action=sticker channel=whatsapp to="+34612345678" filePath=/path/to/sticker.webp ```
必须是 WebP 格式，理想情况下为 512x512。
### 发送语音笔记
``` message action=send channel=whatsapp to="+34612345678" filePath=/path/to/audio.ogg asVoice=true ```
**关键：** 使用 OGG/Opus 格式。MP3 在 WhatsApp 上可能无法正确播放。
### 发送 GIF
``` message action=send channel=whatsapp to="+34612345678" filePath=/path/to/animation.mp4 gifPlayback=true ```
先将 GIF 转换为 MP4（WhatsApp 要求这样做）：
```bash ffmpeg -i input.gif -movflags faststart -pix_fmt yuv420p -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" output.mp4 -y ```
---
## 互动
### 反应
``` # Add reaction message action=react channel=whatsapp chatJid="[email protected]" messageId="ABC123" emoji="🚀"
# Remove reaction message action=react channel=whatsapp chatJid="[email protected]" messageId="ABC123" remove=true ```
### 回复/引用
``` message action=reply channel=whatsapp to="[email protected]" replyTo="QUOTED_MSG_ID" message="Replying to this!" ```
### 编辑和撤回
``` # Edit (own messages only) message action=edit channel=whatsapp chatJid="[email protected]" messageId="ABC123" message="Updated text"
# Unsend/delete message action=unsend channel=whatsapp chatJid="[email protected]" messageId="ABC123" ```
---
## 群组管理
完整的群组生命周期——创建、配置、管理成员和控制访问权限：
``` # Create group message action=group-create channel=whatsapp name="Project Team" participants=["+34612345678"]
# Rename / set icon / set description message action=renameGroup channel=whatsapp groupId="[email protected]" name="New Name" message action=setGroupIcon channel=whatsapp groupId="[email protected]" filePath=/path/to/icon.jpg message action=setGroupDescription channel=whatsapp groupJid="[email protected]" description="Team chat"
# Manage members message action=addParticipant channel=whatsapp groupId="[email protected]" participant="+34612345678" message action=removeParticipant channel=whatsapp groupId="[email protected]" participant="+34612345678" message action=promoteParticipant channel=whatsapp groupJid="[email protected]" participants=["+34612345678"] message action=demoteParticipant channel=whatsapp groupJid="[email protected]" participants=["+34612345678"]
# Invite links message action=getInviteCode channel=whatsapp groupJid="[email protected]" message action=revokeInviteCode channel=whatsapp groupJid="[email protected]"
# Group info message action=getGroupInfo channel=whatsapp groupJid="[email protected]"
# Leave group message action=leaveGroup channel=whatsapp groupId="[email protected]" ```
---
## 🔒 访问控制 (v2.0)
适用于任何 AI 助手的最精细的 WhatsApp 访问控制。因为您最不希望的就是您的助手用关于婚姻财产制的论文来回复您岳母的照片。
### 3 规则门控（群组）
每个群组消息必须通过**所有**三条规则：
| 规则 | 检查项 | 配置方式 | |---|---|---| | 1. 允许的聊天 | 此群组是否在白名单中？ | `groupPolicy` + `groupAllowFrom` 中的群组 JID | | 2. 授权的发送者 | 此人是否被允许与助手交谈？ | `groupAllowFrom` 中的电话号码 | | 3. 触发前缀 | 消息是否以“Jarvis”开头（或 @提及，或回复机器人）？ | `triggerPrefix` |
**没有绕过。** 除非发送者通过名字明确呼叫助手，否则照片、视频、贴纸、文档——全部静默忽略。所有者斜杠命令（`/new`、`/status`）无需前缀即可通过。
### DM 前缀门控
同样的 `triggerPrefix` 也适用于私信（DM）。没有前缀的消息将被静默丢弃。语音笔记会先被转录，然后再进行检查。
### 配置
```json { "channels": { "whatsapp": { "dmPolicy": "allowlist", "allowFrom": ["+34612345678", "+14155551234"], "groupPolicy": "allowlist", "groupAllowFrom": [ "+34612345678", "+14155551234", "[email protected]" ], "triggerPrefix": "jarvis", "messagePrefix": "🤖", "responsePrefix": "🤖" } } } ```
| DM 策略 | 行为 | |---|---| | `"open"` | 任何人都可以发送私信 | | `"allowlist"` | 仅 `allowFrom` 中的号码 | | `"pairing"` | 未知发送者会收到配对提示 | | `"disabled"` | 不接受私信 |
| 群组策略 | 行为 | |---|---| | `"open"` | 响应任何群组中的提及 | | `"allowlist"` | 仅来自 `groupAllowFrom` 中的发送者 | | `"disabled"` | 忽略所有群组消息 |
### 自聊天模式
```json { "channels": { "whatsapp": { "selfChatMode": true } } } ```
通过您的“Note to Self”（给自己留言）聊天与您的助手交谈。
---
## 🤔 思想心跳
**问题：** WhatsApp 关联设备无法在群组中显示“正在输入...”。这是 WhatsApp 服务器端的限制——已在 [Baileys #866](https://github.com/WhiskeySockets/Baileys/issues/866) 中确认。
**我们的解决方案：** 助手立即 (<100ms) 用 🤔 反应，每秒交替为 🧐，并在回复到达时移除反应。它还充当看门狗——如果反应冻结在一个表情符号上，说明有东西卡住了。
适用于群组 ✅ 和私信 ✅。
---
## 📚 消息历史记录与搜索
每条消息都存储在 SQLite 中，支持 FTS5 全文搜索。导入旧聊天记录。按关键字、发送者、日期或聊天进行搜索。
``` # Search by keyword whatsapp_history action=search query="meeting tomorrow"
# Filter by chat whatsapp_history action=search chat="Family Group" limit=50
# What did I say? whatsapp_history action=search fromMe=true query="I promised"
# Filter by sender whatsapp_history action=search sender="John" limit=20
# Date range whatsapp_history action=search since="2026-01-01" until="2026-02-01"
# Database stats whatsapp_history action=stats ```
### 导入历史聊天记录
1. 从手机导出：设置 → 聊天 → 导出聊天 → 不包含媒体 2. 导入：
``` whatsapp_history action=import path="/path/to/exports" whatsapp_history action=import path="/path/to/chat.txt" chatName="Family Group" ```
### 完整历史记录重新同步
通过一次重新链接拉取 3 年以上的历史记录：
```bash curl -X POST http://localhost:18789/api/whatsapp/resync ```
然后扫描二维码。测试中：**跨越 1,229 个聊天的 17,609 条消息，跨度 3 年以上。**
数据库：`~/.openclaw/data/whatsapp-history.db` (SQLite + WAL 模式)
---
## 🎤 语音流水线
### 传入的语音笔记
语音笔记会在前缀检查*之前*被转录：
``` Voice note → Download OGG → Transcribe (Whisper) → Check triggerPrefix → Process ```
说“Jarvis，我的日历上有什么？”——转录内容被检查，前缀匹配，助手响应。没有前缀？转录后静默丢弃。
### 传出的金属质感语音
使用本地 TTS 发送 JARVIS 风格的语音回复：
```bash # Generate metallic voice note jarvis-wa "Systems nominal, sir." /tmp/reply.ogg
# Send as WhatsApp voice note message action=send channel=whatsapp target="+1234567890" filePath=/tmp/reply.ogg asVoice=true ```
效果链：2 倍速 → +5% 音高 → 镶边效果 → 15ms 回声 → 200Hz 高通 → 高音 +6dB
需要 [sherpa-onnx-tts](https://clawhub.com/skills/sherpa-onnx-tts)。另请参阅 [jarvis-voice](https://clawhub.com/skills/jarvis-voice) 以获取完整的扬声器 + 网页聊天语音流水线。
---
## 🔄 离线恢复
网关掉线了？消息不会丢失。WhatsApp 会在重新连接时传递错过的消息，OpenClaw 会自动处理它们（6 小时恢复窗口）。恢复的消息会标记为 `[OFFLINE RECOVERY]`，以便您的助手可以批量审查，而不是盲目地对过期的请求采取行动。
---
## 下载与转录媒体
历史记录数据库存储完整的 WAMessage 原型，包括媒体加密密钥。下载任何语音消息、图片或文档：
| 媒体类型 | 原型字段 | 内容类型 | |---|---|---| | 语音/音频 | `audioMessage` | `"audio"` | | 图片 | `imageMessage` | `"image"` | | 视频 | `videoMessage` | `"video"` | | 文档 | `documentMessage` | `"document"` | | 贴纸 | `stickerMessage` | `"sticker"` |
媒体 URL 会过期——请在接收后尽快下载，或确保 WhatsApp 插槽已连接以重新获取。
---
## 搭配使用
构建完整的 AI 助手堆栈：
| 技能 | 功能 | |---|---| | [agent-memory-ultimate](https://clawhub.com/skills/agent-memory-ultimate) | 认知记忆——你的代理能跨会话记住 WhatsApp 对话 | | [sherpa-onnx-tts](https://clawhub.com/skills/sherpa-onnx-tts) | 本地文本转语音引擎，用于金属感语音回复 | | [jarvis-voice](https://clawhub.com/skills/jarvis-voice) | 完整的 JARVIS 语音管线——网页聊天扬声器 + WhatsApp 语音笔记 | | [openai-whisper](https://clawhub.com/skills/openai-whisper) | 本地语音转文本，用于语音笔记转录（无 API 费用） | | [agent-boundaries-ultimate](https://clawhub.com/skills/agent-boundaries-ultimate) | 具备消息访问权限的代理的安全框架 | | [shell-security-ultimate](https://clawhub.com/skills/shell-security-ultimate) | 在代理运行任何危险操作之前的命令分类 | | [gog](https://clawhub.com/skills/gog) | Google Workspace——你的代理读取 Gmail/日历并通过 WhatsApp 汇报 | | [outlook-hack](https://clawhub.com/skills/outlook-hack) | Outlook 邮件访问——起草回复、查看日历，全部通过 WhatsApp | | [ai-humor-ultimate](https://clawhub.com/skills/ai-humor-ultimate) | 12 种幽默模式——让你的代理的 WhatsApp 回复真正有趣 | | [youtube](https://clawhub.com/skills/youtube) | YouTube 转录——“Jarvis，总结这个视频”可在 WhatsApp 中使用 |
---
## 对比
| 功能 | whatsapp-ultimate | wacli | whatsapp-business | |---|---|---|---| | 原生集成 | ✅ 零依赖 | ❌ Go CLI 二进制文件 | ❌ 外部 API + 密钥 | | 动作 (Actions) | **24+** | ~6 | ~10 | | 投票 | ✅ | ❌ | ❌ | | 贴纸 | ✅ | ❌ | ❌ | | 语音笔记 | ✅ | ❌ | ❌ | | 反应 | ✅ | ❌ | ❌ | | 回复/引用/编辑/撤回 | ✅ | ❌ | ❌ | | 完整群组管理 | ✅ | ❌ | ❌ | | 思考指示器 | ✅ 🤔↔🧐 | ❌ | ❌ | | 3 规则群组门控 | ✅ | ❌ | ❌ | | 私信前缀门控 | ✅ | ❌ | ❌ | | 语音转录 → 前缀检查 | ✅ | ❌ | ❌ | | SQLite 历史记录 + FTS5 | ✅ | ✅ (同步) | ❌ | | 聊天导出导入 | ✅ | ❌ | ❌ | | 完整历史记录重同步 | ✅ | ❌ | ❌ | | 离线恢复 | ✅ | ❌ | ❌ | | 个人 WhatsApp | ✅ | ✅ | ❌ (仅限商业版) | | 每月费用 | **$0** | $0 | $$ (Meta 定价) |
---
## JID 参考
| 类型 | 格式 | 示例 | |---|---|---| | 个人 | `<number>@s.whatsapp.net` | `[email protected]` | | 群组 | `<id>@g.us` | `[email protected]` |
在使用 `to=` 时，OpenClaw 会自动将电话号码转换为 JID 格式。
---
## 故障排除
**来自联系人的消息无法到达代理** → 将其添加到 `allowFrom`（而不仅仅是 `groupAllowFrom`）。群组和私信访问权限是分开的。
**语音笔记无法播放** → 使用 OGG/Opus：`ffmpeg -i input.mp3 -c:a libopus -b:a 64k output.ogg`
**代理响应群组中的所有内容** → 设置 `triggerPrefix: "jarvis"` 并确保 `groupPolicy: "allowlist"`。
**群组中没有输入指示器** → 这是 WhatsApp 的限制。🤔 思考反应就是你的指示器。
---
## 架构
``` Your Agent → OpenClaw message tool → WhatsApp Channel Plugin → Baileys → WhatsApp Servers ```
无外部服务。无 Docker。无 CLI 工具。通过 [Baileys](https://github.com/WhiskeySockets/Baileys) 进行直接协议集成。
---
## 链接
- [OpenClaw](https://docs.openclaw.ai) — 代理框架 - [ClawHub](https://clawhub.com) — 技能市场 - [OpenClaw GitHub](https://github.com/openclaw/openclaw) — 源代码 - [Baileys](https://github.com/WhiskeySockets/Baileys) — WhatsApp Web 协议 - [OpenClaw Discord](https://discord.com/invite/clawd) — 社区
---
## 许可证
MIT — [OpenClaw](https://github.com/openclaw/openclaw) 的一部分
_由每天真正在 WhatsApp 上使用其 AI 代理的人员构建。_