UniQQ 从 0 到 1 安装与 ZL-综合插件使用教程

适用对象:第一次使用 UniQQ、不会安装框架或插件的新手 本文对应环境:Windows、UniQQ 1.2.0.1、ZL-综合插件 2.1.2 插件作者:小林 | 官网:https://blog.zxiaolin.com | 官方群:327942687


一、开始前先看

完成本教程后,你将得到一套可以正常工作的 QQ 群机器人:

下载文件
  ↓
安装必备运行库
  ↓
解压并启动 UniQQ
  ↓
添加机器人 QQ 并扫码登录
  ↓
安装、启用 ZL-综合插件
  ↓
打开插件控制台
  ↓
填写主人 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_1.2.0.1

下载到的通常是压缩包。UniQQ 不是传统安装软件,解压后运行 UniQQ.exe 即可。

2. 必备运行库

当前 UniQQ 1.2.0.1 基于 .NET 10 Windows Desktop 运行。发布包中如附带以下文件,请一并下载:

(必备运行库)windowsdesktop-runtime-10.0.11-win-x86.exe
VC_redist.x64(必备运行库).exe

部分旧版 Windows 还可能需要发布包内标注“老版本系统用这个”的 VC++ 运行库。

3. ZL-综合插件

插件包文件名应为:

XiaoLin.ZLComprehensivePlugin.uniqq

注意:.uniqq 本身就是 UniQQ 可识别的插件安装包,不要把这个文件再次解压。

4. 可选前置插件

如果你购买或领取的插件包明确说明依赖“UniQQ 通用经济系统”,还需要准备:

Jaryan.UniQQ.Economy.uniqq

安装时应先安装并启用经济系统,再安装业务插件。当前 ZL-综合插件本身不要求该经济前置;没有依赖提示时可以跳过。


三、整理安装目录

建议在非系统盘新建一个固定目录,例如:

D:\UniQQ\

不建议放在桌面、临时下载目录或 C:\Program Files 中,避免误删、路径变化或权限不足。

将 UniQQ 压缩包完整解压到这个目录。正确的目录结构类似:

D:\UniQQ\
├─ UniQQ.exe
├─ UniQQ.dll
├─ UniQQ.SDK.dll
├─ UniQQ.updater.exe
├─ Data\
├─ Logs\
├─ Plugins\
└─ runtime\

如果打开目录后还要再进入一层同名文件夹才能看到 UniQQ.exe,也不影响使用,但不要只把 UniQQ.exe 单独复制出来。主程序必须和其他 DLL、Data、Plugins、runtime 等内容保持在同一套目录中。


四、安装运行环境

第 1 步:安装 .NET 10 Windows Desktop Runtime

双击:

windowsdesktop-runtime-10.0.11-win-x86.exe

按安装向导完成安装。即使电脑是 64 位系统,也要安装发布包要求的 x86 版本,因为当前 UniQQ 主程序使用对应架构运行。

第 2 步:安装 VC++ 运行库

双击:

VC_redist.x64(必备运行库).exe

选择“安装”或“修复”,等待完成。

第 3 步:确认 WebView2

ZL-综合插件的图形化控制台需要 Microsoft Edge WebView2 Runtime。Windows 10/11 通常已经自带。

如果以后点击插件“设置”时控制台白屏、闪退或完全打不开,再安装或修复微软官方 WebView2 Runtime。

第 4 步:重启电脑(推荐)

如果刚安装了多个运行库,建议重启一次电脑,再继续下面的步骤。


五、第一次启动 UniQQ

  1. 打开 UniQQ 解压目录;

  2. 双击 UniQQ.exe;

  3. 等待主界面初始化完成;

  4. 如果 Windows 防火墙询问是否允许联网,根据自己的网络环境允许 UniQQ 通信;

  5. 如果主程序一闪而过,先看本文末尾的“常见问题”。

启动成功后,左侧可以看到“控制台”“机器人”“插件”“插件市场”“设置”等入口。

建议为 UniQQ.exe 创建桌面快捷方式,不要移动程序本体。


六、添加并登录机器人 QQ

