概要
AstrBot はオープンソースのワンストップ AI エージェントチャットプラットフォームで、主要なインスタントメッセージングソフトウェアと統合されています。大規模言語モデルとの対話、プラグイン拡張、マルチモーダル、エージェントサンドボックス、ナレッジベースをサポートしており、個人やチームが AI アプリケーションを迅速に構築するのに適しています。
README プレビュー
\n\n\n\n\n简体中文 ｜\n繁體中文 ｜\n日本語 ｜\nFrançais ｜\nEspañol ｜\nРусский \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nDocumentation ｜\nBlog ｜\nRoadmap ｜\nIssue Tracker ｜\nEmail Support\n\n\nAstrBot is an open-source all-in-one Agent chatbot platform that integrates with mainstream instant messaging apps. It provides reliable and scalable conversational AI infrastructure for individuals, developers, and teams. Whether you're building a personal AI companion, intelligent customer service, automation assistant, or enterprise knowledge base, AstrBot enables you to quickly build production-ready AI applications within your IM platform workflows.\n\n\n\n## Key Features\n\n1. 💯 Free & Open Source.\n2. ✨ AI LLM Conversations, Multimodal, Agent, MCP, Skills, Knowledge Base, Persona Settings, Auto Context Compression.\n3. 🤖 Supports integration with Dify, Alibaba Cloud Bailian, Coze, and other agent platforms.\n4. 🌐 Multi-Platform: QQ, WeChat Work, Feishu, DingTalk, WeChat Official Accounts, Telegram, Slack, and [more](#supported-messaging-platforms).\n5. 📦 Plugin Extensions with 1000+ plugins available for one-click installation.\n6. 🛡️ [Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html) for isolated, safe execution of code, shell calls, and session-level resource reuse.\n7. 💻 WebUI Support.\n8. 🌈 Web ChatUI Support with built-in agent sandbox and web search.\n9. 🌐 Internationalization (i18n) Support.\n\n\n\n\n \n 💙 Role-playing & Emotional Companionship\n ✨ Proactive Agent\n 🚀 General Agentic Capabilities\n 🧩 1000+ Community Plugins\n \n \n \n \n \n \n \n\n\n## Quick Start\n\n### One-Click Deployment\n\n> [!NOTE]\n> Requires [uv](https://docs.astral.sh/uv/) to be installed.\n> For macOS users: due to macOS security checks, the first run of the `astrbot` command may take longer (about 10-20s).\n\nFor users who want to quickly experience AstrBot, are familiar with command-line usage, and can install a `uv` environment on the
FAQ (5)
トラブル対応AstrBotがQQ Official（qq_official）アダプターで重複したメッセージを受信し、複数回返信してしまうのはなぜですか？
これは AstrBot v4.19.2 の既知のバグです。原因：(1) qq_official アダプターが message_id に基づくメッセージの重複排除を備えていなかったため、QQ Official webhook のリトライ（Tencent は応答が確認できない場合、通知を最大3回再送する）が繰り返し処理されていました。(2) UI でアダプターを無効化した際にアダプターのイベントハンドラーがクリーンアップされず、再起動後に重複処理が発生していました。修正方法：AstrBot を最新バージョンにアップグレードしてください。PR #6320 で QQ Official webhook のリトライに起因する重複メッセージ処理が修正されました。旧バージョンでの一時的な回避策：Web UI でアダプターを切り替えるのではなく、AstrBot のプロセス/コンテナを完全に再起動し、アダプターの頻繁な有効化/無効化を避けてください。重複した返信は API のレート制限 BAN を引き起こす可能性があるため、アップグレードを強く推奨します。
トラブル対応AstrBot のバックグラウンドタスクまたはサブエージェントが完了しても、ユーザーにメッセージが届かず、警告ログも出力されない問題を修正するには？
影響を受けるバージョン: AstrBot 4.29.0-beta.1。バックグラウンドタスクのウェイクアップターンは通常のメッセージパイプラインをバイパスし、メインエージェントが send_message_to_user を呼び出した場合にのみ出力を配信します。以前の astrbot/core/astr_agent_tool_exec.py:662 にある警告は llm_resp が空の場合にのみ発火していたため、配信が試みられなかった通常のレスポンスは完全に検知されない状態でした。
修正方法: PR #10398 を含む AstrBot リリースにアップグレードしてください(issue #10395 を修正)。Windows デスクトップでは、AstrBotLauncher を通じて更新し、再起動してください。Git デプロイメントの場合:
cd AstrBot
git pull
# install/update dependencies as required by your deployment
# then restart AstrBot以下で修正を確認できます:
grep -n "_has_send_oper" astrbot/core/astr_agent_tool_exec.pyこの修正は、runner.step_until_done() と get_final_llm_resp() の後に cron_event._has_send_oper をチェックします。バックグラウンドタスクが結果を生成したにもかかわらず現在の会話に何も配信されなかった場合、AstrBot は task_id と tool_name を含む WARNING をログに記録するようになりました。このフラグは配信が成功した後にのみ設定されるため、送信の失敗や別セッションへの送信も検出されます。
モデルが意図的に応答しない場合があるため、自動再送信は追加されていません。配信を保証する必要がある場合は、_has_send_oper が false のときに llm_resp.completion_text を通常のレスポンスパス経由で送信するフォールバックを追加で実装する必要があります。これは動作を変更するものであり、慎重にテストする必要があります。
古いバージョンでの一時的な緩和策: 意味のある結果を持つバックグラウンドタスクが完了した際に必ず send_message_to_user を呼び出すようメインエージェントのプロンプトを強化するか、既存の if not llm_resp 分岐の近くに _has_send_oper の WARNING チェックを手動で追加してください。結果はエージェントの状態から失われるわけではなく、会話履歴に [BackgroundTask] ... Result: ... として永続化されますが、ユーザーには通知されません。
トラブル対応画像URLが C:\api\v1\files\tokens\... になってしまう場合に AstrBot で発生する「Model image preparation failed; skipping image (FileNotFoundError)」エラーの修正方法
この問題は AstrBot v4.28.1 に影響します。/api/v1/files/tokens/<token> のようなルート相対のプラグイン URL は URL として認識されません。MediaResolver は存在を確認せずにこれをローカルファイルとして扱うため、Windows では C:\api\v1\... に解決され、その後の読み取りが失敗して画像は警告なくスキップされます。
恒久的な修正方法：
1. issue #10264 向けの PR Fix/reject unresolvable image refs を含むリリースへ AstrBot をアップグレードしてください。フレームワークは、偽のローカルパスを返す代わりに、解決不可能なメディア参照を拒否するようになりました。
2. URL を生成するプラグイン（例：astrbot_plugin_qqwebui v1.1.0）を修正し、/ で始まるパスではなく絶対 HTTP URL を返すようにしてください：
image.url = f'{PUBLIC_BASE_URL.rstrip("/")}/api/v1/files/tokens/{token}'
# Example: http://127.0.0.1:6185/api/v1/files/tokens/<token>有効なメディア入力は、http(s)://...、存在するローカルファイルパス、file://...、data:...、または有効な Base64 です。
すぐにアップグレードできない場合は、astrbot/core/utils/media_utils.py 内の _materialize_media_ref() のフォールバック分岐を以下のように修正してください：
path = Path(media_ref)
if path.is_file():
return _LocalMediaFile(path=path, mime_type=_guess_mime_type(path))
raise ValueError(f'Unresolvable media reference: {media_ref}')変更後に AstrBot を再起動してください。古い会話履歴には無効な [Image Attachment: path ...] プレースホルダーが残っている可能性があります。引用画像や転送画像も同じコードパスを使用するため、それらも含めて新たに送信した画像でテストしてください。
トラブル対応astrbot_plugin_temp_chat_fix プラグインを削除した後、AstrBot のログにまだそのプラグインのエラーが表示されるのはなぜですか？どうすれば解決できますか？
これは、プラグインが main.py:52 で aiocqhttp の call_action にモンキーパッチを適用したものの、削除またはアンインストール時に terminate() で元に戻していなかったためです。AstrBot プロセスが実行中のままだと、メモリ内の bot オブジェクトが古いラッパー関数を保持し続けるため、コールスタックは削除されたプラグインのパスを指し続けます。解決策は AstrBot プロセスを完全に再起動することです。Docker デプロイの場合は docker restart <AstrBotコンテナ名> を実行し、ネイティブデプロイの場合はサービスを停止してから再起動してください。再起動後、data/plugins/astrbot_plugin_temp_chat_fix ディレクトリが削除されていることを確認してください。ログ中の retcode=100 と no such temp session は QQ の一時セッションが無効になっていることを示しており、ユーザーが一時セッションを再度開始する必要があります。これはプラグイン残留によるエラーとは別の問題です。別途 astrbot_plugin_temp_chat_fix リポジトリに報告し、作者に terminate() で call_action を元に戻すよう対応してもらってください。
トラブル対応要約モデルが HTTP 429 quota exhausted（クォータ枯渇）を返した後、メインのチャットモデルを切り替えても AstrBot が数分間ハングしてしまう問題を解決するにはどうすればよいですか？
AstrBot v4.28.2 では、コンテキストコンプレッサーが request_max_retries を指定せずに text_chat() を呼び出すため、プロバイダーは指数バックオフを伴うデフォルトの合計 5 回の試行を使用します。HTTP 429 はリトライされ、すべての試行が失敗するまで返信がブロックされます。メインモデルを切り替えても解決しません。停滞しているリクエストは、別途設定された要約モデルを使用しているためです。また、フォールバックは truncate_by_halving() を一度だけ呼び出すだけで、残りの履歴が収まるかどうかを再確認しません。
修正方法：PR #10436 を含む AstrBot ビルド（コミット 800fdcc 以降の master）にアップグレードしてください。この修正では、要約リクエストに request_max_retries=1 を渡します（1 は試行ゼロではなく、合計 1 回の試行を意味します）。その後、即座に切り捨てへフォールバックします。この修正は、先頭のシステムメッセージを保持し、残りの履歴を完全なラウンドに分割し、推定コンテキストが収まるまで最も古いラウンドを繰り返し削除し、最新のラウンドを保持し、ツール呼び出しとそのツール結果のペアを維持します。
v4.28.2 での一時的な回避策：
1. /new を実行して新しい会話を開始します。これにより返信が復旧することが確認されています。
2. 要約モデルのクォータ/API 認証情報を復旧するか、利用可能な要約モデルを設定します。
3. 利用できない要約モデルをすぐに修正できない場合は、独立した LLM コンテキスト圧縮を無効化します。
メインのチャットモデルだけを切り替えても要約モデルは変更されないため、回避策にはなりません。後でツール呼び出しを伴う API 側で確認されたコンテキストオーバーフローエラーに遭遇した場合は、issue #7225 のペア単位のレコード削除（record-pop）修正を含むビルドも使用してください。