快速上手 NapCatQQ：三步跑起你的第一个 QQ 机器人

快速上手 NapCatQQ：三步跑起你的第一个 QQ 机器人

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

NapCatQQ 是基于 NTQQ 的现代化 Bot 协议端实现，简单说就是一个用 Node.js 驱动 QQ 客户端的 QQ 机器人运行框架。它解决的核心问题是：你不需要写底层协议，只需调用标准接口，就能收发私聊与群聊消息、管理群、收发文件，并对外暴露 OneBot 11 协议接口。适合想快速做出机器人的新手，也适合需要接入现有 OneBot 生态的开发者。

从 0 到跑起来的最短路径

最短路径只有 4 条命令：克隆、装依赖、构建、启动。

前置条件：Node.js 18+、pnpm、一台装有 NTQQ 客户端的 Windows 机器（源码开发路径依赖本地 NTQQ）。

git clone https://gitcode.com/gh_mirrors/na/NapCatQQ cd NapCatQQ pnpm install pnpm run build:shell pnpm run dev:shell

dev:shell 会执行 napcat-develop 下的脚本，自动从注册表定位已安装的 NTQQ、拷贝QQNT.dll等运行所需文件并注入 NapCat 模块，成功后控制台即可看到机器人登录流程，WebUI 默认监听 6099 端口。其余分支（如build:framework、build:webui、test、typecheck）都集中在根目录 package.json 的 scripts 中，用到再查即可。

核心能力

收发消息

标准 OneBot 11 消息动作齐备：send_private_msg、send_group_msg、delete_msg、get_msg，以及ocr_image、get_record（语音转文本）、get_image等扩展动作，路由定义在 napcat-onebot/action/router.ts。事件侧覆盖消息、请求、通知、元事件四类，见 napcat-onebot/event/。

管理群聊

群管理动作超过三十个：set_group_ban、set_group_admin、set_group_kick、set_essence_msg、set_group_name、get_group_member_list，群文件上传/下载/目录操作也在同一路由中，完整清单可直接翻 router.ts 对照。

接入 OneBot 生态

默认开启 HTTP Server（127.0.0.1:3000，支持 CORS）和 WebSocket Server（127.0.0.1:3001），配置模板在 napcat-develop/config/onebot11.json。对下游框架而言，NapCatQQ 就是一个标准 OneBot 11 端点，已有基于 OneBot 11 的机器人框架基本可以直连使用。

配置要点

改配置的原则：先只改端口和 token，其余保持默认。

避坑速查

• dev:shell 报错或定位不到 QQ→ 该路径仅支持 Windows，且本机必须装好 NTQQ，脚本通过注册表Uninstall\QQ找安装目录。
• pnpm install 失败→ 检查网络或切换国内镜像源，必要时pnpm store prune后重装。
• 框架连不上机器人→ 默认 3000/3001 端口可能被占用，改 onebot11.json 后两端 token 保持一致。
• WebUI 打不开或请求 401→ token 默认值 random 每次启动都会变，把 webui.json 里的 token 固定成自己的值。
• 登录二维码扫不上→ 确认 NTQQ 版本较新，或参考官方文档的兼容说明。

下一步去哪

• 协议与动作实现看 napcat-core，接口层看 napcat-onebot
• 前端管理界面源码在 napcat-webui-frontend
• 想改行为，从 router.ts 的动作名入手，顺着查对应实现文件最快

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