WireCat WhatsApp

wa — 面向 AI Agent 的 WhatsApp CLI

在终端中使用你的个人 WhatsApp，在电脑上搜索，并可供 Claude Code、 Codex、Cursor 或任何 Agent 使用——范围由你设定。

文档 · 示例 · WireCat

一段对话示例（人物为虚构，输出仅供说明）：

You:    Use wa CLI. Who is waiting for my answer since yesterday?
Agent:  (runs wa personal review 'date>1d' --unanswered: 3 chats)
        · Alice Example asked about Saturday's table, 18:40 yesterday
        · "Book club" — Bob Sample asked who brings the next book
You:    Tell Alice: yes, 8 pm.
Agent:  Draft to Alice Example: "Yes, 8 pm." Send it?
You:    Yes.

⚠️ wa 是你真实 WhatsApp 账号的非官方客户端。 WhatsApp 的条款禁止使用非官方客户端， 使用此类客户端的账号可能会被封禁。批量发送消息或给不认识你的人发消息也会导致账号被封禁。 wa 只会在命令要求时发送消息，默认每小时最多发送 30 条；当 WhatsApp 要求减速或限制账号时， 它会暂停所有发送操作。请勿批量发送，也不要给陌生人发消息。使用 wa 的风险由你自行承担。更多信息：使用限制

早期版本。 wa 刚推出，其部分功能尚未经过真实 WhatsApp 环境验证。 待办清单列出了仍需进行的检查。

更多信息：与其他工具的比较 · wirecat.dev 上的说明

快速开始

npm install -g @wirecat/whatsapp-cli
wa personal setup --agent claude       # also codex, cursor, gemini, all or none
wa personal server install             # keep receiving in the background
wa personal inbox                      # other people's unread messages; nothing is marked read

预留约 5 分钟。wa personal setup 会将 wa 作为一台设备关联到你的账号——你需要在 WhatsApp → 设置 → 已关联的设备中扫描二维码——随后保存手机在关联后立即发送的历史记录，检查你最先看到的聊天，并安装 Agent 技能。

它需要在 macOS、Linux 或 Windows 上运行 Node 22.16+ 或 24+。npm 还会为你的系统单独安装引擎，即用于通信 WhatsApp 协议的小型程序。

更多信息：安装指南 · 关联设备

可以做什么？

快速了解近况。 “使用 wa CLI。今天早上以来有什么新消息？谁还在等我回复？”

wa personal inbox
wa personal review 'date>1d' --unanswered

查找任何内容。 “使用 wa CLI。我们什么时候和 Alice 确定了场地？”——答案会附上日期和相关消息。

wa personal search all "venue"            # messages and notes kept on this computer

信守承诺。 “使用 wa CLI。我答应了什么？还有什么事在等我处理？”

wa personal review --new                  # what changed since the last review --new
wa personal tasks list state:open

管理群组。 “使用 wa CLI。Hiking 群里哪些问题还没人回答？”

wa personal review chat:Hiking --unanswered
wa personal chats events Hiking 'time>=7d'   # who joined, left, was added or removed

由你决定是否回复。

wa personal messages send "Book club" "Call at 3?" --reply-to 3EB0A1B2C3D4E5F6A7B8
wa personal messages edit "Book club" 3EB0A1B2C3D4E5F6A7B8 "Call at 4?"   # your own, within 20 minutes
wa personal reactions add "Book club" 3EB0A1B2C3D4E5F6A7B8 👍
wa personal messages delete "Book club" 3EB0A1B2C3D4E5F6A7B8 --for-everyone
wa personal chats mark-read "Book club"   # the other side sees it

更多信息：使用场景，每个场景都附有计划安排 · 使用 wa

专为 AI Agent 打造

你的 Agent。你的 WhatsApp。你的规则。

• 配备终端的 Agent（Claude Code、Codex、Gemini CLI）可自行运行 wa 命令。随附的 技能会告诉它们如何操作：运行 wa personal setup --agent … 或 wa skill install 即可完成设置，运行 wa skill show 则会在链接前打印技能内容。Agent 通过二维码链接：它会将代码作为文本粘贴到聊天中，供你扫描，并且绝不会向你索要电话号码或验证码。
• 不带终端的应用（Claude Desktop、Cursor 和其他 MCP 客户端）连接到 wa personal mcp serve。它内置了可直接使用的提示词：/catch-up、/review、/reply、/find 等。

wa personal mcp add claude-code   # or: wa personal mcp add codex
wa personal mcp config              # the entry for Claude Desktop, Cursor and others

该配置文件默认允许发送消息，因此 mcp add 会先停止。检查配置文件的权限，然后添加 --allow-writes 再次运行。

更多信息：MCP 服务 · 通过浏览器使用

为什么选择 wa？