第 1 步:新建机器人

  1. 点击 UniQQ 左侧的“机器人”;

  2. 点击右上角“新建机器人”;

  3. 在“请输入机器人QQ号”中填写机器人 QQ;

  4. 点击“确认”;

  5. 看到“机器人 XXXXX 添加成功”后关闭提示。

机器人 QQ 必须是至少 6 位的纯数字,且不能重复添加。

第 2 步:首次扫码登录

  1. 在机器人列表中单击选中刚添加的机器人;

  2. 右键该机器人;

  3. 选择“扫码登录”;

  4. 阅读风险提示,确认继续;

  5. UniQQ 会显示登录二维码;

  6. 打开手机 QQ,使用与所填 QQ 号一致的账号扫码并确认;

  7. 等待机器人状态变为“已上线”。

请不要用其他 QQ 扫码。若扫码账号与填写的 QQ 不一致,UniQQ 会中止登录并提示重新登录。

第 3 步:后续快速登录

首次扫码成功后,UniQQ 会保存快速登录所需的本地凭据。以后可:

  1. 选中机器人并右键;

  2. 点击“快速登录”;

  3. 等待状态变为“已上线”。

如果快速登录失效,重新使用“扫码登录”即可。

第 4 步:按需开启自动登录

选中机器人后,可在右侧详情区设置“掉线自动登录”等选项。建议先确认机器人能够稳定收发消息,再开启自动登录。


七、安装 ZL-综合插件

推荐方式:在 UniQQ 内安装

  1. 点击左侧“插件”;

  2. 点击右上角“安装新插件”;

  3. 在文件选择窗口中选中:

XiaoLin.ZLComprehensivePlugin.uniqq
  1. 点击“打开”;

  2. 等待“插件加载成功”提示;

  3. 在插件列表中找到“ZL-综合插件”;

  4. 选中插件后右键,点击“启用”;

  5. 看到“启用成功”即表示插件已运行。

如果需要安装经济前置

严格按照下面的顺序操作:

  1. “安装新插件”选择 Jaryan.UniQQ.Economy.uniqq;

  2. 选中“UniQQ 通用经济系统”,右键“启用”;

  3. 再安装并启用业务插件。

备用方式:放入 Plugins 目录

如果“安装新插件”无法选择文件,也可以:

  1. 彻底退出 UniQQ;

  2. 将 .uniqq 文件复制到 UniQQ 根目录下的 Plugins 文件夹;

  3. 重新启动 UniQQ;

  4. 进入“插件”页面刷新列表;

  5. 右键插件并选择“启用”。

正常情况下优先使用界面里的“安装新插件”,操作更直观,也更容易看到错误原因。


八、打开 ZL-综合插件控制台

  1. 进入 UniQQ 的“插件”页面;

  2. 选中“ZL-综合插件”;

  3. 右键,点击“设置”;

  4. 等待 ZL-综合插件控制台打开。

如果右键菜单没有“设置”,先确认插件已启用。如果点击“设置”没有反应,检查 WebView2 Runtime 和 UniQQ 日志。

控制台是插件的配置中心。修改设置后,记得点击页面上的“保存”。


九、首次配置 ZL-综合插件

建议按以下顺序配置,不要一开始就把所有功能全部打开。

第 1 步:填写全局主人 QQ

  1. 打开插件控制台;

  2. 进入“全局配置”;

  3. 找到“全局主人QQ”;

  4. 填写你自己的管理 QQ;

  5. 保存配置。

全局主人拥有最高权限,可以授权群、管理插件管理员、更新插件以及使用其他高权限功能。这里应填写管理者 QQ,不一定要填写机器人 QQ。

第 2 步:完成免费绑定

插件首次安装后提供 7 天全功能试用。试用期结束后,点歌、AI 聊天、自定义回复和 AI 总结等功能会受到限制,菜单、状态等基础功能仍可使用。

免费绑定流程:

  1. 加入官方群 327942687;

  2. 在官方群发送:

绑定码
  1. 获取一次性绑定码,绑定码有效期为 24 小时;

  2. 打开插件控制台右上角“设置”;

  3. 进入“安全”;

  4. 输入绑定码并完成绑定。

绑定本身免费。请勿向陌生人购买所谓的绑定服务。

第 3 步:授权第一个群

ZL-综合插件默认只在已经授权的群中工作。机器人已经进群,不代表插件已经授权该群。

