一、概述

NapCatQQ 是一个基于 NTQQ（新版 QQ 客户端）的无头 QQ 机器人框架。 它无需图形界面即可运行，通过 OneBot v11 标准协议对外暴露接口， 让开发者可以通过 WebSocket / HTTP 接收和发送 QQ 消息。

搭配 AI 机器人框架（如 AstrBot、LangBot），可以快速将 DeepSeek、通义千问、OpenAI 等 大语言模型接入 QQ 群或好友会话，实现智能对话机器人。

二、Linux 安装

2.1 一键安装脚本

使用官方维护的一键安装脚本，支持交互式 TUI 菜单：

curl -o napcat.sh https://raw.githubusercontent.com/NapNeko/NapCat-Installer/main/script/install.sh
sudo bash napcat.sh --tui

根据屏幕提示选择安装选项即可。

2.2 手动安装

如果你更倾向于手动控制版本：

# 下载最新版（以 v4.18.4 为例）
wget https://github.com/NapNeko/NapCatQQ/releases/latest/download/NapCat.linux.x64.zip

# 解压到目标目录
sudo mkdir -p /opt/napcat
sudo unzip NapCat.linux.x64.zip -d /opt/napcat

# 安装依赖
cd /opt/napcat
sudo npm install --production

2.3 启动 NapCat

# 启动（指定 QQ 号）
napcat start 1234567890

# 查看日志
napcat log 1234567890

# 停止
napcat stop 1234567890

首次启动会自动生成配置并打开 WebUI 登录页面地址（见日志输出）。

三、Docker 部署（推荐）

Docker 方式最简洁，资源隔离好，推荐在服务器上使用。

3.1 快速启动

docker run -d \
  --name napcat \
  --restart=always \
  -e NAPCAT_UID=$(id -u) \
  -e NAPCAT_GID=$(id -g) \
  -p 3000:3000 \
  -p 3001:3001 \
  -p 6099:6099 \
  mlikiowa/napcat-docker:latest

各端口作用：

docker logs napcat | grep -i token

3.2 Docker Compose 部署

创建 docker-compose.yml：

services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    ports:
      - "3000:3000"
      - "3001:3001"
      - "6099:6099"
    environment:
      - NAPCAT_UID=1000
      - NAPCAT_GID=1000
    volumes:
      - ./qq-data:/app/.config/QQ
      - ./napcat-config:/app/napcat/config
      - ./napcat-plugins:/app/napcat/plugins

docker compose up -d

3.3 使用预配置脚本（自动登录）

你也可以在环境变量中预设 QQ 账号：

docker run -d \
  --name napcat \
  --restart=always \
  -e ACCOUNT=1234567890 \
  -e NAPCAT_UID=$(id -u) \
  -e NAPCAT_GID=$(id -g) \
  -p 6099:6099 \
  mlikiowa/napcat-docker:latest

设置 ACCOUNT 后容器启动会自动尝试登录该账号，扫码即可完成。

3.4 常用环境变量

四、配置与登录

docker logs napcat 2>&1 | grep -oP 'token\[\K[^\]]+'

napcat start 1234567890

# 查看容器日志是否有登录成功信息
docker logs --tail 20 napcat

# 测试发送消息（HTTP API）
curl -X POST http://127.0.0.1:3000/send_msg \
  -H "Content-Type: application/json" \
  -d '{"message_type":"group","group_id":123456,"message":"Hello NapCat"}'

五、接入 AI 大模型

NapCat 本身只负责 QQ 消息收发，需要配合 AI 机器人框架才能实现智能对话。 以下是主流的对接方案。

5.1 方案一：NapCat + AstrBot + DeepSeek（推荐）

AstrBot 是一个专门对接大模型的 QQ 机器人框架，自带管理面板，配置简单。

创建 Docker 网络：

docker network create bot

编写 docker-compose.yml：

services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: always
    ports:
      - "6099:6099"
    environment:
      - NAPCAT_UID=1000
      - NAPCAT_GID=1000
    volumes:
      - ./napcat-config:/app/napcat/config
      - ./qq-data:/app/.config/QQ
    networks:
      - bot

  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    ports:
      - "6185:6185"    # 管理面板
      - "6199:6199"    # OneBot 端口
    volumes:
      - ./astrbot-data:/AstrBot/data
    networks:
      - bot

networks:
  bot:
    external: true

配置 AstrBot：

1. 访问 http://服务器IP:6185 进入 AstrBot 管理面板
2. 添加模型提供商 → 选择 DeepSeek → 填入 API Key （到 platform.deepseek.com 申请）
3. 创建机器人 → 选择 OneBot v11 → 启用反向 WebSocket
4. 添加 QQ 号到管理员列表、群号到白名单

配置 NapCat 反向 WebSocket：

# 在 NapCat WebUI 中
# 网络配置 → 新建 → WebSocket 客户端
# URL: ws://astrbot:6199/ws
# 保存并启用

5.2 方案二：NapCat + LangBot + DeepSeek

LangBot 是另一个流行的 AI 机器人框架：

# 安装 LangBot
pip install langbot

# 配置 provider.json（填入 DeepSeek API Key）
# 配置 platform.json 启用 aiocqhttp

# 启动 LangBot
python main.py

# 在 NapCat WebUI 中配置 WebSocket 客户端指向
# ws://127.0.0.1:2280/ws

5.3 方案三：NapCat + 自定义程序

NapCat 遵循 OneBot v11 协议，任何支持该协议的程序都可以对接：

# Python 示例（使用 aiohttp 接收 WebSocket 事件）
import json
import aiohttp
from aiohttp import web

async def handle_ws(request):
    ws = web.WebSocketResponse()
    await ws.prepare(request)
    async for msg in ws:
        data = json.loads(msg.data)
        # 处理消息，调用 AI API
        reply = await call_ai_api(data.get("message", ""))
        # 回复消息
        await ws.send_json({
            "action": "send_msg",
            "params": {
                "message_type": data.get("message_type"),
                "group_id": data.get("group_id"),
                "message": reply
            }
        })
    return ws

app = web.Application()
app.router.add_get("/ws", handle_ws)
web.run_app(app, host="0.0.0.0", port=2280)

然后在 NapCat WebUI 中配置反向 WebSocket 客户端指向 ws://127.0.0.1:2280/ws。

5.4 支持的大模型

上述方案均可对接主流 AI 模型，只需配置对应的 API Key 和接口地址：

六、OneBot 协议配置

6.1 基本配置项

NapCat 使用 OneBot v11 标准，通过 WebUI 可以灵活配置网络连接：

6.2 反向 WebSocket 配置（推荐）

这是最常用的模式——AI 框架启动 WebSocket 服务端，NapCat 主动连上去：

# 在 NapCat WebUI 中操作
# 1. 进入“网络配置”
# 2. 点击“新建” → 选择“WebSocket 客户端”
# 3. 填写目标 URL: ws://你的框架地址:端口/ws
# 4. 点击保存并启用

6.3 安全配置

建议在 NapCat 中设置访问鉴权：

# WebUI 管理中设置
# 网络配置 → 全局配置
# Token: 设置一个随机字符串（与框架端保持一致）

# 框架端也要配置相同的 Token（以 AstrBot 为例）
# AstrBot 管理面板 → 机器人配置 → OneBot 设置 → access_token

七、注意事项