• 使用你自己的账号，作为已关联设备。 wa 像 WhatsApp Web 一样建立关联。它可以查看你的聊天、群组和联系人，并以你的身份发言，而不是使用企业账号或机器人账号。
• 如果你有 WhatsApp Business 号码，也可以使用。 wa <profile> bot 可通过 Meta 的 Cloud API 代表 WhatsApp Business 号码发言：发送消息、使用模板，以及通过你的隧道接收 webhook 消息（机器人）。
• 本地优先搜索。 所有收到的内容都保存在你的电脑上。每次读取和搜索都在本地完成，不会连接外部服务。
• 专为 Agent 打造。 每次调用只执行一项操作；使用 --json 时，输出的 JSON 结构始终一致；每种失败都有固定的退出码；并提供 MCP 服务和技能。
• 默认安全。 读取内容不会将其标记为已读，也不会发送“在线”或“正在输入”状态。配置文件会决定 Agent 可以执行哪些操作、可以向哪些聊天发送消息，以及每小时最多发送多少条消息（默认 30 条）。发送结果未知时，wa 会明确告知，绝不会自行重发。

你的账户

wa 以你的名义运行，是与你的 WhatsApp 账户关联的另一台设备。

wa personal chats list --limit 5
wa personal messages list "Book club" --limit 20
wa personal messages send "Book club" "The minutes" --file minutes.pdf
wa personal polls create "Book club" "Which day?" Monday Tuesday
wa personal messages download "Book club" 3EB0A1B2C3D4E5F6A7B8 --output-dir ~/Downloads
wa personal messages transcribe "Book club" 3EB0A1B2C3D4E5F6A7B8 --local  # a voice note as text

消息 ID 3EB0A1B2C3D4E5F6A7B8 是虚构的；请从 messages list -v 中取一个真实的 ID。

• 读取。 从本地存储中读取聊天和消息、读取一条消息及其前后消息、读取其他人的未读消息（wa personal inbox）、读取上次查看以来的所有内容（wa personal review）、接收新消息（wa personal watch）、向手机请求同步某个聊天的较早消息（wa personal messages sync），以及查看你关注的频道帖子（使用频道链接执行 wa personal chats join，然后执行 messages sync）。
• 发送。 发送 Markdown、回复、每条消息附带一个文件、照片、视频或语音消息、将一张照片和一段视频作为一个相册发送、在 20 分钟内编辑自己的消息、转发、添加回应、创建投票并投票、置顶（每次都会通知成员）、为自己或所有人删除消息，以及将聊天标记为已读。
• 你的聊天列表。 在自己的设备上将聊天静音、归档、置顶或标记为未读，为消息加星标，以及删除或清空聊天；聊天中的其他人不会收到通知。
• 在电脑上使用语音。 WhatsApp 没有自带语音识别功能，因此 wa 会在这台机器上运行语音模型，并且仅在你请求时下载。
• 联系人。 查看联系人的个人资料、屏蔽联系人、查询号码是否使用 WhatsApp、将手机通讯录导入存储，以及记录联系人的自定义名称和备注。
• 你的账户。 更新自己的姓名、简介和个人资料照片（wa personal account update）。
• 隐私。 设置谁可以看到你的最后上线时间、在线状态、个人资料照片和简介，是否发送已读回执，谁可以将你添加到群组，以及哪些人的来电会响铃（wa personal account privacy）。

目前尚不支持在一条消息中发送超过一张照片和一段视频的多个文件： wa 尚不支持。

更多内容：使用 wa · 隐私 · 单聊

登录和配置文件

wa 会像 WhatsApp Web 一样，将你的账户关联为一台设备。无需密码，也无需注册应用：只需通过手机关联一次，设备密钥就会保存到一个只有你的用户才能读取的文件中。

wa personal session start               # a QR code: WhatsApp → Settings → Linked devices → Link a device
wa personal session start phone         # or your number, then a pairing code you type on the phone
wa personal account show                # who this profile is linked as
wa account list                         # every profile here, and who each is linked as
wa personal session end                 # unlink, and delete the device keys here

多个账户对应多个配置文件，而配置文件是第一个词，不是一个选项：

wa personal chats list     # profile "personal"
wa work chats list         # profile "work"
export WA_PROFILE=work     # or for the whole shell session

wa 绝不会替你选择配置文件，即使只有一个也不例外：使用账户但未指定配置文件的命令会停止，并列出这台电脑上的配置文件。请指定一个名称，或设置 WA_PROFILE。每个配置文件都是独立关联的设备，各自拥有一个连接。

更多内容：关联、设备和配置文件 · 配置文件

本地存储和搜索

wa 收到的所有内容都会保存在你电脑上的本地存储中，并与 tg 和 max 共享。搜索会在其中进行；任何内容都不会离开你的电脑。

