从零开始，用一台服务器（或你的电脑）搭一个能跑在 QQ、微信、飞书、Telegram 里的 AI 机器人。 全程可视化配置，不需要写一行代码。

一、先搞清楚 AstrBot 是什么

AstrBot 是一个开源的一站式 Agentic 聊天机器人平台，简单说它做了三件事：

1. 在上游对接大模型 —— OpenAI、Anthropic Claude、Google Gemini、DeepSeek、月之暗面、智谱、硅基流动，以及本地部署的 Ollama / LM Studio 都能接。

2. 在下游对接聊天软件 —— QQ、企业微信、微信公众号、飞书、钉钉、Telegram、Discord、Slack、KOOK 等十几个平台。

3. 在中间提供能力层 —— 插件系统（社区插件 1000+）、知识库（RAG）、人格设定、MCP / Skills 扩展、代码执行沙箱、定时任务。

它的定位不是"又一个 ChatGPT 网页壳"，而是跑在你日常聊天软件里的 AI。你在 QQ 群里 @ 它一下，它就回你了；你给它塞一堆 PDF，它就变成你的专属知识库客服。

几个关键事实：

• 开源协议 AGPL-3.0，个人和商业使用都免费

• GitHub 星标 3.5 万+，社区活跃，插件生态成熟

• 数据完全在你自己的机器上，不经过任何第三方中转

⚠️ 合规提醒：如果你在中国大陆境内使用，官方强烈建议选择由模型厂商官方提供或已完成备案的模型服务（如 DeepSeek、MoonshotAI、GLM、MiniMax、Qwen 等）。使用未经备案的第三方中转服务可能导致服务不可用、信息泄露或法律风险。

二、部署方式怎么选

AstrBot 支持很多种部署方式，我先给你一张选型表，别一上来就挑花眼：

我的建议：如果你有一台服务器（哪怕是 2 核 2G 的最低配云主机），直接用 Docker；如果只是想在自己电脑上先玩明白，用 uv 一键部署。

端口速查

部署前先把这几个端口记牢，后面排查问题全靠它：

三、方式一：Docker 部署（生产推荐）

3.1 前置条件

一台装了 Docker 的机器（Linux / Windows / macOS 都行），Linux 上推荐 Ubuntu 22.04 或 Debian 12。

没装 Docker 的先去官方文档装一下，国内机器可以顺手配置镜像加速。

3.2 一行命令启动

mkdir astrbot && cd astrbot

sudo docker run -itd \
  -p 6185:6185 \
  -p 6199:6199 \
  -v $PWD/data:/AstrBot/data \
  -v /etc/localtime:/etc/localtime:ro \
  -v /etc/timezone:/etc/timezone:ro \
  -e TZ=Asia/Shanghai \
  --name astrbot \
  soulter/astrbot:latest

国内拉取镜像慢？ 把镜像名换成 DaoCloud 加速源：

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

参数解释：

• -v $PWD/data:/AstrBot/data —— 把数据目录挂到宿主机，这一步决定了你的配置会不会随容器删除而丢失，千万别漏

• -v /etc/localtime:/etc/localtime:ro + -e TZ=Asia/Shanghai —— 同步宿主机时区，否则日志时间和定时任务会错乱

Windows 用户不需要加 sudo；Windows 上同步时间需要走 WSL2 路径：

-v \\wsl.localhost\<你的WSL发行版>\etc\timezone:/etc/timezone:ro
-v \\wsl.localhost\<你的WSL发行版>\etc\localtime:/etc/localtime:ro

3.3 用 Docker Compose（更规范，推荐）

自己建一个 docker-compose.yml：

version: '3'

services:
  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: always
    ports:
      - "6185:6185"   # WebUI 管理面板（必选）
      - "6199:6199"   # QQ 个人号 WebSocket（可选）
      # - "6195:6195" # 企业微信 Webhook（按需）
      # - "6196:6196" # QQ 官方接口 Webhook（按需）
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./data:/AstrBot/data
      - /etc/localtime:/etc/localtime:ro

然后启动：

docker compose up -d

3.4 确认启动成功

docker logs -f astrbot

看到类似这样的日志就说明起来了：

🌈 管理面板已启动，可访问 http://0.0.0.0:6185

3.5 首次登录

浏览器打开 http://<你的服务器IP>:6185。

