NapCatQQ 上手指南：基于 NTQQ 的 OneBot 11 机器人框架，从启动到接群管 Bot

NapCatQQ 上手指南：基于 NTQQ 的 OneBot 11 机器人框架，从启动到接群管 Bot

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

NapCatQQ 是一个跑在 Windows 上的 QQ 机器人框架：它把 NapCat 注入 NTQQ 进程，让一个真实 QQ 号以"无头"方式运行，并对外暴露标准的 OneBot 11 接口和内置 WebUI。适合想在服务器或自己电脑上长期挂一个机器人、又不想从零写 QQ 协议的开发者。它解决的三件事很具体——用 HTTP/WebSocket 收发 QQ 消息、调用群管与文件 API、用 WebUI 登录和管理机器人。本文按"先跑起来，再会用接口，最后看原理"的顺序展开。

第一次运行：装好、启动、验证登录

环境要求

项目要求
系统Windows（框架注入 NTQQ 进程，依赖其 Windows 壳）
NTQQ已安装，启动脚本会从注册表自动定位安装路径
Node.js≥ 18（packages/napcat-develop/package.json 中 engines 指定）
包管理pnpm（仓库为 pnpm workspace 多包结构）

安装与启动

git clone https://gitcode.com/gh_mirrors/na/NapCatQQ cd NapCatQQ pnpm install

之后运行 packages/napcat-shell-loader/ 里的launcher.bat：它会自动从注册表找到 NTQQ 安装路径（读UninstallString），注入NapCatWinBootHook.dll并拉起NapCatWinBootMain.exe。脚本要求管理员权限，检测到非管理员时会自动请求提权。

"跑通了"的三个验证标志

  1. 浏览器访问 WebUI，默认地址http://127.0.0.1:6099（packages/napcat-webui-backend/webui.json 中port: 6099）。token 默认是random，启动日志里也会打印当前实际值，访问时带上。
  2. 在 WebUI 里用目标 QQ 号扫码登录，页面显示在线状态。
  3. 通过 OneBot HTTP 接口调get_login_info返回该 QQ 号，调get_status返回online——此时机器人已经可以对外服务了。

消息收发：OneBot 11 接口怎么用

NapCat 对外的接口主体是 OneBot 11，所有接口实现在 packages/napcat-onebot/action/，事件定义在 packages/napcat-onebot/event/。你的业务侧只需通过 HTTP POST 或 WebSocket 调用，不用关心底层实现。

发消息

  • send_private_msg：私聊，参数user_id+message
  • send_group_msg：群聊，参数group_id+message
  • send_msg：通用发送，按message_type自动区分私聊/群聊

message支持 CQ 码字符串或 segment 数组，覆盖 text、image（本地文件/url/文件 id）、record（语音）、video、file、face、reply、forward（合并转发）等类型。常用配套接口：get_msg按 message_id 查原消息、send_forward_msg合并转发、delete_msg撤回/删除。

收消息与事件订阅

事件按类别分四个目录：message（消息接收）、request（好友/入群请求）、notice（群成员变动、禁言、卡片等通知）、meta（心跳、上线/下线）。

  • 事件走 WebSocket Server 推送时，默认端口3001（配置见 packages/napcat-develop/config/onebot11.json）
  • 你的机器人以 HTTP 形式接收事件时，则填httpClient.url，NapCat 会 POST 过去

私聊、群聊消息事件都会带上 message_id、群号/用户 id、消息 segment，直接据此写业务逻辑即可。

群管理操作：常用接口速查

群管类接口在 packages/napcat-onebot/action/group/，覆盖"管群"场景需要的全部动作：

任务接口
查群/成员get_group_list、get_group_info、get_group_member_list、get_group_member_info
踢人/禁言set_group_kick、set_group_ban、set_group_whole_ban
管理员/名片set_group_admin、set_group_card
公告/精华send_group_notice、set_essence_msg、get_group_essence
处理入群申请set_group_add_request（同意/拒绝/拉黑）
改名/禁言名单set_group_name、get_group_ban_list

权限判断逻辑建议自己写在业务层：NapCat 返回的是接口原始结果，"谁有权限执行这个动作"由你的机器人代码决定。

文件传输：群文件、私聊文件、图片语音

  • 群文件：upload_group_file上传、get_group_file_url取下载直链、get_group_root_files列目录、create_group_file_folder建目录
  • 私聊文件：upload_private_file上传并直接发给对方
  • 已收到的图片/语音：get_image、get_record把消息里的文件落到本地拿到路径
  • 通用下载：download_file

另外还有一整套基于流的分片上传/下载接口（packages/napcat-onebot/action/stream/），适合大文件场景。文件能力最终落到 packages/napcat-core/apis/file.ts 这一层实现。

