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

快速上手#

bash

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

什么时候用什么#

text

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

命令参考#

send#

bash

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

参数说明--text <msg>消息文本。 "-" 显式读 stdin--file <path>本地文件或 URL（图片 / 视频 / 文件）--to <userId>目标用户 ID。默认: 账号绑定用户--account <id>指定账号。默认: 第一个可用的--jsonJSON 格式输出。 编程调用必须带上--dry-run预览，不发送

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

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

accounts#

bash

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 判断是否成功。

bash

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 字段。

错误处理#

错误含义处理ret=-2频率限制（每 bot 约 7 条 / 5 分钟，所有客户端共享）等 60-120 秒重试，别搞紧循环ret=-14会话过期通过 openclaw 重新登录No account found凭证缺失跑 wxclawbot accounts 排查CDN upload error文件上传失败检查文件大小 / 格式，重试Request timeout网络问题（15 秒超时）重试

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

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

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

json

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

errorKind含义retryable``timeout请求超过 15 秒truednsDNS 解析失败trueconnection连接重置 / socket hang uptruenetwork连接被拒 / 主机不可达 / fetch failedtruetls证书或 TLS 错误falseunknown未分类错误false

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

常见坑#

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

环境变量#

变量用途WXCLAW_TOKEN覆盖 bot token ( bot@im.bot:your-token)WXCLAW_BASE_URL覆盖 API 端点 (默认: https://ilinkai.weixin.qq.com)

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