NapCat 搭建教程 – 让 QQ 机器人稳定上线的现代方案

一、NapCat 是什么

如果你之前尝试过用 AstrBot 或其他 QQ 机器人框架自带的登录功能，大概率遇到过这些问题：

• 登录时提示“密码错误”（密码明明是对的）
• 滑块验证码过不去
• 登录成功后几分钟就被踢下线
• 提示“账号存在安全风险”

这些问题的根源在于：QQ 官方对第三方客户端的检测越来越严格。机器人框架自带的登录协议很容易被识别为“异常登录”，导致各种风控。

NapCat 就是解决这个问题的。它是一个基于 NTQQ（新版 QQ 客户端） 的机器人框架。核心思路是：

1. 你在电脑上正常安装并登录新版 QQ 客户端（9.9.x 版本，腾讯官方出品）。
2. NapCat 作为一个插件附加到这个 QQ 客户端上，通过合法的 QQ 进程来收发消息。
3. 因为消息是通过官方 QQ 客户端发出的，所以不会被风控——腾讯看到的就是一个正常的 QQ 在操作。

类比：以前的机器人框架像是自己造了一辆车开上高速公路，很容易被交警拦下来。NapCat 则是“坐上了官方的大巴车”——车是合法的，你只是搭了个便车。

NapCat 的角色：NapCat 本身不包含 AI 对话能力。它只负责收发 QQ 消息。它把收到的消息通过 HTTP 或 WebSocket 转发给后端的 AI 服务（比如 AstrBot），然后把 AI 生成的回复通过 QQ 发出去。所以典型的组合是：NapCat（负责连接 QQ）+ AstrBot（负责 AI 对话）。

二、你需要准备什么

准备项	说明
一台电脑或云服务器	Windows 或 Linux 都可以。如果希望 24 小时在线，推荐云服务器
新版 NTQQ 客户端	必须安装腾讯官方的最新版 QQ（9.9.x 版本以上）
一个 QQ 号	作为机器人使用，建议用全新的号
NapCat 安装包	从 GitHub 或官网下载

三、Windows 部署教程

3.1 安装最新版 QQ 客户端

关键：NapCat 只能附加到新版 NTQQ上（QQ 9.9.x 及以上版本）。旧版 QQ（8.x、7.x）不支持。

1. 打开浏览器，访问 https://im.qq.com/pcqq
2. 下载最新版本的 QQ PC 客户端。
3. 双击安装包，正常安装并登录你的机器人 QQ 号。
4. 确认 QQ 能正常收发消息，然后退出 QQ（右键任务栏图标 → 退出）。

为什么需要先登录一次再退出：第一次登录会让 QQ 客户端记住登录状态，后续 NapCat 启动时更容易通过验证。如果这个号之前从没在这台电脑上登录过，直接启动 NapCat 更容易触发风控。

3.2 下载 NapCat

1. 打开浏览器，访问 NapCat 的官方 GitHub 仓库：https://github.com/NapNeko/NapCatQQ
2. 在页面右侧找到 Releases（发行版），点击进入。
3. 找到最新版本，下载 Windows 版本。文件名通常类似 NapCat.win32.x64.zip 或包含 win、x64 字样的压缩包。
4. 下载完成后，把压缩包解压到一个独立的文件夹，比如 D:\NapCat 或 C:\NapCat。

注意：不要把 NapCat 解压到 QQ 的安装目录里。它是一个独立程序，放在任意位置都可以。

3.3 配置 NapCat

解压后，进入 NapCat 文件夹，找到 config 目录。里面有一个配置文件，不同版本的 NapCat 文件名可能略有不同，通常叫 napcat.json、config.yaml 或 onebot11.json。用记事本或 VS Code 打开它。

如果你只是想快速跑起来，默认配置基本不需要修改。但有几个关键参数需要确认：

{
  "http": {
    "enable": true,           // 开启 HTTP 服务
    "host": "127.0.0.1",      // 监听地址（仅本机访问）
    "port": 3000              // HTTP 端口（默认 3000，记下来后面要用）
  },
  "ws": {
    "enable": true,           // 开启 WebSocket 服务
    "host": "127.0.0.1",
    "port": 3001              // WebSocket 端口
  }
}

