平台总览
本板块介绍 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 + 微信 BOT | iLink 扫码登录即可收发,无需端口与域名 | 微信渠道的轻量接入 |
� 上手建议
初次搭建 QQ 机器人时,可按以下顺序推进:
- 确定部署平台:个人电脑可即时上手;需要长期稳定运行时,建议部署到 Linux 服务器(zlbot 提供 mk 管理脚本与开机自启支持)。
- 部署框架或控制台:按对应文档完成环境准备、安装与首次启动,登录管理后台。
- 接入消息渠道:QQ 渠道需先部署协议端(如 NapCat)再对接;也可选择 QQ 官方机器人或微信 BOT 渠道。注意每个账号只启用一种对接方式。
- 安装并启用插件:在控制台打开插件总开关,再打开对应连接的连接子开关。
- 测试验证:往测试群或私聊发送一条消息,通过日志确认消息已正常上报、插件已生效。
- 日常运维:按需配置开机自启,定期备份
data与plugins目录(配置、连接、插件均在其内)。
📚 文档导航
以下文档按产品划分,建议先通读本页了解整体关系,再进入对应产品文档查阅细节:
- UniQQ 机器人框架:框架介绍、基本使用、SDK 开发进展与插件生态。
- zlbot(咔咔):Windows / macOS / Linux / Termux 安装部署、连接对接要点、插件开发入门与 MK 工具。
- QQ 官方机器人协作:协作模式说明、身份映射机制与部署要点。
🆘 获取帮助
- 各产品的交流渠道与提问方式见对应文档页内的「获取帮助」章节(如 zlbot 官方交流群:327942687)。
- 提问前建议先查阅对应文档的「常见问题」,并准备好运行日志与版本信息,以便快速定位问题。
- 涉及密钥、凭证与本地数据的问题,请勿在公开渠道张贴
AppSecret、登录密钥及data/目录内容。 - 部署类问题可先对照对应文档的「常见问题」逐条自查,多数集中在忘记密码、端口占用、首次启动构建与后台保活等场景。
