AstrBot 完整安装教程（2026）：Docker 部署 + NapCat 接入 QQ，一次搞定

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

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

AstrBot 是什么

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

和 OpenClaw 的定位区别说清楚：OpenClaw 是个人 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（推荐）

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 替换为：

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

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

方式二：单独 docker run

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

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 的话用不到

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

sudo docker logs -f astrbot

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

第二步：部署 NapCat，登录 QQ

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

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

docker logs napcat

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

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

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 元代金券，点这里注册（邀请链接）。

配置参数：

• 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 需要额外配置一些网络，但配好了非常顺手。
• AstrBot：群聊 AI 机器人，部署在服务器上，接入 QQ/微信群，所有人都能和机器人交互，是"群里的 AI 管家"。

两个不冲突，完全可以同时跑。如果你对这两者的详细对比感兴趣，可以看这篇：CoPaw vs OpenClaw 深度对比，里面也顺带聊了 AstrBot 这类框架的定位差异。

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