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。

WeChat ──iLink──▶ wx-bot (inbox) ──webhook / pull──▶ Agent
       ◀─────────────────────────── wx-bot send ────┘

快速开始

把这句话发给你的 Grok Bot 或 Muse：

帮我用 wx-bot 把微信接入你：https://github.com/lawrencewzen/wx-bot

它会自己装好，你只需要用微信扫码（Grok 还要你点两个链接，把 URL 贴回聊天、把 key 填进加密框）。

[!NOTE]

装好后先用微信给 ClawBot 发一条消息，Agent 才能回复你。

其他接法：Pi Durable（Docker） · Cloudflare Workers · 手动安装 ↓

手动安装

curl -fsSL https://raw.githubusercontent.com/lawrencewzen/wx-bot/main/install.sh | bash
源码安装：git clone 后运行 ./install.sh --service（--service 同时装开机自启）

编辑 ~/.config/wx-bot/config.json，参考 webhook 示例 或 pull 示例；密钥写进 ~/.config/wx-bot/env，配置里用 env:VAR 引用。要放行别的微信号，见白名单。

wx-bot login xiaox          # 微信扫码
wx-bot run                  # 启动
wx-bot health --grace 0     # 退出码 0 才算装好

对接

收：每条消息是一个 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 <event_id>。

wx-bot send --binding xiaox --to  --text - <<'EOF'
回复内容（引号、$ 都不用转义）
EOF
wx-bot send --binding xiaox --to  --image ./a.jpg   # 还有 --file / --video

只发纯文本，微信不渲染 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 |

开发

bun install
bun run typecheck && bun test
cd packages/cli && bun run scripts/cross.ts   # 交叉编译到 dist/

packages/core 协议与收件箱 · packages/cli 命令行 · packages/cloudflare Workers 部署

---

本项目调用腾讯官方 ClawBot / iLink 接口，但与腾讯无关，不是腾讯官方产品。