Skip to content

平台总览 ​

本板块介绍 QQ 机器人生态的三个组成部分——UniQQ 机器人框架、zlbot(咔咔)控制台与 QQ 官方机器人协作模式,帮助您了解三者的定位、能力与相互关系,并快速进入对应文档。

✨ 简介 ​

搭建一个 QQ 机器人,通常需要三类角色配合完成:

组成部分定位说明
UniQQ 机器人框架机器人框架与插件运行底座承载各类插件运行(如综合插件、售卡系统、资料卡、关键词统计、自定义报时等)。框架侧的机器人实例可见真实 QQ 群号与真实用户 QQ 号,能够执行禁言、踢人、撤回、改群名片等强执行动作。
zlbot(咔咔)本地运维控制台全称「ZL官机控制台(ZL-bot)」,提供 Web 控制台,集中管理连接、插件、日志、系统状态与运行配置,支持 OneBot、QQ 官方机器人、微信机器人等接入方式,可部署于 Windows / macOS / Linux / Termux(安卓)。
QQ 官方机器人协作双机器人协同模式在 UniQQ 综合插件上开启的协作模式:官方 QQ 机器人负责前台收发消息与回复,综合插件负责业务判断,UniQQ 插件机器人负责后台执行落地动作。

📖 术语约定 ​

阅读本板块文档前,建议先了解以下术语:

术语含义
官方机器人经 QQ 开放平台接入的机器人,负责前台消息收发与回复;其视角下的群与用户以 group_openid、member_openid 等标识表示
插件机器人运行于 UniQQ 框架的机器人实例,可见真实 QQ 群号与真实用户 QQ 号,负责落地强执行动作
综合插件UniQQ 框架上的业务插件,承担菜单、问答、入群验证、违禁词、定时任务、AI 等业务判断
协议端真正登录 QQ 的那一端(如 NapCat、SnowLuma),机器人框架通过 WebSocket 等方式与其对接
OneBot一种机器人协议约定,约定了消息结构与接口命名;zlbot 支持其反向 WS、正向 WS 及多种 HTTP 对接方式
Web 控制台浏览器中的管理后台,zlbot 默认端口为 8787

🧭 三者如何协作 ​

以「QQ 官方机器人协作」模式为例,一条消息的完整链路如下:

text
用户在群内发送消息
   ↓
官方 QQ 机器人收到消息(前台交互)
   ↓
综合插件进行业务判断(业务大脑)
   ↓
需要回复的内容 → 由官方机器人发出
需要强执行的动作(禁言、踢人、撤回等) → 由 UniQQ 插件机器人执行
  • 用户视角:在群里看到的回复、菜单、验证提示与处理结果,优先由官方机器人发出。
  • 业务视角:菜单匹配、问答、入群验证、违禁词检查、定时任务等判断逻辑由综合插件完成。
  • 执行视角:官方机器人不便稳定完成的强执行动作,交给拥有真实群号与管理员权限的插件机器人落地。
  • 身份衔接:官方机器人侧只能看到 group_openid、member_openid 等标识,插件机器人侧看到的是真实群号与 QQ 号,两侧通过身份映射机制对齐。

关闭协作模式后,综合插件回到原有独立运行方式,不影响已有用户与已有群。

🤔 如何选择 ​

需求场景建议
需要图形化控制台,统一管理连接、插件、日志使用 zlbot(咔咔),其 Web 控制台覆盖概览、连接、插件、资源、工具、日志、设置
需要 QQ 之外的接入渠道(如微信)zlbot 支持微信 BOT(iLink 扫码登录),并兼容 OneBot / QQ 官方机器人接入
已使用 UniQQ 插件生态(综合插件、售卡系统等)继续以 UniQQ 为框架运行插件
希望由官方机器人形象对外回复,同时保留强执行能力在 UniQQ 综合插件上开启「QQ 官方机器人协作」模式
需要 7×24 稳定挂机建议部署在 Linux 服务器上(zlbot 提供 mk 管理脚本与开机自启支持)
需要菜单化的服务器运维工具zlbot 的 mk 管理脚本覆盖装环境、装协议端、启停、端口排查、中文字体、开机自启(Linux / Termux)
手头有闲置安卓手机想当小服务器zlbot 支持 Termux(安卓)部署,闲置旧手机长期插电即可运行(不适合主力机)

🧩 典型部署组合 ​

组合说明适用场景
UniQQ 插件独立运行综合插件按原有方式独立运行,消息收发与动作执行均由插件机器人完成不需要官方机器人形象,沿用原有插件生态
官方机器人协作官方机器人负责前台回复,综合插件负责业务判断,插件机器人负责强执行动作希望由官方机器人形象对外,同时保留群管强执行能力
zlbot + NapCat(反向 WS)本机或同服务器部署时最省事的 QQ 接入组合:咔咔监听 6700,NapCat 作为 WS 客户端连入快速搭建 QQ 群聊机器人
zlbot + QQ 官方机器人(WS 模式)填入 AppID / AppSecret 即可,无需域名与反向代理使用开放平台官方机器人且不想折腾回调部署
zlbot + 微信 BOTiLink 扫码登录即可收发,无需端口与域名微信渠道的轻量接入

� 上手建议 ​

初次搭建 QQ 机器人时,可按以下顺序推进:

  1. 确定部署平台:个人电脑可即时上手;需要长期稳定运行时,建议部署到 Linux 服务器(zlbot 提供 mk 管理脚本与开机自启支持)。
  2. 部署框架或控制台:按对应文档完成环境准备、安装与首次启动,登录管理后台。
  3. 接入消息渠道:QQ 渠道需先部署协议端(如 NapCat)再对接;也可选择 QQ 官方机器人或微信 BOT 渠道。注意每个账号只启用一种对接方式。
  4. 安装并启用插件:在控制台打开插件总开关,再打开对应连接的连接子开关。
  5. 测试验证:往测试群或私聊发送一条消息,通过日志确认消息已正常上报、插件已生效。
  6. 日常运维:按需配置开机自启,定期备份 data 与 plugins 目录(配置、连接、插件均在其内)。

📚 文档导航 ​

以下文档按产品划分,建议先通读本页了解整体关系,再进入对应产品文档查阅细节:

🆘 获取帮助 ​

  • 各产品的交流渠道与提问方式见对应文档页内的「获取帮助」章节(如 zlbot 官方交流群:327942687)。
  • 提问前建议先查阅对应文档的「常见问题」,并准备好运行日志与版本信息,以便快速定位问题。
  • 涉及密钥、凭证与本地数据的问题,请勿在公开渠道张贴 AppSecret、登录密钥及 data/ 目录内容。
  • 部署类问题可先对照对应文档的「常见问题」逐条自查,多数集中在忘记密码、端口占用、首次启动构建与后台保活等场景。

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