1.1 项目组合优势#

很多小伙伴搭建 QQ 机器人都会踩坑，要么协议过期、要么框架报错、要么 AI 对接失败、要么登录闪退。而 AstrBot + NapCat 是目前 2026 年最稳定、功能最强、维护最活跃的 QQ AI 机器人组合，没有之一！

• NapCat：新一代开源 QQ 协议端，替代老旧的 OneBot、CQHTTP，支持最新 QQ 协议，防风控能力更强，支持 websocket 双向通信，适配个人 QQ 账号登录，稳定挂机数月不闪退。

• AstrBot：轻量化高性能 AI 机器人框架，支持 DeepSeek、GPT、通义千问、讯飞等全品类大模型，支持插件拓展、群管理、自动回复、上下文对话、人设自定义，Web 可视化后台，操作极简。

两者搭配，完美实现「QQ 账号登录 + 协议转发 + AI 智能对话 + 自定义功能拓展」，是目前个人搭建免费 AIQQ 机器人的最优解。

1.2 本教程适配环境#

✅ 支持系统：Linux（CentOS7+/Ubuntu20.04+/Debian11+）、Windows10/11 ✅ 部署方式：Docker 容器化（推荐）、手动部署 ✅ 适配场景：个人 QQ 私聊 AI、QQ 群智能问答、自动灌水、群管理、AI 绘图、插件拓展 ✅ 难度等级：零基础友好，全程复制粘贴命令即可 ✅ 时效性：2026 年最新适配，修复所有旧版部署报错、端口冲突、登录失败问题

1.3 部署前置须知#

1. 禁止用于违规刷屏、营销骚扰、恶意控群，仅用于个人学习、娱乐、群管理使用

2. 个人 QQ 登录机器人存在轻微风控概率，建议使用常用小号部署，避免大号受限

3. 服务器建议开放全部所需端口，防火墙放行对应端口，否则会导致连接失败、后台打不开

2.1 硬件 & 服务器要求#

• 最低配置：1 核 2G 云服务器（足够单机器人挂机使用）

• 推荐配置：2 核 4G，可多插件、多模型同时运行，挂机更稳定

• 本地部署：Windows 电脑、虚拟机均可，无需公网 IP 也可本地使用

2.2 核心依赖安装（Linux 通用）#

整套部署基于 Docker，第一步必须安装 Docker 和 Docker Compose，所有服务器通用以下一键安装命令。

1
# 更新系统依赖
2
apt update && apt upgrade -y
3
# 安装Docker一键脚本
4
curl -fsSL https://get.docker.com | bash -s docker
5
# 设置Docker开机自启
6
systemctl start docker
7
systemctl enable docker

1
# 安装compose插件
2
apt install docker-compose-plugin -y
3
# 验证版本，显示版本号即安装成功
4
docker compose version

1
# Ubuntu/Debian
2
ufw allow 3000/tcp
3
ufw allow 3001/tcp
4
ufw allow 6099/tcp
5
ufw allow 6185/tcp
6
ufw allow 6199/tcp
7

8
# CentOS
9
firewall-cmd --permanent --add-port=3000/tcp
10
firewall-cmd --permanent --add-port=3001/tcp
11
firewall-cmd --permanent --add-port=6099/tcp
12
firewall-cmd --permanent --add-port=6185/tcp
13
firewall-cmd --permanent --add-port=6199/tcp
14
firewall-cmd --reload

3.1 Docker 一键部署 NapCat#

创建专属部署目录，避免文件混乱：

1
# 创建napcat文件夹
2
mkdir -p /root/napcat && cd /root/napcat

执行官方稳定版一键部署命令（2026 最新适配，常驻后台、开机自启）：

1
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
--name napcat \
8
--restart=always \
9
-v $(pwd)/data:/app/.napcat \
10
nkxingx/napcat:latest

3.2 命令参数详解（新手可跳过，方便排错）#

• -d：后台静默运行容器

• --restart=always：容器崩溃、服务器重启自动重启，保障永久挂机

• 3000/3001/6099：NapCat 核心通信端口，必须和后续配置一致

• 数据挂载：将容器数据挂载到本地目录，升级部署不丢失登录信息和配置

3.3 查看 NapCat 运行状态#

1
# 查看所有容器，看到napcat状态为UP即为启动成功
2
docker ps
3

4
# 查看运行日志，排查报错
5
docker logs napcat

3.4 QQ 账号登录 NapCat#

1. 浏览器打开访问地址：http://你的服务器IP:3000

2. 进入 NapCat 后台，点击「登录账号」

3. 选择二维码登录（推荐，风控最低），使用手机 QQ 扫码授权

4. 登录成功后，后台显示「在线」，QQ 账号状态正常即为协议端部署完成

重点提示：不要频繁登录下线、不要多设备同时登录，避免 QQ 临时风控冻结。

4.1 创建 AstrBot 部署目录#

1
mkdir -p /root/astrbot && cd /root/astrbot

4.2 Docker 一键部署 AstrBot#

执行稳定版部署命令，映射后台端口和数据目录：

1
docker run -d \
2
-p 6185:6185 \
3
-p 6199:6199 \
4
-v $(pwd)/data:/AstrBot/data \
5
--name astrbot \
6
--restart=always \
7
astrbot/astrbot:latest

