NapCatQQ 上手指南基于 NTQQ 的无头 QQ 机器人框架3 分钟跑通第一个 Bot【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ想在 QQ 里跑一个机器人有人私聊它要自动回群里能踢人禁言、发公告定时往群里推一条通知。你不想自己啃 NTQQ 的底层协议也不想常驻一个带界面的 QQ 客户端。NapCatQQ 就是为此而做的一个基于 NTQQ 的无头 QQ 机器人框架它在服务器里驱动 NTQQ 内核完成登录和消息收发再把能力通过 OneBot 协议暴露成标准接口让你把精力放在业务逻辑上。 3 分钟看懂它是什么NapCatQQ 是「现代化的基于 NTQQ 的 Bot 协议端实现」。所谓无头headless指它不依赖 NTQQ 的图形界面框架加载 NTQQ 的wrapper.node直接驱动内核登录、收发消息、群操作都在服务端完成不需要显示器也不会因为界面卡顿、崩溃拖垮整个机器人。所谓模块化指项目按职责拆成一堆独立的 npm 包改动某一块不会牵连另一块。核心包大致是这样分工的包职责napcat-core协议核心封装 NTQQ 的登录、消息、群组、文件、用户等能力napcat-onebotOneBot 11 协议实现把核心能力映射成标准动作action与事件eventnapcat-shell启动入口与进程管理拉起内核、守护 Worker、崩溃自动重启napcat-webui-backend/napcat-webui-frontend内置 Web 管理界面登录、看消息、调接口、管插件napcat-common公共工具路径、日志、缓存、请求等napcat-native各平台原生模块wrapper、napi2native、ffmpeg 等数据流向可以概括成一句话NTQQ 内核 → napcat-core(协议能力) → napcat-onebot(OneBot 动作/事件) ↕ napcat-webui(管理界面) ↕ 你的 bot 框架(走 HTTP/WS)你写机器人时绝大多数时候只会和napcat-onebot暴露的接口打交道napcat-core负责把它落到 NTQQ 上。 从零跑起来安装、配置、启动安装。从项目 Release 页下载对应系统的版本包如果想从源码构建仓库是 pnpm workspacegit clone https://gitcode.com/gh_mirrors/na/NapCatQQ pnpm install配置。三件事必须做到位NTQQ 路径框架要能定位到你本机装好的 NTQQwrapper.node、major.node所在目录路径配置在启动入口读取的环境里。OneBot 网络监听端口在packages/napcat-develop/config/onebot11.json默认 HTTP3000、WebSocket3001只监听127.0.0.1。WebUI管理界面端口在packages/napcat-webui-backend/webui.json默认6099token字段默认是random。启动。Windows 直接跑启动脚本Linux/macOS 用 Node 跑入口node NapCat 目录/shell/napcat.js看到第一条消息。控制台会打印WebUi User Panel Url默认是http://127.0.0.1:6099/webui浏览器打开它扫码登录。注意当token为默认值时框架会自动生成一个 8 位随机密码并在登录成功后通过私聊把新密码发给你——所以登录后记得先查收那条私聊消息。登录态就绪后别人发的消息就会在 WebUI 的事件流里出现也同时按配置推给你的 HTTP/WS 客户端。 它能帮你做什么按真实使用顺序而不是按源码目录NapCatQQ 的常用能力分四段收消息。内核收到的私聊、群聊、系统消息经napcat-onebot解析后上报支持字符串与数组两种格式撤回、群名片变更、入群申请等灰条通知也会被识别成对应事件。事件清单集中在packages/napcat-onebot/event/。发消息。用 OneBot 的send_msg/send_private_msg/send_group_msg即可。packages/napcat-onebot/action/msg/SendMsg.ts支持文本、图片、语音、文件也支持合并转发node元素。管群。群管理类动作在packages/napcat-onebot/action/group/涵盖踢人、禁言、设管理员、改群名、群公告、群文件等入/退群、加群申请审批也在这里是群管类 bot 的主战场。接事件。事件分三类notice如OB11GroupIncreaseEvent、OB11PokeEvent、BotOfflineEvent、request好友/入群申请、meta心跳、上线下线。你的 bot 框架订阅这些事件就能驱动业务逻辑。每个功能点都能落到「入口路径 能做什么 适合谁」比如「群公告 →SendGroupNotice.ts→ 需要发群通知的运营 bot」。 一个完整例子入群欢迎 关键词回复 定时推送挑一个最常见的组合场景走一遍从配置到验证。需求。新成员入群时自动发一句欢迎群里有人发「帮助」就回一份功能清单每天 9 点推一条签到提醒。配置。在onebot11.json里加一个websocketClients指到你 bot 框架的 WS 地址{ enable: true, name: to-bot, url: ws://127.0.0.1:8080/ws }写逻辑。在你的 bot 框架里订阅三个事件、调三个动作触发事件 / 动作说明入群notice.group_increase收到后用send_group_msg发欢迎语关键词「帮助」message事件文本匹配后调send_group_msg回功能清单定时框架内 cron到点调send_group_msg推签到入群审批如果也要 bot 接管调用set_group_add_requestapprove/reject即可。验证。WebUI 的「消息 / 事件」页能看到实时上报的 JSON用同一页的「接口调试」面板手动发一条send_msg能收到就说明链路通了。三步齐了一个能跑的最小 bot 就成型。 上线之前部署、性能、安全、排查部署。无头是 NapCatQQ 上服务器的最大理由不占显示器、不吃 GUI 资源长时运行内存占用可控。数据落在 QQ 用户数据目录和NapCat子目录里迁移机器时把这两个目录一起带走即可napcat-shell的进程管理自带 Worker 守护Worker 崩溃会自动拉起10 秒内连续崩溃 3 次才退出避免无脑刷日志。性能。关注两点一是端口别撞——WebUI 启动时会从配置端口向上最多试 100 个空位OneBot 端口同理二是消息上报格式messagePostFormat选string还是array会直接影响下游框架的解析成本按需选。安全配置。管理界面默认开在0.0.0.0:6099公网暴露前建议项做法Token用环境变量NAPCAT_WEBUI_SECRET_KEY覆盖别用默认随机值访问控制webui.json里accessControlMode配whitelist填ipWhitelistHTTPS在config目录放cert.pem/key.pem框架自动切到 HTTPS回环不对外时用127.0.0.1监听 反向代理别裸跑0.0.0.0常见问题排查。启动报「找不到 wrapper」优先看 NTQQ 路径与版本是否匹配mfplat.dll缺失常见于 Windows Server需要在「添加角色和功能」里勾选「媒体基础」WebUI 打不开多为端口被占用看控制台打印的实际端口号再访问掉线后 WebUI 会自动进入重连态并触发快速登录日志里能区分是被踢下线还是静默离线。 生态与进阶插件。napcat-onebot内置插件管理器packages/napcat-onebot/network/plugin-manger.ts把插件目录放到插件路径即可热加载napcat-plugin-builtin是现成参考。配套框架。官方文档里推荐过 AstrBot、MaiBot 等适配 bot 框架直接对接 OneBot 接口即可跑起来。文档。项目维护多个文档镜像napneko.github.io等首次使用建议先过一遍官方教程。社区。QQ 群和 Telegram 是主要交流渠道WebUI「关于」页可获取入群密钥。贡献。仓库是 pnpm workspace本地pnpm install pnpm dev:shell起开发环境即可提 PR。写在最后NapCatQQ 把「驱动 NTQQ」这件脏活收进napcat-core把「怎么对上游说话」交给 OneBot把「怎么管」交给 WebUI。你只写业务。如果手头正好要做一个 QQ 机器人从 Release 页下载一个版本按上面的步骤把 WebUI 跑起来就是最快的验证方式。【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/11/4 2:08:01 · 阅读 1.2k NapCatQQ 上手指南：基于 NTQQ 的无头 QQ 机器人框架，3 分钟跑通第一个 Bot
NapCatQQ 上手指南基于 NTQQ 的无头 QQ 机器人框架3 分钟跑通第一个 Bot【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ想在 QQ 里跑一个机器人有人私聊它要自动回群里能踢人禁言、发公告定时往群里推一条通知。你不想自己啃 NTQQ 的底层协议也不想常驻一个带界面的 QQ 客户端。NapCatQQ 就是为此而做的一个基于 NTQQ 的无头 QQ 机器人框架它在服务器里驱动 NTQQ 内核完成登录和消息收发再把能力通过 OneBot 协议暴露成标准接口让你把精力放在业务逻辑上。 3 分钟看懂它是什么NapCatQQ 是「现代化的基于 NTQQ 的 Bot 协议端实现」。所谓无头headless指它不依赖 NTQQ 的图形界面框架加载 NTQQ 的wrapper.node直接驱动内核登录、收发消息、群操作都在服务端完成不需要显示器也不会因为界面卡顿、崩溃拖垮整个机器人。所谓模块化指项目按职责拆成一堆独立的 npm 包改动某一块不会牵连另一块。核心包大致是这样分工的包职责napcat-core协议核心封装 NTQQ 的登录、消息、群组、文件、用户等能力napcat-onebotOneBot 11 协议实现把核心能力映射成标准动作action与事件eventnapcat-shell启动入口与进程管理拉起内核、守护 Worker、崩溃自动重启napcat-webui-backend/napcat-webui-frontend内置 Web 管理界面登录、看消息、调接口、管插件napcat-common公共工具路径、日志、缓存、请求等napcat-native各平台原生模块wrapper、napi2native、ffmpeg 等数据流向可以概括成一句话NTQQ 内核 → napcat-core(协议能力) → napcat-onebot(OneBot 动作/事件) ↕ napcat-webui(管理界面) ↕ 你的 bot 框架(走 HTTP/WS)你写机器人时绝大多数时候只会和napcat-onebot暴露的接口打交道napcat-core负责把它落到 NTQQ 上。 从零跑起来安装、配置、启动安装。从项目 Release 页下载对应系统的版本包如果想从源码构建仓库是 pnpm workspacegit clone https://gitcode.com/gh_mirrors/na/NapCatQQ pnpm install配置。三件事必须做到位NTQQ 路径框架要能定位到你本机装好的 NTQQwrapper.node、major.node所在目录路径配置在启动入口读取的环境里。OneBot 网络监听端口在packages/napcat-develop/config/onebot11.json默认 HTTP3000、WebSocket3001只监听127.0.0.1。WebUI管理界面端口在packages/napcat-webui-backend/webui.json默认6099token字段默认是random。启动。Windows 直接跑启动脚本Linux/macOS 用 Node 跑入口node NapCat 目录/shell/napcat.js看到第一条消息。控制台会打印WebUi User Panel Url默认是http://127.0.0.1:6099/webui浏览器打开它扫码登录。注意当token为默认值时框架会自动生成一个 8 位随机密码并在登录成功后通过私聊把新密码发给你——所以登录后记得先查收那条私聊消息。登录态就绪后别人发的消息就会在 WebUI 的事件流里出现也同时按配置推给你的 HTTP/WS 客户端。 它能帮你做什么按真实使用顺序而不是按源码目录NapCatQQ 的常用能力分四段收消息。内核收到的私聊、群聊、系统消息经napcat-onebot解析后上报支持字符串与数组两种格式撤回、群名片变更、入群申请等灰条通知也会被识别成对应事件。事件清单集中在packages/napcat-onebot/event/。发消息。用 OneBot 的send_msg/send_private_msg/send_group_msg即可。packages/napcat-onebot/action/msg/SendMsg.ts支持文本、图片、语音、文件也支持合并转发node元素。管群。群管理类动作在packages/napcat-onebot/action/group/涵盖踢人、禁言、设管理员、改群名、群公告、群文件等入/退群、加群申请审批也在这里是群管类 bot 的主战场。接事件。事件分三类notice如OB11GroupIncreaseEvent、OB11PokeEvent、BotOfflineEvent、request好友/入群申请、meta心跳、上线下线。你的 bot 框架订阅这些事件就能驱动业务逻辑。每个功能点都能落到「入口路径 能做什么 适合谁」比如「群公告 →SendGroupNotice.ts→ 需要发群通知的运营 bot」。 一个完整例子入群欢迎 关键词回复 定时推送挑一个最常见的组合场景走一遍从配置到验证。需求。新成员入群时自动发一句欢迎群里有人发「帮助」就回一份功能清单每天 9 点推一条签到提醒。配置。在onebot11.json里加一个websocketClients指到你 bot 框架的 WS 地址{ enable: true, name: to-bot, url: ws://127.0.0.1:8080/ws }写逻辑。在你的 bot 框架里订阅三个事件、调三个动作触发事件 / 动作说明入群notice.group_increase收到后用send_group_msg发欢迎语关键词「帮助」message事件文本匹配后调send_group_msg回功能清单定时框架内 cron到点调send_group_msg推签到入群审批如果也要 bot 接管调用set_group_add_requestapprove/reject即可。验证。WebUI 的「消息 / 事件」页能看到实时上报的 JSON用同一页的「接口调试」面板手动发一条send_msg能收到就说明链路通了。三步齐了一个能跑的最小 bot 就成型。 上线之前部署、性能、安全、排查部署。无头是 NapCatQQ 上服务器的最大理由不占显示器、不吃 GUI 资源长时运行内存占用可控。数据落在 QQ 用户数据目录和NapCat子目录里迁移机器时把这两个目录一起带走即可napcat-shell的进程管理自带 Worker 守护Worker 崩溃会自动拉起10 秒内连续崩溃 3 次才退出避免无脑刷日志。性能。关注两点一是端口别撞——WebUI 启动时会从配置端口向上最多试 100 个空位OneBot 端口同理二是消息上报格式messagePostFormat选string还是array会直接影响下游框架的解析成本按需选。安全配置。管理界面默认开在0.0.0.0:6099公网暴露前建议项做法Token用环境变量NAPCAT_WEBUI_SECRET_KEY覆盖别用默认随机值访问控制webui.json里accessControlMode配whitelist填ipWhitelistHTTPS在config目录放cert.pem/key.pem框架自动切到 HTTPS回环不对外时用127.0.0.1监听 反向代理别裸跑0.0.0.0常见问题排查。启动报「找不到 wrapper」优先看 NTQQ 路径与版本是否匹配mfplat.dll缺失常见于 Windows Server需要在「添加角色和功能」里勾选「媒体基础」WebUI 打不开多为端口被占用看控制台打印的实际端口号再访问掉线后 WebUI 会自动进入重连态并触发快速登录日志里能区分是被踢下线还是静默离线。 生态与进阶插件。napcat-onebot内置插件管理器packages/napcat-onebot/network/plugin-manger.ts把插件目录放到插件路径即可热加载napcat-plugin-builtin是现成参考。配套框架。官方文档里推荐过 AstrBot、MaiBot 等适配 bot 框架直接对接 OneBot 接口即可跑起来。文档。项目维护多个文档镜像napneko.github.io等首次使用建议先过一遍官方教程。社区。QQ 群和 Telegram 是主要交流渠道WebUI「关于」页可获取入群密钥。贡献。仓库是 pnpm workspace本地pnpm install pnpm dev:shell起开发环境即可提 PR。写在最后NapCatQQ 把「驱动 NTQQ」这件脏活收进napcat-core把「怎么对上游说话」交给 OneBot把「怎么管」交给 WebUI。你只写业务。如果手头正好要做一个 QQ 机器人从 Release 页下载一个版本按上面的步骤把 WebUI 跑起来就是最快的验证方式。【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQ创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考