微信主动推送 skill#

装上就能用： wechat-push "消息" → 用户手机微信收到

这是什么#

一个让本地 Agent 主动 向用户手机微信推送消息的工程化方案。绕过微信官方的"24 小时客服窗口"限制（用户必须先发消息、Agent 才能在 24 小时内回复），实现真正的"主动告知"。

何时使用#

用户表达需要#

• "我想让 Agent 主动发微信"
• "微信主动推送怎么搞"
• "怎么推消息到用户微信"
• "绕过 24 小时窗口"

用户报告故障#

• "推送失败 / 收不到"
• "脚本说 SUCCESS 但用户没收到"（假成功）
• "推消息 ret=-2 / errcode=-14"
• "session timeout"
• "换了账号还是推不出去"

核心原则（先记住这 3 条）#

1. 必须走 OpenClaw 内部通道 openclaw message send —— 裸 curl ilink 在 macOS 上 99% 不通
2. 必须用活跃 bot 账号 —— 账号目录里可能有多个 *@im.bot.json，按 mtime 选最近的
3. 必须校验业务层响应 —— Sent via + exit 0 双条件 = 真成功；只看 HTTP 200 = 假成功

完整链路（5 跳）#

text

① 触发层（cron / Agent / 健康检查 / 手动）
    ↓
② 推送脚本  wechat-push.py
    ↓
③ 通道选择  →  openclaw message send CLI
    ↓
④ OpenClaw 微信插件（node 进程，长连接常驻）
    ↓
⑤ ilink 服务端  →  POST /ilink/bot/sendmessage
    ↓
⑥ 用户手机微信

详见 references/protocol-notes.md。

装上即用#

bash

# 一键安装
bash ~/.openclaw/skills/wechat-push-skill/install.sh

# 安装过程中会：
#   1. 检查 openclaw CLI
#   2. 探测活跃 bot 账号
#   3. 引导配置 openid
#   4. 链接命令到 ~/.local/bin
#   5. 跑一次 verify 验证链路

用法（装完就能用）#

bash

# 推一条消息
wechat-push "你好"

# 推给指定 openid（临时覆盖配置）
wechat-push --to oXXXXXXXXXXXXXXXXX@im.wechat "你好"

# 静默推送（不响通知，用于探活）
wechat-push --silent "probe test"

# 预演：只打印将使用的 openid/account，不发送
wechat-push --dry-run "你好"

# 链路 5 跳自检
wechat-push-verify

# 故障排查
wechat-push-doctor

文件结构#

text

wechat-push-skill/
├── SKILL.md              ← 你正在看
├── README.md             ← 公开说明（中英）
├── install.sh            ← 一键安装
├── bin/
│   ├── wechat-push       ← 主命令
│   ├── wechat-push-verify   ← 链路自检
│   └── wechat-push-doctor   ← 故障排查
├── lib/
│   ├── wechat_push.py    ← 推送核心
│   ├── ilink_probe.sh    ← 探活
│   └── (config 自动生成在 ~/.config/wechat-push/)
├── templates/
│   └── config.example    ← openid 配置模板
└── references/
    ├── protocol-notes.md ← ilink 协议关键点
    └── troubleshooting.md ← 6 种故障模式库

4 个自动化 cron（可选）#

安装后可加这些 cron 自动化推送：

cron频率作用wechat-monitor-5min5m看 Mac mini 微信插件状态ilink-probe-15min15msilent 探活，状态变 DOWN 时主动告警daily-morning-briefing0 8 * * *早报（C 档详细版）daily-evening-summary0 21 * * *晚报bash

# 加探活 cron（最常用）
openclaw cron add ilink-probe-15min \
  --every "15m" --session main \
  --system-event "触发 ilink 探活，跑 wechat-push-skill 的 ilink_probe.sh"

6 种故障模式（速查表）#

现象根因修法脚本说 SUCCESS，用户没收到假成功（只看 HTTP 200）用本 skill v2，校验 Sent via``errcode=-14, "session timeout"bot session 被微信踢换活跃账号 / 重新扫码ret=-2 / HTTP 000 裸 curl裸 ilink 网络层不通必须走 openclaw message send``getupdates 有响应， sendmessage 推不出半活状态plugin 内部状态不同步，重启 plugin推了 8 次后突然全失败bot session 静默被踢等几小时自动恢复 / 重新扫码推一次 silent 成功，推非 silent 失败openid 不对确认 --to 是目标 openid

详见 references/troubleshooting.md。

验证标准#

装完跑 wechat-push-verify， 所有 5 跳都 ✅ OK = 装成功。

推一条测试消息 wechat-push "test from skill"， 用户手机微信实际收到 = 真成功。脚本 exit 0 只能说明命令层通过，不能替代手机端确认。

局限#

• ❌ 不支持多人 / 群发（每个用户单独 install）
• ❌ 不支持模板消息（卡片 / 图文）
• ❌ 不支持主动告警 cron（自己加）
• ❌ 不支持早报/晚报生成（自己写生成逻辑）
• ✅ 推消息（单条文本）= 唯一核心能力

引用#

• 推送脚本核心： lib/wechat_push.py（~180 行）
• 探活脚本： lib/ilink_probe.sh
• 安装器： install.sh
• 公开说明： README.md
• 协议笔记： references/protocol-notes.md
• 故障库： references/troubleshooting.md