QQ 群机器人腾讯官方可直接申请,但需企业实体,个人通常使用 QQ 小号替代。本文记录在腾讯云服务器(Linux 宝塔应用模板)上部署 NapCat QQ 机器人的过程。
1. 安装 NapCat
NapCat 官方文档提供了两种 Linux 安装方式,详见 Shell 安装。在腾讯云服务器(Linux 宝塔应用模板)环境下,经测试'NapCat.Linux.Launcher - 新式非入侵式启动器'方案有效。
打开终端,cd 至工作目录,执行以下命令:
curl -o napcat.sh https://jiashu.1win.eu.org/https://raw.githubusercontent.com/NapNeko/napcat-linux-installer/refs/heads/main/install.sh && sudo bash napcat.sh
该命令将一键安装 NapCat 和 Linux QQ,无需预先安装 QQ。

2. 启动方式
安装成功后,当前目录下将出现 QQ 和 napcat 两个文件夹,以及 4 个文件。
配置前建议先启动一次 QQ。由于 Linux 无图形界面,以下命令会自动创建临时虚拟显示并启动。
xvfb-run -a qq --no-sandbox
也可采用手动启动,效果相同,但必须在 libnapcat_launcher.so 所在目录下运行。
# 1. 启动 Xvfb 虚拟显示(端口:1,启用 GLX 和渲染)
Xvfb :1 -screen 0 1x1x8 +extension GLX +render > /dev/null 2>&1 &
# 2. 告诉程序使用该虚拟显示
export DISPLAY=:1
# 3. 运行程序(加载动态库)
LD_PRELOAD=./libnapcat_launcher.so qq --no-sandbox
3. NapCat 基本原理
了解实现原理有助于故障排查。
QQ 客户端启动时读取 /opt/QQ/resources/app/package.json,其中 "main" 属性指向执行入口。默认路径为 /opt/QQ/resources/app/app_launcher/index.js,现改为 loadNapCat.cjs 文件,该文件通常位于 /opt/QQ/resources/app/napcat 下。
打开 loadNapCat.cjs 文件,其中语句 await import("file://" + path.join(CurrentPath, "./napcat/napcat.mjs")) 指向 napcat.mjs 文件,请根据实际路径修改。
详情可参考官方文档 BootWay03 (半自动) 教程。
登录 QQ 号的相关配置文件位于 /opt/QQ/resources/app/napcat/config 下,包含 onebot11_<qq>.json、napcat_<qq>.json 等。
4. WebSocket 配置
NapCat 提供 WebUI 控制台。若无法登录,可编辑 文件,对应官方文档中关于 WebUI 配置正向与反向 WebSocket 的部分。