配置与扩展：真正需要动的三处

WebUI 配置

packages/napcat-webui-backend/webui.json 里与日常使用相关的项：

  • host/port：WebUI 监听地址，默认0.0.0.0:6099，远程访问就靠这个
  • token：访问 WebUI 的凭证，默认值random，生产环境务必改掉
  • ipWhitelist/ipBlacklist/accessControlMode：远程部署时的访问控制

OneBot 网络配置

onebot11.json定义四组连接，默认只启用httpServer（3000，收 API 请求）和websocketServer（3001，推事件）：

  • 把token留空意味着无鉴权，远程部署前建议填上
  • messagePostFormat控制消息以array（segment 数组）还是string（CQ 码）格式投递
  • 不想自建服务器而由 NapCat 主动推事件时，改配httpClients/websocketClients即可

插件

插件目录在运行目录的config/plugins/下，NapCat 启动时扫描加载。加载器（packages/napcat-onebot/network/plugin/loader.ts）内置了官方插件白名单和敏感词扫描，WebUI 里还提供了插件市场用于安装社区插件。插件与你的业务解耦：核心消息链路靠 OneBot 接口就够了，插件更多承担"附加功能"角色。

场景落地：两个最典型的用法

场景一：群管机器人

  1. WebSocket 连接 NapCat（3001）监听事件，重点处理group_message、notice（成员变动）、request（入群申请）
  2. 收到群消息后先校验发送者权限：调用get_group_member_info拿 member_level，普通成员无管理权限则忽略其指令
  3. 指令命中后调对应接口，例如/禁言 123456调set_group_ban（group_id + user_id + duration），/踢调set_group_kick
  4. 收到group_request事件时，按预设规则调set_group_add_request自动同意或拒绝

整条链路只用 OneBot 接口，不需要碰 NapCat 内部代码。

场景二：消息推送机器人

把群里/好友间的关键消息推到其他群或外部系统：

  1. 监听message事件，按群号或关键词过滤
  2. 调send_group_msg推送到目标群；消息里带图片时先用get_image落盘再作为imagesegment 发出
  3. 要推给外部系统（Webhook、邮件网关）时，在事件回调里直接 HTTP 转发，NapCat 本身不做二次加工

原理速览：分层怎么摆的

launcher（napcat-shell-loader）──注入/拉起──▶ NTQQ 进程 │ napcat-framework ── 加载原生模块与框架 ──▶ napcat-core（核心 API + 事件监听 + 服务层） │ OneBot 11 适配层（HTTP / WebSocket / 插件）◀──▶ WebUI（前后端）

一句话版：napcat-shell-loader负责把框架注入 NTQQ 壳；napcat-core直接驱动 QQ 的底层服务（发消息、文件、群操作都在这一层，见 packages/napcat-core/）；napcat-onebot把 core 能力翻译成 OneBot 11 接口和事件；WebUI 与插件系统挂在最外层做管理界面和扩展。业务侧只需要最外两层。

常见问题

1. 启动后提示 "QQ installation was not found in the registry"原因：脚本从注册表HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\QQ读取 NTQQ 路径，找不到说明系统里没装 NTQQ 或装的是旧版 QQ。解决：安装 NTQQ 后重试；确认当前账户有权限读取该注册表项。

2. 浏览器访问 6099 被拒或 401原因：WebUI 有 token 鉴权，默认 token 为random，且实际值可能已被 WebUI 重新生成。解决：看启动日志或 WebUI 关于页拿当前 token，按提示格式拼进 URL 访问。

3. 3000/3001 端口被占用原因：OneBot 的 HTTP/WS 服务端口与其他程序冲突。解决：在onebot11.json里改掉port，或释放占用；改完重启 NapCat。

4. 登录一段时间后自动掉线原因：多数情况是 NTQQ 版本过旧，协议行为与 NapCat 内置版本（对应 9.9.x）不匹配。解决：把 NTQQ 更新到较新版本后重新登录；仍复现的话检查是否被异地风控。

5. 消息发出去了但收不到事件原因：事件只走你实际启用的通道——默认是 WebSocket Server，如果你的机器人用 HTTP 客户端模式却没配httpClients，事件不会主动推给你。解决：确认 packages/napcat-onebot/config/config.ts 中启用的通道与你业务侧的接入方式一致。

资源与社区

  • 项目文档站：napneko.github.io（另有 doc.napneko.icu、napcat.top 等镜像，任选其一）
  • 社区：官方 QQ 群（入群密钥在 WebUI 关于页获取）、Telegram 群 napcatqq
  • 仓库内示例：packages/napcat-onebot/action/example/ 整理了各分类接口的参数示例，测试用例在 packages/napcat-test/ 可参考断言写法

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考