AstrBot 完全入门指南

2026-09-02 8 0 0

一、AstrBot 是什么

AstrBot 是一个开源的一站式 Agentic 个人和群聊助手框架。它让你能将自己的 AI 聊天机器人部署到 QQ、Telegram、企业微信、飞书、钉钉、Slack、Discord 等数十款主流即时通讯软件上。同时，它也内置了类似 OpenWebUI 的轻量化 ChatUI，可以在浏览器中直接与 AI 对话。

无论是个人 AI 伙伴、群聊智能助手、企业知识库问答，还是基于插件扩展的自动化工作流，AstrBot 都能在你熟悉的 IM 环境中快速落地。项目基于 AGPL-v3 协议开源，由全球社区贡献者共同维护。

二、核心特性一览

特性	说明
多平台支持	支持 QQ、Telegram、微信、飞书、钉钉、Discord 等 18+ 消息平台，一套配置多处运行。
多模型接入	兼容 OpenAI、Anthropic、Google Gemini 等原生 API 格式，也支持 DeepSeek、GLM、Qwen、MoonshotAI 等国产模型。
插件系统	社区贡献了超过 1000 个插件，涵盖娱乐、工具、管理、自动化等场景。
MCP 协议支持	支持 Model Context Protocol，可无缝接入外部工具和 API。
知识库	内置知识库功能，支持 RAG（检索增强生成），让机器人基于你的私有文档回答问题。
SubAgent 编排	将复杂任务拆解为多个子 Agent 协同执行，实现更高级的自动化。
Agent 沙箱	为 Agent 提供安全的代码执行环境，可以运行 Python、Shell 等脚本。
WebUI 管理面板	美观的可视化面板，支持插件管理、日志查看、统计图表、TOTP 双因素认证。

三、架构概览

AstrBot 采用松耦合的异步架构，整体分为三层：

层次	职责
消息适配层	负责对接各 IM 平台。每个平台有一个独立的适配器，将平台原生消息格式统一为 AstrBot 内部消息。
核心引擎	负责消息路由、会话管理、指令解析、插件调度、Agent 编排等核心逻辑。
AI 模型层	对接各大 LLM 提供商，支持轮询、负载均衡、故障转移等策略。

这种分层设计使得每个环节都可以独立替换和扩展。例如，你可以在不修改任何业务逻辑的情况下，将 QQ 适配器替换为 Telegram 适配器；或者将底层的模型提供商从 OpenAI 切换到 DeepSeek。

四、安装方式详解

AstrBot 提供了多种安装路径，你可以根据自己的技术背景和需求选择最合适的方式。

4.1 桌面客户端安装（推荐新手）

桌面客户端是最快上手的方式，支持 Windows、macOS 和 Linux。它提供图形化安装向导，无需手动配置 Python 或 Docker 环境，开箱即用。

安装步骤：

1. 访问 AstrBot-Desktop Releases 页面（GitHub），下载对应系统的安装包（.exe / .dmg / .deb / .rpm）。

2. 运行安装程序，完成后启动桌面客户端。

3. 按照弹出的初始化向导完成配置。

💡 提示：桌面客户端适合个人本地使用，不建议用于服务器长期运行或生产环境。生产环境请优先考虑 Docker 部署。

4.2 包管理器（uv）安装

uv 是一个极速的 Python 包管理器，用它安装 AstrBot 只需三条命令，适合熟悉命令行的用户。

前置条件：确保已安装 uv（参考官方文档）。

安装并启动：

uv tool install astrbot --python 3.12

astrbot init # 仅首次部署执行

astrbot run

💡 注意：通过 uv 部署的版本不支持在 WebUI 中升级，如需更新请执行：uv tool upgrade astrbot --python 3.12

4.3 Docker 部署

Docker 部署是生产环境的首选方案，隔离性好、易于管理、支持一键更新。

创建目录并启动容器：

mkdir astrbot && cd astrbot

docker run -itd -p 6185:6185 -p 6199:6199 \