⚠️ Docker 部署不能用 localhost 访问，因为 Docker 隔离了网络环境，必须填服务器 IP。

登录凭据在启动日志里：

docker logs astrbot 2>&1 | grep -i password

• 用户名：astrbot（通常是这个，以日志为准）

• 密码：启动时随机生成并打印在日志里

登录后第一件事就是改密码。 在 WebUI 里改，或者用命令行：

astrbot password

四、方式二：uv 一键部署（最快上手）

适合熟悉命令行、想五分钟看到效果的人。

4.1 前置条件

• Python 3.12 或更高版本（这是硬性要求）

• uv 包管理器

装 uv：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或者你已经有了 pip
pip install uv

4.2 三步启动

# 1. 安装 AstrBot
uv tool install astrbot --python 3.12

# 2. 初始化工作目录（仅首次执行）
astrbot init

# 3. 启动
astrbot run

astrbot init 会在当前目录创建 AstrBot 需要的数据目录和配置文件。之后每次启动只需要 astrbot run。

启动后终端会打印管理面板地址，默认 http://localhost:6185，同样用日志里的随机初始密码登录。

macOS 用户注意：由于系统安全检测机制，首次执行 astrbot 命令可能需要等 10–20 秒，不是卡住了，耐心等一下。

4.3 更新

uv tool upgrade astrbot --python 3.12

⚠️ 重要：通过 uv 部署的 AstrBot 不支持在 WebUI 里点升级，必须走上面这条命令行。

五、方式三：桌面用户的最省事方案

如果你主要在 Windows / macOS 桌面上用，只想体验 ChatUI，不想折腾命令行：

• AstrBot Launcher —— 官方启动器，下载安装即用，支持多实例隔离，适合既想要快速部署又想要环境隔离的桌面用户

• AstrBot App —— 桌面应用，主打内置 ChatUI，不建议用于服务器场景

两者都在 AstrBot 官方仓库的 Release 页面下载。

六、配置大模型：给机器人装上大脑

机器人跑起来了，但它现在还是个"哑巴"——它不知道该调用哪个模型。这一步来解决。

6.1 新增模型提供商

进入 WebUI，左侧菜单找 模型提供商（Providers） → 点击 新增。

AstrBot 原生适配三种 API 格式：OpenAI、Google GenAI、Anthropic。任何兼容这三种格式之一的服务都能接。

以 DeepSeek 为例（国内最省心的选择）：

1. 去 DeepSeek 开放平台 注册并创建 API Key

2. 在 AstrBot 里新增提供商，类型选 OpenAI（如果列表里直接有 DeepSeek 就优先选它，官方对部分提供商做了适配优化）

3. 填写：

• API Base URL：https://api.deepseek.com/v1

• API Key：你的 Key

1. 点击 获取模型列表，选择 deepseek-chat 或 deepseek-reasoner

2. 保存

其他方案：

Docker 部署用 Ollama 注意：容器里填 localhost 是访问不到宿主机 Ollama 的，要填宿主机的实际 IP，或用 host.docker.internal。

6.2 设置默认模型

光添加提供商还不够，得指定默认用哪个：

进入 配置文件（普通配置） 页面 → 找到模型一节 → 把 默认聊天模型 改成你刚配置的模型 → 点击右下角 保存。

📌 血泪教训：WebUI 里改完配置，一定要点右下角的保存按钮，否则不生效。

七、接入消息平台：让机器人真正上线

现在机器人有脑子了，但它还被关在 WebUI 里。这一步把它接到你的聊天软件上。

WebUI 左侧 → 机器人 / 消息平台 → 新增适配器 → 选择你想接的平台。

官方维护的平台包括：QQ（官方机器人接口 + OneBot v11）、Telegram、企业微信应用与智能机器人、微信客服、微信公众号、飞书（Lark）、钉钉、Slack、Discord、LINE、Satori、Misskey、KOOK 等。

7.1 实战：接入 QQ（最经典的场景）

QQ 个人号需要通过 OneBot v11 协议 桥接。整体逻辑是：

QQ 服务器 ←→ NapCat（协议端）←→ WebSocket ←→ AstrBot（逻辑端）←→ 大模型

第一步：部署 NapCat

NapCat 是 OneBot v11 协议实现，负责登录 QQ 并把消息标准化。用 Docker 起一个：

