1.1 项目背景#

在 NapCat 出现之前，go-cqhttp 曾是搭建 QQ 机器人的主流方案，但该项目已停止维护。NapCat 作为新一代解决方案，采用完全不同的技术路线——基于 QQ 官方 Linux 版本（NTQQ）而非逆向破解，因此稳定性更好，且项目持续活跃开发中 。

1.2 核心特点#

1.3 工作原理#

NapCat 的角色是一个”翻译官”——它负责登录 QQ 并提供标准化的 API 接口，让机器人框架（如 AstrBot、Koishi、NoneBot）可以通过 HTTP 或 WebSocket 来控制 QQ 账号收发消息 。

1
┌─────────┐     ┌──────────┐     ┌─────────────┐     ┌─────────┐
2
│   QQ    │────▶│  NapCat  │────▶│  OneBot协议 │────▶│ 机器人框架 │
3
│  客户端  │◀────│ (协议端)  │◀────│ (标准化接口) │◀────│ (大脑/中枢) │
4
└─────────┘     └──────────┘     └─────────────┘     └─────────┘

简单来说：NapCat 是”耳朵”和”嘴巴”（收发消息），机器人框架是”大脑”（处理逻辑、调用 AI）。

2.1 环境要求#

2.2 方式一：Docker 部署（推荐 Linux/服务器）#

1
sudo docker run -d \
2
  -e NAPCAT_GID=$(id -g) \
3
  -e NAPCAT_UID=$(id -u) \
4
  -p 3000:3000 \
5
  -p 3001:3001 \
6
  -p 6099:6099 \
7
  --add-host=host.docker.internal:host-gateway \
8
  --name napcat \
9
  --restart=always \
10
  docker.1ms.run/mlikiowa/napcat-docker:latest

1
sudo docker logs napcat

1
[WebUi] WebUi Local Panel Url: http://127.0.0.1:6099/webui?token=xxxxxx

2.3 方式二：Windows 部署#

1
http://127.0.0.1:6099/webui?token=napcat

2.4 方式三：Linux 一键脚本（非 Docker）#

1
curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh && sudo bash napcat.sh

安装完成后，使用以下命令启动（替换为你的 QQ 号）：

1
screen -dmS napcat bash -c "xvfb-run -a qq --no-sandbox -q 123456789"

3.1 WebUI 配置界面#

登录 WebUI 后，可以配置以下网络类型 ：

3.2 配置反向 WebSocket 连接（连接机器人框架）#

在 WebUI 中点击 网络配置 → 新建 → WebSocket 客户端，填写：

3.3 配置说明#

• 正向 WebSocket：NapCat 作为服务端，机器人框架主动连接
• 反向 WebSocket：NapCat 作为客户端，主动连接机器人框架（推荐，更稳定）

4.1 使用 Docker Compose 一键部署#

创建 docker-compose.yml：

1
version: '3'
2

3
services:
4
  napcat:
5
    image: mlikiowa/napcat-docker:latest
6
    container_name: napcat
7
    ports:
8
      - "3000:3000"
9
      - "3001:3001"
10
      - "6099:6099"
11
    restart: always
12
    extra_hosts:
13
      - "host.docker.internal:host-gateway"
14

15
  astrbot:
16
    image: soulter/astrbot:latest
17
    container_name: astrbot
18
    ports:
19
      - "6185:6185"
20
      - "6199:6199"
21
    restart: always
22
    depends_on:
23
      - napcat

启动服务：

1
docker-compose up -d

4.2 配置 AstrBot 连接 NapCat#

1. 访问 AstrBot WebUI：http://localhost:6185（默认账号密码：astrbot）
2. 进入 机器人 → 创建机器人
3. 选择 OneBot v11 类型
4. 填写配置 ：
   • 反向 WebSocket 主机地址：napcat（Docker 容器名）或 127.0.0.1
   • 反向 WebSocket 端口：6199
   • Token：留空或与 NapCat 保持一致

4.3 配置 DeepSeek AI（可选）#

1. 登录 DeepSeek 平台 获取 API Key
2. 在 AstrBot 后台 模型提供商 → 新增 → DeepSeek
3. 填入 API Key 并保存
4. 用另一个 QQ 给机器人发消息测试

4.4 建立容器间网络互通（宝塔面板部署）#

如果使用宝塔面板分别创建容器，需要将 NapCat 和 AstrBot 加入同一 Docker 网络：

1. 创建自定义网络：docker network create astrbot-napcat
2. 将两个容器加入该网络
3. 记录 AstrBot 容器在该网络中的 IP，NapCat 配置中使用该 IP

5.1 安装适配器#

1
npm install koishi-plugin-adapter-napcat

5.2 配置适配器#

在 Koishi 配置中添加 ：

1
export default {
2
  plugins: {
3
    'adapter-napcat': {
4
      protocol: 'ws-reverse',  // 或 http、ws
5
      endpoint: 'ws://localhost:3001',
6
      token: 'your-token'
7
    }
8
  }
9
}

⚠️ 风控风险#

腾讯在用户协议中明确禁止使用非官方客户端或外挂插件。QQ Bot 属于非官方应用，可能存在封号风险，建议 ：

• 使用小号进行测试
• 避免频繁发送相同内容
• 控制发送频率，不要短时间内大量发消息
• 注意账号安全，不要用于重要账号

📝 使用建议#

1. 定期更新：NapCat 持续更新以适配 QQ 版本变化，建议定期检查更新
2. 合理使用：避免用于营销、广告等可能触发风控的行为
3. 备份配置：保存好 WebUI Token 和配置文件