5分钟跑起来一个QQ机器人NapCatQQ无头Bot框架实战指南【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ把 QQ 登录好后台就开始收消息、发文件、监听群事件全程没有 QQ 客户端窗口。NapCatQQ 是一个基于 NTQQ 的无头 Bot 框架完整支持 OneBot 11 协议自带 WebUI 管理界面和插件系统适合想把 QQ 机器人快速跑起来的开发者。NapCatQQ 适合谁先给结论一句话定位NapCatQQ 用 Node.js 把 NTQQ 包成一个可长期挂机的协议端对上输出标准 OneBot 11 接口。适合两类人一是想接入现有 OneBot 11 生态AstrBot、MaiBot、qq-chat-exporter 这类框架和工具都直接兼容不想自己写协议的人二是需要服务器端无人值守、可 Docker 化部署的机器人。不适合两类人想要完整 GUI 聊天体验的用户它是无头的界面只有 WebUI 管理面板以及只想跑个群签到脚本、不愿装 Node.js 环境的用户——那种场景直接用客户端插件更省事。从克隆到跑通最短上手路径先克隆仓库这一步是必须的git clone https://gitcode.com/gh_mirrors/na/NapCatQQ cd NapCatQQ pnpm install装完依赖后在 WebUI 里填入本机 NTQQ 的安装路径仓库里 packages/napcat-core/helper/config.ts 就是配置读取逻辑的入口再扫码登录 QQ。登录成功后 WebUI 的登录状态页会显示在线OneBot 适配器随之启动HTTP 服务默认监听 3000 端口、WebSocket 默认 3001 端口默认值定义在 packages/napcat-onebot/config/config.ts可改。此时用任意 OneBot 客户端连上 3000 端口发一条send_msg调用群里应该立刻收到消息——收到即跑通。消息收发与群文件管理它能帮你做什么接一个 7x24 客服在 packages/napcat-core/apis/msg.ts 这层 API 上做关键词匹配收到提问就回文本、图片、语音、视频支持转发、撤回、引用回复客服机器人就是收消息 → 判断 → 发消息一条链路。群里推文件不用人肉packages/napcat-core/apis/file.ts 覆盖群文件上传下载配合 packages/napcat-onebot/action/stream/ 里的流式接口大文件可以按进度分段传输、支持断点续传适合做资料分发机器人。管群自动化packages/napcat-core/apis/group.ts 提供成员、权限、公告、禁言等群管操作配合 packages/napcat-core/listeners/ 下的监听器群员进出、群请求、禁言事件都会实时回调入群审批、违规提醒、活跃度统计都能拼出来。消息推送与群数据监控监听器捕获到的群消息事件可以转发到 Webhook、邮件等渠道做日报推送和话题热度统计。无头架构怎么分层架构一览整体是三层从上到下各管一件事适配器层packages/napcat-core/adapters/ 把运行平台差异Windows/Linux/macOS抹平上层不用关心系统环境。协议与业务层packages/napcat-protocol/ 处理底层通信packages/napcat-core/services/ 里几十个 Service 对应具体业务能力登录、群、文件、消息备份等是 API 调用的落地点。OneBot 出口层packages/napcat-onebot/ 把内部能力翻译成标准 OneBot 11 事件与 action再经 packages/napcat-webui-frontend/ 的 WebUI 或插件系统暴露给用户。无头意味着没有 QQ 图形界面参与内存占用低、没有 UI 崩溃面、适合 Docker 容器长期部署。插件热加载与安全性能进阶玩法插件开发packages/napcat-plugin-builtin/ 是一个内置插件模板照着写一个自定义插件放进插件目录即可被加载支持热加载——改完代码不用重启整个框架在 WebUI 里操作即可生效调试新 action 时能省掉大量重启等待时间。性能与安全各抓重点性能上重复查询的成员信息、群信息优先走框架缓存而不是每次打 API消息处理一律用异步模式避免阻塞事件循环安全上OneBot 端口默认只绑 127.0.0.1对外暴露前先给适配器配 token见 packages/napcat-onebot/network/ 的适配器配置生产环境开日志审计敏感配置不要明文躺在仓库里。连接失败、发消息失败、插件不加载踩坑实录现象登录一直转圈或连接失败。原因九成是 NTQQ 路径没配对或版本太老。处理到 WebUI 检查 NTQQ 路径是否指向真实的安装目录确认版本是近期版本还不行就换个干净的登录环境重试。现象API 调用返回成功但群里收不到消息。原因通常是频控或权限——比如机器人不是群管理员禁言、踢人这类操作会静默失败发图太快也会触发限流。处理先查调用返回的具体错误码再确认机器人身份和发送间隔。现象插件加载异常WebUI 里插件状态报错。原因一般是插件依赖缺失或配置格式不对。处理看插件加载日志里的具体报错按提示补依赖、核对插件的 package 声明与配置文件字段。文档、社区与下一步入门教程和问题排查先查 NapCat 官方文档README 里列了多个镜像站入口内容一致挑能打开的用对接细节类问题社区不提供解答需要自己搜有编程基础想交流可以进 NapCat Family QQ 群群号在 README 的 Link 区入群密钥在 WebUI 关于页面获取。贡献方式仓库接受功能改进、Bug 修复和文档补全直接提 PR 即可。后续项目方向是多协议扩展、AI 对话集成和云端部署方案。现在就可以把上面 5 分钟步骤走一遍先让第一条消息发出去。【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/11/4 6:10:31 · 阅读 1.2k 5分钟跑起来一个QQ机器人：NapCatQQ无头Bot框架实战指南
5分钟跑起来一个QQ机器人NapCatQQ无头Bot框架实战指南【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ把 QQ 登录好后台就开始收消息、发文件、监听群事件全程没有 QQ 客户端窗口。NapCatQQ 是一个基于 NTQQ 的无头 Bot 框架完整支持 OneBot 11 协议自带 WebUI 管理界面和插件系统适合想把 QQ 机器人快速跑起来的开发者。NapCatQQ 适合谁先给结论一句话定位NapCatQQ 用 Node.js 把 NTQQ 包成一个可长期挂机的协议端对上输出标准 OneBot 11 接口。适合两类人一是想接入现有 OneBot 11 生态AstrBot、MaiBot、qq-chat-exporter 这类框架和工具都直接兼容不想自己写协议的人二是需要服务器端无人值守、可 Docker 化部署的机器人。不适合两类人想要完整 GUI 聊天体验的用户它是无头的界面只有 WebUI 管理面板以及只想跑个群签到脚本、不愿装 Node.js 环境的用户——那种场景直接用客户端插件更省事。从克隆到跑通最短上手路径先克隆仓库这一步是必须的git clone https://gitcode.com/gh_mirrors/na/NapCatQQ cd NapCatQQ pnpm install装完依赖后在 WebUI 里填入本机 NTQQ 的安装路径仓库里 packages/napcat-core/helper/config.ts 就是配置读取逻辑的入口再扫码登录 QQ。登录成功后 WebUI 的登录状态页会显示在线OneBot 适配器随之启动HTTP 服务默认监听 3000 端口、WebSocket 默认 3001 端口默认值定义在 packages/napcat-onebot/config/config.ts可改。此时用任意 OneBot 客户端连上 3000 端口发一条send_msg调用群里应该立刻收到消息——收到即跑通。消息收发与群文件管理它能帮你做什么接一个 7x24 客服在 packages/napcat-core/apis/msg.ts 这层 API 上做关键词匹配收到提问就回文本、图片、语音、视频支持转发、撤回、引用回复客服机器人就是收消息 → 判断 → 发消息一条链路。群里推文件不用人肉packages/napcat-core/apis/file.ts 覆盖群文件上传下载配合 packages/napcat-onebot/action/stream/ 里的流式接口大文件可以按进度分段传输、支持断点续传适合做资料分发机器人。管群自动化packages/napcat-core/apis/group.ts 提供成员、权限、公告、禁言等群管操作配合 packages/napcat-core/listeners/ 下的监听器群员进出、群请求、禁言事件都会实时回调入群审批、违规提醒、活跃度统计都能拼出来。消息推送与群数据监控监听器捕获到的群消息事件可以转发到 Webhook、邮件等渠道做日报推送和话题热度统计。无头架构怎么分层架构一览整体是三层从上到下各管一件事适配器层packages/napcat-core/adapters/ 把运行平台差异Windows/Linux/macOS抹平上层不用关心系统环境。协议与业务层packages/napcat-protocol/ 处理底层通信packages/napcat-core/services/ 里几十个 Service 对应具体业务能力登录、群、文件、消息备份等是 API 调用的落地点。OneBot 出口层packages/napcat-onebot/ 把内部能力翻译成标准 OneBot 11 事件与 action再经 packages/napcat-webui-frontend/ 的 WebUI 或插件系统暴露给用户。无头意味着没有 QQ 图形界面参与内存占用低、没有 UI 崩溃面、适合 Docker 容器长期部署。插件热加载与安全性能进阶玩法插件开发packages/napcat-plugin-builtin/ 是一个内置插件模板照着写一个自定义插件放进插件目录即可被加载支持热加载——改完代码不用重启整个框架在 WebUI 里操作即可生效调试新 action 时能省掉大量重启等待时间。性能与安全各抓重点性能上重复查询的成员信息、群信息优先走框架缓存而不是每次打 API消息处理一律用异步模式避免阻塞事件循环安全上OneBot 端口默认只绑 127.0.0.1对外暴露前先给适配器配 token见 packages/napcat-onebot/network/ 的适配器配置生产环境开日志审计敏感配置不要明文躺在仓库里。连接失败、发消息失败、插件不加载踩坑实录现象登录一直转圈或连接失败。原因九成是 NTQQ 路径没配对或版本太老。处理到 WebUI 检查 NTQQ 路径是否指向真实的安装目录确认版本是近期版本还不行就换个干净的登录环境重试。现象API 调用返回成功但群里收不到消息。原因通常是频控或权限——比如机器人不是群管理员禁言、踢人这类操作会静默失败发图太快也会触发限流。处理先查调用返回的具体错误码再确认机器人身份和发送间隔。现象插件加载异常WebUI 里插件状态报错。原因一般是插件依赖缺失或配置格式不对。处理看插件加载日志里的具体报错按提示补依赖、核对插件的 package 声明与配置文件字段。文档、社区与下一步入门教程和问题排查先查 NapCat 官方文档README 里列了多个镜像站入口内容一致挑能打开的用对接细节类问题社区不提供解答需要自己搜有编程基础想交流可以进 NapCat Family QQ 群群号在 README 的 Link 区入群密钥在 WebUI 关于页面获取。贡献方式仓库接受功能改进、Bug 修复和文档补全直接提 PR 即可。后续项目方向是多协议扩展、AI 对话集成和云端部署方案。现在就可以把上面 5 分钟步骤走一遍先让第一条消息发出去。【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考