AstrBot：开源一站式 AI Agent 聊天机器人平台完全指南

目标读者：想搭建 IM 平台机器人的开发者、AI 应用实践者 前置知识：命令行基础、Python 入门、了解聊天机器人概念 预计阅读时间：25 分钟 核心价值：一个项目搞定所有主流 IM 平台的 AI 聊天机器人

一句话理解 AstrBot

AstrBot（AstrBotDevs/AstrBot，28.4k Stars）是把 AI 对话能力接入所有主流聊天平台的开源解决方案。它的核心逻辑是：

你选平台 → 配置模型 → 装插件 → 对接用户

不需要为每个平台单独开发，AstrBot 统一处理所有 IM 协议的接入，让你在 15+ 平台上同时拥有 AI 对话能力。

为什么值得关注：

• 一个项目支持 QQ、微信、Telegram、飞书、钉钉、Discord 等 15+ 平台
• 支持 OpenAI、Claude、Gemini、本地模型等所有主流 LLM
• 1000+ 社区插件，涵盖图像生成、日程管理、办公等场景
• 内置 Agent Sandbox，在隔离环境中安全执行代码
• 支持多语言，中文文档完善

核心数据一览

工作原理

AstrBot 采用分层架构：

┌─────────────────────────────────────────────────────┐
│                     用户视角                          │
│  QQ / 微信 / Telegram / 飞书 / Discord / ...       │
└─────────────────────┬───────────────────────────────┘
                      │ 各平台协议
┌─────────────────────▼───────────────────────────────┐
│              AstrBot 核心引擎                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │ LLM     │  │ Agent   │  │ Plugin  │           │
│  │ 对话    │  │ 任务执行 │  │ 扩展    │           │
│  └─────────┘  └─────────┘  └─────────┘           │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐           │
│  │ MCP     │  │ RAG     │  │Sandbox  │           │
│  │ 协议    │  │ 知识库  │  │ 沙箱   │           │
│  └─────────┘  └─────────┘  └─────────┘           │
└─────────────────────┬───────────────────────────────┘
                      │ API 调用
┌─────────────────────▼───────────────────────────────┐
│           LLM 提供商（可选）                         │
│  OpenAI / Anthropic / Gemini / Ollama / ...       │
└─────────────────────────────────────────────────────┘

核心模块职责：

• LLM 对话：统一接入各模型，处理多轮对话和上下文
• Agent 引擎：拆解任务、调用工具、执行多步骤操作
• 插件系统：通过插件扩展功能，1000+ 社区插件可用
• MCP 协议：连接外部数据源和服务
• RAG 知识库：基于文档的检索增强生成
• Agent Sandbox：隔离环境执行代码，防止恶意操作

支持的聊天平台

官方支持平台

社区支持平台

Matrix、KOOK、VoceChat 由社区维护。

支持的模型服务

语言模型（LLM）

OpenAI 系列、Anthropic Claude 系列、Google Gemini、Moonshot AI（月之暗面）、智谱 AI、DeepSeek 系列、Ollama（本地模型）、LM Studio（本地模型）等。

语音服务

• STT（语音转文字）：OpenAI Whisper、SenseVoice
• TTS（文字转语音）：OpenAI TTS、Google Gemini TTS、Edge TTS、阿里云百炼 TTS、火山引擎 TTS、MiniMax TTS、GPT-Sovits 声音克隆

LLMOps 平台

Dify、阿里云百炼、Coze 扣子。

安装与部署

方式一：uv 一键部署（推荐新手）

# 1. 安装 uv（如果还没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 安装 AstrBot
uv tool install astrbot

# 3. 初始化配置
astrbot init

# 4. 启动
astrbot run

注意：macOS 用户首次运行可能需要 10-20 秒启动时间。

方式二：Docker 部署（生产环境推荐）

# 下载 docker-compose 配置
git clone https://github.com/AstrBotDevs/AstrBot.git
cd AstrBot

# 启动
docker-compose up -d

访问 http://your-server:20080 打开管理界面。

方式三：云端一键部署

适合不想管理服务器的用户：

部署到 RainYun

方式四：桌面应用

适合主要使用 ChatUI 的桌面用户：

下载 AstrBot Desktop

方式五：Launcher 部署

适合需要快速部署和多实例隔离的用户：

下载 AstrBot Launcher

其他部署方式

快速配置指南

配置 LLM 提供商

启动后，在管理界面（通常是 http://localhost:20080）配置 API Key：

1. 打开管理界面 → 设置 → LLM 配置
2. 选择提供商（OpenAI / Anthropic / Gemini / Ollama 等）
3. 填入 API Key 和模型名称
4. 保存并测试连接

