AstrBot は GitHub で 39,419 スターを獲得している开源プロジェクトで、その立ち位置は明快だ。1つの Bot プログラムで QQ・微信・飛書・Telegram・Discord・Slack を同時接続し、複数社の LLM を回し、Python プラグインを読み込む。
ソースを読み込み、プラグインを書き、Docker で走らせる数日を経てみた。以下は実装寄りの視点で分解した記録である。
何の問題を解くのか
個人開発者が LLM を IM に組み込もうとすると、三つの落とし穴が待ち受けている。
- プロトコルがバラバラ。QQ 公式 Bot は WebSocket + OAuth、微信は WeChat Work コールバックまたは iPad/PC プロトコル、飛書は OpenAPI、Telegram は Bot API と方式が異なり、それぞれで送受信・認証・ハートビートを別個に書く羽目になる。
- LLM Provider を切り替えるたびにコード修正が必要。OpenAI から DeepSeek に変えれば base_url と SDK を差し替え、Claude を追加するなら別系統の実装、アンソロピックからローカル Ollama に移ればさらにメッセージ形式の差分を吸収する必要がある。
- 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.pydiscord.pyslack.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 万スターと活況なプラグインマーケットは、この立ち位置に需要があることを証明している。次に注目すべき進化の方向は、プラグインサンドボックスと権限モデルの強化だろう。それが「個人プロジェクト」から「チーム标配」への越えなければならない敷居である。