参数说明：

• http.enable：是否开启 HTTP 接口。AstrBot 等后端通过 HTTP 和 NapCat 通信。
• http.port：HTTP 服务的端口号。确保这个端口没有被其他程序占用。
• ws.enable：是否开启 WebSocket 服务。WebSocket 可以实现消息的实时推送，比 HTTP 轮询更高效。
• host：监听地址。127.0.0.1 表示只允许本机程序连接。如果你的后端程序也在同一台电脑上，这个设置不用改。

保存配置文件。

3.4 启动 NapCat

1. 进入 NapCat 文件夹，双击运行 napcat.exe（或类似名称的可执行文件）。
2. 此时会自动启动之前安装的 NTQQ 客户端。如果 QQ 没有自动启动，可以手动打开 QQ 并登录机器人账号。
3. 观察 NapCat 的命令行窗口，如果看到类似以下内容，说明启动成功：

[INFO] NapCat 启动成功
[INFO] HTTP 服务已启动: http://127.0.0.1:3000
[INFO] WebSocket 服务已启动: ws://127.0.0.1:3001
[INFO] QQ 已连接

此时 NapCat 已经在运行了。它会把 QQ 收到的消息通过 HTTP/WebSocket 转发出去，等待后端 AI 服务来调用。

保持 NapCat 窗口打开。关闭这个窗口就等于关闭了 QQ 机器人。

3.5 连接 AstrBot（让机器人有 AI 大脑）

NapCat 只负责收发 QQ 消息，本身不会对话。需要把它和 AstrBot 连接起来。

1. 启动 AstrBot（参考 AstrBot 的部署教程），进入 AstrBot 的 Web 管理后台（http://127.0.0.1:6185）。
2. 在左侧菜单中找到“消息平台”。
3. 选择 “OneBot” 或 “反向 WebSocket” 类型。
4. 填写 NapCat 的 WebSocket 地址：ws://127.0.0.1:3001
5. 保存配置并启用。

此时，NapCat 收到的 QQ 消息会通过 WebSocket 发送给 AstrBot，AstrBot 调用 AI 生成回复，再通过 NapCat 发回 QQ。整个链路是：QQ 消息 → NapCat → AstrBot → AI 大模型 → AstrBot → NapCat → QQ 回复。

四、Linux 云服务器部署教程

NapCat 本质上需要附加在 NTQQ 客户端上运行。但Linux 服务器没有图形界面，不能直接运行 QQ 客户端。解决方案有两种：

• 方案 A（推荐）：使用 NapCat 官方提供的 Docker 镜像，里面已经包含了无界面的 QQ 运行环境。
• 方案 B：使用 xvfb（虚拟显示器）在 Linux 上模拟图形界面运行 QQ。

本教程以方案 A（Docker）为主，因为最简单。

4.1 安装 Docker（如果还没装）

# Ubuntu/Debian
sudo apt update
sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

# 验证
docker --version

4.2 拉取并启动 NapCat Docker 镜像

NapCat 官方提供了预构建的 Docker 镜像：

# 创建数据目录
mkdir -p ~/napcat/data

# 拉取并启动容器
docker run -d \
  --name napcat \
  --restart unless-stopped \
  -p 3000:3000 \
  -p 3001:3001 \
  -v ~/napcat/data:/app/data \
  napneko/napcat:latest

命令解释：

• -d：后台运行。
• --name napcat：容器名称。
• --restart unless-stopped：开机自启，除非手动停止。
• -p 3000:3000：映射 HTTP 端口。
• -p 3001:3001：映射 WebSocket 端口。
• -v ~/napcat/data:/app/data：挂载数据目录，配置和登录状态会保存在这里。

4.3 登录 QQ

Docker 容器启动后，QQ 客户端会在容器内运行。你需要通过 NapCat 的 Web 管理页面来扫码登录 QQ。

