框架

AstrBot:把 LLM Agent 塞进微信 QQ 飞书的开源框架,3.9 万星的工程取舍

一个 Bot 同时接 6 个 IM 平台、跑多家 LLM、还能装插件——拆解 AstrBot 的多平台适配与 Agent 架构。

字号

AstrBot:把 LLM Agent 塞进微信 QQ 飞书的开源框架,3.9 万星的工程取舍

AstrBot 是 GitHub 上 39,419 stars 的开源项目,定位很直接:一个 Bot 程序,同时接入 QQ、微信、飞书、Telegram、Discord、Slack,跑多家 LLM,加载 Python 插件。

我花了几天读源码、写插件、跑 Docker。下面从工程视角拆它。


它解决什么问题

个人开发者想把 LLM 接入 IM,绕不开三重坑:

  1. 协议不统一。QQ 官方机器人用 WebSocket + OAuth,微信走企业微信回调或 iPad/PC 协议,飞书是 OpenAPI,Telegram 用 Bot API。每一个都要单独写一遍消息收发、鉴权、心跳。
  2. LLM Provider 切换要改代码。从 OpenAI 换到 DeepSeek,要换 base_url、改 SDK;想加 Claude 又是一套。从 Anthropic 切到本地 Ollama,还要处理不同消息格式。
  3. Agent 工具调用得自己造轮子。让 LLM 调用外部 API、处理 function calling 协议、管理上下文窗口、做消息路由——这些都得自己撸。

AstrBot 的解法是把这三层封成一个框架。用户只写一次 Bot,跑在所有平台。

类似思路的开源项目不少,但大多数只覆盖其中一层:

  • NoneBot2:纯聊天框架,不带 LLM
  • Koishi:插件生态强,AI 能力偏弱
  • LangChain / LangGraph:偏 Agent 编排,不解决 IM 适配

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.py
  • discord.py
  • slack.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

来源: https://github.com/AstrBotDevs/AstrBot