Whatsapp Msg Tool Free

SKILL.md

---
name: "whatsapp-msg-tool-free"
description: "WhatsApp消息免费版：文本/文件发送、聊天搜索、基础认证与历史同步。"
license: Proprietary
allowed-tools: read exec
compatibility: "Requires LLM with tool-use capability"
metadata:
  displayName: "WhatsApp消息工具(免费版)"
  version: "1.0.0"
  summary: "WhatsApp消息免费版：文本/文件发送、聊天搜索、基础认证与历史同步。"
  tags:
    - "沟通协作"
    - "即时通讯"
    - "WhatsApp"
    - "消息自动化"
    - "文件传输"
  source: "SkillHub"
  converted_at: "2026-07-22T17:58:36"
---

# WhatsApp 消息工具（免费版）

## 概述

本工具封装 WhatsApp CLI 的基础消息能力，让 AI Agent 能够通过命令行发送文本与文件消息、查询聊天列表、搜索历史消息。免费版聚焦"能发能搜"——覆盖文本/文件发送与基础聊天搜索；批量操作、历史回填与群组管理留给专业版。

WhatsApp CLI 通过 WhatsApp Web 协议通信，首次使用需 QR 码登录认证。本工具仅用于向第三方联系人发送消息，不用于 Agent 自身与用户的日常对话。

## 核心能力

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

### 核心功能执行
用`input_params`参数进行配置。

**输入**: 用户提供核心功能执行所需的指令和必要参数。
**处理**: 按照skill规范执行核心功能执行操作,遵循单一意图原则。
**输出**: 返回核心功能执行的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 参数配置与调用
用`config_options`参数进行配置。

**输入**: 用户提供参数配置与调用所需的指令和必要参数。
**处理**: 按照skill规范执行参数配置与调用操作,遵循单一意图原则。
**输出**: 返回参数配置与调用的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`config_options`参数,支持修改/重置/导入操作

### 结果处理与输出
用`output_format`参数进行配置。

**输入**: 用户提供结果处理与输出所需的指令和必要参数。
**处理**: 按照skill规范执行结果处理与输出操作,遵循单一意图原则。
**输出**: 返回结果处理与输出的执行结果,包含操作状态和输出数据。
- 执行此能力时使用`output_format`参数,支持导出/保存/转换操作
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：WhatsApp、消息免费版、聊天搜索、基础认证与历史同、消息工具、面向个人用户与独、立开发者、CLI、的基础消息能力、文本消息发送、聊天列表查询、消息搜索与基础认、证流程、通过命令行工具驱、Web、无需外部服务、Use、when、SEO、关键词分析、排名提升、搜索流量优化时使、不适用于黑帽等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

## 使用场景

### 场景一：发送文本提醒

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

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

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

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

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

### 场景三：搜索历史消息

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

```bash
# 按关键词搜索
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` 发送第一条消息

### 认证流程

```bash
# QR 码登录与初始同步
wacli auth

# 终端会显示 QR 码，用 WhatsApp 扫码：
# WhatsApp → 设置 → 关联设备 → 扫描二维码
# 等待同步完成（联系人/聊天列表）

# 验证连接状态
wacli doctor
```

### 查找聊天

```bash
# 列出最近 20 个聊天
wacli chats list --limit 20

# 按名称或号码过滤
wacli chats list --limit 20 --query "张三"
```

### 发送消息

```bash
# 文本消息（个人）
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` 查找。

### 存储目录

```bash
# 默认存储目录
~/.wacli/

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

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

### 消息搜索参数

```bash
# 基础搜索
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命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |