wazap

╭───────────────╮
│        ▄██▀   │   ██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
│      ▄██▀     │   ██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
│    ▄███████▀  │   ██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
│       ▄██▀    │   ██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
│     ▄█▀       │   ╚███╔███╔╝██║  ██║███████╗██║  ██║██║
╰─╮╭────────────╯    ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝
  ╰╯                WhatsApp for your AI agent.

wazap 是一个用于你自己的 WhatsApp 账号的 MCP 服务。它像 WhatsApp Web 一样将账号作为设备关联起来，将看到的内容保存在你的设备上，并为任何 MCP 客户端——Claude、ChatGPT、Gemini、Cursor、Codex——提供 23 个工具，用于处理你的聊天、消息、媒体、联系人和群组。

你不必再打开 WhatsApp 查找信息，而是可以直接询问：

• “我今天在 WhatsApp 上错过了什么？”——汇总所有已关联账号的信息：谁在等你回复、提及、未接来电，以及经过精简的活跃群组动态。
• “找到 Dan 春天发来的发票。”——同时按含义和关键词搜索，然后打开文件。
• “妈妈发来的语音消息说了什么？”——语音消息会转换成文本。
• “告诉 Ana 我会晚到二十分钟。”——你会先看到收件人和确切内容。只有你确认后才会发送。

无需浏览器、商业账号或第三方服务。wazap 没有云服务：它运行在你使用它的设备上。

开始使用

你需要在 22 系列中使用 Node.js 22.16+，或 Node.js 24+，以及一部安装了 WhatsApp 的手机。

npx wazap-mcp setup

setup 会关联你的账号，查找这台设备上已安装的 MCP 客户端（Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI），写入它们的配置，在客户端读取技能的位置安装五个技能，并告诉你需要重启哪些程序。然后向助手询问：“我今天在 WhatsApp 上错过了什么？”

想让 Agent 帮你设置？把下面这句话发给它：

帮我设置 WhatsApp：运行 npx wazap-mcp setup --agent 并按照输出操作。

在终端中单独运行 npx wazap-mcp 不会启动任何程序：它会显示当前状态和下一条命令。遇到问题时，首先运行 npx wazap-mcp status；它会在每个故障项目旁边显示修复方法。

各客户端的设置方式

客户端	最快的方式
Claude Code	/plugin marketplace add razvangirgiz/wazap，然后运行 /plugin install wazap@wazap
Claude Desktop	从 Releases 下载 wazap-<version>.mcpb，然后双击
Cursor	点击下方徽章，然后运行 npx wazap-mcp skills install cursor
Codex CLI	运行 npx wazap-mcp connect codex，然后运行 npx wazap-mcp skills install codex
Gemini CLI	运行 npx wazap-mcp connect gemini
claude.ai、ChatGPT 和其他托管 Agent	使用 OAuth 登录的 URL：参见远程访问
其他客户端	命令：npx -y wazap-mcp，传输方式：stdio

对于支持常见 JSON 配置的客户端，手动配置项如下：

{
  "mcpServers": {
    "whatsapp": { "command": "npx", "args": ["-y", "wazap-mcp"] }
  }
}

setup 执行的每个步骤、connect 写入的每个文件以及升级说明，都在 docs/install.md 中。

关联你的账号

关联账号只需执行一次。setup 会替你完成；如果单独操作，步骤如下：

npx wazap-mcp login                      # QR code: Settings → Linked devices → Link a device
npx wazap-mcp login --phone +15550100    # pairing code instead, no camera needed

使用 --phone 时，wazap 会显示一个 8 位字符的代码。在手机上依次前往 WhatsApp → 设置 → 已关联的设备 → 关联设备 → 改用电话号码关联，然后输入代码。配对码可通过 SSH 使用，也适用于不方便扫描二维码的无头服务端。

助手也可以自行关联账号：link_account 工具会返回相同的代码，因此 Claude Desktop 用户无需使用终端。

一个 wazap 中可以使用多个 WhatsApp 账号（运行 wazap account add <id>，然后运行 wazap login --account <id>）；参见 docs/accounts.md。

23 个工具

每个参数和错误代码的含义都在 docs/tools.md 中。助手通过调用 learn 获取全部内容。

