openclaw/wacli

# 🗃️ wacli — WhatsApp CLI：同步、搜索、发送 一个基于 [`whatsmeow`](https://github.com/tulir/whatsmeow) 构建的可脚本化 WhatsApp 客户端。它作为已连接的 WhatsApp Web 设备进行配对，将你的消息镜像到本地 SQLite 存储中，并允许你通过命令行进行离线搜索、发送以及聊天/群组/联系人管理。 完整文档：**** ## 功能特性 - **认证 + 同步** — QR 码配对、一次性或跟随模式同步、可选媒体下载、可选签名 webhook 分发。 - **离线消息存储** — 使用带有 FTS5 搜索的 SQLite（LIKE 降级回退），支持按聊天、发送者、方向、时间和媒体类型进行过滤。 - **发送** — 支持提及/回复/链接预览的文本，文件（图片/视频/音频/文档，≤100 MiB），贴纸，语音消息，表情回应；具备快速发送防护和接收回执重试宽限期。 - **历史记录回填** — 尽最大努力向你的主设备发起按聊天请求，以获取更早的消息。 - **联系人 / 聊天 / 群组 / 频道** — 搜索、别名、标签、归档、置顶、静音、标记已读、重命名、清理、管理参与者和邀请链接、发送至频道。 - **诊断与安全** — `doctor` 诊断、只读模式、带有所有者报告的存储锁、panic 恢复、有界媒体队列、仅限所有者的 DB 权限。 - **可脚本化** — 全面支持 `--json`，`--events` NDJSON 生命周期流，确定性的退出代码。 ## 安装 ### Homebrew（推荐） ``` brew install steipete/tap/wacli ``` 如果在 Linux 上安装时报告 `Binary was compiled with 'CGO_ENABLED=0'`，请运行 `brew update && brew reinstall steipete/tap/wacli`。 ### 从源码构建 `wacli` 使用了 `go-sqlite3`，因此需要 cgo 和 C 编译器。 - macOS：Xcode Command Line Tools。 - Debian/Ubuntu：`sudo apt install build-essential`。 ``` CGO_ENABLED=1 CGO_CFLAGS="-Wno-error=missing-braces" \ go install -tags sqlite_fts5 github.com/openclaw/wacli/cmd/wacli@latest ``` 用于本地开发： ``` git clone https://github.com/openclaw/wacli.git cd wacli CGO_ENABLED=1 CGO_CFLAGS="-Wno-error=missing-braces" \ go build -tags sqlite_fts5 -o ./dist/wacli ./cmd/wacli ./dist/wacli --help ``` ## 快速开始 ``` # 配对（显示二维码），然后 bootstrap 同步 wacli auth # 在后台保持同步（无二维码；需要事先 auth） wacli sync --follow # 搜索 wacli messages search "meeting" # 发送 wacli send text --to 1234567890 --message "hello" wacli send file --to mom --file ./pic.jpg --caption "hi" # Diagnostics wacli doctor ``` 收件人接受 JID、电话号码（E.164 或格式化后的号码）、频道 JID 或已同步的联系人/群组/聊天名称。如果名称存在歧义，会在 TTY 中提示选择；在脚本中可传递 `--pick N` 进行指定。 更多用法示例 —— 回复、提及、贴纸、语音、表情回应、频道、历史记录回填、聊天管理 —— 都在[文档](https://wacli.sh)中。 ## 文档 | 领域 | 页面 | | --- | --- | | **设置** | [概述](docs/overview.md) · [认证](docs/auth.md) · [账户](docs/accounts.md) · [同步](docs/sync.md) · [诊断](docs/doctor.md) | | **消息** | [消息](docs/messages.md) · [发送](docs/send.md) · [媒体](docs/media.md) · [在线状态](docs/presence.md) | | **通讯录** | [联系人](docs/contacts.md) · [聊天](docs/chats.md) · [群组](docs/groups.md) · [频道](docs/channels.md) | | **历史记录** | [历史记录覆盖率 / 填充 / 回填](docs/history.md) | | **本地存储** | [存储](docs/store.md) · [配套集成](docs/integrations.md) | | **杂项** | [个人资料](docs/profile.md) · [版本](docs/version.md) · [补全](docs/completion.md) · [发布](docs/release.md) | ## 配置 默认存储路径：Linux 上为 `~/.local/state/wacli`，其他平台为 `~/.wacli`。Linux 上已有的 `~/.wacli` 目录将继续有效。使用 `wacli accounts add NAME` 和 `--account NAME` 可实现一等多的多账户存储管理。 **全局标志：** `--store DIR`、`--account NAME`、`--json`、`--events`、`--full`、`--timeout DUR`、`--lock-wait DUR`、`--read-only`。 **环境变量覆盖：** | 变量 | 作用 | | --- | --- | | `WACLI_STORE_DIR` | 默认存储目录。 | | `WACLI_READONLY` | 设置为 `1`/`true`/`yes`/`on` 可启用只读模式。 | | `WACLI_DEVICE_LABEL` | 在 WhatsApp 中显示的已配对设备标签。默认为 `wacli - ()`。 | | `WACLI_DEVICE_PLATFORM` | 已配对设备的平台。默认为 `DESKTOP`；无效值将降级回退到 `CHROME`。 | | `WACLI_SYNC_MAX_MESSAGES` | 当本地消息总数超过此数量时停止同步。 | | `WACLI_SYNC_MAX_DB_SIZE` | 当 `wacli.db` 及附属文件达到指定大小（如 `500MB` 或 `2GB`）时停止同步。 | ## 回填更早的历史记录 `wacli sync` 仅存储 WhatsApp Web 顺带发送的内容。要获取*更早的*消息，`wacli` 会向你的**主设备**（你的手机）发起按需的历史记录请求，且主设备必须在线。 - 尽力而为：WhatsApp 可能不会返回完整的历史记录。 - 每次请求会以该聊天中**本地存储的最旧消息**为锚点 —— 请先运行 `sync`。 - 建议每次请求使用 `--count 50`（最大 500）。每次运行最大 `--requests 100`。 - `history coverage` 可显示哪些聊天符合条件。`history fill --dry-run` 可在不连接的情况下进行规划。 ``` wacli history coverage --include-blocked wacli history fill --dry-run --kind group --limit 20 wacli history backfill --chat 1234567890@s.whatsapp.net --requests 10 --count 50 ``` 遍历每个已知聊天： ``` wacli --json chats list --limit 100000 \ | jq -r '.data[].JID' \ | while read -r jid; do wacli history backfill --chat "$jid" --requests 3 --count 50 done ``` ## 致谢 深受 Vicente Reig 的 [`whatsapp-cli`](https://github.com/vicentereig/whatsapp-cli) 启发。 ## 维护者 - 由 [@steipete](https://github.com/steipete) 创建 - 目前由 [@dinakars777](https://github.com/dinakars777) 维护 ## 许可证 查看 [`LICENSE`](LICENSE)。

标签：CGO, CLI, EVTX分析, FTS5, Go, Homebrew, Ruby工具, SEO检索词, SQLite, Webhook, WhatsApp, whatsmeow, WiFi技术, 个人效率工具, 二维码配对, 力导向图, 即时通讯, 媒体下载, 开源, 数据备份, 日志审计, 本地存储, 消息发送, 消息搜索, 离线搜索, 网络调试, 群组管理, 聊天记录同步, 联系人管理, 脚本集成, 自动化, 自动化控制, 频道管理