ドキュメント · ガイド

AstrBot を任意のモデルで

AstrBot（AstrBotDevs/AstrBot）は QQ、Telegram、Discord、Lark などのプラットフォームにモデルをつなぐチャットボットフレームワークです。設定はすべて data/cmd_config.json 一つにあります。magpie はそこに OpenAI 互換の magpie ソースと magpie の各モデルの項目を加え、選んだものを AstrBot の既定のチャットモデルにします。そのためボットで magpie のすべてのモデル（DeepSeek、GLM、Kimi、Qwen、OpenAI や Anthropic のキー、ChatGPT や Copilot のサブスクリプション）が、AstrBot の WebUI にキーを入れずに使えます。

AstrBot の設定

  1. AstrBot を一度起動する最初の起動で data/cmd_config.json が書かれます。4.10 以降（provider_sources のある設定）が必要です。
  2. magpie にプロバイダーを追加プロバイダー ページで API キーを追加するか、サブスクリプションにサインインします。
  3. AstrBot の行でモデルを選ぶエージェント ページで AstrBot に magpie のモデルを選びます。
  4. AstrBot を再起動するAstrBot は起動時にだけ設定を読みます。再起動するとボットが新しいモデルを使います。
ターミナル
magpie astrbot deepseek/deepseek-v4-pro
# そのあと AstrBot を再起動

magpie は AstrBot のルートをこの順で探します：ASTRBOT_ROOT、デスクトップ版の ~/.astrbot、astrbot init を実行したフォルダー（ホーム、~/astrbot、~/AstrBot。README とソースのクローンが置く場所）。ほかの場所で動かす AstrBot は、ASTRBOT_ROOT をそのフォルダーにして magpie を起動してください。

cmd_config.json に書かれるもの

4.10 から AstrBot はチャットプロバイダーを二つのリストに分けます。provider_sources はエンドポイントとキー、provider の各項目はあるソースのモデル一つです。magpie は id magpie のソース（OpenAI Compatible、ゲートウェイの /v1、AstrBot と分かるキー付き。そのため magpie の使用量で AstrBot の分として数えられます）と、各モデルの項目 magpie/<プロバイダー>/<モデル> を加え、agent_runner.config.model.provider_id を選んだものにします（agent_runner 以前のファイルでは provider_settings.default_provider_id）。

ターミナル
// /data/cmd_config.json
{
  "provider_sources": [
    …,
    {"id": "magpie", "provider": "openai", "type": "openai_chat_completion",
     "provider_type": "chat_completion", "enable": true,
     "key": ["…"], "api_base": "http://127.0.0.1:3425/v1", …}
  ],
  "provider": [
    …,
    {"id": "magpie/deepseek/deepseek-v4-pro", "provider_source_id": "magpie",
     "model": "deepseek/deepseek-v4-pro",
     "modalities": ["text", "tool_use"], "max_context_tokens": …}
  ],
  "agent_runner": {"runner_type": "local",
    "config": {"model": {"provider_id": "magpie/deepseek/deepseek-v4-pro"}}}
}

どのモデルにも tool_use が付きます。ないと AstrBot はモデルのツールを外しますが、ゲートウェイはどのモデルでもツール呼び出しを渡せます。画像は magpie が知るそのモデルの対応どおりに付きます。magpie がコンテキストウィンドウを知らないときは 0 で、AstrBot が自分で調べます。

再起動が要る理由

AstrBot は起動時にファイル全体をメモリに読み、WebUI は保存のたびにファイル全体を書き戻します。そのため magpie の変更には AstrBot の再起動が要り、再起動前に WebUI で保存すると上書きされます。magpie のチェックは magpie のソースが消えたことに気づき、接続し直すよう知らせます。

agent_runner.runner_type が local でないとき（外部のエージェントランナー）は、AstrBot はチャットモデルを使わず、magpie のチェックもそう知らせます。

自分の設定

最初に書く前に、magpie はファイルを cmd_config.json.before-magpie にコピーします。自分のソースとモデルはバイト単位でそのままで、WebUI で magpie の項目に加えた変更（ソースの timeout や proxy、モデルのオフ、extra body）も残ります。/provider で一つのチャットに選んだモデルは AstrBot 自身のデータベースにあり、そのままです。AstrBot は UTF-8 BOM 付きでファイルを書き、magpie もそれを保ちます。

Docker の AstrBot

Docker の AstrBot は magpie がつなぐ対象ではありません。data フォルダーは magpie が知らないボリュームで、このマシンのループバック上のゲートウェイはコンテナのものではないからです。

元に戻す

magpie で行を既定に戻すと、magpie のソースとモデルを外し、既定のチャットモデルを接続前のものに戻します（その後 AstrBot で別のものを選んでいれば、それが残ります）。自分のモデルを選ぶこともでき、magpie のモデルは切断するまでリストに残ります。どちらのあとも AstrBot を再起動してください。

ターミナル
magpie astrbot default
# そのあと AstrBot を再起動

よくある質問

AstrBot で DeepSeek、GLM、Kimi、Qwen は使えますか？

使えます。magpie が cmd_config.json に OpenAI 互換の magpie ソースと各モデルの項目を加え、選んだものを既定のチャットモデルにします。AstrBot を再起動すると使えます。

ボットが前のモデルのままです。

AstrBot は起動時にだけ cmd_config.json を読むので、再起動してください。その前に WebUI で保存すると magpie の変更が上書きされます。

magpie のソースが消えました。

WebUI の保存がファイル全体を書き戻したためでしょう。magpie で AstrBot をもう一度接続し、AstrBot を再起動してください。

Docker の AstrBot でも使えますか？

自動ではつなぎません。magpie はコンテナのデータボリュームを知らず、このマシンのループバックはコンテナのものではありません。

同じモデルを他のエージェントでも：nanobot を任意のモデルで、QwenPaw を任意のモデルで、OpenClaw を任意のモデルで、magpie で Cherry Studio にすべてのモデルを。エラーが出るときは よくあるエラーの直し方、または Discord で質問してください。