docker run -d \
  --name napcat \
  -p 6099:6099 \
  -v $PWD/napcat/config:/app/napcat/config \
  -v $PWD/napcat/data:/app/napcat/data \
  --restart always \
  mlikiowa/napcat-docker:latest

⚠️ 强烈建议用一个小号，不要用你的 QQ 主号。协议端登录有风控风险，主号被封很难受。用一个养了几个月、有正常聊天记录的小号成功率最高。

访问 http://<服务器IP>:6099 打开 NapCat 面板，扫码登录你的机器人 QQ 号。

第二步：AstrBot 侧开启适配器

AstrBot WebUI → 消息平台 → 新增适配器 → 选择 aiocqhttp（OneBot v11）：

• ID：随便起个名，用于区分不同实例

• 启用：勾选

• 反向 WebSocket 主机地址：0.0.0.0（Docker 部署时必须填这个）

• 反向 WebSocket 端口：6199

保存。

第三步：NapCat 侧连接 AstrBot

NapCat 面板 → 网络配置 → 新建 → WebSocket 客户端：

• 启用：勾选

• URL：ws://<宿主机IP>:6199/ws

• 消息格式：Array

• 心跳间隔：5000

• 重连间隔：5000

🚨 最容易踩的坑：URL 末尾的 /ws 必须有，少了这个路径死活连不上。另外这里的 IP 不要填 0.0.0.0——0.0.0.0 是监听端用的，连接端要填真实 IP 或 127.0.0.1。

第四步：验证连接

观察 AstrBot 日志，出现这条蓝色日志说明握手成功：

aiocqhttp(OneBot v11) 适配器已连接

然后用另一个 QQ 号私聊机器人，发送 /help，有回复就大功告成。

7.2 其他平台

• Telegram：在 BotFather 申请 Bot Token，在 AstrBot 里选 Telegram 适配器填入 Token 即可，是最省事的平台

• 飞书 / 钉钉 / 企业微信：走官方应用凭证（App ID / Secret），需要在对应开放平台创建应用并配置事件回调

• 微信公众号 / 微信客服：需要服务器有公网 IP 并配置回调地址，注意放行 11451 端口

八、设置管理员

有些指令（切换模型、改人格、更新面板）需要管理员权限。设置方法：

1. 在聊天软件里对机器人发 /sid，拿到你的用户 ID

2. WebUI → 配置 → 其他配置 → 管理员 ID → 填入你的 ID

3. 点击右下角保存

九、常用指令速查

在聊天窗口里直接发送，/ 是默认唤醒前缀（可以在配置里改，改了之后指令前缀也要跟着变）。

插件还会注册自己的指令，具体看插件说明。发 /plugin 或看插件文档。

十、命令行工具（CLI）

如果你用 uv 部署，CLI 能干不少事。注意：以下命令都要在 AstrBot 工作目录里执行。

astrbot init                     # 初始化当前目录为工作目录
astrbot run                      # 前台启动
astrbot run --port 6185          # 指定 WebUI 端口
astrbot run --reload             # 插件自动重载（开发调试用）
astrbot run --reset-password     # 忘记密码时重置，新密码会打印在启动日志里

astrbot conf get                 # 查看所有可配置项
astrbot conf get dashboard.port  # 查看某一项
astrbot conf set dashboard.port 6185
astrbot conf set dashboard.password "new-password"
astrbot password                 # 交互式改密码

astrbot plug list                # 列出已安装插件
astrbot plug search <关键词>     # 搜索插件
astrbot plug install <插件名>    # 安装插件
astrbot plug update              # 更新所有可更新插件
astrbot plug remove <插件名>     # 卸载插件
astrbot plug new <插件名>        # 从模板创建新插件

astrbot --version                # 查看版本

可用的 conf 配置项：timezone、log_level、dashboard.port、dashboard.username、dashboard.password、callback_api_base。

国内装插件拉不动 GitHub？ 加个代理：

astrbot plug install <插件名> --proxy https://gh-proxy.example.com/

十一、插件：AstrBot 的可玩性全在这里

插件是 AstrBot 扩展性的核心，社区插件已超过 1000 个。

安装方式

方式一：WebUI 插件市场（推荐）

左侧 插件 → 插件市场 标签页 → 浏览或搜索 → 点击安装。也可以点右下角 + 通过 URL 或文件上传手动安装。

装完之后在 已安装插件 里开启、配置参数（比如搜索插件要填 API Key），部分插件需要重启生效。

方式二：命令行

