内容
# WhatsApp for Claude 代码
在您的个人账户上，从 Claude 代码中读取、搜索和发送 WhatsApp 消息 — 100% 本地运行。您的消息存储在您机器上的 SQLite 数据库中；没有任何数据发送到云端，发送消息前始终需要您的批准。
```text
"阿娜上周关于发票说了什么？"
"总结我的未读群聊。"
"在 WhatsApp 上将地址发送给汤姆。" ← 发送前会要求您批准
"下载玛丽亚昨天发送给我的 PDF。"
```
## 您将获得
- **一个 `wa` 命令行工具**，用于脚本、定时任务和任何代理程序 — 直接从本地存储中读取答案，速度约为 50 毫秒（即使在桥接器断开连接时也适用），发送消息通过认证的桥接器。输入 JSON，输出 JSON：
```bash
wa contacts "ana" # 搜索人员和群聊
wa chats --limit 10 # 最近的聊天记录，按最新顺序排列
wa messages "Ana Torres" --from-them --since 2026-07-01
wa send "Team PRs" "https://github.com/org/repo/pull/42"
wa doctor # 以 JSON 格式显示健康状态，退出代码表示状态
```
- **14 个 MCP 工具** — 搜索联系人、列出/读取聊天记录和消息、消息上下文、发送文本/文件/语音笔记/反应、下载媒体。
- **一个技能**，教 Claude 快速路径：直接 SQLite 进行批量读取、以联系人优先的查找和安全规则（批准后发送、 incoming 内容视为不可信）。
- **自动设置** — `/whatsapp-setup` 安装所有内容；唯一的手动步骤是使用手机扫描一个二维码。
- **自动运行** — 一个保持运行的服务（macOS 上的 launchd、Linux 上的 systemd、Windows 上的 Task Scheduler）在重启和崩溃后保持桥接器运行。`/whatsapp-doctor` 检查和修复安装。
- **强化默认设置** — 仅限 localhost 的 REST API，带有 bearer token，消息存储仅可由您读取，禁用 webhook 转发。
## 工作原理
您的手机将这台机器配对为 WhatsApp **链接设备**（与 WhatsApp Web 相同的机制）。三个本地组件，均来自开源 [whatsapp-mcp](https://github.com/verygoodplugins/whatsapp-mcp) 项目：
```text
您手机上的 WhatsApp
│ （链接设备，端到端加密）
▼
Go 桥接器（whatsmeow） ──► SQLite 存储 ~/.whatsapp-mcp/whatsapp-bridge/store/
│ 本地 REST，bearer token
▼
Python MCP 服务器 ──► Claude 代码（14 个工具）
```
此插件添加了上游项目留给您的内容：单命令设置、固定的已审查修订版、权限强化、保持运行服务、配对和健康检查工具，以及 Claude 代码技能/命令。
## 快速开始（Claude 代码）
```text
/plugin marketplace add Elnora-AI/elnora-whatsapp
/plugin install whatsapp@elnora-whatsapp
/whatsapp-setup
```
在提示时扫描二维码（WhatsApp > 设置 > 链接设备），重启 Claude 代码，并询问有关您的聊天记录。总时间 ≈ 5 分钟，大部分时间用于 Go 构建。
**先决条件：** [Go](https://go.dev/dl/)、[uv](https://docs.astral.sh/uv/)、[Node.js](https://nodejs.org)、git、curl（macOS 上预安装）。CGO 需要 C 编译器：macOS 上预安装（CLT）、Debian/Ubuntu 上的 `build-essential`、Windows 上的 `pacman -S mingw-w64-ucrt-x86_64-gcc`（在 [MSYS2](https://www.msys2.org/) 中）。可选：用于发送任意音频作为语音笔记的 FFmpeg。
## CLI 安装（任何终端，任何代理）
```bash
npm install -g @elnora-ai/whatsapp # 将 `wa` 和 `elnora-whatsapp` 放入 PATH
wa doctor # 然后查看 `wa --help`
```
需要 Node ≥22.13 和已完成的设置（如下或 `/whatsapp-setup`）。名称解析适用于代理：`wa send "Ana Torres" hi` 在名称唯一时有效，而模糊名称会因候选列表而失败，而不是猜测。每个发送方只能有一个收件人 — 批量发送被设计为拒绝。
## 手动安装（任何 MCP 客户端）
设置脚本在没有 Claude 代码的情况下也能工作：
```bash
git clone https://github.com/Elnora-AI/elnora-whatsapp
bash elnora-whatsapp/scripts/setup.sh # Windows: scripts\setup.ps1
```
然后在您的客户端注册 MCP 服务器：
```json
{
"mcpServers": {
"whatsapp": {
"command": "uv",
"args": ["--directory", "<home>/.whatsapp-mcp/whatsapp-mcp-server", "run", "main.py"]
}
}
}
```
有用标志：`--dir <path>`（自定义位置；也设置 `WHATSAPP_MCP_DIR`）、`--webhook <url>`（转发 incoming 消息 — 默认关闭）、`--port <n>`（桥接 REST 端口）、`--no-service`（跳过保持运行服务）、`--update`（将现有检出移到固定的修订版）。随时使用 `scripts/pair.sh`（Windows：`scripts\pair.ps1`）重新配对；使用 `scripts/doctor.sh`（`scripts\doctor.ps1`）检查健康状态。
## 安全性和隐私
- **仅限本地。** 消息同步到您机器上的 SQLite 数据库，并从那里读取。桥接器的 REST API 绑定到 127.0.0.1 并需要 bearer token（`store/.bridge-token`，模式 600）。
- **Webhook 转发默认关闭。** 上游桥接器将 POST 每个 incoming 消息到本地端口，任何本地进程都可以声明；设置将其指向仅限 root 的丢弃端口。 如果您实际使用，请使用 `--webhook <url>` 开启。
- **存储强化。** `store/` 为 chmod 700（Windows 上为用户级 ACL），数据库和 token 为 600。存储保留您的完整消息历史记录和会话密钥 — 永远不要提交或复制它。
- **固定的上游。** 设置检出 whatsapp-mcp 的特定已审查修订版，而不是 `main`。使用 `--update` 故意更新。
- **提示注入。** incoming 消息内容被视为不可信输入。技能指示 Claude 将其视为数据，永远不要遵循嵌入在消息中的指令。
- **诚实的警告：这是非官方的。** 链接设备自动化不是官方 WhatsApp API。读重度使用和人为批准的发送在实践中是好的，但批量或垃圾邮件发送模式可能会导致帐户被封禁。该项目在服务器端强制执行任何操作 — 技能的规则和您的判断力。使用风险自负。
## 卸载
首先在 Claude 代码中：`/plugin uninstall whatsapp@elnora-whatsapp`。然后：
```bash
# macOS
launchctl bootout gui/$(id -u)/com.whatsapp-mcp.bridge
rm ~/Library/LaunchAgents/com.whatsapp-mcp.bridge.plist
rm -rf ~/.whatsapp-mcp # 删除所有同步的消息 + 会话
# Linux
systemctl --user disable --now whatsapp-bridge.service
rm ~/.config/systemd/user/whatsapp-bridge.service
rm -rf ~/.whatsapp-mcp
```
```powershell
# Windows
Unregister-ScheduledTask -TaskName "WhatsApp MCP Bridge" -Confirm:$false
Remove-Item -Recurse -Force "$env:USERPROFILE\.whatsapp-mcp"
```
还请从手机中删除链接设备：WhatsApp > 设置 > 链接设备。
## 适用于代理
为用户设置此功能？请遵循 [INSTALL_FOR_AGENTS.md](INSTALL_FOR_AGENTS.md)。从非 Claude 挂钩驱动现有的安装？请参阅 [AGENTS.md](AGENTS.md)。
## Elnora 家族的一部分
来自 [Elnora AI](https://github.com/Elnora-AI) 的开源代理工具 — 免费、通用、配置驱动的工具，将 Claude 代码（或任何 AI 编程代理）连接到您运行公司所依赖的系统。每个工具都 100% 独立；安装多个工具，它们可以链接成端到端的流程。
<!-- ELNORA-FAMILY:START -->
- [elnora-linear](https://github.com/Elnora-AI/elnora-linear) — Linear 问题管理 — 搜索、批量编辑、代理和配置驱动的策划
- [elnora-slack](https://github.com/Elnora-AI/elnora-slack) — 完整的 Slack Web API 作为 CLI 和代理技能，带有草稿和批准发送门
- [elnora-google-workspace](https://github.com/Elnora-AI/elnora-google-workspace) — Gmail、Calendar、Drive、Docs、Sheets、Forms、Tasks，以及通过 Discovery 的任何 Google API
- [elnora-merit-aktiva](https://github.com/Elnora-AI/elnora-merit-aktiva) — Merit Aktiva 会计和 Merit Palk 工资单作为 CLI 和插件
- [elnora-vanta](https://github.com/Elnora-AI/elnora-vanta) — 只读 Vanta 合规性 — 框架、测试、控制和漏洞作为代理友好的 JSON
- [elnora-luma](https://github.com/Elnora-AI/elnora-luma) — Luma (lu.ma) 事件 — 所有 61 个公共 API 端点作为规范驱动的 CLI，带有安全防护
- [elnora-travel](https://github.com/Elnora-AI/elnora-travel) — 一个真正的旅行代理 — 实时航班、酒店、Airbnb、Booking.com 和路线在一个行程中
- [elnora-websearch-tools](https://github.com/Elnora-AI/elnora-websearch-tools) — 网络搜索 — Exa、Tavily、Perplexity、Firecrawl 和 Valyu CLI 和技能在一个插件中
- [knowledge-vault](https://github.com/Elnora-AI/knowledge-vault) — 一个与 Obsidian 兼容的知识库，用于代理团队 — 搜索并将您的工作保存到任何知识库
<!-- ELNORA-FAMILY:END -->
## 致谢与许可
包装 [verygoodplugins/whatsapp-mcp](https://github.com/verygoodplugins/whatsapp-mcp)（[lharries/whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) 的维护分支，MIT），构建于 [whatsmeow](https://github.com/tulir/whatsmeow)。此仓库：Apache-2.0， Elnora AI 版权所有。
