AstrBotDevs/AstrBot · 上手攻略

仓库：AstrBotDevs/AstrBot
链接：https://github.com/AstrBotDevs/AstrBot
分类：agent / llm-infra
作者：Jay
更新：2026-07-09

它是什么

AstrBot 是一个开源的 AI Agent 助手与开发框架，核心特点是将主流即时通讯平台（IM）与大语言模型深度集成。它的定位是「All-in-One Agent 聊天平台」+ OpenClaw 替代方案。

换句话说：你有 QQ、微信、Telegram 同时在线，AstrBot 可以让你的 AI Agent 同时在所有这些平台上跟你对话，还能接插件、加知识库、配 MCP，完全不需要自己折腾 IM Bot 申请和 API 对接。

⚠️ 环境要求：AstrBot 依赖 uv（Astral 出的 Python 包管理器）来安装和运行。macOS 用户首次运行 astrbot 命令时，因系统安全检查，启动可能需要 10-20 秒。

解决什么问题

痛点	传统方案	AstrBot
想在 QQ/微信/Telegram 里跑 AI Agent	各自申请 Bot、装 SDK、配 webhook	一套框架全部搞定
Agent 跑代码/Shell 有安全风险	手动隔离或干脆不跑	Agent Sandbox 隔离执行
想用 1000+ 插件	一个个找、装、配	一键安装社区插件
想接 Dify/Coze 等平台	各自对接	内置兼容层
想有知识库检索能力	自己搭 RAG	内置 Knowledge Base

快速安装

前置要求

Python 3.12（必须）
uv 包管理器：pip install uv

uv 一键部署（推荐给命令行用户）

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

# 首次初始化（仅首次运行执行）
astrbot init

# 启动
astrbot run

# 更新
uv tool upgrade astrbot --python 3.12

Docker 部署（推荐给服务器运维）

# 拉取镜像
docker pull astrbotdevs/astrbot

# 运行
docker run -d -p 8000:8000 \
  -v ./data:/app/data \
  --name astrbot \
  astrbotdevs/astrbot

访问 http://localhost:8000 进入 WebUI。

RainYun 云部署（不想管服务器）

官方推荐使用 RainYun 一键云端部署（适合零服务器经验用户）：

https://app.rainyun.com/apps/rca/store/5994

核心功能与用法

多平台 IM 接入

AstrBot 支持同时接入多个 IM 平台，配置一次，全平台同步对话：

QQ（OneBot 协议）
企业微信（WeChat Work）
飞书（Lark/Feishu）
钉钉（DingTalk）
微信公众号 / 小程序
Telegram
Discord
Slack
以及更多……

配置通过 WebUI 完成，无需写代码。

Agent 类型

AstrBot 内置三种 Agent 形态：

Role-playing & Emotional Companion：角色扮演、情感陪伴，适合做 AI 虚拟角色。
Proactive Agent：主动出击型，主动发消息、推进任务，不只是被动回复。
General Agentic：通用型，执行工具调用、MCP、代码执行等。

MCP 支持

内置 MCP（Model Context Protocol）客户端，可接入各种 MCP Server 扩展工具能力。

插件系统

1000+ 社区插件，支持一键安装。涵盖：图片生成、数据处理、搜索工具等。

Agent Sandbox

在隔离环境中安全执行代码和 Shell 命令，不会污染主进程，也不会因为恶意代码造成安全问题。适合让 Agent 自主执行 Python 脚本、Shell 命令等。

WebUI + Web ChatUI

WebUI：可视化后台管理面板，配置 Agent、插件、IM 连接。
Web ChatUI：直接在浏览器里聊天，内置 Agent Sandbox 和网页搜索。

LLM 接入

支持 OpenAI、Anthropic（Claude）、Gemini、阿里云通义千问等多种大模型。可同时接入多个模型，根据场景切换。

知识库（Knowledge Base）

内置 RAG 知识库功能，上传文档后 Agent 可基于私域知识回答问题。

与 Dify / Coze 集成

支持接入 Dify、阿里云百炼、Coze 等平台的工作流和 Agent，扩展能力边界。

典型适用场景

1. 自托管 AI 客服：在企业微信/飞书/钉钉里接入 AI 客服机器人，7×24 响应客户咨询。

2. 多平台 AI 助手：同时在 QQ、Telegram、微信里跑同一个 Agent，不同平台用户统一体验。

3. 角色扮演 / 情感陪伴 Bot：利用 Role-playing Agent 类型，快速搭建 AI 虚拟角色，部署到 IM 平台。

4. 开发者 Agent：配合 Agent Sandbox，在对话中安全执行代码、Shell 命令，做技术问答或自动化脚本执行。

5. 企业知识库问答：上传内部文档，在 IM 里直接问 AI，私有知识 + 即时通讯。

坑与注意

必须用 uv 安装：AstrBot 不支持普通 pip 直接安装，必须先装 uv。这是因为项目依赖管理基于 uv 的工具链设计。
macOS 首启延迟：约 10-20 秒是正常现象（系统安全检查造成），不是 bug，多次运行后恢复正常。
AGPL-3.0 许可证：若基于 AstrBot 开发并提供网络服务，需要开源你的衍生代码。评估是否符合你的使用场景。
IM 平台政策风险：微信/QQ 等平台对机器人有严格政策，商业使用需注意平台条款，有封号风险。Telegram 和 Discord 对 Bot 相对友好。
Python 3.12 硬性要求：不支持更低版本，确保环境为 Python 3.12+。
部分功能依赖付费 API：如 Whisper 音频转录需要 Groq 免费 Key（官方推荐），知识库功能需合理配置 Embedding 模型。
配置较复杂：多平台同时接入的配置项较多，建议先在 Docker 环境熟悉，再上生产。

与同类对比

工具	许可证	IM 平台数	MCP	Sandbox	定位
AstrBot	AGPL-3.0	9+	✅	✅	IM + Agent 全家桶
OpenClaw	私有	有限	✅	✅	Coding Agent
LobeHub	Community License	9+（IM Gateway）	✅	❌	Agent 团队管理
NoneBot2	Apache-2.0	主要是 QQ	插件式	❌	Python 机器人框架

AstrBot 的核心优势是IM 平台集成深度 + 零配置接入 + Agent 能力全家桶，而 OpenClaw 更偏向 Coding 场景。如果你需要一个「在各种聊天工具里跑 AI」的方案，AstrBot 是当前最接近开箱即用的选择。

一句话推荐结论

如果你想让 AI Agent 跑在 QQ、微信、Telegram 这些国内主流 IM 平台里，同时还需要 MCP 扩展、代码沙盒和知识库，AstrBot 是目前最完整的开源方案——装好 uv 之后三命令就能跑起来，值得一试。

参考来源

GitHub：https://github.com/AstrBotDevs/AstrBot
文档站：https://docs.astrbot.app
官方 README（多语言版）
trendshift.io：https://trendshift.io/repositories/21369