WhatsApp 消息工具（免费版）

概述

本工具封装 WhatsApp CLI 的基础消息能力，让 AI Agent 能够通过命令行发送文本与文件消息、查询聊天列表、搜索历史消息。免费版聚焦"能发能搜"——覆盖文本/文件发送与基础聊天搜索；批量操作、历史回填与群组管理留给专业版. WhatsApp CLI 通过 WhatsApp Web 协议通信，首次使用需 QR 码登录认证。本工具仅用于向第三方联系人发送消息，不用于 Agent 自身与用户的日常对话.

核心能力

能力	说明	免费版
文本消息	发送文本到个人/群组	是
文件发送	发送文件/文档附带说明	是
聊天列表	按名称/号码查询聊天	是
消息搜索	关键词与日期范围搜索	是
QR 认证	二维码登录与初始同步	是
健康检查	连接状态诊断	是
批量发送	批量消息/批量文件	否（专业版）
历史回填	全量历史消息拉取	否（专业版）
群组管理	创建/邀请/退出	否（专业版）
持续同步	实时消息同步	否（专业版）
高级搜索	正则/多维度过滤	否（专业版）
联系人提取	vCard 解析与归档	否（专业版）

核心功能执行

用input_params参数进行配置.

处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志.

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置.

处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志.

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置.

处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志.

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：WhatsApp、消息免费版、聊天搜索、基础认证与历史同、消息工具、面向个人用户与独、立开发者、CLI、的基础消息能力、文本消息发送、聊天列表查询、消息搜索与基础认、证流程、通过命令行工具驱、Web、无需外部服务、Use、when、SEO、关键词分析、排名提升、搜索流量优化时使、不适用于黑帽等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景一：发送文本提醒

用户说"提醒客户下午 3 点开会"。Agent 调用 send text 发送文本消息到指定手机号.

wacli send text --to "+8613800138000" --message "您好！提醒您今天下午 3 点有个项目会议，请准时参加。"

场景二：发送会议议程文件

用户说"把会议议程 PDF 发给客户"。Agent 调用 send file 发送文件，附带说明文字.

wacli send file --to "+8613800138000" --file "/path/to/agenda.pdf" --caption "本周项目会议议程，请提前查阅。"

场景三：搜索历史消息

用户说"搜一下上周和客户聊的关于合同的消息"。Agent 调用 messages search 按关键词与日期范围搜索.

# 按关键词搜索
wacli messages search "合同" --limit 20 --chat "8613800138000@s.whatsapp.net"
# ...
# 按日期范围搜索
wacli messages search "invoice" --after 2026-07-10 --before 2026-07-17

快速开始

60 秒上手

1. 安装 WhatsApp CLI 工具
2. 运行 wacli auth 扫描 QR 码登录
3. 等待初始同步完成
4. 获取目标手机号（含国家代码，如 +86）
5. 调用 send text 发送第一条消息

认证流程

# QR 码登录与初始同步
wacli auth
# ...
# 终端会显示 QR 码，用 WhatsApp 扫码：
# WhatsApp → 设置 → 关联设备 → 扫描二维码
# 等待同步完成（联系人/聊天列表）
# ...
# 验证连接状态
wacli doctor

查找聊天

# 列出最近 20 个聊天
wacli chats list --limit 20
# ...
# 按名称或号码过滤
wacli chats list --limit 20 --query "张三"

发送消息

# 文本消息（个人）
wacli send text --to "+8613800138000" --message "Hello!"
# ...
# 文本消息（群组）
wacli send text --to "1234567890-123456789@g.us" --message "大家好，今天会议改到下午 3 点。"
# ...
# 文件发送
wacli send file --to "+8613800138000" --file "/path/to/document.pdf" --caption "请查收文档"

响应解析: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤.

示例

JID 格式说明

WhatsApp 内部使用 JID（Jabber ID）标识聊天对象：

类型	格式	示例
个人聊天	<number>@s.whatsapp.net	8613800138000@s.whatsapp.net
群组聊天	<id>@g.us	1234567890-123456789@g.us

使用 --to 传入手机号时，CLI 会自动转换为 JID 格式。群组 JID 需通过 chats list 查找.

存储目录

# 默认存储目录
~/.wacli/
# ...
# 自定义存储目录
wacli --store /custom/path send text --to "+8613800138000" --message "Test"

目录	用途
~/.wacli/	认证凭证、会话缓存、配置文件
~/.wacli/store/	消息数据库（SQLite）
~/.wacli/media/	下载的媒体文件

消息搜索参数

# 基础搜索
wacli messages search "关键词" --limit 20
# ...
# 限定聊天
wacli messages search "合同" --chat "8613800138000@s.whatsapp.net" --limit 50
# ...
# 日期范围
wacli messages search "invoice" --after 2026-01-01 --before 2026-12-31
# ...
# JSON 输出（便于解析）
wacli messages search "会议" --limit 20 --json

参数	说明	示例
--limit	返回条数上限	--limit 20
--chat	限定聊天 JID	--chat "8613...@s.whatsapp.net"
--after	开始日期	--after 2026-07-01
--before	结束日期	--before 2026-07-31
--json	JSON 格式输出	--json

手机号格式规范

格式	正确	错误
含国家代码	+8613800138000	13800138000
无空格	+8613800138000	+86 138 0013 8000
无连字符	+8613800138000	+86-138-0013-8000

最佳实践

1. 安全确认

发送前必须确认收件人与消息内容。CLI 不做意图猜测——如果收件人或消息内容不明确，先提问澄清.

2. 速率控制

WhatsApp 有反垃圾措施，避免快速连发或批量发送相同消息。单次发送间隔 ≥ 3 秒，优先回复已有对话.

3. 文件路径

--file 参数使用绝对路径，避免相对路径在不同工作目录下失效。文件大小建议 < 100MB.

4. 认证持久化

QR 码登录后凭证持久化存储在 ~/.wacli/。除非主动退出或更换设备，无需重复登录。定期运行 wacli doctor 检查连接健康.

5. JSON 输出

需要程序化处理搜索结果时，使用 --json 参数获取结构化输出，便于解析与后续处理.

6. 仅用于第三方消息

本工具仅用于向第三方联系人发送消息。Agent 与用户的日常 WhatsApp 对话不应调用此工具——除非用户明确要求联系第三方.

常见问题

Q1：QR 码扫描后一直同步中？

A：初始同步需要时间，取决于聊天历史数量。保持手机在线与网络稳定。同步过程中不要关闭终端。可运行 wacli doctor 检查状态.

Q2：发送失败提示"未登录"？

A：认证凭证可能过期。重新运行 wacli auth 扫码登录。登录状态会持久化，无需每次重复.

Q3：群组 JID 怎么获取？

A：运行 wacli chats list --limit 50 --query "群组名" 查找。群组 JID 以 @g.us 结尾，格式为 <id>@g.us.

Q4：搜索结果为空？

A：检查关键词拼写与日期范围。搜索仅在已同步的消息中进行——未同步的历史消息搜不到（历史回填在专业版提供）.

Q5：发送文件失败？

A：检查文件路径是否正确、文件是否存在、文件大小是否超限（建议 < 100MB）。使用绝对路径避免路径问题.

Q6：被 WhatsApp 限流怎么办？

A：降低发送频率，间隔 ≥ 3 秒。避免向未互动联系人发送。严重时账号可能被临时封禁，需等待解封.

已知限制

A：免费版不支持批量发送、历史回填、群组管理、持续同步、高级搜索与联系人提取。这些能力在专业版提供.

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

免费版限制

本免费版限制以下高级功能：

• 批量操作（批量文本/批量文件/批量群组发送）
• 历史回填（全量历史消息拉取与归档）
• 群组管理（创建/邀请/退出/信息修改）
• 持续同步（实时消息同步与事件推送）
• 高级搜索（正则匹配/多维度过滤/全文索引）
• 联系人提取（vCard 解析与电话号码归档）
• 消息统计与活跃度分析
• 多账号管理与切换

解锁全部功能请使用专业版：whatsapp-msg-tool-pro

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• 网络：可访问 WhatsApp 服务器的网络连接
• 手机：已安装 WhatsApp 的手机（用于 QR 码认证）

依赖详情

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由 Agent 内置 LLM 提供
wacli	CLI 工具	必需	包管理器安装或源码编译
Node.js	运行时	必需	运行 CLI 工具（18+）
SQLite	数据库	内置	CLI 工具自带，用于消息存储
jq	CLI 工具	推荐	用于 JSON 输出解析

API Key 配置

• WhatsApp 凭证：通过 QR 码登录获取，由 CLI 持久化存储在 ~/.wacli/
• 无需额外 API Key：本工具基于 WhatsApp Web 协议，不调用外部付费 API
• 禁止：在 SKILL.md 或脚本中硬编码 WhatsApp 账号密码或认证凭证
• 安全建议：认证凭证等同于账号访问权限，泄露后需在 WhatsApp 中解除关联设备

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，部分功能需要 exec 命令行执行能力）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 执行任务
• 模型路由建议：免费版使用低成本模型（如 GPT-4o-mini / Claude Haiku）即可完成消息发送与搜索

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

输出格式

{
  "success": true,
  "data": {
    "result": "WhatsApp消息工具(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "whatsapp msg"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}