whatsapp-tools

whatsapp-tools

为编码 Agent 提供的 WhatsApp 工具：聊天、消息、联系人、历史记录、接收的文件，以及发送消息和对用户自己的消息与聊天执行操作。

Harness	交付方式	固定版本依据
OpenCode V2	原生插件（npm 包，含技能）	包中的版本
OpenCode V1	原生插件（npm 包，不含技能）	包中的版本
Claude Code	插件：MCP 服务和技能	发布标签，作为 ref
Codex	插件：MCP 服务和技能	发布标签，作为 ref
Grok Build	插件：MCP 服务和技能	发布标签，作为 @ref
Antigravity	插件：MCP 服务和技能	发布标签的树 URL
Hermes Agent	原生插件（Python，调用命令行）	发布提交，作为 SHA
其他 MCP 主机	npm 提供的 MCP 服务	包中的版本

这些工具需要 Node.js 24 或更高版本。 docs/conventions.md 说明了工具的命名方式 及其行为。

安装

请从发布版本安装，切勿从默认分支安装：发布版本是一个包含已构建 dist/ 的提交的标签，而默认分支不包含它。在以下命令中，<version> 是发布版本号（1.2.3），<sha> 是该标签指向的提交：

gh api repos/craft-agent/whatsapp-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2 在 opencode.json 中配置包及其选项：

{
  "plugins": [{ "package": "@craftsamo/whatsapp-tools@<version>", "options": { "read_only": false } }],
  "permissions": [{ "action": "whatsapp_*", "resource": "*", "effect": "ask" }]
}

OpenCode V1 将包配置为字符串，或配置为包含选项的一对值：

{
  "plugin": [["@craftsamo/whatsapp-tools@<version>", { "read_only": false }]],
  "permission": { "whatsapp_*": "ask" }
}

OpenCode 允许执行任何未被规则命名的操作，因此除非规则指定 ask，否则插件的请求会被静默批准。读取工具不会触发询问，因此 whatsapp_* 通配符是安全的。

