新手安装教程
本篇面向第一次使用 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 压缩包完整解压到该目录,正确的目录结构类似:
D:\UniQQ\
├─ UniQQ.exe
├─ UniQQ.dll
├─ UniQQ.SDK.dll
├─ UniQQ.updater.exe
├─ Data\
├─ Logs\
├─ Plugins\
└─ runtime\完整解压
即使解压后多了一层同名文件夹也不影响使用,但不要只把 UniQQ.exe 单独复制出来——主程序必须与 DLL、Data、Plugins、runtime 等内容保持在同一套目录中。
⚙️ 安装运行环境
- 安装 .NET 10 Windows Desktop Runtime:双击安装包按向导完成。即使电脑是 64 位系统,也要安装发布包要求的
x86版本(UniQQ 主程序按该架构运行)。 - 安装 VC++ 运行库:双击
VC_redist.x64,选择「安装」或「修复」。 - 确认 WebView2:插件的图形化控制台依赖 Microsoft Edge WebView2 Runtime,Windows 10/11 通常已自带;若后续控制台白屏、闪退或打不开,再安装或修复官方 WebView2 Runtime。
- 重启电脑(推荐):刚安装多个运行库后建议重启一次再继续。
🤖 添加并登录机器人 QQ
- 双击
UniQQ.exe启动,防火墙询问联网时按需允许; - 进入左侧「机器人」页,点击「新建机器人」,填写机器人 QQ(至少 6 位纯数字,不能重复添加);
- 选中刚添加的机器人,右键选择「扫码登录」;
- 使用与所填 QQ 一致的手机 QQ 扫码并确认,等待状态变为「已上线」。
后续登录
首次扫码成功后 UniQQ 会保存本地凭据,之后右键选择「快速登录」即可;快速登录失效时重新扫码。确认机器人能稳定收发消息后,可在右侧详情区开启「掉线自动登录」。
🧩 安装 ZL-综合插件
推荐方式(界面安装):
- 进入 UniQQ「插件」页,点击「安装新插件」;
- 选择
XiaoLin.ZLComprehensivePlugin.uniqq并打开; - 等待「插件加载成功」提示;
- 在插件列表中选中「ZL-综合插件」,右键选择「启用」。
备用方式(目录安装): 若「安装新插件」无法选择文件,先彻底退出 UniQQ,将 .uniqq 文件复制到 UniQQ 根目录下的 Plugins 文件夹,再重新启动并在插件页右键启用。
需要经济前置时
若插件包明确说明依赖经济系统,请严格按顺序:先安装并启用 Jaryan.UniQQ.Economy.uniqq,再安装并启用 ZL-综合插件。
⚙️ 首次配置
打开控制台:插件页选中「ZL-综合插件」→ 右键「设置」。若右键菜单没有「设置」,先确认插件已启用。
建议按以下顺序配置,不要一开始就打开全部功能:
- 填写全局主人 QQ:控制台 →「全局配置」→「全局主人 QQ」,填写管理者的 QQ(不一定是机器人 QQ)并保存;
- 完成免费绑定:加入官方群
327942687,发送「绑定码」获取一次性绑定码(24 小时有效),在控制台右上角「设置」→「安全」中完成绑定。插件首次安装后有 3 天全功能试用; - 授权第一个群:主人在目标群发送
授权本群(或授权本群 30天),或在控制台「授权群组」中操作; - 按需配置管理员:
添加副主#群号#QQ(仅主人)管理本群副主名单;添加群管理员+QQ加入本群权限名单(不改变 QQ 群身份);上管理员@某人/删除管理员@某人才是真正设置 QQ 群管理员(需机器人本身是群主); - 先开少量功能:首次只启用 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 是否填写并保存;当前群是否已授权;本群插件总开关是否开启;多机器人场景下本群是否已认领给正确的机器人;日志页是否有报错。
📚 下一节:基础概念与权限体系
