zlbot(咔咔)
zlbot(ZL官机控制台,昵称「咔咔」)是面向 QQ 官机与自动化机器人场景的本地运维中枢,提供 Web 控制台,集中管理连接、插件、日志与运行状态;本页覆盖安装部署、连接对接、插件开发入门与常用工具。
✨ 简介
ZL官机控制台(ZL-bot) 由薇薇/智晓科创维护,用于让机器人接入、巡检和维护更清晰可控。
| 能力 | 说明 |
|---|---|
| Web 控制台 | 浏览器后台:概览、连接、插件、资源、工具、日志、设置 |
| 连接管理 | 支持 OneBot、QQ 官方机器人、微信机器人等接入方式 |
| 插件扩展 | 支持本地插件安装、启停、配置与按账号隔离运行 |
| 运行监控 | 查看 CPU、内存、磁盘、进程占用和运行日志 |
| 本地持久化 | 配置、密钥、连接、插件状态保存在本机 data/ |
| 便携打包 | 可生成内置 Node 的 Windows / Linux 便携目录 |
交流群
QQ 群:327942687
兼容性说明
zlbot 保留对 OneBot 生态和部分 NapCat 插件结构的技术兼容,用于降低迁移和接入成本。相关兼容仅表示技术适配关系,不代表与腾讯 QQ、NapCat 或其他第三方项目存在隶属、代理或官方背书。
📦 安装部署
环境要求
- Node.js >= 20(推荐 22 LTS)
- 能联网、硬盘剩余空间 ≥ 2 GB(Linux 建议 ≥ 3 GB)
- Windows / Linux / macOS 均可运行;安卓手机可通过 Termux 运行
Windows
- 打开 https://nodejs.org/ 下载 LTS 版安装包,双击安装,全程下一步即可。
- 装完后按 Win+R 输入
cmd回车,验证版本:
node -v
npm -v- 进入项目文件夹,双击
start.bat启动(或在文件夹地址栏输入cmd回车后执行):
start.bat可选参数:start.bat force(强制重建前端界面)、start.bat verbose(保留全部安装/构建日志)。
注意
- 首次启动会自动安装依赖、构建前端、打包后端,视网络需要 3-15 分钟;之后再启动只需几秒。
- 不要把项目放在 OneDrive / 坚果云 / 百度网盘等同步目录,也不要放在路径过深的位置。
- 启动窗口必须保持开启,关掉窗口即关掉机器人。
macOS
- 安装 Node.js(三选一):
# 方式 A:官网 https://nodejs.org/ 下载 LTS 的 .pkg 安装
# 方式 B:Homebrew
brew install node@22
brew link --overwrite node@22
# 方式 C:nvm
nvm install 22
nvm use 22- 放置项目(建议家目录,如
~/kakake;开启 iCloud「桌面与文稿文件夹」同步时不要放桌面/文稿),然后启动:
cd ~/kakake
chmod +x start.sh
./start.sh可选参数:./start.sh force、./start.sh verbose。macOS 上不适用 mk 管理脚本。
Linux
主流 x86_64 / arm64 发行版(Debian 11+、Ubuntu 20.04+、Rocky/Alma 8+ 等,要求 glibc ≥ 2.28),有两种路线任选其一。
路线 A:mk 一键脚本(推荐服务器)
sudo bash mk # 首次运行即安装
sudo mk # 日常打开菜单[2] NapCat操作:安装并启动协议端,[9]查看面板密钥后进 WebUI 扫码登录 QQ。[4] 咔咔操作:[2]安装咔咔(可选源码版 / 便携版)→[5]启动 →[9]查看登录密钥。[9] 开机自启:为 NapCat 与咔咔写入 systemd 服务(mk-kakake.service)。[5] 端口验证:排查 8787 / 6700 等端口占用。[10] 字体包操作:服务器未装中文字体导致群图片乱码时,先扫描再安装。
路线 B:手动 ./start.sh
先安装 Node.js 20+(Debian/Ubuntu 示例):
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs然后启动:
cd ~/kakake
chmod +x start.sh
./start.sh注意
- 不要
sudo ./start.sh,否则目录属主会变成 root,后续读写报 EACCES。 - 1 GB 及以下内存的机器建议先加 2 GB swap,否则前端构建可能被内核杀掉;或改用 mk 安装自带已构建前端的便携版。
- SSH 会话断开会导致进程退出,请用 mk 启动(自动转后台)或放入 tmux。
Termux(安卓手机)
适用 Android 7.0+ 的 64 位(arm64)机型,建议内存 ≥ 3 GB。
- 从 F-Droid 或 GitHub Releases 安装 Termux(不要用应用商店旧版)。
- 初始化并安装 Node.js:
pkg update && pkg upgrade -y
pkg install -y nodejs-lts git unzip默认镜像不通时先执行 termux-change-repo 切换国内镜像。
- 做好保活设置:关闭 Termux 的电池优化(设为无限制/允许后台高耗电),并在 Termux 常驻通知里点一次「ACQUIRE WAKELOCK」;Android 12+ 还需处理「幻影进程」限制。
- 项目必须放在 Termux 家目录
~/kakake(不能放/sdcard等共享存储),然后启动:
cd ~/kakake
bash start.sh注意
- 手机上跑不了 NapCat,需让手机上的咔咔「主动去连」别处的协议端(常用「正向 WS」),或使用微信 BOT(扫码即用,无需端口与域名)。
- 便携版仅限 x86_64 + glibc,手机上只能装源码版。
- 建议用电脑浏览器打开启动日志里的「局域网」地址操作控制台(手机与电脑需同一 Wi-Fi)。
首次登录
启动完成后,控制台会输出类似信息:
启动完成 · 后台控制台: http://127.0.0.1:8787(本机)
登录密钥 (初始): Xk3!qm7Yv2#tRb9Ldz4A
快捷登录(本机): http://127.0.0.1:8787/?key=...
会话:无互动 30 分钟退出 · 自登录起最长 3 小时 · 重启框架需重新登录- 将「快捷登录」链接复制到浏览器,或打开
http://127.0.0.1:8787后粘贴登录密钥。 - 首次登录需同意协议并设置自己的密码,之后使用新密码登录。
- 密钥存放于
data/auth-key.json;忘记密码时停掉服务、删除该文件后重启,会生成新的初始密钥。
日常操作速查:启动即运行启动命令;停止按 Ctrl+C 或关闭窗口;修改 data/config.json 后必须重启生效;更新版本后用 force 参数重建;备份只需备份 data 与 plugins 两个文件夹。
🔗 连接对接
使用原则
- 每个机器人账号只启用一种对接方式,OneBot 正反向与多种 HTTP 不要一起开,否则易重复收消息。
- Access Token / Token 两边必须一致;两边都空即不鉴权。
- 端口区分:8787 是咔咔后台控制台端口,6700 / 6701 是 OneBot 对接监听端口,不要混淆。
- NapCat 跑在 Docker 容器内时,访问宿主机上的咔咔一般用
http://172.17.0.1:端口(macOS 上为host.docker.internal),且咔咔监听地址须为0.0.0.0。
对接方式一览
| 模式 | 方向 | 说明 |
|---|---|---|
| OneBot 反向 WS | NapCat 连入咔咔 | 咔咔监听 0.0.0.0:6700,NapCat 添加 WS 客户端指向 ws://127.0.0.1:6700(推荐入门) |
| OneBot 正向 WS | 咔咔连出 NapCat | NapCat 开 WS 服务端(如 3001),咔咔填其地址与端口 |
| HTTP 服务器 | NapCat POST 上报 | 咔咔监听 :6701 收上报,并经 NapCat HTTP API(如 http://127.0.0.1:3000)调接口 |
| HTTP SSE 服务器 | 同上 + SSE 订阅 | 参数与 HTTP 服务器相同,另支持其他程序以 SSE 订阅事件 |
| HTTP 客户端 | 不另开上报口 | 事件上报走 http://127.0.0.1:8787/onebot/http/<连接id>,适合只有一个对外端口的场景 |
| QQ 官方 · WS | 咔咔连腾讯网关 | 填 AppID / AppSecret 即可,无需域名(推荐) |
| QQ 官方 · HTTPS | 腾讯回调 | 需域名 + HTTPS,回调地址形如 https://你的域名/gfbot/<连接id>,公网端口须为 80/443/8080/8443 |
| 微信 BOT | iLink 扫码登录 | 无需 NapCat、无需公网域名,扫码登录后长轮询收发 |
三种连接类型对应三套插件页签:OneBot / NapCat →「插件」;QQ 官方机器人 →「QQ官方机器人」;微信 BOT →「微信机器人」。连接启用后,需在对应页签按该连接打开插件开关。
对接后自检
- 确认 NapCat / 开放平台 / 微信扫码状态已保存,对应连接已启用。
- 咔咔连接开关打开,必要时重启咔咔。
- 往测试群或私聊发一条消息,查看咔咔是否出现上报日志。
- 到对应插件页签确认该连接下插件已开启。
🔌 插件开发
插件体系
zlbot 按连接类型区分插件体系,插件以文件夹形式放入 plugins/ 目录,安装后在控制台打开「总开关 + 连接子开关」两层开关方可生效。
OneBot 插件入门
OneBot 插件文件夹以 zl- 开头(如 zl-plugin-hello),入口文件必须导出 plugin_init 函数(收消息还需导出 plugin_onmessage);JavaScript 轨直接编写 .mjs,TypeScript 轨经构建后将产物夹(package.json、plugin.json、index.mjs)整体拷入 plugins/。
plugins/zl-plugin-hello/
package.json
plugin.json
index.mjs开发要点:
- 收发消息均使用 JSON 消息段数组(如
{ type: 'text', data: { text: '你好' } }),不要使用 CQ 码或raw_message。 - 通过
ctx.logger输出日志;通过ctx.actions.call(接口名, 参数对象)调用协议端任意接口,例如send_group_msg(发群消息)、send_private_msg(发私聊)、set_group_ban(群禁言,时长单位为秒,0 表示解除)。 - 参数键名遵循 OneBot11 约定(如
group_id、user_id、duration)。
QQ 官方机器人插件(zlbot-sdk)
面向 QQ 官方机器人(GF 插件体系)的插件,文件夹以 GF- 开头(如 GF-plugin-demo),基于单文件 SDK zlbot-sdk 开发,无需安装依赖。最小插件示例:
import { definePlugin } from 'zlbot-sdk';
export const { plugin_init, plugin_onevent, plugin_cleanup } = definePlugin({
name: 'GF-plugin-demo', // 和文件夹同名
displayName: '演示插件',
version: '1.0.0',
author: '你的名字',
description: '我的第一个插件',
setup(ctx) {
ctx.command(' ping', {}, async (ev) => {
await ev.replyText('pong!');
});
},
});SDK 提供的主要能力:
| 能力 | 说明 |
|---|---|
| 指令系统 | ctx.command,支持别名、权限门槛(0 所有人 / 1 群管理员 / 2 仅主人)、帮助文本 |
| 事件监听 | ctx.on:群消息、私聊消息、进群、退群、进群申请、按钮点击回调等,内置事件去重 |
| 回复与发送 | ev.replyText / replyMarkdown / replyKeyboard / replyArk,富媒体需先上传再发送;主动消息有每日额度,优先用被动回复 |
| 群管 | 撤回、禁言 / 解禁(单次 ≤20 人)、踢人、群黑名单、成员列表翻页等 |
| 存储 | KV 存储 JSON 自动落盘,支持按群隔离命名空间 |
| 配置 Schema | 声明后在后台自动生成设置表单,保存立即生效 |
| 定时任务 | ctx.cron.every 固定间隔、ctx.cron.daily 每天固定时刻 |
| 权限 | 主人列表、群管理员判断、运行时增删主人 |
开发注意
- 修改 SDK 或插件 lib 文件后必须重启框架;只有插件入口
index.mjs支持热重载。 - 同一
msg_id最多被动回复 5 次;ARK 卡片需向平台运营申请权限,建议失败时降级为 markdown + 键盘。 - 群管动作要求机器人在目标群具备管理员身份。
🧰 常用工具:MK 管理脚本
mk 是面向 Linux 服务器与 Termux(安卓手机) 的一键管理脚本(Windows / macOS 不适用),交互菜单覆盖:
| 菜单 | 功能 |
|---|---|
| [1] 宝塔操作 | 安装/管理宝塔面板 |
| [2] NapCat操作 | 安装、启停、配置 NapCat,查看面板登录密钥 |
| [3] snowLuma操作 | 安装/启停 SnowLuma 与兼容 QQ(含扫码桌面) |
| [4] 咔咔操作 | 安装咔咔(源码版/便携版)、装 Node、启停、构建 Web UI、查看登录密钥 |
| [5] 端口验证 | 查端口占用、杀进程 |
| [6] 构建 MK 源码 | 为 MK 插件源码执行构建(需 Node 20+) |
| [9] 开机自启 | systemd 服务 / Termux:Boot 自启 |
| [10] 字体包操作 | 检测与安装中文字体,解决群图片中文乱码 |
安装与常用参数:
sudo bash mk # Linux 首次安装(需要 root)
bash mk # Termux 安装(免 root,不要加 sudo)
sudo mk # 日常打开菜单
mk --version # 查看版本
mk --help # 用法说明
mk --uninstall # 卸载 mk 本身(不自动卸载 NapCat / 咔咔)- 咔咔两种安装形态:便携版自带 Node 与已构建产物,最省事(仅限 x86_64 + glibc);源码版需要 Node,启动前会构建前端。
- mk 重装咔咔会保留
data/与plugins/,不会丢失配置和插件。 - Termux 上仅部分菜单可用(宝塔、NapCat、snowLuma、实验功能、字体包等依赖 root / systemd / 桌面环境的菜单会被拦截)。
❓ 常见问题
后台密码忘了? 停掉服务,删除 data/auth-key.json 后重新启动,会生成新的初始密钥。
端口 8787 被占用? 先查占用进程再决定结束或换端口(改 data/config.json 的 port):
netstat -ano | findstr :8787 # Windows
lsof -nP -iTCP:8787 -sTCP:LISTEN # macOS
ss -tlnp | grep 8787 # Linux也可用 mk 的 [5] 端口验证 查询并结束进程。监听端口需 ≥ 1024。
浏览器打开后台是空白页或一直转圈? 先看控制台有无「Web UI 未构建」警告,有则用 force 参数重启;再按 Ctrl+F5(macOS 为 Command+Shift+R)强制刷新缓存。
机器人重复收消息? 同一账号同时开启了多种对接方式(如反向 WS 与 HTTP 一起开),只保留一种即可;改用 HTTP 客户端模式时请关闭原 HTTP 服务器的监听。
服务器上群里图片中文全是方块? 服务器缺少中文字体,用 mk 的 [10] 字体包操作 先扫描再安装(文泉驿微米黑或 Noto CJK SC 均可)。
SSH 一断开服务就停? 进程随会话退出所致,改用 mk 启动(自动转后台)、放入 tmux/screen,或配置 systemd 开机自启。
手机息屏几分钟后机器人掉线? 未做好保活:关闭 Termux 电池优化、点一次「ACQUIRE WAKELOCK」,并处理 Android 12+ 的幻影进程限制。
对公网开放控制台要注意什么?data/、log/、插件配置、登录密钥与连接凭证不要公开分发;对公网开放前请自行配置防火墙、HTTPS、反向代理和访问控制;使用第三方连接载体、插件、API 或 AI 服务时,请自行评估账号、费用、隐私与合规风险。
🆘 获取帮助
- 交流群:327942687(ZL官机控制台 · 薇薇/智晓科创)。
- 提问时请附上控制台里第一条
[ERROR]开头的完整日志,以及node -v的输出;Linux 另附系统与内存信息(如/etc/os-release、free -h),手机端另附机型与安卓版本。仅描述「起不来」很难定位问题。 - 日志位于
log/目录,配置与连接信息位于data/目录,排查与备份均以这两个目录为主。
