微信 ClawBot 主动发送
通过腾讯 iLink Bot API 向个人微信主动发送消息。通道基于微信官方「ClawBot」插件（我-设置-插件-微信ClawBot 扫码配对），与 WorkBuddy 内置的 weixinClawBot 通道同源，复用已配对凭证即可发送，无需每次扫码。
核心功能
- 主动发送文本消息到已配对的微信账号（
weixin_send.py），支持失败自动重试 - 监听 + 回复：捕获用户最新消息的实时
context_token，用于回复场景（weixin_listen_send.py listen/send） - 自动选择最新活跃 bot 凭证（
~/.workbuddy/claw-state/weixin/*.cursor.json），无需手动配置 - 友好错误提示：凭证过期 / 网络异常 / 配置缺失时给出中文可读的处理指引
- 启动自检：配置文件缺失或损坏时明确提示下一步操作
前置条件
- 微信已安装 ClawBot 插件并扫码配对（
我-设置-插件-微信ClawBot-开始扫一扫，微信需 v8.0.70+） - WorkBuddy 已配置微信通道（
~/.workbuddy/settings.json的claw.channels.weixinClawBot） - Python 3.8+（标准库即可，无第三方依赖）
- 平台支持：macOS 开箱即用；Windows/Linux 需自行保证 WorkBuddy 凭证路径可读（脚本已做路径兼容）
使用方式
① 主动发送（最常用）
python3 scripts/weixin_send.py "消息内容"
自动完成：读取最新 cursor → 提取 botToken → 发送。成功返回 message_id。网络波动时最多自动重试 3 次。
② 监听 + 回复（需要实时 token）
python3 scripts/weixin_listen_send.py listen # 捕获用户最新消息的 context_token
python3 scripts/weixin_listen_send.py send "回复内容" # 用捕获的 token 发送
③ 在 AI 对话中触发（推荐）
直接对 AI 说：
- 「给微信发消息：今晚记得买牛奶」
- 「给微信推一条：会议改到下午3点」
- 「每天早8点给微信推天气」→ 配合定时任务即可
AI 会调用 weixin_send.py 完成发送。
使用场景示例
| 场景 | 怎么做 |
|---|---|
| 待办/备忘推送 | 让 AI 把待办内容发到微信，随手可查 |
| 定时日报 | 配置定时任务，每天固定时间调用 weixin_send.py 推送到微信 |
| 长文本转微信 | 把长文章/摘要作为参数传入，微信端收到纯文本 |
| 脚本通知 | 在 CI/脚本末尾调用 python3 weixin_send.py "部署完成" 实时通知 |
| 回复微信消息 | weixin_listen_send.py listen 捕获 token 后用 send 回复 |
关键原理（必读）
| 要点 | 说明 |
|---|---|
| API | POST https://ilinkai.weixin.qq.com/ilink/bot/sendmessage |
| 凭证 | Authorization: Bearer {botToken} + AuthorizationType: ilink_bot_token + X-WECHAT-UIN（随机 base64） |
| 主动发送 | 不要携带 context_token——带错 token 会被服务端静默丢弃（仍返回 message_id 但实际不送达） |
| 回复场景 | 必须携带用户最新消息自带的 context_token（bot 隔离、随消息轮换），否则同样收不到 |
| 成功标志 | 返回 message_id（不是 ret=0） |
| 活跃凭证 | botToken 藏在 ~/.workbuddy/claw-state/weixin/{bot}_im.bot.cursor.json 的 get_updates_buf（base64 内嵌 {botId}@im.bot:{token}） |
| 能力边界 | 当前仅支持文本消息（不支持图片/文件/语音）；消息会以纯文本形式到达微信 |
安全边界
- ⚠️ botToken / context_token 等同微信登录态，不得外泄、不得提交公开仓库、不得在日志中明文打印
- 只向
ilinkai.weixin.qq.com发起请求，不访问其他域名 - 仅发送用户授权范围内的消息，不群发、不骚扰
- 凭证过期（
errcode=-14）时引导用户重新扫码，不绕过验证 - 所有凭证（userId/botToken）均从本机配置动态读取，无硬编码
错误处理
| 现象 | 原因 | 处理 |
|---|---|---|
{"errcode":-14,"errmsg":"session timeout"} |
bot 凭证过期 | 微信重新打开 ClawBot 扫码，或 hermes gateway setup 重扫 |
返回 message_id 但用户未收到 |
携带了错误的 context_token | 主动发送时移除 context_token 字段 |
HTTP 403/401 |
凭证无效 | 检查 cursor 文件是否存在、bot 是否仍配对 |
| 监听超时 | 消息被 WorkBuddy 轮询先消费 | 直接用 weixin_send.py 主动发送（无需监听） |
| 找不到配置文件 | WorkBuddy 未安装或未配对 | 按脚本提示路径检查，先完成扫码配对 |
| 网络失败 | 断网/服务端波动 | 脚本已自动重试 3 次；仍失败请检查网络 |
FAQ（常见问题）
Q: 为什么发送成功了（有 message_id），但微信没收到？
A: 最常见原因是主动发送时带了错误的 context_token。主动发新消息不要带 context_token；只有"回复"场景才需要用户消息自带的 token。
Q: 提示"session timeout"怎么办？
A: 微信登录会话过期了。打开微信「我-设置-插件-微信ClawBot」，重新扫码配对即可，之后凭证会自动更新。
Q: 换电脑 / 换微信账号能用吗？
A: 能。脚本所有凭证均从本机配置动态读取（无硬编码），换环境后只要重新扫码配对即可。
Q: 支持发图片 / 文件吗？
A: 当前版本仅支持文本消息。图片/文件需额外实现媒体上传接口（见 references/ilink-api.md 的消息类型）。
Q: 支持 Windows 吗？
A: 脚本本身是 Python 标准库、跨平台；但凭证路径以 macOS（WorkBuddy 桌面版）为主。Windows 上若 WorkBuddy 凭证路径不同，需调整 SETTINGS_PATH。
相关文件
scripts/weixin_send.py— 主动发送工具（含重试 + 友好错误提示）scripts/weixin_listen_send.py— 监听/回复工具references/ilink-api.md— iLink API 协议细节（逆向自 WorkBuddy 源码）