1. 确保云服务器的安全组已放行 3000 和 3001 端口。
2. 浏览器访问：http://你的服务器IP:3000（如果打不开，检查安全组和防火墙）。
3. 在页面中找到“登录管理”或“QQ 管理”入口。
4. 点击“获取二维码”，页面会显示一个 QQ 登录二维码。
5. 用手机 QQ（登录你的机器人号）扫描这个二维码，确认登录。
6. 页面提示“登录成功”后，NapCat 就已连接到 QQ。

4.4 连接 AstrBot

和 Windows 部署一样，在 AstrBot 管理后台中配置 OneBot/反向 WebSocket，地址填写 ws://127.0.0.1:3001（如果 AstrBot 和 NapCat 在同一台服务器上）或 ws://服务器IP:3001（如果不在同一台）。

五、NapCat + AstrBot 完整架构图

部署完成后，你的机器人系统架构如下：

┌─────────────────┐
│   手机 QQ / PC QQ │  ← 用户在群里发消息
└────────┬────────┘
         │ 消息通过腾讯服务器转发
         ▼
┌─────────────────┐
│  NTQQ 客户端      │  ← 官方 QQ，不会被风控
│  + NapCat 插件    │  ← 把收到的消息转发出去
└────────┬────────┘
         │ HTTP / WebSocket
         ▼
┌─────────────────┐
│    AstrBot       │  ← 接收消息、调用 AI、返回回复
└────────┬────────┘
         │ API 调用
         ▼
┌─────────────────┐
│   DeepSeek / GPT  │  ← AI 大模型生成回复内容
└─────────────────┘

六、常见问题排查

Q1：NapCat 启动后 QQ 没有自动打开

原因：NapCat 可能没有找到 QQ 的安装路径。
解决：手动打开 QQ 并登录机器人账号，然后再启动 NapCat。或者检查配置文件，手动指定 QQ 的安装路径。

Q2：NapCat 显示“QQ 未连接”

原因：QQ 没有成功登录，或者 NapCat 没有成功附加到 QQ 进程。
解决：确认 QQ 已经打开并处于登录状态。然后重启 NapCat。如果多次失败，重启电脑后再试。

Q3：扫码登录时提示“环境异常”

原因：QQ 检测到登录环境有风险。
解决：

1. 在服务器上先安装一个图形化桌面环境（如 VNC），用正常方式打开 QQ 客户端登录一次。
2. 或者换一个网络环境（比如从 WiFi 换到有线网络）。
3. 或者等待几小时后再试——QQ 的风控有时是临时的。

Q4：机器人能收到消息，但不回复

排查步骤：

1. 确认 AstrBot 已正确配置并运行。
2. 确认 AstrBot 的“消息平台”中已启用 NapCat/OneBot 连接。
3. 确认 AI 大模型的 API Key 有效，且账户有余额。
4. 查看 AstrBot 的日志，看有没有报错信息。

Q5：如何让 NapCat 在后台持续运行（Windows）

如果关闭了 NapCat 的命令行窗口，机器人就会停止。要想让它在后台一直运行：

• 简单方法：不关窗口，让电脑不睡眠。适合短期测试。
• 推荐方法：用 nssm（Non-Sucking Service Manager）把 NapCat 注册为 Windows 服务，这样即使没有登录桌面，NapCat 也会自动运行。nssm 是一个免费的 Windows 服务管理工具，搜索“nssm 教程”即可。
• 终极方法：换 Linux 云服务器 + Docker 部署。一劳永逸。
• 七、总结
• NapCat 是目前最稳定的 QQ 机器人连接方案。相比于传统的协议登录方式，它的核心优势是：
• 
  
• 不会被风控：因为消息是通过官方 QQ 客户端发出的。


• 无需滑块验证：扫码或正常登录一次后，状态会长期保持。


• 支持最新的 NTQQ：兼容腾讯对 QQ 客户端的最新更新。


• 部署流程总结：
• 
  
• 安装最新版 NTQQ 并登录一次。


• 下载 NapCat，解压并配置端口。


• 启动 NapCat，它会附加到 QQ 进程。


• 在 AstrBot 中配置 OneBot 连接到 NapCat。


• 测试机器人对话。


• 如果你之前被 QQ 机器人的各种登录问题折磨过，NapCat 会让你感受到“原来还可以这么丝滑”。项目地址：https://github.com/NapNeko/NapCatQQ