NapCatQQ 完整指南：如何快速搭建基于 NTQQ 的无头 QQ 机器人

【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ

NapCatQQ 是一个基于 NTQQ 的现代化 Bot 协议端框架，面向想要做 QQ 机器人但希望跳过底层协议实现的开发者。它以无头（无界面）服务形式运行，完整实现 OneBot 11 协议，并附带 WebUI 管理面板，适合需要消息收发、群管理、文件传输与事件监听能力的个人开发者和小团队。核心代码分布在 packages/napcat-core/（API 与事件）、packages/napcat-onebot/（OneBot 11 协议层）等模块中。

🎯 项目定位与适用场景

它和纯协议端方案最大的不同，在于不自己拼协议包：NapCat 直接驱动 NTQQ 自带的通信层，稳定性和版本跟随成本都更低。

💻 从零部署：5 分钟完成首次部署

环境准备：Node 18+、pnpm，以及一份可正常登录的 NTQQ 客户端环境（官方发布包会内置所需运行环境，从源码构建则需自备）。

安装：

git clone https://gitcode.com/gh_mirrors/na/NapCatQQ cd NapCatQQ && pnpm install pnpm build:framework && pnpm build:webui

首次运行：Windows 下执行napcat.bat，Linux 下用 Node 加载 packages/napcat-shell-loader/ 中的loadNapCat.js。启动后终端会打印 WebUI 地址（默认 6099 端口）和访问 token，浏览器打开即可扫码登录。默认启用的网络通道见 packages/napcat-develop/config/onebot11.json：HTTP 3000 端口、WebSocket 3001 端口。

⚙️ 核心能力拆解

OneBot 11 协议：四类网络通道按需启用

能力说明：实现 OneBot 11 标准事件与 Action 接口，支持 HTTP 服务端/SSE、WebSocket 服务端/客户端，以及把事件推给插件系统的通道。

关键模块：packages/napcat-onebot/network/ 下每种通道一个实现文件，端口、token、消息格式等参数集中在 onebot11.json 配置里，全部默认关闭、按需开启。

典型用法：如果你的机器人框架用 WebSocket 拉事件，只开一个 websocket-server；如果只是想用 HTTP 调接口，只开 http-server，两者互不影响。

OneBot 11 扩展 Action：从标准接口到 NapCat 私有接口

能力说明：除 OneBot 11 标准接口外，还封装了一批 NapCat 私有 Action，覆盖 AI 会话、群相册、闪传、OCR、群待办等客户端能力，总数超过 100 个。

关键模块：packages/napcat-onebot/action/ 按 group、user、file、msg、go-cqhttp、extends 分组，每个文件对应一个 Action，入参出参有 JSON Schema 描述。

典型用法：通过 HTTP 调getGroupAlbumMediaList拉取群相册媒体列表，调sendGroupAiRecord发送 AI 语音记录，调用方式与标准接口一致。

事件系统：13 个内核监听器统一转 OneBot 事件

能力说明：把 QQ 内核抛出的原始事件统一转换成 OneBot 11 事件下发，包括好友申请、群成员变动、群消息撤回、被踢下线等。

关键模块：packages/napcat-core/listeners/ 包含 13 个监听器类，事件定义集中在 packages/napcat-onebot/event/，按 message、notice、request、meta 四类组织。

典型用法：监听group_request事件实现入群自动审批，监听message事件做关键词触发，监听notice.offline做断线告警。

文件与流式传输：在线文件、闪传与断点能力

能力说明：覆盖在线文件（云端文件）收发、闪传（面对面传文件）、本地文件上传下载，下载走流式实现，大文件不会一次性占满内存。

关键模块：packages/napcat-core/apis/file.ts 提供底层 API，packages/napcat-onebot/action/stream/ 提供下载/上传流的 Action 封装。

典型用法：群内收到文件后调downloadFile落盘，再传给下游处理；发送方向用uploadGroupFile上传到群文件目录。

WebUI 与插件：浏览器管理面板和可扩展插件位

能力说明：内置 WebUI 服务提供登录、日志查看、配置管理、终端能力，默认监听 6099 端口，启动日志中直接给出带 token 的访问地址；同时提供插件机制，第三方代码可以注册自己的 API 路由和页面。

关键模块：packages/napcat-webui-backend/ 承载 WebUI 后端，packages/napcat-onebot/network/plugin/ 负责插件加载、配置校验与路由注册，内置插件示例见 packages/napcat-plugin-builtin/。

典型用法：在 onebot11.json 的 plugins 里登记插件目录，插件启动后通过pluginRouters挂载自定义 HTTP 接口，复用 NapCat 的鉴权与事件上下文。

🔧 典型应用场景

群管理机器人：入群审批、违规封禁与公告维护

场景：一个常驻群的机器人，负责自动审批入群申请、检测违规消息并封禁发言、定期更新群公告。

实现思路：用 websocket-server 接入框架，收到group_request事件后按白名单自动 approve/reject；收到message事件后做关键词检测，命中违规词就调setGroupBan限时禁言、反复违规则setGroupKick；公告维护用sendGroupNotice定时下发。

涉及模块：packages/napcat-onebot/action/group/ 的群组操作集合，以及 packages/napcat-onebot/event/ 的事件定义。

消息推送与导出：把 QQ 消息变成数据流

场景：把群消息实时推送到自建服务做归档或分析，例如接入消息导出工具或 LLM 对话框架。

实现思路：启用 websocket-client 或 http-client，把 OneBot 事件推给外部进程；外部进程负责落库、转存图片（downloadFile拉取原图）、或交给大模型处理后再从机器人账号回发。

涉及模块：packages/napcat-onebot/network/ 的 client 通道，以及 packages/napcat-core/apis/msg.ts 的消息发送接口。

🔍 进阶与调优

日志与行为开关：框架级配置在 napcat.json 中，含fileLog、consoleLogLevel、packetBackend、autoTimeSync等项，模式定义见 packages/napcat-core/helper/config.ts。排查问题时把 consoleLogLevel 调到 debug；autoTimeSync每小时自动与服务器对时，服务器时钟偏差大时建议保持开启，可减少风控触发。

网络通道安全：WebUI 访问走启动时生成的 token；OneBot 各通道支持独立 token。生产环境建议：给每个通道配置非空 token，避免把服务端口直接暴露到公网，只对本机或内网监听。

缓存与性能：重复查询联系人、群信息等数据时，优先复用框架内部缓存与 LRU 机制（见 packages/napcat-common/src/），不要为同一数据反复发起请求；大批量消息处理用异步顺序处理，避免短时高频调用触发频率限制。

🛠️ 常见问题排查

📌 资源与社区

• 文档与入口：README.md 汇总了构建方式、文档站与交流群信息
• 插件开发参考：packages/napcat-plugin-builtin/ 内置插件示例
• 社区交流：README 中列出的 QQ 交流群与 Telegram 群组，入群密钥可在 WebUI 的关于页面获取

下一步建议：先按上面的步骤把 WebUI 跑起来、完成一次扫码登录，然后用 websocket 写一个只打印消息的最小监听脚本。跑通后再去 packages/napcat-onebot/action/ 里按目录浏览可用 Action，从群消息处理入手写第一个真正有用的机器人。

【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