方式一:使用群内指令

让全局主人在目标群中发送:

授权本群

需要限制天数时可发送:

授权本群 30天

方式二:使用插件控制台

  1. 打开“授权群组”;

  2. 找到目标群;

  3. 点击授权;

  4. 保存设置。

第 4 步:按需配置管理员

如需让其他人协助管理,可以在群内使用:

添加插件管理员 123456789
添加群管理员 123456789
管理员列表
  • 插件管理员:可管理插件的大部分群配置;

  • 添加群管理员:加入插件的本群权限名单,不会改变对方在 QQ 群里的身份;

  • 全局主人:最高权限,请只设置可信账号。

如果要真正提升或取消 QQ 群管理员,请使用:

上管理员@某人
删除管理员@某人

这两个操作要求机器人本身是群主;也兼容 设置管理员、取消管理员 等别名。

第 5 步:先开启少量功能

建议首次只启用 1~3 个容易验证的功能,例如菜单、签到、问答。确认稳定后,再逐项配置违禁词、刷屏检测、AI、点歌、入群审核、定时任务等功能。


十、完整验收流程

按下面的顺序逐项检查:

1. 检查 UniQQ

  • UniQQ 主程序保持运行;

  • “机器人”页面的状态为“已上线”;

  • “日志”页面没有持续刷新的红色错误。

2. 检查插件

  • “插件”列表中能看到“ZL-综合插件”;

  • 插件处于启用状态;

  • 右键“设置”可以正常打开控制台;

  • 全局主人 QQ 已填写并保存;

  • 测试群已经授权。

3. 在群里测试

在已授权群中依次发送:

插件状态
菜单
签到

预期结果:

  • “插件状态”有回复;

  • “菜单”返回完整功能菜单;

  • “签到”返回签到结果或明确的功能状态提示。

只要“菜单”能够正常回复,基本安装链路就已经打通。

4. 测试群管能力

测试撤回、禁言、入群审核前,请先把机器人设为群管理员。建议使用测试成员和测试内容,不要直接在重要群里做高风险测试。


十一、日常启动与关闭

每次开机后的启动顺序

  1. 启动 UniQQ.exe;

  2. 等待机器人自动登录;

  3. 如果没有自动登录,在“机器人”页面右键选择“快速登录”;

  4. 确认 ZL-综合插件为启用状态;

  5. 在群内发送“插件状态”检查。

正确关闭方式

点击 UniQQ 的退出按钮时:

  • 选择“最小化到系统托盘”,机器人会继续运行;

  • 选择彻底退出,机器人会停止运行并离线。

不要直接删除正在运行的程序文件或强制结束进程,避免配置尚未保存完整。


十二、更新、备份与迁移

1. 更新插件前先备份

彻底退出 UniQQ,然后备份:

UniQQ\Data\plugins\XiaoLin.ZLComprehensivePlugin\

该目录中通常包含插件配置、问答、上传素材和运行数据。

2. 更新插件

拿到新版 XiaoLin.ZLComprehensivePlugin.uniqq 后,优先在 UniQQ 的“插件”页面使用“安装新插件”进行覆盖安装。安装完成后,选中插件右键“重载”;如果重载后功能异常,直接重启 UniQQ。

更新时不要主动删除插件数据目录,否则原有配置可能丢失。

3. 更新 UniQQ

更新框架前,建议完整备份整个 Data 文件夹。解压新版 UniQQ 时,不要误删旧版的 Data 目录。最稳妥的做法是:

  1. 退出旧版 UniQQ;

  2. 备份旧版 Data;

  3. 解压全新的 UniQQ 到新目录;

  4. 按官方版本说明迁移 Data;

  5. 启动后检查机器人、插件和日志。


十三、常见问题与解决办法

1. 双击 UniQQ.exe 没反应或一闪而过

依次检查:

  1. 是否完整解压,不能只运行压缩包里的 UniQQ.exe;

  2. 是否安装 .NET 10 Windows Desktop Runtime x86;

  3. 是否安装或修复 VC++ 运行库;

  4. 路径是否具有正常读写权限;

  5. 查看 Logs 文件夹中最新日期的日志。

2. UniQQ 启动后提示 6099 端口异常

