NapCatQQ：把最难接的 QQ 协议层，变成一组能直接调用的接口

简介说明
QQ 机器人真正难的，往往不是业务代码
做一个自动回复机器人并不复杂。判断消息、调用接口、拼接回复，这些逻辑用几十行代码就能写出原型。
麻烦的是如何稳定地接收 QQ 消息，又怎样把发送消息、群管理、好友请求、文件操作等能力提供给业务程序。

只要涉及真实客户端、登录状态、消息事件和版本适配，原本简单的机器人就会迅速变成一项协议工程。
NapCatQQ 解决的正是这一层问题。
它不是聊天机器人，也没有规定机器人必须接入哪个大模型。更准确地说，NapCatQQ 是连接 NTQQ 与上层应用的协议端：

下层调用 NTQQ 客户端提供的能力，上层则把这些能力转换成 OneBot 11 风格的接口，

交给 NoneBot、Koishi 等机器人框架，或者开发者自己的程序使用。
简单理解，它位于下面这条链路的中间：

NTQQ 客户端
↓
NapCatQQ 核心
↓
OneBot 11 适配层
↓
HTTP / WebSocket
↓
机器人框架或独立业务程序

这也是 NapCatQQ 最有价值的地方：业务开发者不必从 QQ 客户端这一侧重新开始，只需要面对一套更熟悉、更容易调试的接口。
它没有重新实现一套 QQ
“QQ 协议端”很容易让人误以为 NapCatQQ 是从零实现了 QQ 登录、通信和消息协议，实际并非如此。
根据官方文档的说明，NapCatQQ 会调用 NTQQ 客户端暴露的底层 Node 模块和客户端能力，再将消息、

事件与操作转换成上层可以使用的接口。它还可以自行引导 QQ 启动，核心调用不依赖传统意义上的 Electron IPC Hook。
这种方案带来的好处很直接：大量客户端能力不需要再独立实现，项目也能更自然地融入 NTQQ 环境。
代价同样存在。NapCatQQ 与 QQ 客户端版本之间并非完全解耦，QQ 更新后可能出现兼容性变化。

因此，它更像一个需要持续维护和适配的工程组件，而不是安装一次便永远不变的标准服务。
OneBot 11 让业务层少走很多弯路
NapCatQQ 对上提供 OneBot 11 接口。对于已经使用机器人生态工具的开发者来说，这一点比单纯“能收发消息”更重要。
业务程序可以通过动作接口发送私聊或群聊消息、撤回消息、处理请求、管理群成员、查询历史记录和操作文件；

消息、通知、请求等内容，则通过事件上报交给上层处理。
结构组成
Languages
TypeScript
97.7%
JavaScript
1.3%
HTML
0.4%
Python
0.3%
Batchfile
0.2%
CSS
0.1%

接入方式

NapCatQQ 支持多种连接方式：

HTTP 服务端
HTTP 客户端
WebSocket 服务端
WebSocket 客户端

如果机器人框架主动调用 NapCatQQ，可以使用 HTTP 或连接它提供的 WebSocket 服务。

如果业务系统已经有固定入口，也可以让 NapCatQQ 主动连接指定地址。
这让它既能接入现成框架，也能服务于自己编写的后台程序。

你可以用 Python、JavaScript、Go 或其他语言开发业务层，只要程序能够处理 HTTP 或 WebSocket，

就不必与 NapCatQQ 使用相同的技术栈。
需要说明的是，NapCatQQ 提供了相当丰富的动作与事件支持，但这不代表 OneBot 11 的每一项定义都已完整覆盖。

准备依赖某个具体能力时，最好先在官方 API 和事件支持列表中确认。
WebUI 让配置和排查不再全靠命令行
NapCatQQ 自带的 WebUI 是它区别于许多协议端工具的一项实用设计。
启动服务后，管理员可以在浏览器中完成网络连接配置，并查看登录二维码、运行日志、系统状态和文件。

WebUI 还提供终端、调试和插件相关功能，遇到消息没有上报、连接断开或接口调用失败时，不必在多个日志文件之间来回翻找。
WebUI 默认使用 6099 端口，初始访问令牌随机生成，首次登录后会要求修改密码。

这个设计适合本机部署，但如果服务运行在云服务器上，仍然需要认真处理暴露范围：
不要直接把管理端口无保护地开放到公网。
为 HTTP 和 WebSocket 接口启用访问令牌。
使用防火墙限制来源地址。
通过反向代理提供 HTTPS 或 WSS。
不要在日志、脚本和公开仓库中泄露 Token。
NapCatQQ 能降低配置门槛，但网络边界和凭据安全仍然是部署者自己的责任。
Shell 模式更适合服务器
NapCatQQ 主要有 Shell 和 Framework 两种运行方式。
Shell 模式不依赖完整的图形界面，资源占用相对更低，更适合 Linux 服务器、Docker 容器和长期运行环境。

对于准备正式部署机器人服务的人来说，这通常是更合适的选择。
Framework 模式更接近桌面客户端使用体验，可以保留 GUI 交互。不过官方文档提到，

