Whatsapp

WhatsApp Skill

本 skill 通过 wacli CLI 控制 WhatsApp。所有操作必须遵守以下规则。

1. 执行前检查清单

每次执行 wacli 命令前必须运行以下检查：

1. 查阅 references/safety.md 中的读写分类表。未列出的命令运行 wacli --help；如果它会向 WhatsApp 发送数据、修改本地 store DB 或拉取实时数据并更新本地 store，则归类为写操作。
2. 读操作追加 --read-only；写操作确保 --read-only 不存在。
3. 默认追加 --json，除非用户明确要求人类可读输出或命令是交互式（如 QR 码 wacli auth）。
4. 如果用户指定或之前使用过 --account NAME 或 --store DIR，则加上。
5. 所有全局标志放在 wacli 之后、子命令之前：顺序为 wacli [--json] [--read-only] [--account NAME] [--store DIR] [--timeout DURATION] [--full] [--events] ...。
6. 接收方是否明确？如不明确，使用 --pick N（N 从 1 开始）或询问用户。
7. 文件路径参数是否存在？发送前用 ls / test -f 验证。
8. media download 与 --read-only 一起使用时，必须提供 --output 且路径在 store media 目录之外。
9. 网络/store 密集型写命令使用 --timeout 5m：send、sync、history backfill、groups info/refresh、channels list/info、profile *、auth、accounts add。轻量写命令使用 --timeout 1m：messages edit/delete/revoke/forward、contacts refresh/import-system、chats archive/pin/mute、groups participants、presence。
10. 写命令因 store is locked 失败时，使用 --lock-wait 30s 重试一次；仍失败则提示用户停止 wacli sync 或换 account/store。
11. 禁止臆造 wacli --help 或本 skill 未记录的子命令或标志。

2. 全局标志约定

默认排序（紧跟 wacli 之后）：

• --json：默认启用，便于解析。
• --read-only：读操作必须，写操作禁止。
• --account NAME：多账号选择。
• --store DIR：自定义 store 目录。
• --timeout DURATION：默认 5m；轻量写入命令可显式使用 --timeout 1m。
• --full：人类可读表格时禁用截断。
• --events：仅在用户明确要求事件流时开启，向 stderr 输出 NDJSON 生命周期事件。

3. 接收方解析规则

• 接受 JID（1234567890@s.whatsapp.net）、手机号（+1234567890 或格式化号码）、频道 JID（...@newsletter）或已同步的联系人/群组/聊天名称。
• 如果名称匹配多个结果，不得猜测。脚本中使用 --pick N（N 为 1-indexed，第一个匹配是 --pick 1）；交互场景中列出匹配项并询问用户。

4. 错误处理速查

遇到错误时先解析 JSON 信封中的 error 字段，再读取 stderr：

• not authenticated → 运行 wacli auth。
• store is locked → 等待或停止正在运行的 wacli sync --follow。
• ambiguous recipient → 使用 --pick N 或询问。
• read-only mode → 写命令移除 --read-only。
• message too old to edit → 告知用户 WhatsApp 编辑窗口已过期。
• file not found → 发送前验证路径。

5. 首次使用工作流

1. which wacli && wacli --version 检查安装。
2. 未安装则按 references/install.md 指引安装（brew → go install → source），不得静默安装。
3. 运行 wacli auth 进行 QR 配对，或 wacli auth --phone 进行电话码配对。非 TTY 环境优先电话码。
4. 持续后台同步运行 wacli sync（默认 --follow）；一次性同步运行 wacli sync --once。
5. 用 wacli --json --read-only auth status 验证。

6. 常用命令模板

wacli --json send text --to  --message ""
wacli --json --read-only messages search ""
wacli --json --read-only messages list --chat 
wacli --json --read-only contacts show --jid 
wacli --json --read-only groups list
wacli --json groups info --jid 
wacli --json --read-only polls list
wacli --json --read-only media download --chat  --id  --output 

完整命令列表见 references/command-index.md。

7. 自动化与 Webhook

如需实现全自动/半自动消息回复、监听 incoming messages、与 AI Agent CLI 集成，参考 references/automation.md。

推荐： 使用 services/agent-bridge/ 下已实现的 Bun daemon，它自动管理 wacli sync --webhook、AI 回复生成、首次消息判断、草稿队列和 SQLite 持久化，并支持编译为独立二进制。

cd services/agent-bridge
bun install
export WAB_AI_PROVIDER=claude   # 或 kimi / codex / opcode / api / mock
export WAB_MODE=manual          # manual 半自动，auto 全自动
bun run dev

直接运行（需要 Bun）：

./bin/whatsapp-agent-bridge

或编译为独立二进制（约 60MB，可选）：

bun run build:bin
./bin/whatsapp-agent-bridge

核心命令（手动集成时）：

wacli --json sync --webhook http://127.0.0.1:8787/whatsapp-webhook

参考资料

• references/safety.md — 读/写命令分类
• references/install.md — wacli 安装指南
• references/command-index.md — 完整命令索引
• references/error-handling.md — 错误码与恢复
• references/automation.md — Webhook 自动化、自动回复、AI Agent CLI 集成

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sky-flux
• Source: sky-flux/skills
• License: MIT

Install and usage instructions live in the source repository linked above.