astrbot plug install <插件名>

值得一装的插件类型

• 联网搜索 —— 解决大模型知识时效性问题，强烈推荐

• 点歌 / 音乐 —— 群里活跃气氛神器

• 代码执行 —— 运行 Python/JS，注意配合沙箱使用

• 知识库相关 —— 导入本地文档做 RAG 问答

• 定时提醒 / 定时任务 —— 结合 Cron 能力做自动化

• 签到 / 群游戏 —— 群运营

⚠️ 安全提醒：AstrBot 团队无法完全保证插件市场里第三方插件的安全性，请自行甄别，团队不对插件造成的损失负责。

插件加载失败怎么办

WebUI 会显示错误信息，并提供 "尝试一键重载修复" 按钮。修好环境（比如装了缺失的依赖）后点它，不用重启整个应用，开发调试时非常方便。

十二、进阶玩法

12.1 知识库（RAG）

上传 PDF / DOCX / Markdown 文档，机器人就能基于你的私有数据精准问答。

• 集成了 Microsoft Markitdown 做高质量文档解析

• 混合检索：稠密检索 + 稀疏检索（BM25），针对中文场景优化

• 支持在一个会话里引用多个知识库

12.2 人格设定

在 WebUI 里配置人格，可以给机器人设定名称、人设、预设对话、对话风格。社区有大量现成人设模板，猫娘、助教、客服、毒舌程序员随便挑。

12.3 Agent 沙箱

让 AI 执行代码是很危险的事（万一它跑个 rm -rf /）。AstrBot 提供 Agent Sandbox，把 AI 执行的代码和 Shell 命令全部关在隔离环境里，闯祸范围可控。

Docker 部署可以用 compose-with-shipyard.yml 启用沙箱环境：

git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot
# 先修改 compose-with-shipyard.yml 里的环境变量，比如 Shipyard 的访问令牌
docker compose -f compose-with-shipyard.yml up -d
docker pull soulter/shipyard-ship:latest

12.4 MCP 与 Skills

原生支持 MCP，把外部能力标准化接入，让机器人真正"能干活"而不只是"能聊天"。

12.5 分段回复与主动对话

在配置里开启分段回复，机器人会模拟真人的聊天节奏，把长回复拆成几条发，不用再盯着一大段文字刷屏。

十三、常见问题排查

Q：机器人不回复？ 按顺序检查三件事：① 消息平台连接状态是否在线（看适配器日志）；② 模型 API Key 是否正确、余额是否充足；③ 网络是否通畅。

Q：模型调用失败？ 核对 API Key 和 Base URL，在提供商页面用测试连接功能验证。可以给同一个提供商配多个模型做回退。

Q：插件不生效？ 重启机器人 → 检查插件配置参数是否填写完整 → 检查插件版本是否过旧。

Q：端口打不开 / 面板访问不了？

• 云服务器要在控制台安全组放行 6180-6200 和 11451

• 本机检查防火墙

• 端口被占用的话改端口：WebUI 里 设置 → 通用 → 端口，或用 astrbot conf set dashboard.port 6186

• Docker 部署记得不能用 localhost

Q：忘了 WebUI 密码？

astrbot run --reset-password

或在源码部署下：python main.py --reset-password。新密码会打印在启动日志里，登录后立刻改掉。

Q：Docker 里时间和本地差 8 小时？ 挂载 /etc/localtime 和 /etc/timezone，并加 -e TZ=Asia/Shanghai。

Q：改了配置没生效？ 右下角保存按钮点了吗？这是最高频的"bug"。

十四、写在最后

AstrBot 的核心价值就一句话：一次部署，多平台运行，数据在自己手里。

整个搭建流程拆开看其实就五步：

部署 AstrBot → 配置大模型 → 接入消息平台 → 设置管理员 → 装插件扩展能力

踩坑最多的地方无非是三个：Docker 的 localhost 陷阱、NapCat 连接 URL 少写了 /ws、改完配置忘了点保存。避开这三个，基本一路畅通。

项目在快速迭代，本文提到的菜单名称、配置项可能随版本变化。遇到和本文描述不一致的地方，以官方文档为准：

• 官网：<https://astrbot.app>

• 文档：<https://docs.astrbot.app>

• GitHub：<https://github.com/AstrBotDevs/AstrBot>

玩得开心，别忘了去 GitHub 给项目点个 Star ⭐