工具	类型	功能
learn	读取	每个工具、ID 格式、工作流和错误代码的指南。请先调用。
get_status	读取	连接、同步、已关联的账号、历史记录的新旧程度、Webhook 投递情况和版本。
link_account	读取	从助手关联账号；返回一个 8 个字符的代码，需在手机上输入。
list_chats	读取	按最新时间优先列出对话：all、unread、groups、individual 或 archived。
read_messages	读取	查看一个聊天，并向前翻阅手机上的历史记录；chat_id: "status" 用于查看动态。
catch_up	读取	一次调用即可查看所有账号中的“我错过了什么？”，并控制在 Token 预算内。
search	读取	同时按含义和关键词搜索消息，并按聊天、发件人或日期缩小范围。
get_message	读取	查看完整消息：引用内容、回应及回应者、投票、投递和已读回执。
find_contact	读取	在起草任何内容前，确认“妈妈”、昵称、群组名称或号码对应的人。
list_contacts	读取	分页查看手机通讯录：已保存的姓名、号码、上次交谈时间。
get_group_info	读取	查看参与者、管理员、群组设置，以及供管理员使用的邀请链接。
get_media	读取	语音消息以转录文本形式呈现，照片以图片形式呈现，任意文件保存到磁盘；优先从消息到达时保存的副本中提供。
wait_for_messages	读取	最长阻塞 55 秒，直到收到消息；使用游标确保两次调用之间不会漏掉消息。
remember	本地	在此设备上保存关于某人的备注、标签或详细信息。不会更改 WhatsApp 上的任何内容。
send_message	写入	起草消息、媒体、投票、位置或转发内容——但不发送任何内容。send_at 用于起草稍后发送的消息。
confirm_send	写入	用户查看预览并确认后，仅发送一次该草稿；稍后发送的草稿会被安排发送。
edit_message	写入	在 WhatsApp 的 15 分钟时限内编辑自己发送的消息。
react_to_message	写入	添加或移除表情回应。
delete_message	写入	为所有人删除（自己的消息，或在自己管理的群组中删除任何人的消息），或仅从此账号删除。
manage_chat	写入	预览归档、置顶、静音、加星标、清空、删除、屏蔽和撤销操作；确认预览后仅应用一次。mark_read 仍可直接执行。
manage_group	写入	创建、加入、重命名、添加、移除、提升为管理员、管理邀请链接和加入请求、设置，以及退出。
scheduled_messages	写入	列出已安排的消息（包括已发送、错过和失败的消息），或在发送前取消一条。
reminder	本地	设置、列出或取消“如果 Ana 2 天内没回复就提醒我”等提醒；到期时会发送到你的 Webhook。

安排消息和提醒。 使用 send_at 调用 send_message（例如将“明天 9 点”设为 Europe/Bucharest 时区下的 2026-10-12T09:00），即可起草稍后发送的消息； 用户确认预览（包括时间）后，消息便会被安排发送；每次发送检查都会在实际发送时重新执行。若某条 wazap 消息在预定时间的 15 分钟内仍无法发送，则会报告为错过，绝不会延迟发送。reminder 会保存“如果 Ana 2 天内没回复就提醒我”这类提醒，并在到期时发送到你的 Webhook。两者在重启后都会保留；请参阅安排消息 和提醒。

有两项功能默认关闭，可完全在你的设备上运行： 语音转录，使用 whisper.cpp (docs/voice.md)；以及 语义回忆，让 search 能匹配含义，而不只是关键词 (docs/recall.md)。使用 wazap config transcribe local 和 wazap config recall local 启用这些功能。

技能

工具说明可以做什么；skills/ 中的五项 Agent Skills 则说明如何把工作做好。

技能	Agent 的操作
whatsapp-inbox	分流：需要你处理／仅供参考／无关信息，以及你忘记回复的消息。只读。
whatsapp-recall	查找地址、发票、照片或别人说过的话。只读。
whatsapp-groups	跟进活跃群组：决策、日期以及对你的要求。只读。
whatsapp-send	找到你指的人，按聊天本身的语气起草消息，展示给你，并在你确认后发送。
wazap-setup	诊断、关联或修复连接。

setup 会为 Claude Code、Codex 和 Cursor 安装这些技能 （也可以手动运行 npx wazap-mcp skills install <harness>）。其他所有客户端 都能从 MCP 服务获取相同的五个 MCP 提示词，无需安装任何内容。

传输方式

stdio 是默认方式：客户端启动 npx -y wazap-mcp，并通过 stdin/stdout 与其通信。网络上不会有任何端口监听。

HTTP（Streamable HTTP）适用于生命周期长于客户端的服务，或 可由另一台机器访问的服务：

npx wazap-mcp serve --http                 # http://127.0.0.1:8766/mcp, health at /healthz

使用 --host/--port（或 WAZAP_HOST/WAZAP_PORT）可更改监听地址和端口。wazap 拒绝绑定 除环回地址以外的任何地址，除非设置了 WAZAP_READ_TOKEN。客户端可使用 静态 bearer 令牌（WAZAP_READ_TOKEN，写入工具还需要 WAZAP_WRITE_TOKEN）进行身份验证， 也可以使用 OAuth 2.1，wazap 会自行提供 OAuth 服务。详情请参阅 docs/self-host.md。

远程访问

运行以下两个命令，即可让 wazap 持续运行并可供托管 Agent 访问：