-v $PWD/data:/AstrBot/data \

--name astrbot soulter/astrbot:latest

中国大陆用户建议使用镜像加速：

docker run -itd -p 6185:6185 -p 6199:6199 \

-v $PWD/data:/AstrBot/data \

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

查看日志确认启动成功：

docker logs -f astrbot

💡 重要：Docker 默认隔离了网络，所以不能用 localhost 访问管理面板，需要用宿主机 IP 或映射端口。首次登录请使用启动日志中打印的随机初始密码。

五、初次启动与 WebUI 登录

无论哪种方式部署，启动成功后，访问 http://localhost:6185 即可进入管理面板。

首次登录流程：

1. 在启动日志中找到以 "管理面板已启动，可访问" 开头的行，里面包含随机初始密码。

2. 在登录页面输入用户名（默认 astrbot）和该密码。

3. 登录后立即在「配置文件 → 系统配置」中修改密码。

4. 建议开启 WebUI TOTP 双因素认证，进一步提升安全性。

管理面板包含以下主要模块：机器人（消息平台接入）、服务提供商（AI 模型配置）、插件（市场与本地管理）、配置（可视化配置修改）、数据（统计、日志、对话记录、追踪调试）。

六、接入 AI 模型

AstrBot 适配了 OpenAI、Google GenAI 和 Anthropic 三种原生 API 格式。国内推荐使用 DeepSeek、GLM、Qwen、MoonshotAI 等经备案的模型服务商。

以接入 DeepSeek 为例：

1. 登录 DeepSeek 控制台，创建并复制 API Key。

2. 在 API 文档中找到 OpenAI 兼容接口的 Base URL（如 https://api.deepseek.com/v1）。

3. 打开 AstrBot 管理面板 → 服务提供商页面，点击新增，选择 DeepSeek（或 OpenAI 通用类型）。

4. 填入 API Key 和 Base URL，点击获取模型列表。

5. 选择你想要的模型，点击右侧 + 号添加，然后打开开关。

6. 进入配置文件页面，找到对话模型，选择刚添加的提供商和模型，保存配置。

💡 提示：从 v4.13.0 开始，API Key 支持通过环境变量加载，在配置中填写 $DEEPSEEK_API_KEY 即可。

AstrBot 支持的部分模型提供商：

提供商	API 格式	特点
OpenAI	OpenAI	GPT-4o / GPT-4o-mini 等
Anthropic	Anthropic	Claude 3.5 Sonnet / Haiku
Google	Google GenAI	Gemini 1.5 Pro / Flash
DeepSeek	OpenAI 兼容	国产性价比高，支持 V3 / R1
GLM (智谱)	OpenAI 兼容	GLM-4 系列，中文能力强
Qwen (通义千问)	OpenAI 兼容	Qwen 系列，多模态
Ollama	OpenAI 兼容	本地部署开源模型，完全离线

七、连接消息平台

AstrBot 支持 18+ 消息平台。在 WebUI 中，点击左侧「机器人」→「创建机器人」，选择平台类型，按照文档左侧的接入指南操作即可。

7.1 接入 QQ（NapCat + OneBot v11）

QQ 是目前最常用的接入场景。推荐使用 QQ 官方机器人（WebSockets 方式），但也支持通过 NapCat + OneBot v11 协议实现。

步骤一：在 AstrBot 中配置 OneBot 适配器

1. 进入 WebUI → 机器人 → 创建机器人

2. 选择 "OneBot v11"

3. 填写：

- ID: 任意标识

- 启用: 勾选

- 反向 WS 主机地址: 0.0.0.0

- 反向 WS 端口: 6199（默认）

4. 点击保存

步骤二：部署并配置 NapCat

# Linux 一键安装 NapCat

# 参考官方文档使用一键脚本安装

# 安装完成后，进入 NapCat WebUI（默认 6099 端口）

# 网络配置 → 新建 → WebSocket 客户端

# URL: ws://127.0.0.1:6199/ws

