WechatHookBot

基于个微大客户版 Hook API 的微信机器人框架，参考 XYBotV2 架构设计。

项目特点

• 🎯 无需登录：Hook 已登录的微信客户端，无需二维码登录
• 🔌 插件化：兼容 XYBotV2 风格插件系统
• ⚡ 实时回调：HTTP 回调机制，消息接收更及时
• 🚦 消息队列：支持优先级队列、并发控制、熔断与优雅关闭
• 🔄 热更新：主配置可热更新，运行中可调整队列和并发参数
• 🧠 消息细分：支持文本、图片、语音、视频、文件、引用、链接、小程序、名片等消息类型
• 🖥️ 可选 WebUI：支持开启轻量管理界面

技术栈

• Python 3.x
• asyncio 异步编程
• aiohttp + httpx
• SQLite 数据库
• APScheduler 定时任务

快速开始

环境要求

• Windows 系统
• Python 3.x
• 微信客户端已登录

安装

cd WechatHookBot
pip install -r requirements.txt

如使用 Playwright 相关插件，首次安装后还需要执行：

playwright install

配置

编辑 main_config.toml 配置文件：

[HttpHook]
api-url = "http://127.0.0.1:19088"
callback-host = "0.0.0.0"
callback-port = 5000

[Bot]
admins = ["your_wxid"]
disabled-plugins = []

插件自己的配置位于 plugins/<PluginName>/config.toml。

例如 MessageLogger 需要单独配置 MySQL / MinIO：

[minio]
enabled = true
endpoint = "127.0.0.1:9000"
access_key = "your_access_key"
secret_key = "your_secret_key"
bucket = "wechat"
secure = false
public_base_url = "http://127.0.0.1:9000"

也可以通过环境变量覆盖：

• MESSAGE_LOGGER_MINIO_ENDPOINT
• MESSAGE_LOGGER_MINIO_ACCESS_KEY
• MESSAGE_LOGGER_MINIO_SECRET_KEY
• MESSAGE_LOGGER_MINIO_BUCKET
• MESSAGE_LOGGER_MINIO_PUBLIC_BASE_URL

运行

# 启动机器人
python bot.py

项目结构

WechatHookBot/
├── docs/                    # 文档目录
│   ├── 封装接口清单.md
│   └── 内部接口清单.md
├── WechatHook/              # Hook 层
├── utils/                   # 工具类
├── database/                # 数据库
├── plugins/                 # 插件目录
├── bot.py                   # 主入口
├── FEATURES.md              # 功能与指令说明
└── main_config.toml         # 主配置

文档

• 功能与指令 - 插件功能、指令、配置说明
• 封装接口清单 - WechatHookClient 对外接口
• 内部接口清单 - HttpClient 内部接口

注意事项

⚠️ 重要提示

• 需要微信客户端在运行
• 需要正确配置 Hook 的 HTTP 回调地址与端口
• 当前项目仅保留 bot.py 启动方式，不包含额外管理界面入口
• Hook 方式风控风险较高，谨慎使用
• 运行产生的缓存、日志、数据库、临时图片/视频默认不建议提交到 Git

免责声明

本项目仅供学习和技术研究使用，不得用于任何商业或非法行为。使用本工具造成的任何后果由使用者自行承担。

开发状态

🚧 项目开发中...

License

MIT License