wxclawbot-send（wxclawbot 发送）

wxclawbot-send

这个技能解决什么问题

微信机器人（iLink Bot）只能被动回复用户消息，不能主动发起对话。 这意味着 agent 没法做定时提醒、告警推送、报告发送等主动触达场景。

这个技能通过 wxclawbot CLI 让 agent 能主动给微信用户推送消息， 包括文本、图片、视频、文件。配合 cron 可实现定时任务。

前置条件

• Node.js >= 20
• npm install -g @claw-lab/wxclawbot-cli
• openclaw-weixin 已登录（凭证在 ~/.openclaw/openclaw-weixin/accounts/）

验证: wxclawbot accounts --json

快速上手

wxclawbot send --text "消息内容" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "请查收" --json

什么时候用什么

主动发文本消息  → wxclawbot send --text "msg" --json
主动发文件/图片 → wxclawbot send --file ./path --json
检查账号状态    → wxclawbot accounts --json
编程调用        → see references/programmatic-api.md

命令参考

send

wxclawbot send --text "message" --json
wxclawbot send --to "user@im.wechat" --text "你好" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "请查收" --json
wxclawbot send --file "https://example.com/img.png" --json
echo "日报已生成" | wxclawbot send --json
wxclawbot send --text "test" --dry-run

媒体类型按扩展名自动识别:

• 图片:.png.jpg.jpeg.gif.webp.bmp
• 视频:.mp4.mov.webm.mkv.avi
• 文件: 其他所有

accounts

wxclawbot accounts --json

返回: [{"id":"<botId>-im-bot","configured":true,"baseUrl":"..."}]

账号发现机制

CLI 自动从 ~/.openclaw/openclaw-weixin/accounts/*.json 发现账号。 每个文件包含 token, baseUrl, userId（默认 --to 目标）。

• Bot ID 从 token 运行时提取（不是硬编码的）
• 账号 ID 会在 openclaw-weixin 升级或重新注册后变化
• --to 默认是账号文件里的 userId（绑定用户）
• 设了 WXCLAW_TOKEN 环境变量会覆盖文件发现

Context Token（主动推送关键）

微信要求 context_token 才能主动推送消息。没有它，消息会留在服务器上， 直到用户主动打开聊天窗口才能看到——这就不叫"主动推送"了。

CLI 自动读取 {accountId}.context-tokens.json（和账号文件同目录）。 这个文件由 openclaw-weixin 维护，格式是 userId → contextToken 的映射。 不需要手动配置——用户给机器人发过消息后 openclaw-weixin 会自动保存。

如果 context_token 缺失（新用户、token 过期），消息仍然会发送成功 （ok:true），但不会主动推送通知。

升级 openclaw-weixin 后，务必用 wxclawbot accounts --json 验证。

Agent 集成

编程调用必须用 --json。解析 JSON 判断是否成功。

result=$(wxclawbot send --text "任务完成" --json)
result=$(wxclawbot send --file ./chart.png --text "每日指标" --json)

• 成功: {"ok":true,"to":"user@im.wechat","clientId":"..."}
• 失败: {"ok":false,"error":"..."}
• 退出码: 0 = CLI 执行成功, 1 = 失败

注意: exit 0 只代表 CLI 跑完了，不代表消息送达。看 ok 字段。

错误处理

频率限制是服务端的，同一个 bot token 下所有客户端共享配额。

结构化传输错误 (v0.5.1+)

--json 模式下，传输层失败会包含额外字段:

{"ok":false,"error":"send failed: ...","errorKind":"timeout","retryable":true}

用 retryable 字段判断应该重试还是直接失败。

常见坑

• 必须用 --json —— 不带的话输出是人类可读格式，没法解析
• 看 ok 字段 —— exit 0 只代表 CLI 跑了，不代表消息到了
• 别紧循环重试 ret=-2 —— 至少等 5-10 秒
• 大文本用 stdin —— echo "..." | wxclawbot send --json，避免 shell 引号问题
• 文件会加密上传到微信 CDN —— 大文件可能要等一会

环境变量

编程接口详见 references/programmatic-api.md。