npx wazap-mcp service install   # a launchd agent (macOS) or systemd user unit (Linux)
npx wazap-mcp expose            # a public https URL through Tailscale Funnel or Cloudflare Tunnel

expose 会输出 URL 和同意密码。只需将 URL 提供给 Agent； 它会自行注册，同意页面会要求你输入密码，并选择该 Agent 是否只能读取或也可以发送消息。请参阅 保持运行。

服务会自动恢复：连接断开后会通过退避重试；看门狗会替换因休眠而失效或停止响应的套接字； 如果重连持续失败，wazap 会退出，以便 launchd 或 systemd 重新启动它。 无论发生上述哪种情况，已关联的会话都不会被删除；只有 WhatsApp 取消关联设备时才需要重新关联。将 WAZAP_WEBHOOK_EVENTS 设置为包含 alert，即可在连接中断 5 分钟、恢复连接以及需要重新关联时收到通知（连接提醒）； get_status 会在 link 下显示相同信息。

部署

在自己的服务器上，会话不会离开服务器。使用 Docker（提供适用于 amd64 和 arm64 的镜像，地址为 ghcr.io/razvangirgiz/wazap）：

mkdir wazap && cd wazap
curl -fsSLO https://raw.githubusercontent.com/razvangirgiz/wazap/main/docker-compose.yml
printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env
docker compose run --rm wazap login --phone +15550100   # once; the session lands in the volume
docker compose up -d
curl -s http://127.0.0.1:8766/healthz

容器只在环回地址上发布端口 8766；请在前面配置 TLS （deploy/Caddyfile 只有两行）。deploy/wazap.service 中提供了 systemd 单元。 两种部署方式、反向代理信任设置和 OAuth 服务均见 docs/self-host.md。 如何在自己的产品中调用 wazap，以及如何接收已签名的传入消息 Webhook，请参阅 docs/api-and-webhooks.md。

配置

所有设置都是可选的。它们是环境变量，可从进程环境或 ~/.wazap/.env 中读取（真实环境变量优先，命令行标志的优先级高于两者）。你很少需要手动编辑它们：wazap config 会显示生效的设置，并可修改其中一项。

设置	默认值	作用
WAZAP_DATA_DIR	~/.wazap	凭据、数据库和模型的存放位置（也可使用 --data-dir）。
WAZAP_READ_ONLY	未设置	1 表示完全不注册写入工具。wazap config writes on|off。
WAZAP_PERSIST_HISTORY	1	0 表示重启后不在磁盘上保留消息。
WAZAP_HOST / WAZAP_PORT	127.0.0.1 / 8766	serve --http 的监听地址。
WAZAP_READ_TOKEN / WAZAP_WRITE_TOKEN	未设置	用于 HTTP 的静态 Bearer 令牌；只有写入令牌会启用写入工具。
WAZAP_PUBLIC_URL / WAZAP_OAUTH_PASSWORD	未设置	同时设置这两项会为托管 Agent 启用 OAuth。wazap expose 会设置它们。
WAZAP_TRANSCRIBE	off	local（whisper.cpp）或 openai（兼容 OpenAI 的 API）。
WAZAP_RECALL	off	local 会使用本地嵌入模型启用语义搜索。
WAZAP_WEBHOOK	off	on 会将收到的消息发送到 WAZAP_WEBHOOK_URL，并使用 WAZAP_WEBHOOK_SECRET 签名。
WAZAP_MEDIA_KEEP	unmuted	收到媒体时会下载并保留哪些聊天中的媒体，这样即使 WhatsApp 上的副本失效，get_media 仍可使用：unmuted、all、chats 或 off。限制项：WAZAP_MEDIA_KEEP_MAX_MB、WAZAP_MEDIA_KEEP_QUOTA_MB、WAZAP_MEDIA_KEEP_DAYS。

完整列表（包括 webhook 筛选条件、媒体保留限制、保留期限和代理信任设置）见 docs/settings.md；.env.example 是 同一列表的注释版文件。

安全与隐私

