微信机器人框架 — 基于 PC 微信 UI 自动化的消息收发中间件。
wx_claw 将微信 PC 客户端的操控能力封装为标准的 HTTP API 和 WebSocket 推送接口，为上层 AI 应用（如 OpenClaw）提供统一的消息通道。
- 消息监控 — 实时检测指定对话的新消息，通过 WebSocket 推送
- 消息发送 — HTTP API 发送文本消息，支持群聊 @成员
- 热更新配置 — 修改
bot_settings.yaml即时生效，无需重启 - 可替换传输层 — 适配器模式隔离底层操控方案，支持未来切换为 Hook / API 等方案
- 数据持久化 — MongoDB 存储消息日志、会话记录、用户画像
- Swagger 文档 — 所有接口自带交互式 API 文档
┌─────────────────────────────────────────────┐
│ API 层 │
│ FastAPI (HTTP + WebSocket) │
├─────────────────────────────────────────────┤
│ Core 层 │
│ MessagePoller · MessageSender · EventBus │
├─────────────────────────────────────────────┤
│ Transport 层（可替换） │
│ ┌──────────────┐ ┌──────────┐ ┌────────┐│
│ │PyWeChatAdapter│ │HookAdapter│ │ApiAdapter││
│ └──────┬───────┘ └────┬─────┘ └───┬────┘│
│ │ │ │ │
│ pywechat hook lib HTTP API │
├─────────────────────────────────────────────┤
│ DB 层 │
│ MongoDB (pymongo) │
└─────────────────────────────────────────────┘
微信 4.0 及以上版本采用 QT 框架重构了 UI，默认屏蔽了部分 UI Automation 控件的可见性。为确保 wx_claw 能正常捕获控件元素，首次使用前需执行以下步骤：
- 先启动 Windows 讲述人（
Win + Ctrl + Enter），再登录微信 - 保持讲述人运行 至少 5 分钟，使 Windows UI Automation 完整加载 QT 框架的控件树
- 关闭讲述人，此后即可正常使用 UI 自动化
原理：Windows 可访问性 API（UI Automation）在讲述人激活时会强制应用程序暴露所有 UI 元素信息。微信在检测到讲述人后会解除控件屏蔽，且此状态会被缓存——频繁执行上述操作后，后续启动微信将不再需要讲述人。
注意：此方法目前对微信 PC 有效。企业微信对 UI 自动化有更严格的限制，本项目不支持企业微信。
- 本项目仅供 学习研究 使用，严禁用于任何违反法律法规或微信使用条款的用途
- 使用者应自行承担使用本项目所产生的一切风险和责任
- 本项目不提供任何形式的担保，作者不对因使用本项目造成的任何损失负责
- 请勿将本项目用于批量营销、骚扰他人、传播违法信息等非法用途
- 如有侵权请联系删除
详细部署步骤请参阅 部署文档
| 依赖 | 版本 |
|---|---|
| Windows | 10 / 11 |
| Python | >= 3.11 |
| uv | >= 0.4 |
| 微信 PC | 3.9.x / 4.0.x |
| MongoDB | >= 4.4（可选） |
# 1. 克隆项目
git clone https://github.com/<your-org>/wx_claw.git
cd wx_claw
# 2. 克隆 pywechat 依赖（放在项目根目录下）
git clone https://github.com/Hello-Mr-Crab/pywechat.git
# 3. 安装 Python 依赖
uv sync
# 4. 复制配置文件（按需修改）
# config.yaml — 系统配置（端口、数据库、功能开关）
# bot_settings.yaml — 运行时设置（监控列表，热更新）uv run wx-claw启动后：
- API 文档: http://127.0.0.1:18790/docs
- WebSocket: ws://127.0.0.1:18790/ws
- 健康检查: http://127.0.0.1:18790/api/health
curl -X POST http://127.0.0.1:18790/api/messages/send \
-H "Content-Type: application/json" \
-d '{"chat_name":"文件传输助手","messages":["Hello from wx_claw!"]}'编辑 bot_settings.yaml，添加需要监控的对话名称：
monitor:
- 文件传输助手
- 某个群聊名称保存后自动生效，新消息会通过 WebSocket 推送。
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/messages/send |
发送消息 |
GET |
/api/sessions |
获取会话列表 |
POST |
/api/monitor |
设置监控列表 |
GET |
/api/health |
健康检查 |
WS |
/ws |
WebSocket 事件推送 |
完整接口文档请访问 /docs（Swagger UI）。
server:
host: "127.0.0.1"
port: 18790
mongo:
uri: "mongodb://localhost:27017"
db_name: "wx_claw"
poller:
interval: 0.5
mode: "light" # light | deep
wechat:
send_delay: 0.3
virtual_desktop: falsemonitor:
- 文件传输助手
- 某个群聊wx_claw/
├── app/ # Python 主包
│ ├── api/ # HTTP/WebSocket 接口层
│ ├── core/ # 业务编排（轮询、发送、事件总线）
│ ├── transport/ # 传输层抽象 + 适配器
│ │ ├── base.py # MessageTransport 抽象接口
│ │ └── pywechat_adapter.py # pywechat UI 自动化适配器
│ ├── db/ # 数据持久化（MongoDB）
│ ├── config.py # 配置加载
│ ├── models.py # 数据模型
│ ├── main.py # 程序入口
│ └── server.py # FastAPI 应用工厂
├── pywechat/ # 第三方依赖（需自行克隆）
├── doc/ # 文档
├── config.yaml # 系统配置
├── bot_settings.yaml # 运行时设置
└── pyproject.toml # 项目元数据 & 依赖
wx_claw 的传输层采用适配器模式，底层操控方案可随时替换：
# 实现 MessageTransport 接口
from app.transport.base import MessageTransport
class HookAdapter(MessageTransport):
def connect(self) -> None: ...
def send_message(self, chat_name, messages, ...) -> dict: ...
def get_chat_list_snapshot(self) -> list[Session]: ...
def pull_messages(self, chat_name, count) -> list[Message]: ...
# ...然后在 app/main.py 中替换一行即可，core/api/db 层零改动。