1.1 项目背景#

AstrBot 的定位是一个 Agent 编排器（Agent Orchestrator） 和开发框架，重点放在多 Bot、热重载、会话级隔离、插件扩展和多平台接入上。

1.2 核心特点#

1.3 协作关系（与 NapCat）#

如果你想把 AstrBot 接入 QQ，需要配合 NapCat 使用：

• NapCat 负责登录 QQ 并提供标准化的 OneBot v11 API 接口，充当“耳朵”（接收消息）和“嘴巴”（发送消息）
• AstrBot 作为智能中枢，处理消息逻辑、调用 AI 模型并生成回复，是机器人的“大脑”

二者通过 WebSocket 建立连接，方可实现完整功能闭环。

2.1 Docker 部署（推荐）#

1
mkdir astrbot
2
cd astrbot
3
wget https://raw.githubusercontent.com/NapNeko/NapCat-Docker/main/compose/astrbot.yml
4
sudo docker compose -f astrbot.yml up -d

1
curl -fsSL https://gitee.com/jun-wan/script/raw/master/astrbot/deploy_astrbot.sh | bash

1
irm https://gitee.com/jun-wan/script/raw/master/astrbot/deploy_astrbot.ps1 | iex

1
version: '3'
2

3
services:
4
  astrbot:
5
    image: soulter/astrbot:latest
6
    container_name: astrbot
7
    ports:
8
      - "6185:6185"   # WebUI 端口
9
      - "6199:6199"   # 反向 WebSocket 端口
10
    restart: always

1
docker compose up -d

2.2 源码部署#

1
# 克隆仓库
2
git clone https://github.com/AstrBotDevs/AstrBot.git
3
cd AstrBot
4

5
# 安装依赖并运行
6
uv sync
7
uv run main.py

1
# 克隆仓库
2
git clone https://github.com/AstrBotDevs/AstrBot.git
3
cd AstrBot
4

5
# 创建并激活虚拟环境
6
python3 -m venv ./venv
7
source venv/bin/activate  # Linux/Mac
8
# 或 venv\Scripts\activate  # Windows
9

10
# 安装依赖
11
pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
12

13
# 运行
14
python main.py

2.3 使用宝塔面板部署#

如果你使用宝塔面板管理服务器，可以通过 Docker 容器部署：

1. 登录宝塔面板，进入 Docker → 容器 页面
2. 点击 创建容器，填写以下参数：

3. 点击创建，等待容器启动完成

3.1 访问 WebUI#

部署成功后，通过浏览器访问 http://<服务器IP>:6185。

默认用户名和密码均为 astrbot，首次登录后会提示修改密码。

3.2 WebUI 功能概览#

4.1 接入 DeepSeek#

1. 前往 DeepSeek 平台 获取 API Key
2. 在 API Keys 页面创建新的 API Key，复制保存
3. 进入 AstrBot WebUI，点击左侧 模型提供商 → 新增模型提供商 → 选择 DeepSeek
4. 填入 API Key，点击保存
5. 点击 测试 按钮验证配置是否成功

4.2 接入其他模型#

AstrBot 支持多种模型提供商：

• OpenAI：ChatGPT、GPT-4 等
• 硅基流动：SiliconCloud 上的各类开源模型
• 阿里云百炼：通义千问等
• Dify / Coze：LLMOps 平台应用

配置方式与 DeepSeek 类似，选择对应提供商后填写 API Key 和模型名称即可。

5.1 接入 QQ（配合 NapCat）#

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
  --add-host=host.docker.internal:host-gateway \
8
  --name napcat \
9
  --restart=always \
10
  docker.1ms.run/mlikiowa/napcat-docker:latest

1
# 创建自定义网络
2
docker network create astrbot-napcat
3

4
# 将两个容器加入网络
5
docker network connect astrbot-napcat astrbot
6
docker network connect astrbot-napcat napcat
7

8
# 记录 AstrBot 容器的 IP 地址
9
docker inspect astrbot | grep IPAddress

5.2 接入飞书#

1. 前往 飞书开发者后台，创建企业自建应用，添加机器人能力
2. 获取 app_id 和 app_secret
3. 在 AstrBot WebUI 中，点击 机器人 → 创建机器人 → 选择 lark（飞书）
4. 填写 app_id、app_secret 和机器人名称
5. 设置 domain 为 https://open.larksuite.com
6. 在飞书开发者后台配置事件回调（使用长连接）、添加接收消息权限，创建版本并发布
7. 在飞书 APP 中将机器人拉入群聊测试

6.1 人格设定#

AstrBot 支持自定义 AI 人设：

1. 进入 WebUI 左侧 更多功能 → 人格设定
2. 点击 创建人格，填写：
   • 人格 ID：用于切换的标识
   • 系统提示词：定义 AI 的角色和行为
3. 在对话中使用指令切换：
   • /persona list：查看所有可用人格
   • /persona <人格ID>：切换到指定人格
   • /reset：清空上下文，防止原人格对话影响现人格

6.2 插件系统#

AstrBot 拥有 1000+ 可一键安装的插件：

1. 进入 WebUI 左侧 插件
2. 在插件市场中搜索需要的插件（如点歌插件、天气查询等）
3. 点击安装，等待完成即可使用

安装插件后，在对话中发送对应指令（如 /点歌 歌曲名）即可调用。

6.3 MCP 服务#

AstrBot 支持 MCP（Model Context Protocol）服务，可以让 AI 调用外部工具和能力。

6.4 分段回复#

启用分段回复可以让 AI 的消息分条发送，更适合聊天场景：

1. 进入 WebUI 左侧 配置文件
2. 找到 流式回复 选项，勾选启用
3. 点击保存

6.5 更新管理面板#

AstrBot 启动时会自动检查管理面板更新。如需手动更新：

• 使用命令 /dashboard_update（需管理员权限）
• 或从 GitHub Releases 下载 dist.zip 解压到 data 目录