UniQQ 从 0 到 1 安装与 ZL-综合插件使用教程
适用对象:第一次使用 UniQQ、不会安装框架或插件的新手 本文对应环境:Windows、UniQQ
1.2.0.1、ZL-综合插件2.1.2插件作者:小林 | 官网:https://blog.zxiaolin.com | 官方群:327942687
一、开始前先看
完成本教程后,你将得到一套可以正常工作的 QQ 群机器人:
1. 系统要求
Windows 10 或 Windows 11;
可以正常联网;
一个用于机器人的 QQ 号;
机器人已经加入准备使用插件的 QQ 群;
建议机器人在群内拥有管理员权限,否则撤回、禁言、审核等群管功能无法生效。
2. 账号安全提醒
UniQQ 登录 QQ 时会提示扫码登录可能存在账号安全风险。建议:
优先使用专门的机器人 QQ,不建议直接使用重要的主号;
首次登录前阅读 UniQQ 官方论坛的账号稳定、防踢建议;
扫码时确认手机 QQ 当前登录的账号,与 UniQQ 中填写的机器人 QQ 完全一致;
登录机器人时,不要让同一个 QQ 同时登录电脑 QQ 客户端,以免发生登录冲突;
不要频繁切换设备、网络或重复扫码登录。
二、需要下载哪些文件
建议只从 UniQQ 官方渠道和 ZL-综合插件官方渠道下载,避免使用来源不明的二次打包版本。
1. UniQQ 主程序
前往 UniQQ 官方社区,下载最新的 Windows 版本。
本文演示版本为:
下载到的通常是压缩包。UniQQ 不是传统安装软件,解压后运行 UniQQ.exe 即可。
2. 必备运行库
当前 UniQQ 1.2.0.1 基于 .NET 10 Windows Desktop 运行。发布包中如附带以下文件,请一并下载:
部分旧版 Windows 还可能需要发布包内标注“老版本系统用这个”的 VC++ 运行库。
3. ZL-综合插件
插件包文件名应为:
注意:.uniqq 本身就是 UniQQ 可识别的插件安装包,不要把这个文件再次解压。
4. 可选前置插件
如果你购买或领取的插件包明确说明依赖“UniQQ 通用经济系统”,还需要准备:
安装时应先安装并启用经济系统,再安装业务插件。当前 ZL-综合插件本身不要求该经济前置;没有依赖提示时可以跳过。
三、整理安装目录
建议在非系统盘新建一个固定目录,例如:
不建议放在桌面、临时下载目录或 C:\Program Files 中,避免误删、路径变化或权限不足。
将 UniQQ 压缩包完整解压到这个目录。正确的目录结构类似:
如果打开目录后还要再进入一层同名文件夹才能看到 UniQQ.exe,也不影响使用,但不要只把 UniQQ.exe 单独复制出来。主程序必须和其他 DLL、Data、Plugins、runtime 等内容保持在同一套目录中。
四、安装运行环境
第 1 步:安装 .NET 10 Windows Desktop Runtime
双击:
按安装向导完成安装。即使电脑是 64 位系统,也要安装发布包要求的 x86 版本,因为当前 UniQQ 主程序使用对应架构运行。
第 2 步:安装 VC++ 运行库
双击:
选择“安装”或“修复”,等待完成。
第 3 步:确认 WebView2
ZL-综合插件的图形化控制台需要 Microsoft Edge WebView2 Runtime。Windows 10/11 通常已经自带。
如果以后点击插件“设置”时控制台白屏、闪退或完全打不开,再安装或修复微软官方 WebView2 Runtime。
第 4 步:重启电脑(推荐)
如果刚安装了多个运行库,建议重启一次电脑,再继续下面的步骤。
五、第一次启动 UniQQ
打开 UniQQ 解压目录;
双击
UniQQ.exe;等待主界面初始化完成;
如果 Windows 防火墙询问是否允许联网,根据自己的网络环境允许 UniQQ 通信;
如果主程序一闪而过,先看本文末尾的“常见问题”。
启动成功后,左侧可以看到“控制台”“机器人”“插件”“插件市场”“设置”等入口。
建议为
UniQQ.exe创建桌面快捷方式,不要移动程序本体。
六、添加并登录机器人 QQ
第 1 步:新建机器人
点击 UniQQ 左侧的“机器人”;
点击右上角“新建机器人”;
在“请输入机器人QQ号”中填写机器人 QQ;
点击“确认”;
看到“机器人 XXXXX 添加成功”后关闭提示。
机器人 QQ 必须是至少 6 位的纯数字,且不能重复添加。
第 2 步:首次扫码登录
在机器人列表中单击选中刚添加的机器人;
右键该机器人;
选择“扫码登录”;
阅读风险提示,确认继续;
UniQQ 会显示登录二维码;
打开手机 QQ,使用与所填 QQ 号一致的账号扫码并确认;
等待机器人状态变为“已上线”。
请不要用其他 QQ 扫码。若扫码账号与填写的 QQ 不一致,UniQQ 会中止登录并提示重新登录。
第 3 步:后续快速登录
首次扫码成功后,UniQQ 会保存快速登录所需的本地凭据。以后可:
选中机器人并右键;
点击“快速登录”;
等待状态变为“已上线”。
如果快速登录失效,重新使用“扫码登录”即可。
第 4 步:按需开启自动登录
选中机器人后,可在右侧详情区设置“掉线自动登录”等选项。建议先确认机器人能够稳定收发消息,再开启自动登录。
七、安装 ZL-综合插件
推荐方式:在 UniQQ 内安装
点击左侧“插件”;
点击右上角“安装新插件”;
在文件选择窗口中选中:
点击“打开”;
等待“插件加载成功”提示;
在插件列表中找到“ZL-综合插件”;
选中插件后右键,点击“启用”;
看到“启用成功”即表示插件已运行。
如果需要安装经济前置
严格按照下面的顺序操作:
“安装新插件”选择
Jaryan.UniQQ.Economy.uniqq;选中“UniQQ 通用经济系统”,右键“启用”;
再安装并启用业务插件。
备用方式:放入 Plugins 目录
如果“安装新插件”无法选择文件,也可以:
彻底退出 UniQQ;
将
.uniqq文件复制到 UniQQ 根目录下的Plugins文件夹;重新启动 UniQQ;
进入“插件”页面刷新列表;
右键插件并选择“启用”。
正常情况下优先使用界面里的“安装新插件”,操作更直观,也更容易看到错误原因。
八、打开 ZL-综合插件控制台
进入 UniQQ 的“插件”页面;
选中“ZL-综合插件”;
右键,点击“设置”;
等待 ZL-综合插件控制台打开。
如果右键菜单没有“设置”,先确认插件已启用。如果点击“设置”没有反应,检查 WebView2 Runtime 和 UniQQ 日志。
控制台是插件的配置中心。修改设置后,记得点击页面上的“保存”。
九、首次配置 ZL-综合插件
建议按以下顺序配置,不要一开始就把所有功能全部打开。
第 1 步:填写全局主人 QQ
打开插件控制台;
进入“全局配置”;
找到“全局主人QQ”;
填写你自己的管理 QQ;
保存配置。
全局主人拥有最高权限,可以授权群、管理插件管理员、更新插件以及使用其他高权限功能。这里应填写管理者 QQ,不一定要填写机器人 QQ。
第 2 步:完成免费绑定
插件首次安装后提供 7 天全功能试用。试用期结束后,点歌、AI 聊天、自定义回复和 AI 总结等功能会受到限制,菜单、状态等基础功能仍可使用。
免费绑定流程:
加入官方群
327942687;在官方群发送:
获取一次性绑定码,绑定码有效期为 24 小时;
打开插件控制台右上角“设置”;
进入“安全”;
输入绑定码并完成绑定。
绑定本身免费。请勿向陌生人购买所谓的绑定服务。
第 3 步:授权第一个群
ZL-综合插件默认只在已经授权的群中工作。机器人已经进群,不代表插件已经授权该群。
方式一:使用群内指令
让全局主人在目标群中发送:
需要限制天数时可发送:
方式二:使用插件控制台
打开“授权群组”;
找到目标群;
点击授权;
保存设置。
第 4 步:按需配置管理员
如需让其他人协助管理,可以在群内使用:
插件管理员:可管理插件的大部分群配置;
添加群管理员:加入插件的本群权限名单,不会改变对方在 QQ 群里的身份;全局主人:最高权限,请只设置可信账号。
如果要真正提升或取消 QQ 群管理员,请使用:
这两个操作要求机器人本身是群主;也兼容 设置管理员、取消管理员 等别名。
第 5 步:先开启少量功能
建议首次只启用 1~3 个容易验证的功能,例如菜单、签到、问答。确认稳定后,再逐项配置违禁词、刷屏检测、AI、点歌、入群审核、定时任务等功能。
十、完整验收流程
按下面的顺序逐项检查:
1. 检查 UniQQ
UniQQ 主程序保持运行;
“机器人”页面的状态为“已上线”;
“日志”页面没有持续刷新的红色错误。
2. 检查插件
“插件”列表中能看到“ZL-综合插件”;
插件处于启用状态;
右键“设置”可以正常打开控制台;
全局主人 QQ 已填写并保存;
测试群已经授权。
3. 在群里测试
在已授权群中依次发送:
预期结果:
“插件状态”有回复;
“菜单”返回完整功能菜单;
“签到”返回签到结果或明确的功能状态提示。
只要“菜单”能够正常回复,基本安装链路就已经打通。
4. 测试群管能力
测试撤回、禁言、入群审核前,请先把机器人设为群管理员。建议使用测试成员和测试内容,不要直接在重要群里做高风险测试。
十一、日常启动与关闭
每次开机后的启动顺序
启动
UniQQ.exe;等待机器人自动登录;
如果没有自动登录,在“机器人”页面右键选择“快速登录”;
确认 ZL-综合插件为启用状态;
在群内发送“插件状态”检查。
正确关闭方式
点击 UniQQ 的退出按钮时:
选择“最小化到系统托盘”,机器人会继续运行;
选择彻底退出,机器人会停止运行并离线。
不要直接删除正在运行的程序文件或强制结束进程,避免配置尚未保存完整。
十二、更新、备份与迁移
1. 更新插件前先备份
彻底退出 UniQQ,然后备份:
该目录中通常包含插件配置、问答、上传素材和运行数据。
2. 更新插件
拿到新版 XiaoLin.ZLComprehensivePlugin.uniqq 后,优先在 UniQQ 的“插件”页面使用“安装新插件”进行覆盖安装。安装完成后,选中插件右键“重载”;如果重载后功能异常,直接重启 UniQQ。
更新时不要主动删除插件数据目录,否则原有配置可能丢失。
3. 更新 UniQQ
更新框架前,建议完整备份整个 Data 文件夹。解压新版 UniQQ 时,不要误删旧版的 Data 目录。最稳妥的做法是:
退出旧版 UniQQ;
备份旧版
Data;解压全新的 UniQQ 到新目录;
按官方版本说明迁移
Data;启动后检查机器人、插件和日志。
十三、常见问题与解决办法
1. 双击 UniQQ.exe 没反应或一闪而过
依次检查:
是否完整解压,不能只运行压缩包里的
UniQQ.exe;是否安装 .NET 10 Windows Desktop Runtime x86;
是否安装或修复 VC++ 运行库;
路径是否具有正常读写权限;
查看
Logs文件夹中最新日期的日志。
2. UniQQ 启动后提示 6099 端口异常
UniQQ 的反向 WebSocket 服务需要使用相关端口。先检查是否已经重复启动 UniQQ,或是否有其他程序占用 6099 端口。关闭重复进程或处理端口占用后重试。
3. 扫码登录超时
常见原因:
没有及时扫码,二维码已经过期;
快速登录凭据已经失效;
扫码 QQ 与新建机器人时填写的 QQ 不一致;
同一个 QQ 已经登录电脑 QQ,发生登录冲突;
网络不稳定或运行库异常。
关闭二维码窗口后重新选择“扫码登录”。
4. 插件安装失败
检查:
选择的是
.uniqq文件,而不是解压后的 DLL;文件名是否为
XiaoLin.ZLComprehensivePlugin.uniqq;插件包是否下载完整;
当前 UniQQ 版本是否满足插件要求;
“日志”页面是否有更具体的加载错误。
UniQQ 要求插件包文件名与插件 ID 一致,随意改名可能造成加载失败。
5. 插件已经安装,但群里完全不回复
按顺序检查:
机器人状态是否为“已上线”;
ZL-综合插件是否已经“启用”;
全局主人 QQ 是否填写正确并保存;
当前群是否已经授权;
当前群是否关闭了插件总开关;
多机器人场景下,本群是否已经认领给正确的机器人;
UniQQ“日志”页面是否出现报错。
6. 只有“菜单”有回复,其他功能不回复
这通常表示当前群没有完成授权,或者插件试用/绑定状态限制了部分高级功能。先发送“插件状态”,再检查“授权群组”和“设置 → 安全”中的绑定状态。
7. 右键插件点击“设置”后没有反应
依次处理:
确认插件已经启用;
安装或修复 Microsoft Edge WebView2 Runtime;
右键插件选择“重载”;
重启 UniQQ;
查看日志中的
WebView2、Settings或插件错误信息。
8. 撤回、禁言、审核等功能无效
确认机器人在该群拥有管理员权限。机器人不能对群主操作,也不能对权限高于自己的成员执行部分群管动作。
9. 配置改了却没有生效
确认已经点击“保存”。部分功能需要重载插件或重启 UniQQ。仍不生效时,检查是否改错了群、是否存在多机器人群归属,以及当前群的独立配置是否覆盖全局配置。
十四、发给新手的最短操作清单
如果你已经安装好运行库,可以只照这 12 步操作:
完整解压 UniQQ;
双击
UniQQ.exe;点击“机器人”;
点击“新建机器人”,填写机器人 QQ;
选中机器人,右键“扫码登录”;
手机 QQ 扫码,等状态变为“已上线”;
点击“插件”;
点击“安装新插件”,选择
XiaoLin.ZLComprehensivePlugin.uniqq;选中“ZL-综合插件”,右键“启用”;
再次右键“设置”,填写全局主人 QQ 并完成免费绑定;
在目标群发送“授权本群”;
在群里发送“菜单”,收到回复即安装成功。
十五、寻求帮助时要提供什么
如果按本教程仍无法解决,请准备以下信息后联系作者或在官方群咨询:
Windows 版本;
UniQQ 版本;
ZL-综合插件版本;
出问题的具体步骤;
完整错误提示截图;
Logs中对应时间的错误内容;机器人是否在线、插件是否启用、群是否授权。
请先隐藏 QQ 密码、Cookie、Token、API Key、支付密钥等敏感信息,再发送截图或日志。
官方咨询群:327942687
作者 QQ:939921104
在线指令大全:https://blog.zxiaolin.com/docs/view/ZL-pub?docSlug=DOC20260922174002388475