4.3 检查 AstrBot 启动状态#

1
# 查看容器运行状态
2
docker ps | grep astrbot
3

4
# 查看启动日志，无报错即成功
5
docker logs astrbot

4.4 访问 AstrBot 可视化后台#

浏览器输入地址：http://服务器IP:6185 默认登录账号密码：NapCat / NapCat 首次登录建议立即修改密码，保障后台安全。

5.1 AstrBot 创建 QQ 机器人实例#

1. 登录 AstrBot 后台，左侧菜单栏找到【机器人】-【创建机器人】

2. 机器人类型选择：OneBot v11 / QQ 个人账户

3. 自定义机器人名称、备注，开启启用开关

5.2 填写 OneBot 连接参数#

核心配置参数（直接照抄，无需修改）

• 连接方式：WebSocket 被动连接

• 监听地址：0.0.0.0

• 监听端口：6199

• 启用心跳检测、自动重连

保存配置后，此时 AstrBot 已开启监听，等待 NapCat 对接。

5.3 NapCat 反向连接 AstrBot#

1. 再次打开 NapCat 后台 http://IP:3000

2. 进入【配置】-【OneBot 配置】

3. 开启 WebSocket 推送

4. 填写推送地址：ws://服务器IP:6199/onebot/v11/ws

5. 保存配置，重启 NapCat 容器生效

重启命令：

1
docker restart napcat

5.4 验证联动是否成功#

1. 重启两个容器

1
docker restart napcat && docker restart astrbot

2. 查看 AstrBot 后台机器人状态，显示「已在线、已连接」

3. 用任意 QQ 给机器人登录账号发消息，机器人自动响应即联动成功

6.1 主流模型推荐（免费好用）#

1. DeepSeek（推荐）：免费额度大、对话流畅、上下文稳定

2. 通义千问：响应速度快，适合群聊快速回复

3. GPT 系列：功能最全，需付费密钥

6.2 后台配置大模型#

1. AstrBot 后台左侧进入【模型设置】

2. 选择对应模型服务商，填入你的 API 密钥、接口地址

3. 设置默认对话模型、最大上下文、回复字数、温度参数

4. 开启「私聊自动回复、群聊 @回复、群聊关键词触发」

6.3 自定义机器人人设#

在人设设置中，可以自定义机器人性格、身份、说话风格、禁词、开场白，打造专属 AI 机器人。

7.1 基础实用功能#

1. 自动聊天：默认开启，私聊、被 @自动 AI 回复

2. 上下文记忆：开启后，机器人可记住整场对话内容，聊天更连贯

3. 防刷屏限制：设置回复间隔、单人每日提问次数，防止风控

7.2 热门插件推荐#

1. 群管插件：自动踢人、禁言、欢迎新人、关键词屏蔽

2. AI 绘图插件：支持文生图、图生图

3. 热搜查询、天气查询、翻译插件

4. 定时播报、自动打卡、群公告推送

所有插件均可在后台【插件市场】一键安装、启用、配置。

9.1 容器启停重启#

1
# 重启全部
2
docker restart napcat astrbot
3
# 单独重启napcat
4
docker restart napcat
5
# 单独重启astrbot
6
docker restart astrbot
7
# 停止服务
8
docker stop napcat astrbot
9
# 开启服务
10
docker start napcat astrbot

9.2 开机自启检查#

两个容器均设置了always自启，服务器重启后自动恢复运行，无需手动操作。

9.3 查看运行日志#

1
# 查看napcat报错日志
2
docker logs -f napcat
3
# 查看astrbot运行日志
4
docker logs -f astrbot

9.4 彻底卸载重装#

1
# 删除容器
2
docker rm -f napcat astrbot
3
# 删除本地配置文件（清空所有数据）
4
rm -rf /root/napcat /root/astrbot

问题 1：后台打不开、端口无法访问#

解决：1. 云服务器安全组放行端口；2. 服务器防火墙关闭 / 放行端口；3. 确认容器状态为 UP

问题 2：NapCat 登录成功，AstrBot 显示离线#

解决：1. 反向 WS 地址填写错误；2. 端口映射冲突；3. 重启两个容器重新对接

问题 3：接收不到消息、机器人不回复#

解决：1. 大模型密钥失效 / 余额不足；2. 未开启消息监听；3. QQ 账号被临时风控

问题 4：容器启动失败、端口占用#

解决：查询端口占用，更换端口或关闭占用程序，重新部署

问题 5：频繁掉线、挂机不稳定#

解决：服务器网络波动、内存不足，升级服务器配置，开启容器自动重启

长期稳定挂机优化建议#

1. 使用低配云服务器 7×24 小时挂机，耗电低、零维护

2. 定期查看日志，及时更新镜像版本

3. 避免高频刷屏、批量操作，降低风控概率

4. 定期备份 data 配置文件夹，防止数据丢失

码字不易，纯原创万字干货教程 如果部署成功，欢迎点赞收藏！后续持续更新插件教程、模型对接、风控优化、多机器人搭建教程，有任何部署问题随时留言提问，一一解答！

（注：部分内容可能由 AI 生成）