wa personal search messages 'contract chat:"Project Alpha"'
wa personal store status                  # how much of each chat is kept
wa personal store export "Project Alpha" --format markdown --output alpha.md
wa personal messages evidence "Project Alpha" --json   # bounded evidence for a chat brief
wa personal store backup ~/wa-backup.db   # a copy, safe while the store is in use

更多内容：搜索 · 本地存储 · 查询语言

你管理的群组

wa personal review chat:Hiking --unanswered          # questions nobody answered
wa personal review 'chat:Hiking date>7d'             # the week: decisions, promises, open questions
wa personal chats events Hiking 'time>=7d'           # who joined, left, was added or removed, and by whom
wa personal chats inspect https://chat.whatsapp.com/AAAAAAAAAAAAAAAAAAAAAA  # where an invite leads, without joining
wa personal stats chats show Hiking --offline        # the group's activity, from the local store
wa personal chats create "Hiking 2027" 100000000000002@lid   # a new group, with people you know
wa personal chats members add [email protected] 100000000000002@lid
wa personal chats update [email protected] --join-approval on
wa personal chats requests list [email protected]

重命名群组、更换群组照片、管理成员和管理员、设置邀请链接、处理加入请求，以及设置谁可以发送消息或添加成员，也都可以通过命令完成。成员会看到每项更改，因此每项操作都受配置文件权限和每小时限额限制。wa 只会添加通讯录中的联系人或你联系过的人：WhatsApp 会封禁添加陌生人的账户。

更多内容：群组

Agent 设置详解

技能。 Claude Code 会读取 ~/.claude/skills/whatsapp-cli/；Codex 和 Gemini CLI 会读取 ~/.agents/skills/whatsapp-cli/。如果 Agent 看不到该技能，请启动新的 Agent 会话。

wa skill install --for all        # both folders, without linking
wa skill show                     # the complete instructions, without installing them

MCP 服务。 配置文件中的 permissions 决定它提供哪些工具。readonly 会阻止 Agent 更改任何内容；设为 ask 时，服务不会显示表单，因此请在 Agent 应用中设置审批。

claude mcp add wa -- wa personal mcp serve  # Claude Code, by hand
wa personal mcp check                       # check the local MCP server

通过浏览器使用。 在终端中使用一次性访问码登录后，ChatGPT 或 Claude 浏览器版即可通过你的隧道访问 wa personal mcp serve --http --public-url。

更多内容：MCP 服务 · 通过浏览器使用

面向脚本和 Agent 的输出

使用 --json 时，命令只会打印数据，且仅输出一个 JSON 值。--jsonl 则每行打印一个对象。所有列表的结构都相同：

{ "items": [ … ], "page": { "limit": 20, "has_more": true }, "meta": { … } }

错误会作为单行内容输出到 stderr，stdout 为空；命令会以固定代码退出：4 表示关联配置文件，5 表示配置文件无权执行此操作，6 表示未找到聊天或消息，8 表示触发限制，12 表示另一条命令正在占用设备，14 表示无法确定消息是否已发送。wa commands --json 会输出完整的命令树。

更多内容：CLI 约定 · 所有命令和退出代码

设置和权限

wa personal config set permissions.messages readonly   # no change to messages from this profile
wa personal config set permissions.messages.send ask   # a question in the terminal before each send
wa personal config set sends_per_hour 10               # at most 10 sends an hour (30 by default)
wa personal recipients add "Book club"                 # the first add turns the recipient list on
wa personal sends list                                 # every attempt: sent, refused, failed or not known
wa personal config show                                # what is set, and where it came from

更多内容：权限 · 配置文件 · 配置 · 限制

限制

每个配置文件都有统一的请求频率限制，所有命令、serve 和 MCP 服务共用，因此脚本不会触及 WhatsApp 的封禁阈值。默认情况下，每个配置文件每小时最多发送 30 条消息。同一时间只有一条命令可以连接配置文件；其他命令会被拒绝，并以退出代码 12 退出，同时指出占用者；但如果 serve 正在运行并通过自己的连接持有配置文件，则不受此限制。无法批量下载内容：读取操作会从本地存储中返回数据。

更多内容：限制和等待时间

安全

• 设备密钥保存在一个仅你的用户可读取的文件中。任何复制该文件的人都能以你的身份读取和发送消息，直到你在手机上移除该设备。没有任何命令会将电话号码或配对码作为参数。
• 本地存储会保存收到内容的完整文本，不加密，且仅你的用户可读取。
• 所有发送操作，无论通过命令还是 MCP，都受配置文件的限制约束，并会记录到日志中——但不记录消息文本。
• wa 发送给 WhatsApp 的内容都不会提及此工具：它会以桌面浏览器的身份关联。

要报告漏洞：SECURITY.md。更多内容：安全

出现问题时

