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

NapCatQQ 完整指南如何快速搭建基于 NTQQ 的无头 QQ 机器人【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQNapCatQQ 是一个基于 NTQQ 的现代化 Bot 协议端框架面向想要做 QQ 机器人但希望跳过底层协议实现的开发者。它以无头无界面服务形式运行完整实现 OneBot 11 协议并附带 WebUI 管理面板适合需要消息收发、群管理、文件传输与事件监听能力的个人开发者和小团队。核心代码分布在 packages/napcat-core/API 与事件、packages/napcat-onebot/OneBot 11 协议层等模块中。 项目定位与适用场景维度说明解决什么问题省去手写 QQ 协议的工作量提供可直接调用的 OneBot 11 接口目标人群QQ 机器人开发者、需要消息自动化与群管理能力的团队运行形态无头服务可长期运行在本地或服务器配合 WebUI 远程管理与同类方案差异运行在 NTQQ 客户端进程内部复用官方协议实现而不是从零构造协议包它和纯协议端方案最大的不同在于不自己拼协议包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.batLinux 下用 Node 加载 packages/napcat-shell-loader/ 中的loadNapCat.js。启动后终端会打印 WebUI 地址默认 6099 端口和访问 token浏览器打开即可扫码登录。默认启用的网络通道见 packages/napcat-develop/config/onebot11.jsonHTTP 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 提供底层 APIpackages/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 调到 debugautoTimeSync每小时自动与服务器对时服务器时钟偏差大时建议保持开启可减少风控触发。网络通道安全WebUI 访问走启动时生成的 tokenOneBot 各通道支持独立 token。生产环境建议给每个通道配置非空 token避免把服务端口直接暴露到公网只对本机或内网监听。缓存与性能重复查询联系人、群信息等数据时优先复用框架内部缓存与 LRU 机制见 packages/napcat-common/src/不要为同一数据反复发起请求大批量消息处理用异步顺序处理避免短时高频调用触发频率限制。️ 常见问题排查现象可能原因处理办法启动即报 The specified module could not be found日志提示缺少 mfplat.dllWindows Server 默认不装「媒体基础」组件wrapper.node 依赖它在服务器管理器中添加「媒体基础」角色和功能重启后重试WebUI 打开不是预期的 6099 端口端口被占用框架会自动顺延尝试下一个端口查看启动日志中实际打印的 WebUi 地址而不是写死 6099账号掉线后没有重新拉起静默离线SelfOffline默认等待 60 秒让 QQ 自行重连被踢下线才立即重启看日志确认是哪种下线事件需要更快恢复时调整 offline-recovery 的重启延迟参数机器人收不到消息事件对应网络通道websocket-server 等未启用或 token 不匹配检查 onebot11.json 中该通道的 enable 与 token 配置 资源与社区文档与入口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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考