wechat-bridge-linux 🤖

Linux WeChat native bridge — 把微信变成 AI Agent 的本地 API。

在 Linux 上运行官方原生微信，通过标准 Linux 接口（AT-SPI2 + SQLCipher）实现消息收发， 暴露轻量 HTTP API，供 Hermes Agent / n8n / Dify / 任意 AI 平台接入。

微信 (Linux 原生 QT) → Xvfb + AT-SPI2 + DB 读取 → HTTP API (:18400) → AI Agent

✨ 特性

特性	状态
🟢 文本消息收发 — 纯 AT-SPI2 无障碍接口，零注入	✅
🔓 本地 DB 读取 — SQLCipher 解密接收消息，零延迟	✅
🖥️ Xvfb 无头运行 — 服务器无需显示器	✅
🔌 HTTP API — 兼容 wechat-bridge 协议	✅
🔄 开机自启 — systemd 保活	✅
🛡️ 全链路自愈 — 崩溃自动恢复	✅
🖼️ 图片/文件收发	🚧
🎙️ 语音消息	🚧
👥 群聊支持	🚧

🏗️ 架构

┌──────────────────────────────────────────┐
│ Linux WeChat (QT 原生) │
│ 官方 linux.weixin.qq.com 2024+ │
│ 运行于 Xvfb :99 虚拟显示器 │
└────┬───────────────────────┬──────────────┘
│ AT-SPI2 无障碍接口 │ SQLCipher 加密 DB
▼ ▼
┌──────────────────────────────────────────┐
│ wechat-bridge-linux │
│ │
│ ┌──────────────────┐ │
│ │ DB Watcher │ ← inotify + WAL │
│ │ 密钥提取 → 解密 │ 实时新消息 │
│ └──────────────────┘ │
│ ┌──────────────────┐ │
│ │ AT-SPI2 Sender │ → 定位输入框 │
│ │ xdotool + Atspi │ 填入文字+发送 │
│ └──────────────────┘ │
│ ┌──────────────────┐ │
│ │ HTTP API (:18400)│ ← SSE 消息流 │
│ │ aiohttp │ POST /send │
│ └──────────────────┘ │
└──────────┬───────────────────────────────┘
│ Hermes Gateway 标准接口
▼
┌──────────────────────────────────────────┐
│ Hermes Agent / n8n / Dify │
└──────────────────────────────────────────┘

🚀 快速开始

前置要求

• Linux (Debian 12 / Ubuntu 22.04+ 实测)
• Python 3.10+
• 一个微信个人号

一键安装

git clone https://github.com/djasdh/wechat-bridge-linux.git
cd wechat-bridge-linux
bash scripts/install.sh

手动安装

# 1. 安装系统依赖
sudo apt install -y xvfb at-spi2-core xdotool python3-gi python3-pip
# 2. 安装 Python 依赖
pip install -r requirements.txt
# 3. 启动微信
bash scripts/start-wechat.sh
# 4. 扫码登录# 5. 启动 bridge
python -m src.main

验证

# 健康检查
curl http://127.0.0.1:18400/health
# 发送消息
curl -X POST http://127.0.0.1:18400/send \
-H "Content-Type: application/json" \
-d '{"wxid": "filehelper", "text": "你好，世界！"}'# 查看联系人
curl http://127.0.0.1:18400/contacts

📡 API 文档

GET /health

Bridge 健康状态。

GET /messages/stream

SSE 消息流，实时推送新消息。

POST /send

发送消息。

{ "wxid": "目标ID", "text": "消息内容" }

GET /contacts?limit=20

联系人列表。

GET /chats?limit=20

最近会话列表。

🔧 与 Hermes Agent 集成

配置 ~/.hermes/config.yaml:

platforms:
weixin:
enabled: trueextra:
base_url: "http://127.0.0.1:18400"dm_policy: "open"

📜 许可证

MIT

🙏 致谢

• wechat-decrypt — DB 解密参考
• wechat-use — 架构灵感
• Hermes Agent — AI Agent 框架