★ FEATURED ARTICLE NapCatQQ 上手指南基于 NTQQ 的 OneBot 11 机器人框架从启动到接群管 Bot【免费下载链接】NapCatQQModern protocol-side framework based on NTQQ项目地址: https://gitcode.com/gh_mirrors/na/NapCatQQNapCatQQ 是一个跑在 Windows 上的 QQ 机器人框架它把 NapCat 注入 NTQQ 进程让一个真实 QQ 号以无头方式运行并对外暴露标准的 OneBot 11 接口和内置 WebUI。适合想在服务器或自己电脑上长期挂一个机器人、又不想从零写 QQ 协议的开发者。它解决的三件事很具体——用 HTTP/WebSocket 收发 QQ 消息、调用群管与文件 API、用 WebUI 登录和管理机器人。本文按先跑起来再会用接口最后看原理的顺序展开。第一次运行装好、启动、验证登录环境要求项目要求系统Windows框架注入 NTQQ 进程依赖其 Windows 壳NTQQ已安装启动脚本会从注册表自动定位安装路径Node.js≥ 18packages/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。脚本要求管理员权限检测到非管理员时会自动请求提权。跑通了的三个验证标志浏览器访问 WebUI默认地址http://127.0.0.1:6099packages/napcat-webui-backend/webui.json 中port: 6099。token 默认是random启动日志里也会打印当前实际值访问时带上。在 WebUI 里用目标 QQ 号扫码登录页面显示在线状态。通过 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_idmessagesend_group_msg群聊参数group_idmessagesend_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.urlNapCat 会 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/portWebUI 监听地址默认0.0.0.0:6099远程访问就靠这个token访问 WebUI 的凭证默认值random生产环境务必改掉ipWhitelist/ipBlacklist/accessControlMode远程部署时的访问控制OneBot 网络配置onebot11.json定义四组连接默认只启用httpServer3000收 API 请求和websocketServer3001推事件把token留空意味着无鉴权远程部署前建议填上messagePostFormat控制消息以arraysegment 数组还是stringCQ 码格式投递不想自建服务器而由 NapCat 主动推事件时改配httpClients/websocketClients即可插件插件目录在运行目录的config/plugins/下NapCat 启动时扫描加载。加载器packages/napcat-onebot/network/plugin/loader.ts内置了官方插件白名单和敏感词扫描WebUI 里还提供了插件市场用于安装社区插件。插件与你的业务解耦核心消息链路靠 OneBot 接口就够了插件更多承担附加功能角色。场景落地两个最典型的用法场景一群管机器人WebSocket 连接 NapCat3001监听事件重点处理group_message、notice成员变动、request入群申请收到群消息后先校验发送者权限调用get_group_member_info拿 member_level普通成员无管理权限则忽略其指令指令命中后调对应接口例如/禁言 123456调set_group_bangroup_id user_id duration/踢调set_group_kick收到group_request事件时按预设规则调set_group_add_request自动同意或拒绝整条链路只用 OneBot 接口不需要碰 NapCat 内部代码。场景二消息推送机器人把群里/好友间的关键消息推到其他群或外部系统监听message事件按群号或关键词过滤调send_group_msg推送到目标群消息里带图片时先用get_image落盘再作为imagesegment 发出要推给外部系统Webhook、邮件网关时在事件回调里直接 HTTP 转发NapCat 本身不做二次加工原理速览分层怎么摆的launchernapcat-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），仅供参考
阅读完成 · 觉得有帮助？