UniQQ 的反向 WebSocket 服务需要使用相关端口。先检查是否已经重复启动 UniQQ,或是否有其他程序占用 6099 端口。关闭重复进程或处理端口占用后重试。

3. 扫码登录超时

常见原因:

  1. 没有及时扫码,二维码已经过期;

  2. 快速登录凭据已经失效;

  3. 扫码 QQ 与新建机器人时填写的 QQ 不一致;

  4. 同一个 QQ 已经登录电脑 QQ,发生登录冲突;

  5. 网络不稳定或运行库异常。

关闭二维码窗口后重新选择“扫码登录”。

4. 插件安装失败

检查:

  • 选择的是 .uniqq 文件,而不是解压后的 DLL;

  • 文件名是否为 XiaoLin.ZLComprehensivePlugin.uniqq;

  • 插件包是否下载完整;

  • 当前 UniQQ 版本是否满足插件要求;

  • “日志”页面是否有更具体的加载错误。

UniQQ 要求插件包文件名与插件 ID 一致,随意改名可能造成加载失败。

5. 插件已经安装,但群里完全不回复

按顺序检查:

  1. 机器人状态是否为“已上线”;

  2. ZL-综合插件是否已经“启用”;

  3. 全局主人 QQ 是否填写正确并保存;

  4. 当前群是否已经授权;

  5. 当前群是否关闭了插件总开关;

  6. 多机器人场景下,本群是否已经认领给正确的机器人;

  7. UniQQ“日志”页面是否出现报错。

6. 只有“菜单”有回复,其他功能不回复

这通常表示当前群没有完成授权,或者插件试用/绑定状态限制了部分高级功能。先发送“插件状态”,再检查“授权群组”和“设置 → 安全”中的绑定状态。

7. 右键插件点击“设置”后没有反应

依次处理:

  1. 确认插件已经启用;

  2. 安装或修复 Microsoft Edge WebView2 Runtime;

  3. 右键插件选择“重载”;

  4. 重启 UniQQ;

  5. 查看日志中的 WebView2、Settings 或插件错误信息。

8. 撤回、禁言、审核等功能无效

确认机器人在该群拥有管理员权限。机器人不能对群主操作,也不能对权限高于自己的成员执行部分群管动作。

9. 配置改了却没有生效

确认已经点击“保存”。部分功能需要重载插件或重启 UniQQ。仍不生效时,检查是否改错了群、是否存在多机器人群归属,以及当前群的独立配置是否覆盖全局配置。


十四、发给新手的最短操作清单

如果你已经安装好运行库,可以只照这 12 步操作:

  1. 完整解压 UniQQ;

  2. 双击 UniQQ.exe;

  3. 点击“机器人”;

  4. 点击“新建机器人”,填写机器人 QQ;

  5. 选中机器人,右键“扫码登录”;

  6. 手机 QQ 扫码,等状态变为“已上线”;

  7. 点击“插件”;

  8. 点击“安装新插件”,选择 XiaoLin.ZLComprehensivePlugin.uniqq;

  9. 选中“ZL-综合插件”,右键“启用”;

  10. 再次右键“设置”,填写全局主人 QQ 并完成免费绑定;

  11. 在目标群发送“授权本群”;

  12. 在群里发送“菜单”,收到回复即安装成功。


十五、寻求帮助时要提供什么

如果按本教程仍无法解决,请准备以下信息后联系作者或在官方群咨询:

  • Windows 版本;

  • UniQQ 版本;

  • ZL-综合插件版本;

  • 出问题的具体步骤;

  • 完整错误提示截图;

  • Logs 中对应时间的错误内容;

  • 机器人是否在线、插件是否启用、群是否授权。

请先隐藏 QQ 密码、Cookie、Token、API Key、支付密钥等敏感信息,再发送截图或日志。

官方咨询群:327942687 作者 QQ:939921104 在线指令大全:https://blog.zxiaolin.com/docs/view/ZL-pub?docSlug=DOC20260922174002388475

共 27 篇 ZL-综合插件知识库 / 新手安装教程 0 字 0 行 zhangxiaolin
创建 2026-10-04T11:23:30.764191679Z 更新 2026-10-13T08:11:45.358630454Z