Skip to content

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 ​

  1. 打开 https://nodejs.org/ 下载 LTS 版安装包,双击安装,全程下一步即可。
  2. 装完后按 Win+R 输入 cmd 回车,验证版本:
node -v
npm -v
  1. 进入项目文件夹,双击 start.bat 启动(或在文件夹地址栏输入 cmd 回车后执行):
bat
start.bat

可选参数:start.bat force(强制重建前端界面)、start.bat verbose(保留全部安装/构建日志)。

注意

  • 首次启动会自动安装依赖、构建前端、打包后端,视网络需要 3-15 分钟;之后再启动只需几秒。
  • 不要把项目放在 OneDrive / 坚果云 / 百度网盘等同步目录,也不要放在路径过深的位置。
  • 启动窗口必须保持开启,关掉窗口即关掉机器人。

macOS ​

  1. 安装 Node.js(三选一):
bash
# 方式 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
  1. 放置项目(建议家目录,如 ~/kakake;开启 iCloud「桌面与文稿文件夹」同步时不要放桌面/文稿),然后启动:
bash
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 一键脚本(推荐服务器)

bash
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 示例):

bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

然后启动:

bash
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。

  1. 从 F-Droid 或 GitHub Releases 安装 Termux(不要用应用商店旧版)。
  2. 初始化并安装 Node.js:
bash
pkg update && pkg upgrade -y
pkg install -y nodejs-lts git unzip

默认镜像不通时先执行 termux-change-repo 切换国内镜像。

  1. 做好保活设置:关闭 Termux 的电池优化(设为无限制/允许后台高耗电),并在 Termux 常驻通知里点一次「ACQUIRE WAKELOCK」;Android 12+ 还需处理「幻影进程」限制。
  2. 项目必须放在 Termux 家目录 ~/kakake(不能放 /sdcard 等共享存储),然后启动:
bash
cd ~/kakake
bash start.sh

注意

  • 手机上跑不了 NapCat,需让手机上的咔咔「主动去连」别处的协议端(常用「正向 WS」),或使用微信 BOT(扫码即用,无需端口与域名)。
  • 便携版仅限 x86_64 + glibc,手机上只能装源码版。
  • 建议用电脑浏览器打开启动日志里的「局域网」地址操作控制台(手机与电脑需同一 Wi-Fi)。

首次登录 ​

启动完成后,控制台会输出类似信息:

text
启动完成 · 后台控制台: http://127.0.0.1:8787(本机)
登录密钥 (初始): Xk3!qm7Yv2#tRb9Ldz4A
快捷登录(本机): http://127.0.0.1:8787/?key=...
会话:无互动 30 分钟退出 · 自登录起最长 3 小时 · 重启框架需重新登录
  1. 将「快捷登录」链接复制到浏览器,或打开 http://127.0.0.1:8787 后粘贴登录密钥。
  2. 首次登录需同意协议并设置自己的密码,之后使用新密码登录。
  3. 密钥存放于 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 反向 WSNapCat 连入咔咔咔咔监听 0.0.0.0:6700,NapCat 添加 WS 客户端指向 ws://127.0.0.1:6700(推荐入门)
OneBot 正向 WS咔咔连出 NapCatNapCat 开 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
微信 BOTiLink 扫码登录无需 NapCat、无需公网域名,扫码登录后长轮询收发

三种连接类型对应三套插件页签:OneBot / NapCat →「插件」;QQ 官方机器人 →「QQ官方机器人」;微信 BOT →「微信机器人」。连接启用后,需在对应页签按该连接打开插件开关。

对接后自检 ​

  1. 确认 NapCat / 开放平台 / 微信扫码状态已保存,对应连接已启用。
  2. 咔咔连接开关打开,必要时重启咔咔。
  3. 往测试群或私聊发一条消息,查看咔咔是否出现上报日志。
  4. 到对应插件页签确认该连接下插件已开启。

🔌 插件开发 ​

插件体系 ​

zlbot 按连接类型区分插件体系,插件以文件夹形式放入 plugins/ 目录,安装后在控制台打开「总开关 + 连接子开关」两层开关方可生效。

OneBot 插件入门 ​

OneBot 插件文件夹以 zl- 开头(如 zl-plugin-hello),入口文件必须导出 plugin_init 函数(收消息还需导出 plugin_onmessage);JavaScript 轨直接编写 .mjs,TypeScript 轨经构建后将产物夹(package.json、plugin.json、index.mjs)整体拷入 plugins/。

text
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 开发,无需安装依赖。最小插件示例:

js
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] 字体包操作检测与安装中文字体,解决群图片中文乱码

安装与常用参数:

bash
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):

bash
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/ 目录,排查与备份均以这两个目录为主。

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