Skip to content

新手安装教程 ​

本篇面向第一次使用 UniQQ 的新手,覆盖从系统要求、运行库安装、机器人登录,到插件安装、首次配置与验收排错的完整流程。

✅ 开始前的准备 ​

项目要求
操作系统Windows 10 或 Windows 11
网络可以正常联网
账号一个用于机器人的 QQ 号,且已加入准备使用插件的 QQ 群
权限建议机器人在群内拥有管理员权限,否则撤回、禁言、审核等群管功能无法生效

账号安全提醒

  • 优先使用专门的机器人 QQ,不建议直接使用重要的主号;
  • 首次登录请使用扫码方式,并确认扫码账号与 UniQQ 中填写的机器人 QQ 完全一致;
  • 不要让同一个 QQ 同时登录电脑 QQ 客户端,以免发生登录冲突;
  • 不要频繁切换设备、网络或重复扫码登录。

📥 需要下载的文件 ​

建议只从 UniQQ 官方渠道与插件官方渠道下载,避免使用来源不明的二次打包版本。

文件说明
UniQQ 主程序从 UniQQ 官方社区下载 Windows 版本,为压缩包形态,解压后运行 UniQQ.exe 即可
.NET 10 Windows Desktop Runtime如 windowsdesktop-runtime-10.0.11-win-x86.exe,发布包附带时一并下载
VC++ 运行库如 VC_redist.x64(必备运行库).exe,老系统另需发布包内标注的老版本运行库
ZL-综合插件插件包 XiaoLin.ZLComprehensivePlugin.uniqq(官方直链下载),.uniqq 即 UniQQ 可识别的插件包,请勿自行解压
UniQQ 通用经济系统(可选)Jaryan.UniQQ.Economy.uniqq,仅当插件包明确说明依赖时才需要;当前插件本身不要求该前置

📁 整理安装目录 ​

建议在非系统盘新建固定目录(如 D:\UniQQ\),不要放在桌面、临时下载目录或 C:\Program Files,避免误删、路径变化或权限不足。

将 UniQQ 压缩包完整解压到该目录,正确的目录结构类似:

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

完整解压

即使解压后多了一层同名文件夹也不影响使用,但不要只把 UniQQ.exe 单独复制出来——主程序必须与 DLL、Data、Plugins、runtime 等内容保持在同一套目录中。

⚙️ 安装运行环境 ​

  1. 安装 .NET 10 Windows Desktop Runtime:双击安装包按向导完成。即使电脑是 64 位系统,也要安装发布包要求的 x86 版本(UniQQ 主程序按该架构运行)。
  2. 安装 VC++ 运行库:双击 VC_redist.x64,选择「安装」或「修复」。
  3. 确认 WebView2:插件的图形化控制台依赖 Microsoft Edge WebView2 Runtime,Windows 10/11 通常已自带;若后续控制台白屏、闪退或打不开,再安装或修复官方 WebView2 Runtime。
  4. 重启电脑(推荐):刚安装多个运行库后建议重启一次再继续。

🤖 添加并登录机器人 QQ ​

  1. 双击 UniQQ.exe 启动,防火墙询问联网时按需允许;
  2. 进入左侧「机器人」页,点击「新建机器人」,填写机器人 QQ(至少 6 位纯数字,不能重复添加);
  3. 选中刚添加的机器人,右键选择「扫码登录」;
  4. 使用与所填 QQ 一致的手机 QQ 扫码并确认,等待状态变为「已上线」。

后续登录

首次扫码成功后 UniQQ 会保存本地凭据,之后右键选择「快速登录」即可;快速登录失效时重新扫码。确认机器人能稳定收发消息后,可在右侧详情区开启「掉线自动登录」。

🧩 安装 ZL-综合插件 ​

推荐方式(界面安装):

  1. 进入 UniQQ「插件」页,点击「安装新插件」;
  2. 选择 XiaoLin.ZLComprehensivePlugin.uniqq 并打开;
  3. 等待「插件加载成功」提示;
  4. 在插件列表中选中「ZL-综合插件」,右键选择「启用」。

备用方式(目录安装): 若「安装新插件」无法选择文件,先彻底退出 UniQQ,将 .uniqq 文件复制到 UniQQ 根目录下的 Plugins 文件夹,再重新启动并在插件页右键启用。

