使用 wacli 技能为 OpenAgent 打通 WhatsApp 消息发送与历史检索
使用 wacli 技能为 OpenAgent 打通 WhatsApp 消息发送与历史检索
本篇文章以开源仓库 openagent 中 skills/wacli/SKILL.md 技能文档为核心,系统讲解如何借助 wacli CLI 让 OpenAgent 智能体在对话中直接发送 WhatsApp 文本/群组/文件消息、检索聊天记录并同步历史。读完本文,你将掌握 wacli 技能的全部命令用法、JID 与存储目录等关键参数,以及 OpenAgent 中技能从 skills/ 目录加载到注入系统提示词(load_skill)的完整实现链路。
技能定位:Agent 与 WhatsApp 之间的桥
skills/wacli/SKILL.md 是一个典型的 OpenAgent 技能(Skill)文件,其 front matter 中声明:
---
name: wacli
description: Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI.
homepage: https://wacli.sh
metadata:
{
"emoji": "📱",
"requires": { "bins": ["wacli"] }
}
---
它解决的核心问题是:当用户在对话中提出"给某人发 WhatsApp 消息"、"同步我的 WhatsApp 历史"、"在聊天记录里检索某条信息"等诉求时,Agent 应优先调用本技能所描述的 wacli CLI 命令来完成操作,而不是凭模型记忆猜测。技能正文开篇即给出明确的触发约定:
Use
wacliwhen the user asks you to message someone on WhatsApp or to sync/search WhatsApp history.
从元数据看,requires.bins 声明了运行本技能的前提——系统必须存在 wacli 可执行文件。这意味着在使用该技能前,需要先安装 wacli 并保证其在 PATH 中(仓库内不包含 wacli 二进制,技能只负责告诉 Agent 如何使用它)。仓库解析器 skillmd/skillmd.go 会把整段 metadata 作为原始文本存入 Skill.Metadata 字段,并显式提取其中的 emoji(📱);requires.bins 这类声明式依赖标注可供上层在触发技能时核对运行环境。
技能文件的加载原理:SKILL.md 如何进入 Agent 上下文
在深入命令细节之前,先理解这条技能在 OpenAgent 中的"生命周期",有助于你理解技能正文为何如此精炼:
-
目录扫描加载:服务启动时,object/init.go 的
initSkillsFromFolder()会在可执行文件旁或当前工作目录下查找skills/目录,对每个子目录调用LoadSkill(dir);若磁盘上没有skills/目录,则回退到嵌入的 skills 文件系统。 -
解析与入库:object/skill.go 的
LoadSkill基于 skillmd.LoadFolder 读取{dir}/SKILL.md与可选的references/目录,生成Skill对象(Owner 默认admin,State 为Active)并入库;技能名称缺失时会回退为目录名。解析细节(front matter 支持单引号/双引号/裸值、未闭合 front matter 的处理、references 目录只读取文件不读子目录等)都有对应测试用例验证,见 skillmd/skillmd_test.go。 -
注入系统提示词:当某个 Store 配置了
Skills列表时,controllers/message_answer.go 会调用object.GetSkillsCatalog(),把"技能使用规则 + 技能目录"追加进store.Prompt。object/skill.go 生成的目录形如:## Skills Usage Rules - If the user explicitly mentions a skill by name, you MUST call load_skill for that skill before answering. - If the user's request is clearly about a listed skill's domain, you MUST load that skill before giving procedural, policy, workflow, or step-by-step guidance. - Do not answer from general memory when a relevant listed skill exists but has not been loaded. - If the user asks what skills are available, answer from the catalog below instead of giving a generic summary of your broad abilities. ## Skills Catalog You have access to the following skills. Do not assume all details are already loaded. If a skill looks relevant, call the load_skill tool to load its full instructions before relying on it. - wacli description: Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI. | type: built-in -
按需加载正文:Agent 判定 wacli 相关时,调用内置
load_skill工具(tool/skill.go)加载完整正文。该工具由 object/merge_agent_tools.go 通过NewLoadSkillBuiltin注册,受allowedSkillNames(即 Store 的 Skills 列表)约束,未启用会返回skill is not enabled for this store;加载内容由 LoadSkillPromptContent 生成——正文 + 可选的## Available References列表或指定 reference 全文。
这种"先目录、后正文、按需加载"的渐进式披露设计,正是技能正文可以短小精悍、聚焦于命令速查的原因所在。
安全约束:发送前的"确认"护栏
技能正文对发送类操作给出了三条硬性安全规则:
- 必须获得明确的收件人 + 消息文本(Require explicit recipient + message text);
- 发送前确认收件人与消息内容(Confirm recipient + message before sending);
- 任何信息有歧义时,先提问澄清,不要擅自猜测后发送(If anything is ambiguous, ask a clarifying question)。
这三点对应到 Agent 的实操行为是:当用户说"帮我给小王发个消息"但未提供完整号码、或消息内容不明确时,Agent 应当先列出待确认信息向用户求证,而非直接执行 wacli send。这是技能文档中少有的"约束型"条款,也是 WhatsApp 这类强身份绑定 IM 渠道的合规底线。
认证与历史同步:三个命令搭建数据通道
wacli 的接入从认证开始,技能正文给出的命令组合是:
| 命令 | 作用 |
|---|---|
wacli auth |
QR 登录 + 首次同步(QR login + initial sync) |
wacli sync --follow |
持续同步模式(continuous sync),跟随新消息 |
wacli doctor |
环境/连接诊断,排查登录与同步问题 |
建议的实际落地顺序为:
- 先执行
wacli doctor检查 CLI 与运行环境是否就绪; - 执行
wacli auth完成二维码扫码登录,这一步同时触发首次全量同步,把历史聊天数据落到本地; - 后续如需保持数据新鲜,启动
wacli sync --follow做持续增量同步。
技能的 Notes 一节特别提醒:历史回填(backfill)要求手机保持在线,且结果是 best-effort(尽力而为)的——这源于 WhatsApp 个人账号的端到端机制,Agent 在执行回填后若发现部分消息缺失,属于预期内的行为,应向用户如实说明。
查找会话与消息:用查询缩小检索范围
同步完成后,Agent 需要先"找到目标会话",再"定位具体消息",技能正文给出了两级检索命令:
# 列出会话,按名称或号码过滤,最多返回 20 条
wacli chats list --limit 20 --query "name or number"
# 在指定会话(--chat <jid>)中搜索消息
wacli messages search "query" --limit 20 --chat <jid>
# 按时间窗口搜索,例如查找 2025 年内的 "invoice" 相关消息
wacli messages search "invoice" --after 2025-01-01 --before 2025-12-31
参数语义拆解:
--limit:限制返回条数,防止检索结果淹没上下文窗口;--query:会话过滤条件,可填联系人姓名或号码片段;--chat <jid>:把搜索范围限定到某个具体会话(JID 格式见下文);--after/--before:时间窗口过滤,配合日期格式YYYY-MM-DD,适合"查某段时间内关于某事的聊天"这类典型场景。
历史回填:补齐不完整的历史
当本地历史存在缺口(例如仅部分同步、或需要更早的数据)时,使用回填命令:
wacli history backfill --chat <jid> --requests 2 --count 50
参数含义:
--chat <jid>:指定要回填的会话;--requests 2:发起 2 次回填请求;--count 50:每次请求拉取 50 条消息。
如 Notes 所述,回填需要手机在线,且"best-effort"意味着不保证每次请求都能取满 --count 条数。在 OpenAgent 场景中,Agent 应在执行前先通过 wacli chats list 确认 JID 存在,再回填,并在结果不足以回答问题时如实告知用户。
发送消息:文本、群组与文件
技能正文覆盖了三种发送形态,对应三类高频需求:
# 文本消息(个人号码,E.164 格式)
wacli send text --to "+14155551212" --message "Hello! Are you free at 3pm?"
# 群组消息(JID 形如 <id>@g.us)
wacli send text --to "1234567890-123456789@g.us" --message "Running 5 min late."
# 文件消息(附带 caption 说明文字)
wacli send file --to "+14155551212" --file /path/agenda.pdf --caption "Agenda"
要点:
--to支持两类收件人:个人号码(带国家码的 E.164 格式,如+14155551212)与群组 JID(如1234567890-123456789@g.us);--message为文本内容,可直接使用自然语言,Agent 会原样传递;--file为待发送文件的路径,--caption为文件配文,适合发送 PDF、图片等附件(例如把生成的 agenda.pdf 直接发给客户)。
所有发送操作都必须先满足上文"安全约束":确认收件人号码/群组无误、消息内容正确后,方可执行。
关键概念:JID、存储目录与结构化输出
技能正文的 Notes 一节集中解释了三个容易被忽略的核心概念:
1. JID(Jabber/WhatsApp ID)
WhatsApp 的会话标识符(JID)有两种形态,直接聊天与群组形态不同:
- 直接聊天:
<number>@s.whatsapp.net,如+14155551212@s.whatsapp.net; - 群组:
<id>@g.us,如1234567890-123456789@g.us。
技能明确建议:不确定 JID 时用 wacli chats list 查询,而不是凭记忆拼写——这是避免"找不到会话/发错群"的最可靠手段。
2. 存储目录
本地数据默认存放在 ~/.wacli,可用 --store 参数覆盖路径。这意味着:
- 认证凭证、同步索引与消息数据库都在该目录下;
- 多环境/多账号场景可通过
--store隔离数据; - Agent 排查问题时,可结合
wacli doctor检查该目录的完整性与可读性。
3. --json 结构化输出
技能建议在程序解析场景下使用 --json 标志获取机器可读输出:
wacli chats list --limit 20 --json
wacli messages search "invoice" --after 2025-01-01 --before 2025-12-31 --json
对于 OpenAgent 这类由 LLM 驱动的 Agent,结构化 JSON 比人类友好的文本输出更利于:
- 可靠地提取 JID、消息时间戳、发件人等字段;
- 降低解析歧义,避免模型"看走眼";
- 支持后续的会话级二次检索(拿返回的 JID 再执行
messages search --chat <jid>)。
wacli 技能与项目内其他 WhatsApp 通道的关系
需要厘清的是:wacli 是个人账号级的本地 CLI 方案(扫码登录个人 WhatsApp 账号,读写个人历史);而仓库中 pipe/whatsapp.go 实现的是 WhatsApp Business API(Cloud API) 通道,基于 https://graph.facebook.com/v19.0,需要 accessToken / phoneNumberId / verifyToken,面向企业号的 webhook 收发。二者定位互补:
- 面向个人日常消息的收发与历史检索 → 使用
wacli技能; - 面向企业客服/自动化消息管道 → 使用 pipe 层的 WhatsAppPipe。
作为对比,web 前端 provider-setting.ts 中也登记了 WhatsApp Business 的连接配置(EAAxxx... 格式的 Access Token)。理解这条边界,能帮助你在对话中准确判断该让 Agent 走 wacli 命令,还是走企业 API 通道。
实战速查表
将技能正文的完整命令汇总如下,便于直接复制使用:
| 场景 | 命令 |
|---|---|
| 首次登录 + 同步 | wacli auth |
| 持续同步 | wacli sync --follow |
| 环境诊断 | wacli doctor |
| 列出会话 | wacli chats list --limit 20 --query "name or number" |
| 会话内搜索 | wacli messages search "query" --limit 20 --chat <jid> |
| 时间窗搜索 | wacli messages search "invoice" --after 2025-01-01 --before 2025-12-31 |
| 历史回填 | wacli history backfill --chat <jid> --requests 2 --count 50 |
| 发送文本 | wacli send text --to "+14155551212" --message "Hello! Are you free at 3pm?" |
| 发送群组消息 | wacli send text --to "1234567890-123456789@g.us" --message "Running 5 min late." |
| 发送文件 | wacli send file --to "+14155551212" --file /path/agenda.pdf --caption "Agenda" |
配套约束(贯穿所有命令):
- 发送前必须确认收件人 + 内容,有歧义先提问;
- 检索/解析场景优先加
--json; - 默认数据目录
~/.wacli,可用--store覆盖; - 回填依赖手机在线,结果为 best-effort;
- JID 拿不准时用
wacli chats list确认。
小结
skills/wacli/SKILL.md 是一份"命令即文档"的高密度技能:以 auth/sync 建立数据通道,以 chats/messages 检索历史,以 history backfill 补齐缺口,以 send 完成文本、群组、文件的对外发送,再用安全约束与 JID/--json 等细节把误操作风险降到最低。配合 OpenAgent 从 object/init.go 目录扫描、object/skill.go 提示词注入到 tool/skill.go load_skill 按需加载的完整链路,它可以让 Agent 在"给客户发文件、查某段时间的聊天记录、群内报备迟到"等真实场景中直接完成任务,无需任何人工复制粘贴。