当我们谈论终端自动化工作流时，邮件、Slack、飞书等工具已经拥有成熟的 CLI 方案，但 WhatsApp 作为全球月活超过二十亿的即时通讯平台，其 CLI 自动化能力却长期处于空白状态。wacli 的出现填补了这一细分领域 —— 它是一个完全使用 Go 语言编写的 WhatsApp 命令行客户端，基于 whatsmeow 库实现的 Web 多设备协议，能够在终端完成消息同步、离线搜索、文件发送以及群组管理等核心操作。对于需要将 WhatsApp 融入自动化流水线（比如客服工单提醒、监控系统告警推送、批量客户通知）的开发者而言，wacli 提供了一个轻量且可控的解决方案。
技术架构与依赖根基
wacli 的核心依赖是 whatsmeow，这是一个纯 Go 实现的 WhatsApp Web 多设备协议库。与传统的 WhatsApp Web 方案不同，多设备协议允许用户在不绑定浏览器会话的情况下使用 WhatsApp，这意味着 wacli 可以作为独立的客户端设备接入你的账号，而无需保持浏览器标签页的持续运行。whatsmeow 库原生支持发送和接收文本消息、媒体文件（图片、视频、文档）、群组消息、已读回执、输入状态等几乎所有日常场景需要的功能。wacli 在此基础上封装了一层 CLI 交互界面，将这些能力以子命令的形式暴露给终端用户。
在数据存储方面，wacli 使用 SQLite 作为本地数据库，并启用了 FTS5（Full-Text Search 5）全文索引模块。这一设计选择直接决定了工具的核心竞争力 —— 离线快速搜索。当你在终端执行 wacli messages search "meeting" 时，查询直接在本地 SQLite 数据库中完成，无需等待网络响应，也无需将搜索请求发送给 WhatsApp 服务器。这对于需要频繁检索历史消息（比如查找某个客户 Previously 提到的订单号）的使用场景尤为关键。默认的存储目录为 ~/.wacli，可以通过 --store 参数覆盖，这在需要为不同账号隔离数据或使用加密存储时非常有用。
从代码结构来看，wacli 采用了典型的 Go 项目布局：命令行入口位于 cmd/wacli，业务逻辑封装在 internal 目录中，文档和规格说明放在 docs 目录。最新稳定版本为 v0.6.0，发布于 2026 年 4 月 14 日，截至目前已获得约 1.7k Star 和 197 个 Fork，社区活跃度相当可观。项目当前由 maintainer dinakars777 维护，原始作者是知名的独立开发者 steipete。
核心功能深度解析
消息同步机制
wacli 的消息同步采用了「尽力而为」的本地同步策略，这一设计选择需要在使用时特别注意。首次运行 wacli auth 进行认证时，工具会显示二维码供你用手机扫码登录。认证完成后，它会立即启动初始同步，将 WhatsApp Web 协议推送过来的消息历史存储到本地 SQLite 数据库中。之后的同步使用 wacli sync --follow 命令，该命令会进入一个持续运行的循环，持续接收新消息而不需要再次扫码。值得注意的是，sync 命令在已经有有效认证的情况下不会再次显示二维码，这是合理的 UX 设计 —— 它假设你已经完成了初始登录。
对于历史消息的回填（backfill），wacli 提供了 wacli history backfill 子命令。回填的原理是向你的主设备（手机）发送历史消息请求，WhatsApp 服务器会以你本地最旧的消息作为锚点，向前拉取更早的对话记录。项目文档明确指出这是「尽力而为」的操作 ——WhatsApp 可能不会返回完整的历史，且你的主设备必须在线才能成功回填。推荐的回填参数是每次请求 50 条消息，对于需要批量回填多个聊天的场景，项目文档提供了一个 bash 脚本示例，通过管道将聊天列表传给循环进行批量处理。在实际工程实践中，建议将回填操作安排在低峰时段，并设置合理的重试间隔以避免触发 WhatsApp 的速率限制。
搜索与消息管理
离线搜索是 wacli 最实用的功能之一。wacli messages search 命令在本地 SQLite FTS5 索引上执行全文检索，响应速度取决于本地数据量而非网络状况。在 v0.2.0 版本更新中，搜索结果已经能够显示回复、反应和媒体类型的显示文本，这意味着你可以直接判断某条搜索结果是否是你需要的内容，而无需逐条打开查看。wacli messages list 命令则用于列出指定聊天的消息历史，支持分页参数，适合需要批量导出或处理历史记录的场景。
媒体文件的下载同样可以在终端完成。wacli media download 命令接受聊天 ID 和消息 ID 作为参数，将对应的媒体文件（图片、语音、视频、文档）下载到本地指定路径。在同步完成后，这个命令完全在本地执行，不依赖手机在线状态。这对于需要将 WhatsApp 中的附件批量归档（比如客服记录的工单附件）的自动化脚本非常友好。
消息发送
发送消息是自动化工作流的核心能力。wacli 提供了两种发送模式：文本消息和文件（媒体）消息。发送文本消息使用 wacli send text --to <号码> --message "内容" 的格式，其中目标号码需要填写完整的 WhatsApp ID 格式（通常是号码加上 @s.whatsapp.net 后缀，但在命令行中通常可以直接使用数字格式）。发送文件使用 wacli send file --to <号码> --file <文件路径> --caption <说明>，这在需要发送报告、发票或其他业务文档时非常有用。v0.2.0 版本还增加了 --filename 参数，允许你在发送文件时覆盖显示的文件名，这一细节对于需要保持文件命名规范的场景（比如统一格式的报表）非常实用。
群组管理
群组功能的支持使得 wacli 不仅仅是一个私信工具。wacli groups list 列出当前账号加入的所有群组，返回群组 JID 和名称。wacli groups rename 允许修改群组名称，这在需要根据项目进度动态更新群组标签（比如将「项目待定」改为「项目进行中」）的自动化流程中非常有用。群组成员的添加和移除功能目前可以通过发送邀请链接或利用 WhatsApp 原生的群组管理机制间接实现，wacli 本身提供了基础的管理接口。对于需要更精细群组控制（比如自动根据工单状态踢人）的场景，可能需要结合 WhatsApp 的邀请链接机制或等待后续版本的更新。
实际使用参数与工程建议
安装与构建
项目提供了两种安装方式。推荐的方式是通过 Homebrew 安装：brew install steipete/tap/wacli，这种方式会自动处理依赖并配置好可执行文件路径。如果你需要使用最新的开发版本或自定义构建选项，可以选择本地构建：go build -tags sqlite_fts5 -o ./dist/wacli ./cmd/wacli。注意构建命令中的 -tags sqlite_fts5 是必须的，因为 FTS5 功能是作为 Go SQLite 驱动的编译标签提供的。构建完成后，可执行文件位于 ./dist/wacli，首次使用前建议执行 wacli doctor 进行诊断，排查认证状态、存储路径、数据库完整性等潜在问题。
环境变量配置
wacli 提供了两个可选的环境变量用于定制设备信息。WACLI_DEVICE_LABEL 用于设置连接设备在 WhatsApp 中显示的标签（比如「自动化助手」或「CI 通知器」），这有助于在手机端的多设备列表中识别不同的自动化客户端。WACLI_DEVICE_PLATFORM 用于覆盖设备平台标识，默认值为 CHROME，如果你需要模拟特定平台（比如 IOS 或 ANDROID），可以设置此变量。在实际部署中，建议为不同用途的 wacli 实例设置不同的设备标签，以便在手机端进行区分和管理。
输出格式与脚本集成
wacli 的所有命令默认输出人类可读的格式，但可以通过添加 --json 参数切换为机器可解析的 JSON 输出。这一设计对脚本集成非常友好 —— 你可以将 JSON 输出通过管道传递给 jq 进行解析，或在 Python、Shell 脚本中直接解析处理。项目文档中提供的批量回填脚本就是一个典型的例子：先以 JSON 格式列出所有聊天，然后逐个调用回填命令。这种「管道式」的工作流是 Unix 哲学的延续，也是 wacli 设计上的一个亮点。
性能与资源考虑
在资源占用方面，wacli 作为纯 Go 编写的 CLI 工具，运行时内存占用非常低，通常在几十 MB 级别。SQLite 数据库的大小取决于同步的消息量，如果需要长期运行且消息量巨大，建议定期清理或归档旧消息以控制数据库体积。sync --follow 命令会持续保持 WebSocket 连接，理论上不会产生显著的网络带宽消耗，但需要确保终端持久运行的环境（比如服务器或始终开机的开发机）。如果你只需要定时检查新消息而不需要实时推送，可以将 sync 命令配合 cron 或定时任务使用，每次运行时拉取增量消息。
局限性与风险提示
使用 wacli 首先需要明确的一个根本事实是：这是一个第三方工具，基于对 WhatsApp Web 协议的逆向工程实现。WhatsApp 官方并未公开其 Web 协议，也未授权任何第三方客户端。这意味着 WhatsApp 可能在未来版本中调整协议导致工具失效 —— 虽然 whatsmeow 社区通常能够较快适配，但使用此工具需要接受这一技术风险。此外，过度频繁的操作（如短时间内发送大量消息）可能触发 WhatsApp 的反滥用机制，导致账号被限制或封禁。在生产环境中使用时，建议对发送频率进行合理限制，并在多个账号之间分散负载。
数据同步的「尽力而为」特性也需要纳入考量。wacli 不会（也无法保证）同步所有的历史消息，特别是那些在工具未运行期间产生的大量历史记录。如果你对消息归档有严格的合规要求（比如需要保留所有客户沟通记录一定年限），则需要额外考虑与 WhatsApp 官方 API 或其他企业级解决方案的配合使用。wacli 更适合作为终端自动化工作流的「通知通道」和「轻量查询工具」，而非完整的企业消息归档系统。
最后，安全性方面需要关注本地存储的数据保护。默认情况下，SQLite 数据库文件存储在 ~/.wacli 目录中，包含完整的消息历史和认证凭证。虽然 WhatsApp 的多设备协议使用了端到端加密，但本地数据库本身（如果你使用的是个人电脑）仍然可能成为攻击面。建议在共享或公共环境中使用加密的文件系统或额外的访问控制机制。
小结
wacli 为需要将 WhatsApp 融入终端自动化工作流的开发者提供了一个简洁且功能完整的选择。它基于成熟的 whatsmeow 库，利用 SQLite FTS5 实现快速离线搜索，通过 CLI 子命令暴露消息同步、搜索、发送和群组管理等核心能力。在使用上，它遵循 Unix 管道的设计哲学，支持 JSON 输出便于脚本集成，同时也提供了合理的配置选项（如存储路径、设备标签、环境变量覆盖）满足定制化需求。在工程实践中，关键的参数建议包括：默认存储路径 ~/.wacli 可通过 --store 覆盖；回填操作推荐每次请求 50 条消息；设备标签通过 WACLI_DEVICE_LABEL 环境变量设置；所有命令支持 --json 输出便于管道集成。需要注意的局限主要包括：第三方工具的属性决定了协议变更的风险、消息同步是尽力而为而非完整归档、以及生产环境使用时的频率控制以避免账号风险。
资料来源
- wacli GitHub 仓库：https://github.com/steipete/wacli
- whatsmeow Go 库：https://github.com/tulir/whatsmeow