フレームワーク

AstrBot徹底解剖:6つのIM×複数LLM×プラグインを束ねる开源フレームワークの実装と判断

QQ・微信・飛書・Telegram・Discord・Slackを1つのBotで束ね、複数LLMの切り替えとPythonプラグイン加载に対応した开源フレームワーク。3.9万スターのAstrBotをアーキテクチャと実装面から読み解く。

文字サイズ

AstrBot は GitHub で 39,419 スターを獲得している开源プロジェクトで、その立ち位置は明快だ。1つの Bot プログラムで QQ・微信・飛書・Telegram・Discord・Slack を同時接続し、複数社の LLM を回し、Python プラグインを読み込む。

ソースを読み込み、プラグインを書き、Docker で走らせる数日を経てみた。以下は実装寄りの視点で分解した記録である。


何の問題を解くのか

個人開発者が LLM を IM に組み込もうとすると、三つの落とし穴が待ち受けている。

  1. プロトコルがバラバラ。QQ 公式 Bot は WebSocket + OAuth、微信は WeChat Work コールバックまたは iPad/PC プロトコル、飛書は OpenAPI、Telegram は Bot API と方式が異なり、それぞれで送受信・認証・ハートビートを別個に書く羽目になる。
  2. LLM Provider を切り替えるたびにコード修正が必要。OpenAI から DeepSeek に変えれば base_url と SDK を差し替え、Claude を追加するなら別系統の実装、アンソロピックからローカル Ollama に移ればさらにメッセージ形式の差分を吸収する必要がある。
  3. Agent のツール呼び出しは自前実装が前提。LLM に外部 API を叩かせ、function calling プロトコルをさばき、コンテキストウィンドウを管理し、メッセージをルーティングする——これら一式を自分で組み立てる必要がある。

AstrBot のアプローチは、この三層を1つのフレームワークに閉じ込めることだ。Bot のロジックは一度だけ書けば、あらゆるプラットフォームで動く。

同じ思想の开源プロジェクトは他にもあるが、多くは層の一部分しかカバーしていない。

  • NoneBot2:純粋なチャットフレームワークで LLM は扱わない
  • Koishi:プラグイン生態系は強力だが AI 機能は薄い
  • LangChain / LangGraph:Agent オーケストレーション寄りで IM 适配は対象外

AstrBot は「AI Agent + マルチプラットフォーム」という中間の路線を取っている。


使い方

最小構成は Docker 1行でサービスが立ち上がる。

docker run -d --name astrbot -p 6185:6185 -v /data/astrbot:/data/astrbot soulter/astrbot:latest

コンテナ起動後 http://localhost:6185 にアクセスし、Web 管理画面に入る。設定ファイルに QQ / 微信 / Telegram の認証情報を書き込み、LLM Provider に DeepSeek か OpenAI を選び、コンテナを再起動すれば運用開始できる。

以下は実際に動作するプラグインのサンプルである(公式 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() で元プラットフォームにそのまま返送する。今 QQ なのか飛書なのかを気にする必要はない。

プラグインマーケットは Web 管理画面から直接ブラウズしてインストールできる。pip でパッケージを入れる感覚で、UI 化された体験になっている。


アーキテクチャの内部

AstrBot のコード構成は三層になっている。

1. プラットフォーム适配層

IM プラットフォームごとに adapter が astrbot/core/platform/ 配下に置かれている。

  • qq_official.py(QQ 公式 Bot)
  • wechat.py(微信 / WeChatPad)
  • lark.py(飛書)
  • telegram.py
  • discord.py
  • slack.py

各 adapter はプロトコル握手、送受信、イベント回调を担うが、外側に出すのは統一された PlatformEvent オブジェクト——メッセージ種別、送信者、グループ/個人チャット、@メンションといったフィールドが正規化済みである。

2. コア调度層

メッセージルーティング、コンテキスト管理、LLM Provider 抽象を担当する。

  • メッセージルーティング:受信メッセージをプラグインコマンド・LLM 対話・パススルーのいずれかに振り分ける。
  • コンテキスト管理:セッションごとに会話履歴を保持し、トークン数カウント、コンテキストウィンドウの切り詰め、複数ターンの記憶に対応する。
  • LLM Provider 抽象:OpenAI 互換プロトコル(base_url + api_key + model)を統一仕様として扱い、DeepSeek・OpenAI・Azure OpenAI・Moonshot・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 で大規模モデルを回す際の VRAM 管理やストリーミング最適化は「動く」レベルであり、「最高に動く」レベルではない。
  • 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 バッジで動的に表示される。
  • Docker pull 数:Docker Hub のバッジから確認可能で、コミュニティ活性度の客観指標になる。

メッセージの文字数を数えるだけの簡単なプラグインを書いてみたところ、ドキュメントを読んでから稼働まで 20 分で済んだ。宣言的登録とホットリロードの二つの設計が時間を大幅に節約してくれる——コード修正後も Bot を止めずに済む。


どんな人に向くか

向いているケース

  • 公众号 / 微信グループ / 飛書グループに AI アシスタントを掛けたい運用担当
  • 個人 AI アシスタントを素早く立ち上げたい独立開発者
  • 中小規模チームの社内 Bot(ナレッジベース Q&A、值班リマインド、グループ Bot など)

向かないケース

  • 厳密な権限分離が必要なエンタープライズ用途——自前開発か、飛書内蔵の智能伙伴・企微の腾讯元宝のような商用 IM Bot プラットフォームを推奨。
  • Telegram 単一プラットフォームで十分な軽量ユーザー——python-telegram-bot を直接使うほうがシンプルで、抽象層を一つ減らせる。
  • 高頻度取引 / 金融系シナリオ——IM プロトコルの安定性、メッセージ遅延、到達率のいずれも十分ではなく、メッセージロスは致命的。

総括

AstrBot は「マルチプラットフォーム + LLM Agent」という中間の路線における、 pragmatic な選択肢である。LangChain ほど複雑な Agent オーケストレーション機能は持たず、エンタープライズ IM Bot のようなコンプライアンス対応能力もないが、Python 開発者なら 20 分で 6 プラットフォーム対応の AI Bot を立ち上げられるという実用性を備えている。

3.9 万スターと活況なプラグインマーケットは、この立ち位置に需要があることを証明している。次に注目すべき進化の方向は、プラグインサンドボックスと権限モデルの強化だろう。それが「個人プロジェクト」から「チーム标配」への越えなければならない敷居である。

ソース:github.com/AstrBotDevs/AstrBot

出典:https://github.com/AstrBotDevs/AstrBot

出典: https://github.com/AstrBotDevs/AstrBot