lawrencewzen / wx-bot

wx-bot 
 把微信接入到 Personal Agent（Grok、Muse 等）。 
 微信消息经腾讯官方 ClawBot / iLink 进入本机 wx-bot ，
 落盘后推送给你的 Agent（webhook）或由 Agent 拉取（pull）；Agent 再用 wx-bot send 发回微信。
---
> [!IMPORTANT]
> **🤖 如果你是 Agent：先读 `AGENTS.md`，找到你对应的文件，按步骤执行。**
> Grok Bot：创建 routine 后，**必须在聊天回复里直接发出「Webhook URL」和「Webhook key」两个字段链接**，用户自己找不到。
## 特点
- **不丢消息**：先落盘到本地 SQLite 收件箱，再确认；投递失败自动重投。
- **只出站**：不对外开端口，本地 API 只监听 loopback。
- **默认白名单**：只理会扫码登录的那个微信号。
- **两种投递**：`webhook` 推给 Agent，`pull` 由 Agent 来取。
- 收发文本、图片、语音（带转写）、文件、视频。支持 Linux / macOS。
 [code] 
## 快速开始
把这句话发给你的 Grok Bot 或 Muse：
 [code] 
它会自己装好，你只需要**用微信扫码**（Grok 还要你点两个链接，把 URL 贴回聊天、把 key 填进加密框）。
> [!NOTE]
> 装好后**先用微信给 ClawBot 发一条消息**，Agent 才能回复你。
其他接法：Pi Durable（Docker） · Cloudflare Workers · 手动安装 ↓
### 手动安装
 [code] 
编辑 `~/.config/wx-bot/config.json`，参考 webhook 示例 或 pull 示例；密钥写进 `~/.config/wx-bot/env`，配置里用 `env:VAR` 引用。要放行别的微信号，见白名单。
 [code] 
## 对接
**收**：每条消息是一个 JSON 事件，含 `event_id`、`from_wxid`、`text`、`voice_text`、`media[]`（本机文件路径）。**同一事件可能送达多次，按 `event_id` 去重。**
- webhook：POST 到你的地址，返回 2xx 即送达。
- pull：`wx-bot inbox pull --lease 5m` 领取，处理完 `wx-bot inbox ack `。
**回**：
 [code] 
**只发纯文本**，微信不渲染 Markdown。事件格式、签名、本地 HTTP API、`alert` 异常通知等细节见 `docs/protocol.md`。
## 运维
| 做什么 | 命令 |
| --- | --- |
| 看状态 | `wx-bot status` |
| 排查收不到消息 | `wx-bot health --grace 0` |
| 升级（不用重新扫码） | `wx-bot update` |
| 回滚 | `wx-bot update --version ` |
| 卸载 | `wx-bot uninstall --yes`（加 `--keep-data` 保留登录） |
v0.4.0 之前的版本，重跑一遍 `install.sh` 即可升级。也可以直接让 Agent「把 wx-bot 升级到最新版」。
## 常见问题
| 现象 | 处理 |
| --- | --- |
| Agent 收不到消息 | 先跑 `wx-bot health --grace 0`，按提示处理；详见断线排查 |
| `send` 报 `no context_token` | 对方还没给 ClawBot 发过消息，先发一条 |
| 日志出现 `-14` / `expired` | 登录过期，重新 `wx-bot login ` |
| 只能走代理出网 | 把 `https_proxy` 写进 `~/.config/wx-bot/env`，重启服务 |
| `status` 里有 `dead` 消息 | 被 Agent 拒绝（400/413/422）或超过 7 天，看日志 |
| 二维码要发给别人扫 | `wx-bot login --qr-png ./qr.png` |
## 开发
 [code] 
`packages/core` 协议与收件箱 · `packages/cli` 命令行 · `packages/cloudflare` Workers 部署
---
本项目调用腾讯官方 ClawBot / iLink 接口，但与腾讯无关，不是腾讯官方产品。