Ollama 本地模型配置示例：

llm:
  provider: ollama
  model: llama3.3:latest
  base_url: http://localhost:11434

配置 Telegram Bot

1. 在 Telegram 找 @BotFather，发送 /newbot 创建机器人
2. 复制获得的 Bot Token
3. 在 AstrBot 管理界面 → 渠道 → Telegram → 填入 Token → 启用

配置 Agent Sandbox

sandbox:
  enabled: true
  max_memory_mb: 512      # 最大内存
  timeout_seconds: 30      # 执行超时时间

Sandbox 允许 AI 安全地执行代码和 Shell 命令，不会影响宿主机安全。

核心功能详解

1. 多平台统一对话

AstrBot 最大的价值是一个后端服务，多个平台同时响应。你在 Telegram 配置的 Bot 和在 Discord 配置的 Bot，共享同一套 AI 配置和插件系统。

用户无论从哪个平台发送消息，都会得到一致的服务体验。

2. Agent 能力

AstrBot 不只是问答机器人，它能执行多步骤任务：

用户：帮我查一下北京的天气，然后发一条 Slack 消息告诉团队

AstrBot 内部：
1. 调用天气 API 查询北京天气
2. 格式化消息内容
3. 调用 Slack API 发送消息
4. 将结果汇总回复用户

3. 插件系统

1000+ 社区插件覆盖各种场景：

安装插件：

astrbot plugin install <plugin-name>

或在管理界面搜索安装。

4. 知识库（RAG）

上传文档（PDF、Word、Markdown 等），AstrBot 会自动分块、向量化存储。当用户提问时，检索相关内容作为上下文注入，提升回答准确度。

5. MCP 协议支持

MCP（Model Context Protocol）允许 AstrBot 连接外部服务：

• 读取 GitHub Issues
• 查询数据库
• 发送 Slack 消息
• 更多第三方集成

6. 人格与角色

• 自定义人格：设定 AI 的性格、语气、专长
• 角色扮演：支持情感陪伴、角色扮演模式
• 上下文压缩：长对话自动压缩，保持响应速度

实际使用示例

示例一：搭建 Telegram AI 助手

目标：让团队在 Telegram 里直接问 AI 问题

步骤：

1. 创建 Telegram Bot，获取 Token
2. 安装 AstrBot 并启动
3. 配置 Telegram 渠道和 LLM
4. 在群里 @机器人 开始对话

效果：

团队成员：@mybot 帮我翻译这段英文文档
[AstrBot 回复翻译结果]

团队成员：@mybot 用这个功能写一封道歉邮件
[AstrBot 生成邮件草稿]

示例二：搭建企业微信客服

目标：用 AI 回答用户常见问题

步骤：

1. 配置企业微信应用
2. 上传产品文档到知识库
3. 开启 RAG 增强
4. 设置自动回复规则

示例三：多平台同步通知

目标：一个命令，向所有平台发送通知

# 假设插件支持多平台广播
astrbot broadcast "系统维护通知：今晚 22:00 停机"

项目结构

AstrBot/
├── astrbot/           # 核心 Python 包
├── dashboard/          # Vue.js Web 管理界面
├── docs/              # 项目文档
├── k8s/               # Kubernetes 部署配置
├── changelogs/         # 更新日志
├── samples/            # 示例配置
├── scripts/            # 辅助脚本
├── tests/              # 测试代码
└── openspec/           # 开放规范

核心文件：

硬件要求

如果使用本地模型（Ollama），需要额外显存支持。

常见问题

Q1：AstrBot 和 OpenClaw 有什么区别？

选 AstrBot：你已经明确要接入特定 IM 平台 选 OpenClaw：你需要更通用的 Agent 能力

Q2：支持私有部署吗？

支持。通过 Ollama 或 LM Studio，可以完全本地运行，不依赖任何外部 API。

Q3：如何更新 AstrBot？

# uv 安装的更新
uv tool upgrade astrbot

# Docker 安装的更新
docker pull soulter/astrbot:latest
docker-compose up -d

Q4：支持中文吗？

支持。官方提供简体中文、繁体中文、日语、法语、俄语等多语言 README 和文档。

Q5：遇到问题怎么获取帮助？

• 官方文档：https://astrbot.app/
• GitHub Issues：https://github.com/AstrBotDevs/AstrBot/issues
• QQ 群：多个中文群组（详见 GitHub README）
• Discord：https://discord.gg/hAVk6tgV36

总结

核心优势

适用场景

相关资源

文档版本 1.1 | 更新日期：2026-03-31 | 基于 v4.22.2 | Stars: 28.4k ⭐