V1 不会注册技能。解压包，并将其 skills/* 文件夹复制到 ~/.config/opencode/skills/：

npm pack @craftsamo/whatsapp-tools@<version>
tar -xzf craftsamo-whatsapp-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-whatsapp-tools-<version>.tgz

Claude Code

claude plugin marketplace add craft-agent/whatsapp-tools#v<version>
claude plugin install whatsapp-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/whatsapp-tools --ref v<version>
codex plugin add whatsapp-tools@craft-agent

Codex 会将服务器名称中的 - 转换为 _，因此工具会显示为 mcp__whatsapp_tools__whatsapp_*。它会在插件的安装目录中启动 MCP 服务，且不会传递根目录，因此服务会从 Codex 随调用发送的内容中获取每次调用的目录：它会先使用服务所请求的沙盒状态，否则使用 Codex 指定的唯一工作区。

插件声明了 default_tools_approval_mode = "writes"：Codex 会在每次调用未标记为只读的工具前询问用户。用户的 [plugins."<plugin>".mcp_servers.<server>] 设置只能进一步收紧此限制。在此处设置 auto 会得到 prompt（读取操作也会询问），因为 Codex 将 auto 和 writes 视为不可比较。

Grok Build

grok plugin install craft-agent/whatsapp-tools@v<version> --trust

Grok 会在会话的工作目录中启动 MCP 服务。

Antigravity

请从发布标签的树安装，切勿从默认分支安装，因为默认分支没有已构建的 dist/；Antigravity 会将该标签克隆到 ~/.gemini/config/plugins/whatsapp-tools。

agy plugin install https://github.com/craft-agent/whatsapp-tools/tree/v<version>

Hermes Agent

该插件需要 Hermes Agent 0.22 或更高版本。Hermes 安装的是提交，而不是标签，并且插件安装后处于禁用状态：

hermes plugins install craft-agent/whatsapp-tools --ref <sha>
hermes plugins enable whatsapp-tools

如果 Hermes 网关已经在运行，请重启它（hermes gateway restart）以加载插件。网关运行期间，hermes chat 也会在网关中运行插件的工具，因此这些工具会使用网关的环境，而不是 shell 的环境：用于找到 wacli 和 node 的 PATH，以及任何 WHATSAPP_TOOLS_* 变量，都是网关启动时使用的值。

插件会运行 Hermes 启动时找到的 Node。如果版本管理器在 Hermes 运行期间移除了该版本，调用时会重新查找 Node；如果找不到，则请在 node 可运行的 shell 中重启 Hermes。

其他 MCP 主机

将服务器添加到主机的 MCP 配置中。标志放在 args 中：

{
  "mcpServers": {
    "whatsapp-tools": {
      "command": "npx",
      "args": ["-y", "@craftsamo/whatsapp-tools@<version>", "--read-only"]
    }
  }
}

工具和技能

每个工具集都附带一个技能，告诉 Agent 如何使用其中的工具。技能会在其 frontmatter 的 metadata 中声明所属工具集（以代码块形式写作 metadata: { toolset: sends }）。OpenCode V2 和 Hermes 只有在设置中注册了该工具集的至少一个工具时才会注册对应技能，因此，关闭该工具集或移除其中所有工具的配置不会显示该技能；未指定工具集的技能始终会注册。Claude Code、Codex、Grok Build 和 Antigravity 会整体安装技能文件夹，并仅将设置传递给 MCP 服务，因此无论设置选择了什么，它们都会列出所有技能。OpenCode V1 不会注册任何技能，而它复制的技能也会全部列出。

账号（account）

工具	功能	类别
whatsapp_account_read	各标签：配对、同步服务状态、上次同步和活动、wacli 支持情况，以及此人的下一步操作	读取

它只读取本地状态：不需要联网或运行服务，返回结果中也不包含消息内容、号码、JID 或密钥。对应的技能是 whatsapp-account，在 Claude Code 中显示为 whatsapp-tools:whatsapp-account，在 Hermes 中显示为 whatsapp-tools:account。与其他工具不同，省略 account 会列出所有标签。

聊天（chats）

工具	功能	类别
whatsapp_chat_read	根据 method 执行操作：list 查找聊天，view 读取单个聊天的消息，search 按关键词查找消息，around 读取某条消息前后的消息	读取

它只读取账号的本地镜像，无需联网；返回的他人言论仅为数据，绝非指令。对应的技能是 whatsapp-chats，在 Claude Code 中显示为 whatsapp-tools:whatsapp-chats，在 Hermes 中显示为 whatsapp-tools:chats；还有 whatsapp-count-activity，在 Claude Code 中显示为 whatsapp-tools:whatsapp-count-activity，在 Hermes 中显示为 whatsapp-tools:count-activity，说明如何统计一段时间内的聊天和回复数量。

联系人（contacts）

工具	功能	类别
whatsapp_contact_read	根据 method 执行操作：search 按姓名、号码或 JID 查找联系人，check 向 WhatsApp 查询最多 20 个电话号码是否已注册	读取

search 只读取账号的本地镜像，无需联网或运行服务。check 通过该标签正在运行的同步服务向 WhatsApp 发起查询，不会写入任何内容，也不会添加联系人。对应的技能是 whatsapp-contacts，在 Claude Code 中显示为 whatsapp-tools:whatsapp-contacts，在 Hermes 中显示为 whatsapp-tools:contacts。

历史记录（history）

工具	功能	类别
whatsapp_history_backfill	向手机请求某个聊天中的较早消息，尽力分 1 到 5 批获取，每批 50 条	添加

它只会写入该标签自己的镜像，不会向任何人发送内容。同步服务会运行此工具，并在调用期间暂停同步，因此服务必须处于运行状态；结果会说明收到的消息数量、目前保存的最早一条消息、停止原因，以及服务是否已恢复同步。手机必须处于在线状态；没有新增消息并不能证明不存在更早的消息。它使用的技能是 whatsapp-chats。

一次调用最长可能需要约 5 分钟。有些执行环境默认会更早停止工具调用，此时调用会失败，但已收到的内容仍会保留，服务也会恢复同步：

• Codex 默认会在 60 s 后停止调用；插件会将上限提高到 330 s。如果将服务添加到 [mcp_servers]，而不是添加到插件中（参见设置），则需要设置 tool_timeout_sec = 330。
• Antigravity 会在 180 s 后停止调用。在 MCP 配置中为服务设置 "timeoutSeconds": 330。
• Hermes 会为插件调用设置 150 s 的超时时间，为 whatsapp_history_backfill、whatsapp_file_save 和 whatsapp_file_send 设置 330 s；无需设置任何内容。

文件（files）

工具	功能	类别
whatsapp_file_save	将一条消息中的文件保存到 download_dir，检查归档文件，并在收到请求时解包一个文件	add
whatsapp_file_send	向个人或群组发送 1 到 10 个文件，最多 100 MiB，每个文件单独发送一条消息，并在发送任何文件前进行检查	add

默认关闭：使用 files 工具集即可启用。消息中的文件会保存到 download_dir 下各自的文件夹中（默认路径为 ~/Downloads/whatsapp-tools），并设为私有且不可执行，绝不会覆盖已有文件。程序、 安装程序、磁盘映像、宏文档以及无法读取的归档文件都会被拒绝；zip、tar 和 gzip 压缩的 tar 会先接受检查，只有在收到请求时才会解包。macOS 上保存的每个文件都会带有隔离标记。对于 WhatsApp 服务器已不再保留的文件，会通过正在运行的同步服务向手机请求。 该技能为 whatsapp-files，在 Claude Code 中显示为 whatsapp-tools:whatsapp-files，在 Hermes 中显示为 whatsapp-tools:files。

如果调用需要回退到手机，可能需要几分钟；上述 History 部分列出的工具时间限制同样适用。

whatsapp_file_send 只会从工作目录和 send_dirs 设置指定的目录发送文件，并根据真实路径进行判断；其他位置的文件以及状态目录中的文件都会被拒绝。密钥和机密文件（.ssh、.env、*.pem 等）、浏览器、密码管理器和即时通讯应用的数据文件夹、空文件、程序、安装程序，以及任何包含私钥块的文件，无论位于何处都不会发送。归档文件只有在所有条目都通过检查后才会发送，并且绝不会解包。每个文件都会复制到对应标签的发件箱中并在那里接受检查，因此实际发送的就是已检查的文件；用户批准的 sha256 会使发生更改的文件标记为 stale。每个文件各自作为一条消息发送，并按指定顺序发送；文本会作为第一个文件的说明（最多 1,024 个字符，音频文件不接受说明）。WhatsApp 自身会显示为照片、视频或音频的内容，会根据文件名和开头的字节来判定，并按相应类型发送；其他内容则作为文件发送。as_document 会将所有内容都作为文件发送。如果调用在部分文件发出后停止，就会失败，并在 details 中列出已发出的文件及其消息 ID，以及尚未发出的文件，以避免重复发送；可能已经发出的文件会标记为 uncertain。单次调用最长为 280 s，上述 History 部分列出的工具时间限制同样适用。

发送（sends）

工具	功能	类别
whatsapp_message_send	向个人或群组发送一条文本消息，最多 4,000 个字符，可选附带引用回复	添加

默认启用，并通过标签对应的运行中同步服务发送，因此该服务必须处于运行状态。此工具仅向个人和群组发送消息：频道、广播列表和状态动态均会被拒绝。聊天会话是来自 whatsapp_chat_read 的 JID；对于尚未被镜像保存的联系人，则使用 whatsapp_contact_read check 返回的 chat，并在发送前立即向 WhatsApp 查询该号码是否有账号。文本按原样发送，会去掉首尾空白，绝不拆分，也不会生成链接预览。返回结果表示 WhatsApp 已接受消息，不代表消息已送达或已读。若已知失败发生在任何内容发出之前，结果会说明这一点；其他在请求移交后发生的失败均为 uncertain：消息可能已经发出，系统会检查聊天，并在再次发送前询问用户。与在手机上撰写消息一样，发送消息会降低镜像中的聊天未读数，且不会发送已读回执。对应技能为 whatsapp-sends，在 Claude Code 中显示为 whatsapp-tools:whatsapp-sends，在 Hermes 中显示为 whatsapp-tools:sends。

操作（actions）

工具	功能	类别
whatsapp_chat_archive	归档聊天，或取消归档	幂等
whatsapp_chat_mark	将聊天标记为已读或未读，可选择发送已读回执	幂等
whatsapp_chat_mute	将聊天静音 8 小时、一周或永久，或取消静音	幂等
whatsapp_chat_pin	置顶聊天，或取消置顶，最多可置顶 WhatsApp 允许的三个聊天	幂等
whatsapp_message_delete	为所有人删除用户发送的消息，且须在发送后两天内操作	管理性操作
whatsapp_message_edit	替换用户发送的文本消息内容，且须在发送后 15 分钟内操作	覆盖
whatsapp_message_react	使用一个表情符号回应消息，或移除用户的回应	覆盖

默认关闭：使用 actions 工具集启用。每项操作都通过标签对应的运行中同步服务执行，且仅作用于镜像中保存的聊天和消息，聊天和消息分别由 whatsapp_chat_read 提供的 JID 和 id 指定。为所有人删除消息时，同步服务会在调用期间暂停几秒，结果会说明是否已恢复同步。操作遵循 WhatsApp 自有应用的限制，并会在任何内容发出前拒绝超出限制的请求。返回结果表示 WhatsApp 已接受该操作；若已知失败发生在任何内容发出之前，结果会说明这一点；其他失败均为 uncertain：系统会检查聊天，并在再次尝试操作前询问用户。聊天的归档、置顶、静音和已读状态仅会显示在用户自己的设备上，重复设置这些状态是安全的，因此其 uncertain 结果会说明这一点。将聊天标记为已读默认不会通知任何人；只有用户提出要求时，receipts: true 才会改为为最多 100 条未读消息发送已读回执，这会通知消息发送者，并且只清除镜像中的未读数，不一定会清除手机上的标记。对应技能为 whatsapp-actions，在 Claude Code 中显示为 whatsapp-tools:whatsapp-actions，在 Hermes 中显示为 whatsapp-tools:actions。

添加工具

1. 使用 defineTool 在 src/core/<domain>/<verb>.ts 中编写规范：包括 ID <prefix>_<domain>_<verb>、标题和描述、Zod 参数与输出架构、工具集和写入类别，以及 execute(args, context)。写入工具还需提供 targets(args, context)：说明调用会写入哪些目标， 权限规则应据此命名。
2. 在规范旁边测试该工具（<verb>.test.ts），通过 invoke 调用它，与各入口的调用方式一致。 运行程序的工具应针对 PATH 中该程序的假对象进行测试；没有测试会连接真实服务。
3. 在 src/tools.ts 中列出该工具。将新工具集添加到 src/project.ts 的 toolsets 中（如果默认启用， 也添加到 defaultToolsets）；将包自身的设置添加到 options 中（并在 project.py 的 OPTIONS 和 plugin.yaml 的 config_schema 中添加）；将工具除设置外读取的变量添加到 toolVariables 中。
4. 添加或更新该工具集的技能文件 skills/<prefix>-<toolset>/SKILL.md， 并在其 frontmatter 的 metadata 下声明工具集名称。
5. 运行 pnpm run build && pnpm run manifests，将工具列入 plugin.yaml，并将其变量列入 Codex 的清单，然后在“工具和技能”一节中描述该工具。

docs/conventions.md 列出了各步骤须遵循的规则。

包可将每个选项声明为 text、boolean、number、list、path 或 paths，也可声明为带有 type 和可选边界值的对象。例如，在 src/project.ts 中：

options: {
  notes_dir: "path",
  note_limit: { type: "number", integer: true, min: 1, max: 50 },
}

integer: true 要求数值为整数；min 和 max 用于限制数值，或限制 list 或 paths 值中项目的数量。仅包含 type 的对象与直接使用该类型的含义相同。Hermes 的 OPTIONS 会将这些声明对应地写在一行中，使用双引号，并在 integer 处使用 Python 的 True：

OPTIONS: dict[str, str | dict[str, object]] = {"notes_dir": "path", "note_limit": {"type": "number", "integer": True, "min": 1, "max": 50}}

读取和写入

每个读取工具都命名为 <prefix>_<domain>_read。读取操作可以在未经询问的情况下运行； 写入操作会由执行环境要求确认。

执行环境	无需询问即可读取
OpenCode	始终如此；插件只会在写入前询问
Claude Code	~/.claude/settings.json 的 permissions.allow 中的规则 mcp__plugin_whatsapp-tools_whatsapp-tools__*_read
Codex	始终如此；Codex 会在未经询问的情况下运行声明了 readOnlyHint 的工具，读取工具正是如此
Grok Build	grok --allow 'MCPTool(whatsapp-tools__*_read)' --allow 'MCPTool(whatsapp_*_read)'（两条规则；见下文）
Antigravity	permissions.allow 中的规则 mcp(whatsapp-tools_whatsapp-tools/<tool id>)，每个读取工具一条
Hermes	始终如此；插件只会在写入前询问

关于写入操作何时会被询问、何时不会：

• OpenCode 不指定规则名称时会允许任何操作，因此写入操作会在未经询问的情况下运行，除非添加规则要求确认：添加 OpenCode 下所示的 whatsapp_* 规则。
• Codex 由于插件的审批模式，会在每次写入前询问。 在 codex exec 下，它会拒绝并提示 "MCP tool call requires approval, but approval policy is never"。
• Grok Build 在 grok -p 下会拒绝无法询问确认的写入操作，除非事先允许该操作。
• Grok Build 通过其 use_tool 工具调用插件的工具，而且 Agent 通常会先不带服务名称地指定工具。Grok 会根据给定的名称检查规则，因此仅有带服务名称的规则无法匹配首次调用。第二条规则会匹配简短名称；写入操作仍然两条规则都不匹配。
• Antigravity 会在任何未被规则允许的 MCP 工具调用前询问，包括读取操作，并将插件的服务命名为 whatsapp-tools_whatsapp-tools（先是插件，再是服务）。agy -p 会拒绝无法询问确认的工具调用。
• Hermes 的 hermes chat -q 会拒绝无法询问确认的写入操作；hermes -z 和 --yolo 会跳过审批，因此写入操作会在未经询问的情况下运行。

设置

每个入口点都使用相同的设置。标志的优先级高于其环境变量，选项或设置的优先级也高于变量，Hermes 除外，详见下文。

设置	标志	变量	含义
toolsets	--toolsets	WHATSAPP_TOOLS_TOOLSETS	启用的工具集，或 all；默认使用 src/project.ts 中的名称
read_only	--read-only	WHATSAPP_TOOLS_READ_ONLY	不注册任何会写入的工具；优先级高于所有其他设置
tools	--tools	WHATSAPP_TOOLS_TOOLS	按 ID 添加单个工具，无论它属于哪个工具集
exclude_tools	--exclude-tools	WHATSAPP_TOOLS_EXCLUDE_TOOLS	按 ID 移除单个工具；优先级高于 tools 和 toolsets
confirm	--confirm	WHATSAPP_TOOLS_CONFIRM	仅限 MCP 服务：harness（默认）或 elicitation，按惯例选择
language	--language	WHATSAPP_TOOLS_LANGUAGE	仅限原生插件：审批提示词所用的语言，例如 ja
emoji	—	—	仅限 Hermes：显示在每个工具集旁边的表情符号，按工具集名称设置（"" 表示无）
state_dir	--state-dir	WHATSAPP_TOOLS_STATE_DIR	path：各标签的状态存放位置；默认值为 $XDG_STATE_HOME/whatsapp-tools
download_dir	--download-dir	WHATSAPP_TOOLS_DOWNLOAD_DIR	path：接收的文件保存位置；默认值为 ~/Downloads/whatsapp-tools
send_dirs	--send-dirs	WHATSAPP_TOOLS_SEND_DIRS	paths：除工作目录外，可从中发送文件的目录

标志或变量中的列表以逗号分隔。state_dir、download_dir 和 send_dirs 是本软件包自己的设置，在 src/project.ts 的 options 中列出，并以相同方式读取。path 会先去除首尾空白；~ 和 ~/… （也包括使用平台分隔符的写法）表示主目录（若 HOME 是绝对路径，则使用 HOME，否则使用账户的主目录）。路径随后必须是绝对路径，并会以规范化形式 传给工具，不会检查文件系统。空白路径视为未设置，因此会应用默认值。paths 是由此类路径组成的列表，在标志或变量中以逗号分隔，在插件选项中则是字符串 数组。空白项会被删除，删除后没有剩余项的列表视为未设置。重复的发送目录会 被删除。边界检查只针对显式给定的值，不检查未设置的选项。被拒绝的值会返回 invalid_argument，并指出对应的标志、变量或选项以及其必须满足的要求。 Hermes 会将路径和列表传给命令行，由命令行检查路径和边界。各个运行环境的读取方式如下：

• OpenCode 使用上面所示的插件 options，其中列表为数组， read_only 为布尔值，state_dir 和 download_dir 为路径， send_dirs 为路径数组，并在未提供时回退到变量。V2 在后台服务中运行插件， 该服务会保留启动时的环境：在 opencode run 启动时设置变量，在该环境中 重启服务之前不会生效（opencode service restart）。V1 在自身进程中运行插件。

• Hermes 使用 config.yaml 中的 plugins.entries.whatsapp-tools.settings：

  plugins:
    entries:
      whatsapp-tools:
        settings:
          read_only: false
          exclude_tools: []
  

  如果未设置 language，审批卡片将使用 Hermes 自身的 display.language（或 HERMES_LANGUAGE），其审批按钮也使用相同的语言； 否则保持英文。插件会将自身的环境传递给它运行的命令行，因此这些变量也会生效。 设置为关闭或留空时（read_only: false、tools: []、exclude_tools: []、 send_dirs: []），不会传递任何内容，因此在该环境中设置的变量仍然适用： 无论设置如何，WHATSAPP_TOOLS_READ_ONLY=true 都会让插件保持只读。正在运行的网关会保留 启动时的环境，而 hermes chat 运行期间，工具也会在该环境中运行；更改环境后请重启 网关（hermes gateway restart）。

• Claude Code、Grok Build 和 Antigravity 启动插件服务时不带标志，并会传递客户端的环境， 因此请在运行该框架的环境中设置这些变量。

• Codex 只会向插件的 MCP 服务传递少数基本变量（例如 PATH 和 HOME），以及插件清单中 列出的变量，也就是上述变量：请在运行 Codex 的环境中设置它们。工具除设置之外还会读取的 变量，应添加到 src/project.ts 中的 toolVariables；pnpm run manifests 会在设置对应的 变量之后，将其添加到清单中。要传递标志，或向服务提供软件包未列出的变量，请在 Codex 的 config.toml 中将服务添加到 [mcp_servers] 下，而不要使用插件：标志放在 args 中， env_vars 用于指定要从 Codex 环境转发的变量，env 用于设置固定值。

  [mcp_servers.whatsapp-tools]
  command = "npx"
  args = ["-y", "@craftsamo/whatsapp-tools@<version>", "--read-only"]
  env_vars = ["WHATSAPP_TOOLS_TOOLSETS"]
  tool_timeout_sec = 330
  

账户与同步服务

这些工具通过 wacli 将 WhatsApp 账户用作用户手机的关联设备， 方式与 WhatsApp Web 相同。你需要自行安装 wacli（brew install openclaw/tap/wacli，或安装 发布的二进制文件）。它们绝不会操控 WhatsApp Web，也不会读取其他客户端的数据。

• wacli 0.26 或更高版本。 WhatsApp 会停止为旧客户端提供服务，直到 wacli 跟上其协议， 因此请保持更新；更新后，重启同步服务以运行新版本。
• 每个关联设备都有一个标签，由 1 到 24 个小写字母、数字和 _ 组成（配对时未命名则为 default）。工具的 account 参数用于选择标签；如果只配对了一个设备，可以省略该参数。 如果未提供 account，账户工具则会列出所有标签。
• 每个标签都会在一个目录中保存其状态，路径为 <state_dir>/<label>/ （权限模式为 700）：其中包括 wacli 的存储（会话密钥、消息镜像和已下载的媒体）、同步服务的 套接字，以及待发送文件的副本。state_dir 默认为 $XDG_STATE_HOME/whatsapp-tools， 或 ~/.local/state/whatsapp-tools。不会使用 wacli 自身位于 ~/.wacli 的账户。请勿将此目录 纳入与他人共享的备份：其中的密钥可代你读取和发送消息。
• 每个标签都会运行一个同步服务：该服务会让镜像保持最新状态，且每次发送及其他所有写入 操作都会通过它进行，因此执行写入操作的工具需要该服务处于运行状态。无论服务是否运行， 读取操作都可用。历史记录从设备配对时开始，包含手机当时发送的内容；也可以尽力向手机请求 更早的消息。
• WhatsApp 会取消 30 天未使用的设备的关联；如果手机 14 天未使用，则会取消所有关联设备的 关联；一部手机最多可关联四台设备。运行中的服务会让设备保持使用状态。取消关联的标签需要 通过手机重新配对。
• wacli 不是官方客户端。 WhatsApp 不为个人账户提供 API，并且可能会限制或封禁使用非官方 客户端的账户。

配对设备并运行同步服务

请先安装 wacli 0.26 或更高版本：macOS 上运行 brew install openclaw/tap/wacli；其他系统则安装发布的二进制文件。支持 macOS 和 Linux；Windows 支持情况见 #11。 除了任何 harness 插件外，这些命令都随 npm 软件包提供：插件提供的是工具，而不是 PATH 上的命令。请按所用插件的版本全局安装软件包，以便它安装的服务拥有稳定路径：

npm install -g @craftsamo/whatsapp-tools@<version>

# On the phone, WhatsApp > Linked devices > Link a device, then scan the QR.
whatsapp-tools-cli pair --account work

# Start syncing at logon, and restart after a failure.
whatsapp-tools-cli service install --account work
whatsapp-tools-cli service status

仅有一个标签时，可以省略 --account（pair 会将新标签命名为 default），但 remove 始终需要此参数；每条命令都像工具一样接受 --state-dir。有多个标签时，也请在 service status 中添加 --account work。

以下每条命令都以 whatsapp-tools-cli 开头：

命令	功能
pair [--account <label>] [--phone <number>] [--full-history [--history-days <n>]]	通过 QR 码配对此设备，或使用 --phone 打印供手机输入的代码，然后等待首次同步
sync [--account <label>]	在前台运行同步服务，将日志写入标准错误输出，直到停止
service install | uninstall | status [--account <label>]	将服务注册为 launchd Agent（macOS）或 systemd 用户单元（Linux）、启动服务、移除服务或报告其状态
remove --account <label> [--yes]	卸载服务，在可能时将设备登出，并在确认后删除该标签的密钥和历史记录

• 服务会记录此软件包和 Node 的路径，因此更新其中任意一项后，请重新运行 service install。如果 Node 的路径包含其版本号（例如使用版本管理器时），service install 会记录一个位于不含版本号路径下、且可启动相同 Node 的 node；如果找不到这样的路径，则会发出警告。随后，这个 node 会运行版本管理器当前选用的 Node。使用此版本安装服务后，service status 和 whatsapp_account_read 会提示记录的程序是否已不存在。在 macOS 上，日志位于 ~/Library/Logs/io.github.craft-agent.whatsapp-tools/<label>.log；在 Linux 上，日志位于 service status 显示的 journalctl --user -u <unit> 中；运行 loginctl enable-linger 可让服务在你登出后继续运行。
• 在 macOS 上，“登录项”会将服务列为 whatsapp-tools-sync-<label>： Agent 会通过该启动脚本启动；service install 会将脚本写入 ~/Library/Application Support/io.github.craft-agent.whatsapp-tools/，而 service uninstall 会将其删除。在那里关闭此登录项会停止同步。
• 一部手机最多可关联四台设备，每个标签对应其中一台。WhatsApp 会解除闲置 30 天的设备，以及闲置 14 天手机上的所有关联设备；运行中的服务会让关联设备保持活跃，但不会让手机保持活跃。
• 配对时，--full-history 会向手机请求完整历史记录，而非最近几个月的记录；--history-days 可限制回溯天数。此选项仅在配对期间生效；pair 结束后，手机仍会继续发送一段时间，服务运行后，这些内容就会同步到镜像中。已配对的设备可使用 whatsapp_history_backfill 按聊天逐个获取更早的消息，或者移除设备后重新配对。
• 要重新配对已撤销的标签，请再次运行 pair：失效的会话会被删除，镜像则会保留。要连接其他账户，请使用新标签。
• 移除标签时，会在可能的情况下将设备登出。 如果无法登出，也请在手机上的 WhatsApp > 已关联的设备中移除该设备。
• whatsapp_account_read 会告知 Agent 某个标签需要执行哪个步骤。

目录结构

• src/project.ts — 包名称、工具 ID 前缀、设置前缀、工具集、工具选项以及工具读取的其他变量。
• src/core/ — 工具契约和工具，不包含任何框架，也不包含项目名称。
• src/tools.ts — 所有工具的列表，各入口点都会注册这些工具。
• src/words.ts — 各语言中工具用语的译文，原生插件会在审批提示词中使用这些译文。
• src/mcp/ — MCP 服务，构建到 dist/mcp.js，并由 whatsapp-tools 运行。
• src/opencode/ — OpenCode 插件，构建到 dist/opencode.js。
• src/cli/ — Hermes 插件调用的命令行，构建到 dist/cli.js，并由 whatsapp-tools-cli 运行。
• src/hermes/、plugin.yaml 和 __init__.py — Hermes 插件。
• skills/ — 每个工具集对应一个技能，路径为 skills/<name>/SKILL.md。所有支持技能的框架都会从包或插件根目录加载这些技能；原生插件只会加载已启用工具集的技能。
• .claude-plugin/、.codex-plugin/、.agents/plugins/、.mcp.json、.antigravity-plugin/ 和 mcp_config.json — 其他框架的插件清单。Codex 会读取 .codex-plugin/plugin.json；根目录下的 plugin.json 会使其将插件作为 Agent Plugin 加载，其工具预算会隐藏超出固定数量的工具。根目录下的 .mcp.json 是 Grok Build 读取的配置（使用 ${CLAUDE_PLUGIN_ROOT}，该变量会由 Grok Build 和 Claude Code 展开）；在 Claude Code 中处理此仓库时，请拒绝它通过该文件提供的项目 MCP 服务。

如何发布版本，请参阅 RELEASING.md。

许可证

AGPL-3.0 with Commons Clause