打造QQ群聊机器人

发表于 更新于
NapCatQQ + AstrBot，再接入AI大模型，打造自己的QQ智能机器人。

你是否想拥有一个 24 小时在线的 QQ 智能助理，帮你自动回复消息、管理群聊，还能随时陪你聊天？本文记录了我个人在 Linux 云服务器上，使用 Docker Compose 快速部署 AstrBot + NapCat 并接入智谱 AI 大模型的全过程。整个过程只需几条命令，非常适合想快速上手的朋友。

Windows、Linux桌面版安装

我使用 Linux 云服务器部署QQ机器人，如果是 Windows 或者 Linux 桌面版系统，建议直接上B站查看教程，B站上教程众多，这里只推荐一个视频，如若失效自行查找即可：

QQ聊天机器人本地部署教程 - 幻_湮（BiliBili）

Linux 云服务器部署配置

ssh 登录到云服务器。

NapCatQQ、AstrBot和大模型

NapCatQQ 文档
AstrBot 文档
智普AI开放平台

首先我们要在智普AI开放平台注册一个账号，新建一个 API Key 备用，选择智普AI只是我个人推荐，它注册有2000w免费Token使用，也有便宜好用的 Coding Plan 可用，对于大模型的选择完全自由，不限定于一家。

还有，在AI开放平台的页面选项中找到开发文档，其中记录了调用API需要的步骤，最重要的是查找到 BASE URL，这必不可少。

NapCat 是连接 QQ 的 MCP 工具，AstrBot 是协调一切的 Agent 大脑。AI应用的基本概念：Agent、MCP 和 Skills，如果想了解可以和 AI 大模型进行QA学习，简单来说，Agent 是软件应用，MCP 是本地机器和应用之间的媒介（比如读写文件，实际是MCP的功能），Skills 是特定内容文档，会被利用添加到与大模型沟通的上下文信息中。 

flowchart LR
    subgraph A [你的 Linux 服务器]
        B[NapCat QQ
（MCP 工具）] -- 收发消息 --> C[QQ 服务器]
        B -- OneBot 协议 --> D[AstrBot
（Agent 大脑）]
    end

    C -- QQ 消息 --> B
    D -- API 调用 --> E[大模型
（DeepSeek 等）]
    E -- AI 回复 --> D

    F[QQ 用户] -- 发送消息 --> C
    D -- 控制指令/配置 --> G[Web 管理界面]
组件 作用 部署方式
NapCat 基于官方 QQ Linux 版，负责登录 QQ 并收发消息 Docker 容器
AstrBot 聊天机器人核心，负责处理消息、调用大模型、管理插件 Docker 容器
智谱 AI 提供大模型对话能力（也可替换为 DeepSeek、OpenAI 等） API 调用

两者通过 OneBot v11 协议在容器内部通信，无需额外配置网络，开箱即用。

下面正式开始讲解部署步骤。

准备工作

  1. 一台运行着 Linux 的服务器（建议 2核2G 以上，我使用Ubuntu系统演示）。
  2. 服务器上已安装 Docker 和 Docker Compose（下面步骤说明如何安装）。
  3. 一个准备好的 QQ 小号（降低主号被风控的风险）。
  4. AI 大模型 API Key（在AI开放平台注册账号购买）。

安装 Docker 及 Docker Compose 插件

英文原版安装文档

中文镜像安装文档

下面记录一下我的步骤 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 更新软件包索引
sudo apt update

# 安装必要依赖
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加 Docker APT 仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 更新并安装 Docker 引擎及 Compose 插件
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动 Docker 并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version
docker compose version

国内服务器拉取 Docker Hub 镜像可能较慢，可编辑 /etc/docker/daemon.json 添加镜像加速： 

1
2
3
4
5
6
7
8
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

Docker Compose 一键部署

1
2
3
4
5
# 创建并进入项目目录
mkdir astrbot && cd astrbot

# 下载官方提供的 Docker Compose 配置文件
wget https://raw.githubusercontent.com/NapNeko/NapCat-Docker/main/compose/astrbot.yml

注：若 wget 下载失败，可手动创建 astrbot.yml 文件，内容如下： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
version: '3'
services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    environment:
      - NAPCAT_UID=1000
      - NAPCAT_GID=1000
    ports:
      - "6099:6099"
    volumes:
      - ./napcat/data:/app/.napcat
      - ./napcat/config:/app/napcat/config
    restart: unless-stopped

  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    ports:
      - "6185:6185"
    volumes:
      - ./astrbot/data:/app/data
    environment:
      - ASTRBOT_WS_URL=ws://napcat:3001
    depends_on:
      - napcat
    restart: unless-stopped

启动所有服务

在 astrbot.yml 文件所在目录下，执行： 

1
sudo docker compose -f astrbot.yml up -d

执行成功后，Docker 会自动拉取镜像并启动两个容器。可以通过 sudo docker ps 查看容器状态，确保 napcat 和 astrbot 均为 Up 状态。

