AstrBot 是什麼
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 萬星與活躍的插件市集已證明這個定位確實有人需要。下一個值得關注的演進方向是把插件沙箱與權限模型做厚——這是它從「個人專案」走向「團隊標配」的門檻。