• 未经确认，不会发送任何内容。 send_message 只会创建草稿：它会返回收件人和确切文本，不会触及网络。只有 confirm_send 才会发送，而且一份草稿最多发送一次，即使发生崩溃也不例外。先创建草稿再确认是一种工作流，并不能证明已获得同意：除非你的客户端要求你批准第二个工具，否则 Agent 可以调用这两个工具。
• 只读是真正的开关。 设置 WAZAP_READ_ONLY=1、使用 --read-only 或运行 wazap config writes off 后，写入工具不会注册，因此助手即使误操作也无法给任何人发消息。Claude Desktop 配套版本默认勾选只读。
• 可以固定收件人。 wazap config send allow +15550100,… 会将账户限制为指定列表；deny 会拒绝指定对象；两者都会在创建草稿时和发送前分别检查 (docs/send-rules.md)。
• 写入操作有速率限制，默认每个账户每分钟 20 次，因为发送速度快过真人正是号码被封禁的原因。
• 你的数据留在自己的设备上。 凭据、消息、媒体和笔记都保存在 ~/.wazap（权限为 0700，凭据文件为 0600）。无需账户，也没有遥测。离开设备的数据包括：WhatsApp 流量；用于版本检查的 npm 注册表；下载转录或嵌入模型时访问的 Hugging Face；仅当你选择 openai 时访问的转录 API；以及你设置的 webhook（如有） (docs/data.md)。
• 可以屏蔽某些人。 为联系人添加 #private 标签后，他们的内容不会出现在助手未按姓名明确询问的任何内容中，也不会发送到 webhook。#no-catchup 会让他们的聊天不出现在 catch_up 中。
• 它不会做什么。 不支持批量发送、定时发送或营销活动。它不会自行将任何内容标记为已读；发送文本时也不会生成链接预览，因此不会抓取你分享的链接页面。

威胁模型、发现的问题以及上述各项的限制： docs/security-audit.md。

已知限制

• 该协议并非官方协议。 wazap 基于 Baileys 构建；Baileys 是对 WhatsApp 多设备协议进行逆向工程后实现的版本。它不是 WhatsApp Business API，Meta 也不提供支持。协议变更可能导致 wazap 无法使用，直到 Baileys 跟进为止；大量发送消息或向未主动请求的人发送消息的账号可能会受到限制或被封禁。上述防护措施可以降低风险，但无法消除风险，后果由你自行承担。
• 模型行为仅在 Claude 上进行了评估。 eval/ 中的评估（58 个用例，每个运行三次）是在 Claude 上进行的。其他客户端获得相同的工具和服务端防护措施，但尚无人评估它们的模型如何使用这些工具。ChatGPT 的手动协议见 eval/chatgpt-protocol.md。
• 历史记录仅包含手机同步到关联设备的内容，并非你的全部存档。使用 before 参数调用 read_messages 会向手机请求更多消息，但仅限 WhatsApp 仍保留的内容。
• 旧媒体会过期。 WhatsApp 会从其服务器删除旧附件；此时 get_media 会返回 MEDIA_UNAVAILABLE，除非 wazap 在附件到达时保存了副本。默认情况下，只要 wazap serve 正在运行，它就会保留未静音聊天中的照片、语音消息、音频和文档；每个文件最多 16 MB，总计最多 1 GB，保留 90 天。如果媒体到达后，在无人保留的期间过期，就无法恢复。
• 姓名来自手机通讯录，WhatsApp 只会在新连接时发送通讯录。如果联系人显示为号码（get_status 中的 contacts_named: 0），可在服务器未运行时执行 wazap contacts resync 再次请求。
• @lid ID。 较新的账号使用隐私 ID 寻址；如果 wazap 已获知对应关系，就会将其映射回号码。
• 仅支持 WhatsApp 通话，如果通话在 wazap 停止运行期间开始并结束，可能不会显示。蜂窝电话通话始终不可见。
• 手机必须保持可连接状态。 手机离线时间过长后，关联设备会停止接收消息；get_status 会说明这一情况。

1.x 系列承诺保持稳定的内容见 docs/stability.md。

文档

docs/install.md	setup 的逐步说明、各客户端、后台服务、expose、升级、技能
docs/tools.md	23 种工具的完整介绍、工作流及所有错误代码
docs/accounts.md	多个 WhatsApp 账号、单个服务器上的多个 MCP 客户端
docs/voice.md	将语音消息转换为文本：本地使用 whisper.cpp，或使用兼容 OpenAI 的 API
docs/recall.md	使用本地嵌入模型进行语义搜索
docs/data.md	数据目录、wazap backup、保留期限、已删除和阅后即焚消息
docs/send-rules.md	只读模式、各账号的发送规则、速率限制
docs/self-host.md	HTTP 模式、systemd、Docker、隧道、代理信任、OAuth
docs/api-and-webhooks.md	静态令牌接入、签名 Webhook 事件发出
docs/settings.md	所有 WAZAP_* 设置及其默认值
docs/security-audit.md	安全审计
docs/stability.md	1.0 承诺保持稳定的内容
CHANGELOG.md	各版本发布记录

参与贡献

git clone https://github.com/razvangirgiz/wazap && cd wazap
npm ci
npm run check                  # lint, typecheck, then build and test
node test/smoke-stdio.mjs      # drives the built binary over MCP stdio
npm run dev -- status          # run from source with tsx

测试无需 WhatsApp 账号。CLAUDE.md 是贡献者指南，介绍项目结构、绝不能破坏的规则以及发布流程。欢迎在 github.com/razvangirgiz/wazap 提交问题和拉取请求。

许可证

MIT © Răzvan Girgiz