如果你的 Docker Compose 是独立安装的老版本，上面的命令执行会报错，先升级 Docker Compose：首选 docker compose（V2）插件。 

1
2
sudo apt update
sudo apt install docker-compose-plugin

升级后再执行下面的命令重新启动服务。 

1
NAPCAT_UID=$(id -u) NAPCAT_GID=$(id -g) sudo -E docker compose -f astrbot.yml up -d

正常情况下这里 tui 会输出一个登录二维码，用你的QQ小号扫码登录。

通过SSH隧道访问网页界面

和桌面版配置差异的关键来了，服务器只有一个终端，并没有界面，我们需要利用 SSH隧道 使我们本地机器能访问到服务器端的 WebUI。

本地开一个新终端，使用下面的命令登录服务器： 

1
ssh -L 6099:localhost:6099 -L 6185:localhost:6185 <你的服务器用户名>@<你的服务器IP地址>

注意：请把命令中的 <你的服务器用户名> 和 <你的服务器IP地址> 替换成你自己的信息。这条命令会同时建立两条隧道，分别对应 NapCat 的 6099 端口和 AstrBot 的 6185 端口。

输入密码登录后，先不要关闭这个窗口。然后打开你电脑的浏览器，输入对应的地址就能访问管理面板了： 

1
2
3
4
5
NapCat 面板: 
http://localhost:6099/webui

AstrBot 面板: 
http://localhost:6185

NapCat登录需要token，在服务器终端使用下面的命令获取，粘贴登录即可： 

1
sudo docker logs napcat 2>&1 | grep -i token

AstrBot登录，初始账户密码均为astrbot（忘了有没有大写了，在页面下端有提示），登录后会提醒你修改账户名和密码。

配置 NapCat 面板

在上一步之后，后面的配置几乎和网络上的教程没有任何差别了（因为几乎都是通过浏览器界面配置的），如果想探索更多玩法，可以自行搜索教程配置，我就不赘述了，下面仅仅记录最基础的内容，让我们把QQ机器人用起来。

……

如你所见，只是用起来的话，NapCat并不再需要任何配置，实际上我们使用NapCat，主要的配置就是让他连接上AstrBot，由于上面我们是docker一体部署启动，所以这一步已经完成了（大概如此，或许只是创建连接接口，但是我们一体部署都做好了吧）。

总之，后面配置检查不成功，再去搜索看看这一步怎么做。

在实际的使用中，我们想要更多QQ机器人的功能，多半也是去配置AstrBot。

配置 AstrBot 面板

创建机器人

  1. 左侧 机器人；
  2. 右上角 创建机器人；
  3. 选择消息平台类别：OneBot V11；
  4. 保存 -> 无视警告并继续创建。

然后就出现了一个名为 default 的机器人名片，点击名片右上角开关启用它，查看下方 平台日志，出现 适配器已连接 即成功，如果不成功可能要去看看NapCat面板怎么配置。

接入大模型（以智谱 AI 为例）

  1. 左侧 模型提供商；
  2. 提供商源卡片 新增；
  3. 选择 Zhipu;
  4. 填写 API Key 和 API Base URL （默认的应该也对），保存配置；
  5. 下方 获取模型列表，按自己需求点击右侧 +，然后打开开关；
  6. 左侧 配置文件 -> 普通配置，在默认对话模型选择提供商，按喜好选一个即可；
  7. 下方 选择人格，这里可以自行编写一些机器人的设定；
  8. 最下面 其他配置 中 身份识别 以及 显示群名称，这两项建议开启，开启后可以在人格设定或者skill中用自然语言让你拥有绝对控制权；
  9. （还有其他功能就不多说了，比如联网搜索功能，打开开关就行，更多其他配置参考AstrBot文档）
  10. web 页面右下角图标保存配置。

测试与验证

（累啊。。我说手码字已经过时了）

现在，向你的机器人 QQ 号发送一条消息，收到回复，则说明部署成功！

一般，我都会发一个：你是谁？

查看日志排查问题

1
2
3
4
5
# 查看 AstrBot 日志
sudo docker logs -f astrbot

# 查看 NapCat 日志
sudo docker logs -f napcat

常见问题速查

现象 可能原因 解决方法
无法访问 NapCat WebUI (6099) 防火墙未开放端口 在云控制台安全组/系统防火墙中放行 6099 端口
扫码后登录失败 账号被风控 尝试更换网络环境，或更换小号重试
机器人不回复消息 AI 配置有误或余额不足 检查 API Key 是否正确、账户是否有额度；查看 AstrBot 日志
AstrBot 面板无法访问 (6185) 端口未开放或容器未启动 检查防火墙规则，运行 docker ps 确认容器状态

我说 写完了

至此，一个功能完整、24 小时在线的 QQ 机器人就部署完成了。你可以通过 AstrBot 的插件市场为其添加更多能力，比如天气查询、网页搜索、定时提醒等，把它打造成专属的智能助理。祝玩得开心。