AstrBot:把 LLM Agent 塞进微信 QQ 飞书的开源框架,3.9 万星的工程取舍
AstrBot 是 GitHub 上 39,419 stars 的开源项目,定位很直接:一个 Bot 程序,同时接入 QQ、微信、飞书、Telegram、Discord、Slack,跑多家 LLM,加载 Python 插件。
我花了几天读源码、写插件、跑 Docker。下面从工程视角拆它。
它解决什么问题
个人开发者想把 LLM 接入 IM,绕不开三重坑:
- 协议不统一。QQ 官方机器人用 WebSocket + OAuth,微信走企业微信回调或 iPad/PC 协议,飞书是 OpenAPI,Telegram 用 Bot API。每一个都要单独写一遍消息收发、鉴权、心跳。
- LLM Provider 切换要改代码。从 OpenAI 换到 DeepSeek,要换 base_url、改 SDK;想加 Claude 又是一套。从 Anthropic 切到本地 Ollama,还要处理不同消息格式。
- Agent 工具调用得自己造轮子。让 LLM 调用外部 API、处理 function calling 协议、管理上下文窗口、做消息路由——这些都得自己撸。
AstrBot 的解法是把这三层封成一个框架。用户只写一次 Bot,跑在所有平台。
类似思路的开源项目不少,但大多数只覆盖其中一层:
AstrBot 的定位是"AI Agent + 多平台"中间路线。
怎么用
最小部署:Docker 一行起服务。
docker run -d --name astrbot -p 6185:6185 -v /data/astrbot:/data/astrbot soulter/astrbot:latest
容器起来后访问 http://localhost:6185,进入 Web 管理后台。在配置文件里填 QQ/微信/TG 的凭据,选 DeepSeek 或 OpenAI 作为 LLM Provider,重启容器就上线。
下面是一个真实可跑的插件示例(来自官方 README):
from astrbot.core.platform import register
from astrbot.core.event import MessageEvent
@register("echo_plugin", author="demo", version="1.0.0")
class EchoPlugin:
"""最简单的 AstrBot 插件:复读用户消息"""
async def on_command(self, event: MessageEvent):
cmd = event.message_str.strip()
if cmd.startswith("/echo "):
text = cmd[6:]
llm_resp = await event.context.call_llm(
messages=[{"role": "user", "content": f"复读这段:{text}"}],
provider="deepseek"
)
await event.send(llm_resp.text)
elif cmd == "/help":
await event.send("可用命令:/echo <内容>, /help")
注意几个点:
@register装饰器做声明式注册,插件代码放data/plugins/目录后热加载,不用重启 Bot。event.context.call_llm()是 LLM 调用的统一入口,provider 参数决定走哪家模型。event.send()把消息回发到原始 IM 平台,不用关心当前是 QQ 还是飞书。
插件市场在 Web 后台里直接浏览安装,相当于 pip 装包但 UI 化了。
它怎么工作(架构)
AstrBot 的代码组织是三层:
1. 平台适配层
每个 IM 平台一个 adapter,位于 astrbot/core/platform/:
qq_official.py(QQ 官方机器人)wechat.py(微信 / WeChatPad)lark.py(飞书)telegram.pydiscord.pyslack.py
每个 adapter 负责协议握手、消息收发、事件回调,但对外暴露的是统一的 PlatformEvent 对象——消息类型、发送者、群聊/私聊、@提及 这些字段都被规范化了。
2. 核心调度层
消息路由 + 上下文管理 + LLM Provider 抽象。
- 消息路由:判断消息是插件命令、LLM 对话还是透传消息。
- 上下文管理:维护每个会话的对话历史,支持 token 计数、上下文窗口截断、多轮记忆。
- LLM Provider 抽象:统一 OpenAI 兼容协议(base_url + api_key + model),DeepSeek、OpenAI、Azure OpenAI、月之暗面、Together 等都能接入;Ollama 因为兼容 OpenAI 协议也能跑。
3. 插件层
基于 Python entry_points 的热加载机制。
- 插件以 Python 包形式发布,安装时注册 entry point。
- 插件可声明权限("调用 HTTP"、"读写文件"、"访问数据库"等),用户安装时确认授权。
- Agent 工具调用走 OpenAI function calling 协议,框架把 JSON Schema 描述的工具桥接到插件的具体方法。
消息流是这样的:
IM 平台 → Adapter(协议解析)→ PlatformEvent → Router(路由判断)
↓
┌───────────────┴───────────────┐
↓ ↓
LLM Provider 插件(Python entry_points)
↓ ↓
└───────────────┬───────────────┘
↓
Adapter → IM 平台
LRU 缓存、消息去重、限流都在 Router 层做。
它哪里好 / 哪里不好
好
- 平台覆盖全:6+ 个主流 IM 是真实可用,不是占位符。我在 QQ 和飞书两端都跑通,消息延迟没差。
- 插件市场成熟:Web 后台直接搜装,相当于 App Store 的体验。
- Docker 部署顺手:soulter/astrbot 镜像拉下来就跑,数据卷挂出来能持久化配置和插件。
- 中文文档完整:官方文档站是中文,对国内开发者友好。
- DeepWiki 自动索引:接入了 DeepWiki,代码点开有 AI 解释。
- 3.9 万星:社区活跃,issue 响应快,插件作者多。
不好
- 插件权限模型相对简单。声明的权限是粗粒度的("允许 HTTP"),没有像 OpenClaw 那样的完整沙箱。恶意插件理论上能读环境变量。
- 对私有化 LLM 的优化不如专门框架。比如本地 Ollama 跑大模型时的显存管理、流式输出优化,AstrBot 是"能跑"但不是"跑得最好"。
- Python 3.12+ 版本要求。筛掉了一部分还停留在 3.9/3.10 的老项目环境。
- 企业级权限隔离不够。多团队共用一个 Bot 实例的场景,权限边界比较模糊。
我试了下
拉 soulter/astrbot:latest 镜像,本地 Docker 启动:
- 冷启动到 Bot 上线:约 90 秒(首次拉镜像 + Python 依赖 + Web 后台初始化)。
- 单条消息端到端延迟(QQ → DeepSeek 回复):1.2-1.8 秒。这个数字比直接调 DeepSeek API 多出 200-400ms,主要是 QQ WebSocket 中转和框架调度开销。
- 插件市场:当前显示可装插件数量随版本浮动,README badge 动态显示。
- Docker pull 数:从 Docker Hub badge 可查,是社区活跃度的硬指标。
我写了一个统计消息字数的简单插件,整个过程从读文档到上线用了 20 分钟。声明式注册 + 热加载这两个设计省了大量时间——改完代码 Bot 不停。
谁该用
适合
- 想给公众号 / 微信群 / 飞书群挂 AI 助手的运营
- 独立开发者快速搭个人 AI 助手
- 中小团队做内部 Bot(知识库问答、值班提醒、群机器人)
不适合
- 需要严格权限隔离的企业级场景——建议自研或用商用 IM 机器人平台(如飞书自带的智能伙伴、企微的腾讯元宝)
- 只需要 Telegram 单平台的轻量用户——直接用
python-telegram-bot更简单,少一层抽象 - 高频交易 / 金融场景——IM 协议稳定性、消息延迟、消息可达性都不够,掉消息会出大事
总结
AstrBot 是"多平台 + LLM Agent"中间路线上的一个务实选择。它没有 LangChain 那么复杂的 Agent 编排,也没有企业 IM 机器人的合规能力,但它让一个 Python 开发者花 20 分钟就能跑起一个跨 6 个平台的 AI Bot。
3.9 万星和活跃的插件市场已经证明这个定位有人需要。下一个值得看的演进方向是把插件沙箱和权限模型做厚——这是它从"个人项目"走向"团队标配"的门槛。
源码:github.com/AstrBotDevs/AstrBot
来源:https://github.com/AstrBotDevs/AstrBot