wa personal doctor          # the engine, the device keys' file modes and who holds the connection
wa personal doctor --online # also connect once and read the account
wa personal runs list       # recorded runs

更多内容：按症状查找故障 · 诊断

区别

wa 与 tg 和 max 共用命令、存储和 Agent 工具，因此你在其中一个工具中学到的内容同样适用于其他工具。WhatsApp 有三点不同：

• 历史记录来自手机。 WhatsApp 的服务器不保存可供查询的历史记录。wa 建立链接时，手机会发送近期聊天记录，此后 wa serve 会持续接收新消息。只要 WhatsApp 在手机上处于打开状态，就可以每次 50 条向手机请求某个聊天中的较早消息（wa personal messages sync）。每次读取都从本地存储中返回结果，不会建立连接。
• 每台设备只能有一个连接。 WhatsApp 只允许一个连接。wa serve 运行期间，同一配置的其他命令（包括发送消息）都会通过它的连接运行。目前，在 Windows 上，serve 停止前，这些命令会被拒绝。
• 非官方。 封禁风险已在本页顶部的警告中说明。wa 绝不会发送“在线”或“正在输入”状态，也不会标记任何消息为已读，除非你主动要求。

WireCat 的一部分

WireCat 是一个面向 AI Agent 的开源、本地优先上下文层。wa 与用于 Telegram 的 tg 和用于 MAX 的 max 并列，使用同一个本地存储。

技术文档

所有页面都位于 docs/：

页面	解答
index	文档站点的起始页：wa 是什么、第一分钟该做什么、接下来去哪里
installation	如何安装？需要什么？
usage	如何按顺序关联、读取、发送和修改消息？
sessions	如何关联：使用 QR 码或配对码、每台设备一个连接、配置文件，以及取消关联？
archive	本地存储会保留什么、如何填充，以及如何导出和备份？
search	如何按文字、发送者、聊天、日期、文件或标签查找消息、保存搜索并计数？
attachments	发送、保存和转发文件；文件中的文字，以及将语音消息转换为文字
query-language	所有搜索字段、运算符、预设、限制和 JSON 答案
groups	如何跟进群组并运行群组？
people	单个联系人：存储中保存了哪些信息、你的自定义名称和备注
mcp	如何在不使用终端的情况下连接 Claude Desktop、Cursor 或其他客户端？
remote	通过登录和隧道，在浏览器中使用 ChatGPT 或 Claude
bot	在 Meta Cloud API 上使用 WhatsApp Business 号码：设置、发送、模板，以及通过 webhook 接收
recipes	Agent 每天能为我做什么？如何按计划运行？
commands	所有命令、选项和退出代码——由程序生成
configuration	如何配置常见行为？
permissions	配置文件可以读取什么、哪些操作需要先询问，以及哪些操作可以直接执行
profiles	如何在一台计算机上使用多个账户，以及命令如何选择账户
configuration-reference	所有键、默认值、作用范围和变量
cli-contract	调用方式、输出、错误、无头运行、边界和预览
limits	限制、等待时间，以及每台设备一个连接
compare · web	wa 与 wacli、whatsapp-mcp、mudslide 和 Cloud API 有何不同？何时其他工具更合适？
diagnostics	命令做了什么？哪些内容绝不会被记录？
troubleshooting	遇到问题时：屏幕上显示什么，以及该怎么做
security	wa 会在我的计算机上保留什么？可能出现什么问题？
roadmap	接下来会推出什么？
每个版本的变更：CHANGELOG.md。

开发

pnpm install
pnpm lint && pnpm typecheck && pnpm test
pnpm engine:build && pnpm engine:test   # the Go engine; needs Go
pnpm generate                           # rewrites docs/commands.md from the command tree
bin/wa personal chats list              # config, state and device under .wa/; a worktree's store too

所有与 WhatsApp 无关的内容——命令、存储、发送保护机制和 MCP 服务——都位于 cli-core，并与 tg 和 max 共用。

更多信息：ARCHITECTURE · TESTING

贡献

欢迎提交拉取请求、错误报告和想法，见 issues。

如需使用 WhatsApp、其他消息应用和 AI Agent 构建自定义自动化：[email protected]。

许可证

CLI 使用 Apache-2.0 许可证。引擎则不使用该许可证：engine/ 中的 Go 程序及承载该程序的 @wirecat/whatsapp-engine-* 软件包使用 GPL-3.0-only 许可证，因为该引擎通过 whatsmeow 链接了受 GNU 通用公共许可证 3.0 约束的 go.mau.fi/libsignal。两者是独立程序：wa 会将引擎作为子进程启动，并且只通过 stdin 和 stdout 与其通信。每个引擎软件包都会说明其源码位置，并在 THIRD_PARTY_NOTICES 中列出它链接的所有 Go 模块。