WeixinClawBot Send — WeixinClaw机器人 发送

wxclaw机器人-发送 这个技能解决什么问题

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

这个技能通过 wxclaw机器人 命令行工具 让 代理 能主动给微信用户推送消息， 包括文本、图片、视频、文件。配合 cron 可实现定时任务。

前置条件 Node.js >= 20 npm 安装 -g @claw-lab/wxclaw机器人-命令行工具 OpenClaw-weixin 已登录（凭证在 ~/.OpenClaw/OpenClaw-weixin/accounts/）

验证: wxclaw机器人 accounts --json

快速上手 wxclaw机器人 发送 --text "消息内容" --json wxclaw机器人 发送 --file ./photo.jpg --json wxclaw机器人 发送 --file ./报告.pdf --text "请查收" --json

什么时候用什么 主动发文本消息 → wxclaw机器人 发送 --text "msg" --json 主动发文件/图片 → wxclaw机器人 发送 --file ./path --json 检查账号状态 → wxclaw机器人 accounts --json 编程调用 → see references/programmatic-API.md

命令参考 发送 wxclaw机器人 发送 --text "message" --json wxclaw机器人 发送 --to "user@im.wechat" --text "你好" --json wxclaw机器人 发送 --file ./photo.jpg --json wxclaw机器人 发送 --file ./报告.pdf --text "请查收" --json wxclaw机器人 发送 --file "https://example.com/img.png" --json echo "日报已生成" | wxclaw机器人 发送 --json wxclaw机器人 发送 --text "test" --dry-运行

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

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

图片: .png .jpg .jpeg .gif .网页p .bmp 视频: .mp4 .mov .网页m .mkv .avi 文件: 其他所有 accounts wxclaw机器人 accounts --json

返回: [{"id":"<机器人Id>-im-机器人","配置d":true,"baseUrl":"..."}]

账号发现机制

命令行工具 自动从 ~/.OpenClaw/OpenClaw-weixin/accounts/*.json 发现账号。 每个文件包含 令牌, baseUrl, userId（默认 --to 目标）。

机器人 ID 从 令牌 运行时提取（不是硬编码的） 账号 ID 会在 OpenClaw-weixin 升级或重新注册后变化 --to 默认是账号文件里的 userId（绑定用户） 设了 WXCLAW_令牌 环境变量会覆盖文件发现 上下文 令牌（主动推送关键）

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

命令行工具 自动读取 {accountId}.上下文-令牌s.json（和账号文件同目录）。 这个文件由 OpenClaw-weixin 维护，格式是 userId → 上下文令牌 的映射。 不需要手动配置——用户给机器人发过消息后 OpenClaw-weixin 会自动保存。

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

升级 OpenClaw-weixin 后，务必用 wxclaw机器人 accounts --json 验证。

代理 集成

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

结果=$(wxclaw机器人 发送 --text "任务完成" --json) 结果=$(wxclaw机器人 发送 --file ./图表.png --text "每日指标" --json)

成功: {"ok":true,"to":"user@im.wechat","命令行工具entId":"..."} 失败: {"ok":false,"error":"..."} 退出码: 0 = 命令行工具 执行成功, 1 = 失败

注意: exit 0 只代表 命令行工具 跑完了，不代表消息送达。看 ok 字段。

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

频率限制是服务端的，同一个 机器人 令牌 下所有客户端共享配额。

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

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

{"ok":false,"error":"发送 fAIled: ...","errorKind":"timeout","retryable":true}

errorKind 含义 retryable timeout 请求超过 15 秒 true dns DNS 解析失败 true connection 连接重置 / socket hang up true network 连接被拒 / 主机不可达 / fetch fAIled true tls 证书或 TLS 错误 false unknown 未分类错误 false

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

常见坑 必须用 --json —— 不带的话输出是人类可读格式，没法解析 看 ok 字段 —— exit 0 只代表 命令行工具 跑了，不代表消息到了 别紧循环重试 ret=-2 —— 至少等 5-10 秒 大文本用 stdin —— echo "..." | wxclaw机器人 发送 --json，避免 shell 引号问题 文件会加密上传到微信 CDN —— 大文件可能要等一会 环境变量 变量 用途 WXCLAW_令牌 覆盖 机器人 令牌 (机器人@im.机器人:your-令牌) WXCLAW_BASE_URL 覆盖 API 端点 (默认: https://ilinkAI.weixin.qq.com)

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