> ## Content Index
> Fetch the complete content index at: https://tbbbk.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# AstrBot 完整安装教程（2026）：Docker 部署 + NapCat 接入 QQ，一次搞定
- URL: https://tbbbk.com/astrbot-install-qq-bot-docker-napcat-guide-2026/
- Published: 2026-03-16T00:48:46.000Z
- Updated: 2026-03-16T00:48:46.000Z
- Description: AstrBot 是 GitHub 4万+ star 的开源 AI 机器人框架，支持 QQ、微信、Telegram 等多平台。本文记录 Docker Compose 部署 AstrBot + NapCat 接入 QQ 的完整过程，含国内镜像加速、风控避坑等实操经验。
- Author: TuBaiBai
- Tags: VPS 与云服务, 折腾日记, #Import 2026-07-20 07:13

上周在刷 GitHub Trending 的时候，看到一个叫 AstrBot 的项目一直挂在榜单上，4 万多 star，README 里写着支持 QQ、微信、Telegram、飞书、钉钉……看完我的第一反应是：这不就是个更重量级的群聊版 OpenClaw 吗？

我自己之前折腾过 [OpenClaw 接 QQ](https://tbbbk.com/openclaw-qq-bot-setup-guide-2026/)，主要是给自己用，当个私人助手。但朋友一直问能不能弄个机器人进群，让大家都能和 AI 聊——OpenClaw 不是为这个场景设计的。于是这个周末我就把 AstrBot 搭起来研究了一遍，踩了好几个坑，顺手把完整流程整理出来。

## AstrBot 是什么

简单说：AstrBot 是一个开源的多平台 AI 机器人框架，GitHub 目前 4 万+ star，活跃度很高。它支持同时接入 QQ（个人号/官方机器人）、微信、Telegram、飞书、钉钉等 IM 平台，后端可以对接 DeepSeek、Claude、GPT、Qwen、GLM 等主流模型，自带 WebUI 管理面板，还有插件系统，可以扩展图片生成、联网搜索、待办清单等功能。

和 OpenClaw 的定位区别说清楚：[OpenClaw](https://tbbbk.com/openclaw-qq-bot-setup-guide-2026/) 是个人 AI 助手，跑在你自己的设备上，帮你读文件、写代码、发邮件、管日历，是一个"只服务于你"的数字雇员。AstrBot 的定位是群聊 AI 机器人，部署在服务器上，接进 QQ 群或微信群，所有群成员都能跟它聊，更像"群里的 AI 管家"。两个不是同类产品，没有谁替代谁的问题。

## 准备工作

开始之前把这几样东西凑齐，省得中途卡住：

- **一台 Linux VPS 或本地机器**：2 核 1G 内存够跑，推荐 Ubuntu 22.04 或 Debian 12
- **安装好 Docker**：没装的话直接搜 Docker 官方文档安装，国内机器可以换 DaoCloud 加速源
- **一个 QQ 号**：用来登录成机器人，**强烈不建议用主号**，风控触发直接封号很难受
- **一台手机**：NapCat 登录 QQ 需要扫码，手机要在旁边

如果你在国内 VPS 上操作，拉镜像可能会超时，后面我会说怎么走 DaoCloud 加速，提前有个心理准备。

## 第一步：部署 AstrBot

有两种方式，我推荐第一种——直接用官方提供的 Docker Compose 文件，AstrBot 和 NapCat 一起起来，省去单独配置的麻烦。

### 方式一：Docker Compose（推荐）

```bash
mkdir astrbot && cd astrbot
wget https://raw.githubusercontent.com/NapNeko/NapCat-Docker/main/compose/astrbot.yml
sudo docker compose -f astrbot.yml up -d
```

国内 VPS 拉 GitHub 的 yml 文件如果超时，可以手动复制内容创建文件。镜像拉取失败的话，编辑 `astrbot.yml`，把其中的 `soulter/astrbot:latest` 替换为：

```yaml
image: m.daocloud.io/docker.io/soulter/astrbot:latest
```

改完保存，重新 `up -d` 就能走 DaoCloud 加速拉镜像。

### 方式二：单独 docker run

如果你不想用 Compose，或者 NapCat 想单独管理，也可以单独跑 AstrBot：

```bash
mkdir astrbot && cd astrbot
sudo docker run -itd \
  -p 6180-6200:6180-6200 \
  -p 11451:11451 \
  -v $PWD/data:/AstrBot/data \
  -v /etc/localtime:/etc/localtime:ro \
  -v /etc/timezone:/etc/timezone:ro \
  --name astrbot \
  m.daocloud.io/docker.io/soulter/astrbot:latest
```

几个关键端口说明一下：

- **6185**：WebUI 管理面板，浏览器访问用这个
- **6199**：OneBot/aiocqhttp 协议端口，NapCat 接进来用这个
- **11451**：微信回调端口，只接 QQ 的话用不到

部署完查看日志确认状态：

```bash
sudo docker logs -f astrbot
```

看到类似"管理面板已启动"的日志输出就行了。然后浏览器打开 `http://你的服务器IP:6185`，默认账号密码都是 `astrbot`，**第一次登录会强制要求改密码**，改完才能进面板。

## 第二步：部署 NapCat，登录 QQ

NapCat 是基于无头 QQNT 的 OneBot v11 协议实现，本质就是在服务器上跑一个没有界面的 QQ 客户端，对外暴露 WebSocket 接口。AstrBot 通过这个接口收发 QQ 消息。

如果你用的是方式一的 Docker Compose，NapCat 已经随着 AstrBot 一起部署好了，直接看 NapCat 的日志：

```bash
docker logs napcat
```

日志里会打出 WebUI 的访问地址和 Token，记下来备用。

如果你是单独部署 NapCat，跑这个命令：

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

然后同样 `docker logs napcat` 拿 Token。浏览器打开 `http://服务器IP:6099`，输入 Token 进 NapCat WebUI，里面会有个二维码，掏出手机，用你准备好的小号 QQ 扫码登录。

**踩坑提示**：QQ 号最好不是新注册的。不少人反馈用新号扫码后很快就被风控封号，连申诉窗口都没来得及打开。建议用一个养了几个月、有正常使用记录的小号，成功率高很多。

## 第三步：连接 NapCat 和 AstrBot

QQ 登录成功之后，还需要把 NapCat 和 AstrBot 对接上。逻辑是：NapCat 作为 WebSocket 客户端，主动连接到 AstrBot 监听的 WebSocket 服务端，把 QQ 收到的消息转发给 AstrBot 处理。

### 在 NapCat WebUI 配置 WebSocket 客户端

1. 进入 NapCat 管理面板 → **网络配置** → **新建** → 选 **WebSocket 客户端**
2. URL 填：`ws://宿主机IP:6199/ws`（注意末尾要有 `/ws`，少了这个连不上）
3. 消息格式：**Array**
4. 心跳间隔：`5000`
5. 重连间隔：`5000`
6. Token：随便设一个强密码，后面 AstrBot 那边要填一样的
7. 保存

### 在 AstrBot WebUI 开启 aiocqhttp 适配器

1. 进入 AstrBot 管理面板 → **消息平台** → **新增适配器**
2. 选择「**接入 QQ 个人号（aiocqhttp）**」
3. 反向 WebSocket 主机地址填：`0.0.0.0`
4. 端口：`6199`
5. Token：填和 NapCat 一样的那个密码
6. 保存，然后重启 AstrBot 容器

重启之后盯着 AstrBot 的控制台日志，看到蓝色的「aiocqhttp(OneBot v11) 适配器已连接」就说明两边握手成功了。

验证方式：用另一个 QQ 号私聊你的机器人 QQ，发送 `/help`，有回复就全部搞定。

## 第四步：配置 AI 模型

机器人能收发消息了，但还没接 AI 大脑，现在来配置模型。

进入 AstrBot 管理面板 → **大语言模型** → **新增**。AstrBot 支持 OpenAI API 格式，所以兼容 DeepSeek、SiliconCloud、月之暗面等国内提供商，不用担心直连 OpenAI 的问题。

我推荐用 **SiliconCloud（硅基流动）**：一个账号能调 DeepSeek-V3、Qwen3、GLM-4 等一堆国内模型，价格比官方便宜，注册还送 14 元代金券，[点这里注册](https://cloud.siliconflow.cn/i/gZIsiB9U)（邀请链接）。

配置参数：

- **API Base URL**：`https://api.siliconflow.cn/v1`
- **API Key**：去 SiliconCloud 控制台生成
- **模型名**：`deepseek-ai/DeepSeek-V3`（或者 `Qwen/Qwen3-32B` 等）

保存之后，去 AstrBot 面板的**对话管理**页面，可以实时看到用户和机器人的对话记录，方便调试和监控。

## 踩坑记录

- **Docker 网络问题，WS URL 不能填 localhost**  
AstrBot 和 NapCat 都跑在 Docker 容器里，容器之间的 `localhost` 指的是各自容器内部，不是宿主机。NapCat 填 WS URL 时要填宿主机的实际内网 IP，或者两个容器在同一个 Compose 网络里可以填容器名（如 `ws://astrbot:6199/ws`）。这个坑我卡了半个多小时。
- **VPS 防火墙没放行端口**  
阿里云、腾讯云这类 VPS 除了系统级 iptables，还有控制台的安全组要配。6180-6200 和 6099 这两段端口要在安全组手动放行，光在服务器上 `ufw allow` 不够。
- **QQ 风控封号**  
新号或长期没用的号扫码高危。用养过的小号，扫码后别立刻发大量消息，让机器人"热身"一下再正式用。
- **国内拉镜像失败**  
Docker 官方镜像在国内基本不通，用 DaoCloud 加速：所有镜像地址前加 `m.daocloud.io/docker.io/` 前缀。

## 和 OpenClaw 怎么选

我知道有人会问这个，简单说清楚：

- **OpenClaw**：个人 AI 助手，跑在你自己的电脑或服务器上，帮你读文件、发邮件、跑代码、管日历，是"只服务于你一个人"的数字雇员。[国内使用 OpenClaw](https://tbbbk.com/openclaw-china-mainland-setup-guide/) 需要额外配置一些网络，但配好了非常顺手。
- **AstrBot**：群聊 AI 机器人，部署在服务器上，接入 QQ/微信群，所有人都能和机器人交互，是"群里的 AI 管家"。

两个不冲突，完全可以同时跑。如果你对这两者的详细对比感兴趣，可以看这篇：[CoPaw vs OpenClaw 深度对比](https://tbbbk.com/copaw-vs-openclaw-comparison-2026/)，里面也顺带聊了 AstrBot 这类框架的定位差异。

---

折腾完之后群里几个朋友开始问机器人各种奇怪的问题，有人拿它写诗，有人让它算命，比我预想的活跃。下一步打算研究一下 AstrBot 的插件系统，看看能不能接个图片生成进去——硅基流动的图生图 API 应该能对接上。