wx-bot - 把微信接入个人 Agent 的本地消息桥

wx-bot 是一个把微信接入 Personal Agent 的本地桥接工具。按项目自述，微信消息经腾讯官方 ClawBot / iLink 进入本机运行的 wx-bot，先落盘到本地 SQLite 收件箱，再推送给 Agent（webhook）或由 Agent 主动拉取（pull）；Agent 处理完后用 wx-bot send 把回复发回微信。它适合已经有一个能执行命令、能接收 HTTP 请求的 Agent（项目自述中举例 Grok、Muse），并希望用微信作为对话入口的个人用户。项目说明中明确，它只理会扫码登录的那个微信号，不支持好友消息，因此定位是「个人自用」而非群机器人或客服系统。

维护者与状态

仓库由 lawrencewzen 维护，采用 MIT 许可证。仓库创建于 2026-10-09，最后提交时间为 2026-10-23，最新 release 为 v0.5.1（2026-10-23）。截至 2026-11-05，仓库星标数为 203。从时间线看，这是一个创建不到一个月、仍在快速迭代的早期项目，版本号也停留在 0.x 阶段。

主要能力

以下能力均来自项目 README 的自述，未经独立验证：

• 不丢消息：消息先落盘到本地 SQLite 收件箱，再向来源确认；投递失败会自动重投。
• 只出站：不对外开端口，本地 API 只监听 loopback，减少暴露面。
• 只能本人使用：只处理扫码登录的那个微信号的消息，不支持好友。
• 两种投递方式：webhook 把事件推给 Agent，pull 由 Agent 主动领取。
• 多类型消息：收发文本、图片、语音（带转写）、文件、视频；支持 Linux / macOS。
• 运维命令：status 看状态、chatlog 查聊天记录、health 排查收不到消息、inbox requeue 重放已放弃的消息、update 升级（不用重新扫码）与回滚、uninstall 卸载。
• 可选聊天记录：配置项 chatlog_days 默认 0 关闭；开启后收发原文按天追加为 JSONL 并保留最近 N 天，改回 0 只停止写入、不删已有文件。项目说明称聊天记录属隐私数据，默认不写。

在对接层面，README 说明每条消息是一个 JSON 事件，含 event_id、from_wxid、text、voice_text、media[]（本机文件路径）；同一事件可能送达多次，需要按 event_id 去重。webhook 模式返回 2xx 即视为送达；pull 模式用 wx-bot inbox pull --lease 5m 领取，处理完再 ack。回复侧支持 --text、--image、--file、--video，但项目提醒只发纯文本，微信不渲染 Markdown。

使用入口

仓库地址：lawrencewzen/wx-bot。

据项目说明，最省事的方式是把一句话发给自己的 Agent，让它自行安装，用户只需用微信扫码；Grok 场景下还需要点两个链接，把 Webhook URL 贴回聊天、把 key 填进加密框。手动安装方式为：

curl -fsSL https://raw.githubusercontent.com/lawrencewzen/wx-bot/main/install.sh | bash

源码安装则是 clone 后运行 ./install.sh --service（--service 同时装开机自启）。之后编辑 ~/.config/wx-bot/config.json，密钥写进 ~/.config/wx-bot/env，配置里用 env:VAR 引用。启动流程为 wx-bot login xiaox 扫码、wx-bot run 启动、wx-bot health --grace 0 检查（退出码 0 才算装好）。README 还提到 Pi Durable（Docker）、Cloudflare Workers 等其他接法，以及 docs/protocol.md 中的事件格式、签名、本地 HTTP API 与异常通知细节。

许可与限制

许可证为 MIT。项目自述中列出的已知限制与边界包括：

• 只服务扫码登录的本人微信号，好友发来的消息收不到，这是预期行为。
• 装好后需要先用微信给 ClawBot 发一条消息，Agent 才能回复；否则 send 会报 no context_token。
• Grok Bot 等 Agent 的云电脑会自动休眠或被重置，期间 wx-bot 可能被停掉，安装的程序、服务、登录态都可能丢失；README 建议按安装步骤配置每 10 分钟的保活，登录态丢失后需重新扫码，期间收不到消息。
• 日志出现 -14 / expired 表示登录过期，需要重新 wx-bot login。
• 只能走代理出网时，需把 https_proxy 写进 ~/.config/wx-bot/env 并重启服务。
• 被 Agent 拒绝（400/413/422）或超过 7 天的消息会进入 dead 状态，需要查看日志或手动 requeue。

项目在 README 末尾声明：它调用腾讯官方 ClawBot / iLink 接口，但与腾讯无关，不是腾讯官方产品。使用前应自行评估微信账号相关的合规与稳定性风险。