QQ 9.9.19 之后 LiteLoaderQQNT 的维护状况不够理想，并建议相关用户迁移到 Shell 模式。
项目提供的安装选择很多，包括 Windows Shell、Windows 一键包、桌面管理器、Linux 安装器、

Docker、AppImage、macOS 安装器以及 Termux。社区还维护了部分面板和云平台部署方案。
选择安装方式时，没有必要追求最复杂的组合：
Windows 本地体验可优先使用一键包或桌面管理器。
Linux 服务器适合 Shell 安装或 Docker。
需要迁移和重建环境时，Docker 更容易管理。
需要观察 QQ 客户端界面时，再考虑 Framework 模式。
无论选择哪一种方式，基本流程都差不多：安装匹配的 NTQQ 环境，下载对应的 NapCatQQ 版本，

启动并登录，在 WebUI 中配置 HTTP 或 WebSocket，最后让上层机器人框架连接进来。
它不只是一个 OneBot 转换器
除了协议端能力，NapCatQQ 还提供了 TypeScript 和 JavaScript 插件系统。
插件可以监听消息和事件、直接调用 OneBot 动作、注册 HTTP 路由、添加 WebUI 页面，

并保存自己的配置与数据。官方定义了较清晰的生命周期，包括初始化、消息处理、事件处理和卸载清理。

plugin_init
plugin_onmessage
plugin_onevent
plugin_cleanup

因此，一些不复杂的功能可以直接作为插件运行，不必再单独维护一个机器人进程。

例如消息记录、小型管理接口、状态面板或内部辅助功能，都可以留在 NapCatQQ 进程内完成。
不过，插件也能够接触更底层的 NapCatQQ 能力。这意味着第三方插件不应被当成普通网页扩展看待。

安装来源不明的插件之前，至少要检查其网络请求、文件读写、命令执行和凭据访问行为。
对于大型项目，业务逻辑依然更适合放在独立服务中。这样升级协议端时不容易影响业务代码，也便于单独测试、扩容和迁移。
NapCatQQ 适合拿来做什么
NapCatQQ 最常见的用途，是为机器人框架提供 QQ 接入能力。例如：

群聊问答与关键词回复
大模型聊天机器人
群成员管理和审核辅助
通知推送与定时任务
文件收集和消息归档
客服分流与工单接入
游戏群、社区和内部团队工具
QQ 消息与其他系统之间的桥接

它也适合不想引入完整机器人框架的开发者。一个小型服务只要连接 WebSocket、

监听事件并调用动作接口，就能够完成消息处理闭环。
但如果需求只是调用官方开放平台允许的能力，并且更看重长期稳定、规则明确和商业合规，

那么应当优先评估 QQ 官方机器人方案。NapCatQQ 的优势在于能力范围和接入灵活性，而不是替代所有官方场景。
使用之前，必须看清三个问题
第一个问题是账号风险。
NapCatQQ 属于非官方项目，使用第三方协议端可能触发平台风控，也不能保证账号长期稳定。

不要直接使用重要账号进行未经验证的自动化操作，更不应通过高频发言、批量加群或骚扰性行为测试系统极限。
第二个问题是版本适配。
它依赖 NTQQ 环境，QQ 客户端升级可能造成启动、登录或部分 API 异常。

正式部署时应固定经过验证的版本，并在升级前保留配置和回退方案。
第三个问题是项目许可。
NapCatQQ 不是可以随意商用和再发布的 MIT 项目。仓库采用混合许可，第三方代码继续遵循各自许可，

而项目自身的 LICENSE 对使用、修改、分发、公开修改代码以及商业用途设置了明确限制。
尤其需要注意的是，许可中包含禁止商业使用、限制修改后代码公开发布等条款。

准备把它集成到商业产品、制作二次发行包或公开修改版本之前，应当阅读当前仓库中的完整许可证，并在必要时联系作者取得授权。
这一点不能仅凭“GitHub 上公开了源码”来判断。能够查看源码，与拥有自由使用、修改和商业分发的权利，是两件不同的事。
它更适合哪些人
如果你正在使用 NoneBot、Koishi 或其他支持 OneBot 的框架，需要一个能力丰富的 QQ 协议端，

NapCatQQ 是值得研究的项目。它也适合熟悉 HTTP、WebSocket 和服务器运维，希望把 QQ 消息接入现有系统的开发者。
如果你需要的是官方服务等级协议、完全无账号风险、长期不受客户端版本变化影响，

或者准备在未取得授权的情况下进行商业发行，那么 NapCatQQ 并不适合作为默认答案。
它真正解决的问题，并不是教你写出一个会回复消息的机器人，而是把 QQ 客户端能力整理成一层可连接、

可配置、可调试的工程接口。协议端一旦稳定下来，上层开发才终于能回到业务本身。
对于 QQ 机器人生态来说，这正是最费时间，也最容易被低估的那部分工作。

图片预览

下载地址

https://github.com/NapNeko/NapCatQQ

https://pan.baidu.com/s/1cbIFDVPuC6SJLoICWokv6Q?pwd=6qke 提取码: 6qke

https://pan.quark.cn/s/d14142c7ce5b