微信群机器人 · 开源项目与部署教程

先理解它为什么分成三层

层	作用	怎么选
基础收发	识别消息、收图、发送、队列、回执、去重、账号与目标群校验	必须安装
AI 内核	Codex 原版、OpenCode、Kimi Code、Grok Build	四选一
软件插件	定时任务、快捷指令、公告板、新人任务、长期记忆、知识缺口、COC	可以一个、多个或完全不装

插件不等于 AI 技能。插件扩展机器人程序本身，很多功能完全不用模型；技能只是给智能体的工作说明，不能绕过程序权限。

准备环境

Windows 10 或 Windows 11。
微信 4.1，专用机器人账号已登录，并能打开目标群。
Python 3.12。
从四种 AI 内核中选一种，在主机按官方方式安装并登录。
若使用虚拟机，再安装 VirtualBox 与客体增强功能。

登录、扫码和系统授权必须由你本人完成。配置、日志和共享目录里不要放密码、Cookie、验证码、二维码或模型接口密钥。

创建自己的装配配置

复制 profiles/example.json，填写微信运行方式、目标群、机器人在群里的名称、预期微信账号、队列目录、AI 内核和插件列表。

python .\scripts\assemble.py --profile .\profiles\my-bot.json --output .\build\my-bot

装配器只接受一个 AI 内核和零到多个插件，并生成主机配置、微信收发端配置与组件版本锁定文件。不要手改生成目录里的版本关系。

启动微信收发端

Set-Location .\guest-agent .\build.ps1 -Publish # 先自检，再常驻运行 .\WeChatGroupAgentGuest.exe --self-test

虚拟机模式需要把主机队列目录设为固定共享文件夹；实体机模式则让主机配置和收发端配置指向同一本地目录。首次生成的 guest-config.json 会把账号绑定确认设为关闭，只有核对专用账号、微信号和目标群都正确后才可开启。

“调用了发送”不等于“对方已收到”。程序会区分发送调用、屏幕变化确认、事件回执和未确认隔离；没有确认的消息不会盲目重发。

启动主机端

Set-Location .\host-app python -m venv .venv .\.venv\Scripts\python.exe -m pip install -e . $env:PYTHONPATH = (Resolve-Path .\src).Path .\.venv\Scripts\python.exe -m wechat_group_bot.main --config ..\build\my-bot\host-config.json

主机端启动后会检查配置、队列、账号与群范围，再连接所选 AI 内核。Codex 使用 App Server 和用户自己的 ChatGPT 账号；其它三种内核使用各自支持的账号登录。项目不捆绑这些外部程序。

七个插件怎么选

插件	适合场景	是否必须调用 AI
定时任务	一次性、间隔、每天或每周提醒	否
快捷指令	固定命令、别名、模板回复	否
公告板	群内查询、维护时段和通知	否
新人任务	群主自定义清单	否
长期记忆	按群隔离、候选审核和遗忘	按需
知识缺口	记录暂时无法可靠回答的问题	按需
COC 能力	国际服公开玩家、部落、战争、突袭、排名和赛季数据	查询脚本不需要模型计算

插件没有微信发送权限，只能提交受控动作；最终目标检查、权限判断、发送去重和回执解释始终由基础层完成。

真正上线前必须验收

运行 python .\scripts\check.py，确认组件、版本、协议、插件和许可证检查全部通过。
收发端自检通过，账号和目标群由本人核对。
在测试群分别验证普通文字、图片、直接提及机器人、停止生成和发送失败隔离。
核对审计记录中的消息编号、目标群、发送调用和最终回执。
确认插件范围，不需要的插件保持关闭。

离线检查通过不代表微信实发成功。正式运行状态必须以真实收发回执为准，不能用构建成功或界面截图代替。

常见问题与排查顺序

机器人没有回复

依次检查收发端是否识别到消息、队列是否出现稳定消息编号、主机是否领取任务、AI 内核是否返回、发送动作是否被调用、回执是否确认。不要只看群里的一句错误文字猜原因。

回复重复

先核对同一消息编号是否被重复领取，或未确认发送是否被错误重试。正常实现会把“已调用但未确认”隔离，不会直接重发。

图片没有被模型看到

检查附件是否从微信提取到本地文件，再沿消息记录传到内核的图片输入。日志里只有“[图片]”占位不算模型真正收到了图片。

虚拟机突然失联

检查共享目录、客体增强功能、微信窗口和客体心跳；不要先删除队列。保留现场可以区分识别、共享目录和主机领取问题。

更新、插件开发与贡献

主机、收发端、四个 AI 内核和每个插件各自独立版本化，当前组合写在 versions.lock.json。更新时先阅读版本记录，再重新装配和自检，不要只替换某个生成文件。

git pull python .\scripts\check.py python .\scripts\assemble.py --profile .\profiles\my-bot.json --output .\build\my-bot

自制插件从 templates/software-plugin/ 开始，并用项目命令验证、打包和本机上传。上传只会复制到当前电脑的扩展目录，不会自动发布到 GitHub。欢迎通过议题和合并请求贡献新的内核适配器、插件、测试与修复。

把完整智能体带进普通微信群