需要经济前置时

若插件包明确说明依赖经济系统,请严格按顺序:先安装并启用 Jaryan.UniQQ.Economy.uniqq,再安装并启用 ZL-综合插件。

⚙️ 首次配置 ​

打开控制台:插件页选中「ZL-综合插件」→ 右键「设置」。若右键菜单没有「设置」,先确认插件已启用。

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

  1. 填写全局主人 QQ:控制台 →「全局配置」→「全局主人 QQ」,填写管理者的 QQ(不一定是机器人 QQ)并保存;
  2. 完成免费绑定:加入官方群 327942687,发送「绑定码」获取一次性绑定码(24 小时有效),在控制台右上角「设置」→「安全」中完成绑定。插件首次安装后有 3 天全功能试用;
  3. 授权第一个群:主人在目标群发送 授权本群(或 授权本群 30天),或在控制台「授权群组」中操作;
  4. 按需配置管理员:添加副主#群号#QQ(仅主人)管理本群副主名单;添加群管理员+QQ 加入本群权限名单(不改变 QQ 群身份);上管理员@某人 / 删除管理员@某人 才是真正设置 QQ 群管理员(需机器人本身是群主);
  5. 先开少量功能:首次只启用 1~3 个易验证的功能(如菜单、签到、问答),确认稳定后再逐项开启违禁词、刷屏检测、AI、点歌、入群审核、定时任务等。

✅ 验收清单 ​

检查项预期结果
UniQQ 机器人状态「已上线」,日志页无持续刷新的红色错误
插件状态列表中可见、已启用、右键可打开控制台
配置全局主人 QQ 已填写并保存,测试群已授权
群内发送 插件状态有回复
群内发送 菜单返回完整功能菜单
群内发送 签到返回签到结果或明确的功能状态提示

只要「菜单」能正常回复,基本安装链路即已打通。测试撤回、禁言、入群审核前,请先把机器人设为群管理员,并尽量使用测试群,不要直接在重要群里做高风险测试。

🔄 日常启动与关闭 ​

  • 启动顺序:启动 UniQQ.exe → 等待自动登录(未登录则右键「快速登录」)→ 确认插件为启用状态 → 群内发送 插件状态 检查。
  • 关闭方式:选择「最小化到系统托盘」机器人继续运行;彻底退出则机器人离线。不要直接删除正在运行的程序文件或强制结束进程。

更新与备份

更新插件前,彻底退出 UniQQ 并备份 UniQQ\Data\plugins\XiaoLin.ZLComprehensivePlugin\(含插件配置、问答、上传素材与运行数据)。新版插件通过「安装新插件」覆盖安装,完成后右键「重载」,异常则重启 UniQQ;更新时不要删除插件数据目录。

❓ 常见安装问题 ​

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

依次检查:是否完整解压;是否安装 .NET 10 x86 运行库;是否安装或修复 VC++ 运行库;目录是否有读写权限;查看 Logs 文件夹中最新日志。

提示 6099 端口异常

UniQQ 的反向 WebSocket 服务需要使用该端口。检查是否重复启动了 UniQQ,或其他程序占用了 6099 端口,关闭重复进程或解除占用后重试。

扫码登录超时

常见原因:二维码过期、快速登录凭据失效、扫码 QQ 与填写的 QQ 不一致、同一 QQ 已登录电脑 QQ 客户端、网络不稳定。关闭二维码窗口后重新扫码即可。

插件安装失败

确认选择的是 .uniqq 文件而非解压后的 DLL;确认文件名为 XiaoLin.ZLComprehensivePlugin.uniqq 且下载完整;确认 UniQQ 版本满足要求;查看「日志」页的加载错误。插件包文件名需与插件 ID 一致,随意改名可能导致加载失败。

右键「设置」后没有反应

依次处理:确认插件已启用 → 安装或修复 WebView2 Runtime → 右键插件「重载」→ 重启 UniQQ → 查看日志中的 WebView2 相关错误。

插件已安装但群里完全不回复

按顺序检查:机器人是否已上线;插件是否已启用;全局主人 QQ 是否填写并保存;当前群是否已授权;本群插件总开关是否开启;多机器人场景下本群是否已认领给正确的机器人;日志页是否有报错。


📚 下一节:基础概念与权限体系

薇薇官机平台 · ZL 系列插件