WeixinClawBot Send

主动给微信用户发消息（文本、图片、视频、文件）。微信机器人默认只能被动回复， 这个技能让 agent 能主动推送消息到用户微信。 Use when: 主动发微信, 定时提醒, 告警通知, 推送报告, 发图片/文件到微信, proactive WeChat message, push notification to...

Security Scan

The skill's code, install spec, and runtime instructions match its stated purpose (proactively sending WeChat text/media) and request only the expected token/config files; be aware it can read local files (for attachments) and the account state directory, which is expected but enables potential data exfiltration if misused.

Purpose & Capability

Name/description, required binary (wxclawbot), install (npm package @claw-lab/wxclawbot-cli) and primaryEnv (WXCLAW_TOKEN) align with a CLI that sends WeChat messages. Required config path (~/.openclaw/openclaw-weixin/accounts/) and code that reads account/context-token files are consistent with stated functionality.

Instruction Scope

SKILL.md instructs the agent to run wxclawbot CLI commands and to use --json for programmatic calls. The included code reads account files and context-token files from the declared account directory and will read arbitrary local files or download URLs when sending attachments (readFileOrUrl). Reading those files is necessary for file-send functionality but also means the agent/CLI can send any local file the agent is instructed to send.

Install Mechanism

Install uses an npm package (@claw-lab/wxclawbot-cli) that provides the wxclawbot binary — a standard, traceable install mechanism for a Node CLI. No suspicious download hosts or extract-from-arbitrary-URL steps are present.

Credentials

Declared primary env WXCLAW_TOKEN and optional WXCLAW_BASE_URL are appropriate. The code also honors OPENCLAW_STATE_DIR and CLAWDBOT_STATE_DIR as state-dir overrides (used to locate account files) but those env vars are not declared in metadata — this is minor but worth noting. Access to the accounts directory and context-token files is required for operation; these files contain tokens and are therefore sensitive.

Persistence & Privilege

Skill is user-invocable, not always-on, and does not request system-wide persistent privileges or modify other skills' configs. It runs as a CLI invoked by the agent (normal behavior).

Assessment

This skill appears to do exactly what it claims: install a CLI that uses your WeChat bot token and account files to send text and media. Before installing, verify the npm package and GitHub repo are trusted and that the WXCLAW_TOKEN you provide has only the needed privileges. Be aware: sending files requires the CLI to read local files or download URLs — an agent with this skill could be instructed to send sensitive local files (secrets, keys, documents) to a WeChat user, so only grant the skill to agents you trust and avoid leaving highly sensitive data in paths the agent can access. Also note the code respects OPENCLAW_STATE_DIR/CLAWDBOT_STATE_DIR (not listed in metadata) for locating account data — if you use custom state dirs, ensure they contain only expected account files. Rotate tokens if you suspect misuse and validate account discovery (wxclawbot accounts --json) after install.

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 "[e-mail]" --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>	指定账号。默认: 第一个可用的
--json	JSON 格式输出。编程调用必须带上
--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":"[e-mail]","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 模式下，传输层失败会包含额外字段:

{"ok":false,"error":"send 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 只代表 CLI 跑了，不代表消息到了
• 别紧循环重试 ret=-2 —— 至少等 5-10 秒
• 大文本用 stdin —— echo "..." | wxclawbot send --json，避免 shell 引号问题
• 文件会加密上传到微信 CDN —— 大文件可能要等一会

环境变量

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

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