# 心跳间隔: 1000ms

# 重连间隔: 1000ms

# 保存

步骤三：验证连接

前往 AstrBot WebUI → 数据 → 日志，如果出现 "aiocqhttp(OneBot v11) 适配器已连接" 的蓝色日志，说明连接成功。如果出现 "适配器已被关闭" 则为连接超时，请检查网络和端口配置。

💡 重要：建议在部署前预先安装 ffmpeg（并确保支持 amr 格式），否则媒体类文件可能无法正常收发。

八、使用插件

插件是 AstrBot 生态的核心。社区已有超过 1000 个插件可供安装使用，涵盖娱乐、工具、管理、自动化等各个领域。

管理插件有三种方式：

方式	说明
WebUI 插件市场	在管理面板 → 插件中浏览官方插件市场，一键安装。
CLI 命令	使用 astrbot plug install <插件名> 安装，astrbot plug remove <插件名> 卸载。
手动安装	通过 URL 或上传 ZIP 文件安装社区插件。

常用插件管理命令：

astrbot plug list # 查看已安装插件

astrbot plug search <关键词> # 搜索插件

astrbot plug install <插件名> # 安装插件

astrbot plug update [插件名] # 更新插件（不指定则全部更新）

astrbot plug remove <插件名> # 删除插件

astrbot plug new <插件名> # 基于模板创建新插件

💡 注意：由于插件更新机制，AstrBot 团队无法完全保证插件市场中插件的安全性，请自行甄别。

九、高级功能简介

9.1 MCP 工具集成

AstrBot 支持 Model Context Protocol（MCP），这是 Anthropic 推出的开放标准，用于 LLM 与外部工具之间的通信。通过 MCP，你可以让 AstrBot 直接调用外部 API、查询数据库、操作文件系统等。

例如，你可以为机器人配置一个「天气查询」MCP 工具，当用户询问天气时，机器人自动调用真实的天气 API 获取数据，而不是依赖模型训练数据中的过时信息。

9.2 知识库

AstrBot 内置了基于 RAG（检索增强生成）的知识库功能。你可以上传 PDF、Word、TXT 等文档，将其转换为向量嵌入存储。当用户提问时，系统会先从知识库中检索相关片段，再交给 LLM 生成回答，从而实现基于私有文档的精准问答。

适用场景包括：企业内部 FAQ、产品手册智能问答、学术论文辅助阅读等。

9.3 SubAgent 编排

SubAgent 是 AstrBot 的高级编排能力，允许你将一项复杂任务拆解为多个子 Agent 协同执行。每个子 Agent 可以拥有独立的指令、模型配置和工具集，它们并行或按序工作，最终由主 Agent 汇总结果。

例如，一个「市场调研报告」任务可以拆解为：信息搜集 Agent（搜索并整理资料）、数据分析 Agent（处理数据表格）、报告撰写 Agent（生成最终报告）。三个子 Agent 各司其职，大幅提升复杂任务的处理质量。

十、常见问题与技巧

问题	解决方案
忘记 WebUI 密码怎么办？	删除 data/cmd_config.json 中 dashboard.password 键值对，重启后使用初始密码登录。
如何更新管理面板？	在 AstrBot 中执行 /dashboard_update 指令（管理员权限），或手动下载 dist.zip 替换 data/dist 目录。
Docker 部署后无法访问管理面板？	Docker 隔离了网络，需要通过宿主机 IP 访问，不能使用 localhost。检查端口映射和防火墙放行。
如何开启 DEBUG 日志？	在 WebUI 配置文件 → 系统配置中开启控制台 DEBUG 日志级别。
插件加载失败怎么办？	管理面板会显示错误信息，并提供「一键重载修复」按钮，可在修复环境后快速重载，无需重启程序。
国内用户拉取 Docker 镜像慢？	使用 DaoCloud 镜像加速：将 soulter/astrbot 替换为 m.daocloud.io/docker.io/soulter/astrbot。