ドキュメント · ガイド

はじめに

magpie は、各エージェントが使うモデルを一か所で選べるツールです。手持ちのプロバイダを追加し、エージェントごとにモデルを選ぶと、magpie がそのエージェント自身の設定に書き込みます。

その裏では、小さなゲートウェイがあなたのマシンの 127.0.0.1:3425 で動いています。OpenAI、Anthropic、Gemini の API を話し、ストリーミングやツール呼び出しも含めて相互に変換するので、どのエージェントでもどのプロバイダのモデルでも使えます。たとえば ChatGPT プランの GPT モデルで動く Claude Code、DeepSeek で動く Codex、Claude プランで動く OpenCode といった具合です。

1. プロバイダを追加するサブスクリプションにサインインし、API キーを貼り付けます。一度で済みます。
2. エージェントごとにモデルを選ぶエージェントのモデルをクリックして選びます。magpie がそのエージェントの設定を書き換えます。
3. 新しいセッションを始めるエージェントは起動時に設定を読むので、次のセッションから新しいモデルが使われます。

1 · プロバイダを追加する

Providers タブを開き、＋ Add provider を押します。タイルを選ぶか、ベンダー名を入力して探します。

サブスクリプション · サインインのみ、キー不要

Claude（Pro、Max、Team）、ChatGPT（Plus、Pro、Business）、Cursor、Grok（SuperGrok）、Copilot、Devin。タイルをクリックすると、magpie がブラウザでベンダー自身のサインインページを開き、完了するとすぐにアカウントが表示されます（Copilot では GitHub のページに入力するコードが表示されます）。サブスクリプションは他のエージェント内でログインするのではなく、ここ magpie で追加します。

• 複数のアカウント。 Claude や ChatGPT のタイルをもう一度クリックすると、別のアカウントを追加できます。各アカウントはプロバイダの下に並び、ワンクリックで使用中のものに切り替えられます。
• すでにサインイン済み？ このマシンでサインインしているエージェントも、signed in as … というプロバイダとして表示されます。
• どのエージェントからも使えます。 サブスクリプションのモデルは、他のすべてのエージェントのピッカーに claude/…、codex/…、copilot/… として並びます。Claude サブスクリプションのリクエストはこのマシンにインストールされた Claude Code を通して実行されるため、Claude Code はインストールしたままにしてください。

ベンダー

Anthropic、OpenAI、Google Gemini、DeepSeek、Kimi、Zhipu GLM、MiniMax、Qwen、Mistral、Groq、xAI など。1 つ選んでキーを貼り付け（Get a key ↗ はベンダーのキー発行ページへのリンクです）、保存します。magpie はベンダーに提供モデルを問い合わせてそれを候補に出します。プロバイダの行を開くと、エージェントに見せるモデルを選んだり、Test で動作確認したりできます。

このマシン上

Ollama と LM Studio。キーは不要です。

カスタム · 互換性のある任意の URL

それ以外のものには、Name、OpenAI compatible のベース URL（末尾は /v1）、Anthropic compatible のベース URL（ルート、つまり ANTHROPIC_BASE_URL に指定するもの）のどちらかまたは両方、そしてキーを入力します。エンドポイントが話す API はすべて指定してください。各エージェントはネイティブに話せる API を使い、それ以外は magpie が変換します。

キーは ~/.config/magpie/providers.json に保存され、あなただけが読めます。magpie はシェルの環境変数からキーを読みません。追加したものだけが使われます。

2 · エージェントごとにモデルを選ぶ

Agents タブには、このマシンにインストールまたは設定されているエージェントごとに行があります。magpie が対応しているのは Claude Code、Codex、Gemini CLI、OpenCode、MiMo Code、Pi、Goose、Cursor、Copilot CLI、Crush、DeepSeek Harness、Command Code、omp、OmO、Devin、Hermes Agent、MiniMax Code、Grok Build、ZCode、OpenHanako、Alma です。

• モデルをクリックするとピッカーが開きます。モデルはエージェント自身のもの、ルーティンググループ、追加した各プロバイダの順にまとめられています。入力して絞り込むことも、一覧にないモデル id を直接入力することもできます。
• 推論の強さは、エージェントが対応している場合（Codex の effort、Pi の thinking）、一覧の下のスライダーで設定します。
• magpie 経由の Claude Code では、opus・sonnet・haiku の各ティアに個別のモデルを割り当てることもできます。デフォルトではメインのモデルに従います。

モデルを選ぶと、エージェント自身の設定ファイルに書き込まれます。変更されるのは magpie が必要とするキーだけで、コメント、順序、インデントはそのまま残り、書き込みはアトミックに行われます。

実行中のセッションは、開始時のモデルを使い続けます。 エージェントは起動時に設定を読むので、変更は次のセッションから反映されます。Codex は起動時にモデル一覧も作るため、切り替えたら Codex アプリと開いている codex セッションを再起動してください。

3 · 任意：ルーティンググループ

プロバイダごとにアカウントが 1 つなら、ここは読み飛ばして構いません。ChatGPT アカウントが 2 つある、あるいは同じモデルをサブスクリプションとキーの両方で使えるなど、複数あるときに意味を持ちます。

1 つのプロバイダに複数のアカウントやキー

プロバイダの行を開き、使うアカウントやキーをすべてチェックします。Routing はリクエストをそれらにどう振り分けるかを決めます：Smart（デフォルト）、In order、In turn、Least used first、Weekly pace。Fallback には、プロバイダのクォータ切れ、レート制限、ダウン時に代わりに使うモデルを並べます。

1 つのモデルを複数のプロバイダで

グループとは、1 つまたは複数のプロバイダのモデルを、エージェントが 1 つとして選べるようにまとめたものです。ピッカーの Routing groups の下に group/<id> として表示されます。2 つのプロバイダが同じ名前で提供しているモデルは、それだけでグループになります。Routing タブの New group では、好きなモデルを組み合わせてグループを作れます。グループで何ができるかは、最初のモデルが基準になります。

ルール · ターンを指定したモデルへ

グループの Rules は、指定した種類のターンをグループ内の特定のモデルに送ります。種類とは、長いもの（tokens ≥ N）、画像を含むもの、推論を求めるもの（オン、または一定レベル以上）、特定のエージェントからのもの、あなたが記述した内容を求めるもの（インテント）、エージェントがコンテキストを圧縮するもの、です。メッセージを送ると上から順に評価され、最初に一致したルールのモデルが先頭になり、失敗したときはグループの他のモデルが後に続きます。どのルールにも一致しないターンは、グループの通常のルーティングに従い、それまでの送り先に留まります。

• ルールはターンの開始時に決まり、エージェントがツールの結果を返している間もそのターンは同じモデルに留まるため、ベンダーのキャッシュが途中で失われません。唯一の例外として、ターンがモデルのコンテキストを超えて大きくなった場合は、それを受け付けられるメンバーに移ります。
• トークン数は、リクエストのサイズから推定した値と、会話の直前のリクエストでベンダーが数えた値のうち、大きいほうを使います。余裕を持たせてください。200k のモデルなら、ルールは 199k ではなく 150k にします。
• サブエージェントはそれ自体が独立した会話なので、親のエージェントはそのままに、ルールでサブエージェントだけを別の送り先に送れます。
• インテントは、ユーザーが求めていることを数語で表したものです（「テストを書く・直す」「ちょっとした質問」など）。ターンの開始時に、グループの分類モデル（magpie にある任意のモデル。小さく高速で推論なしのものが最適です）に、一致しうるインテントのうちユーザーのメッセージがどれに当たるかを一度だけ尋ねます。送られるのはそのメッセージだけで、会話全体ではありません。分類モデルが失敗した、遅すぎた（8 秒）、または判断できなかった場合は、どのインテントも一致せず、そのターンは他のルールに従います。インテントのないルールでいずれにせよ決まる場合は問い合わせず、同じメッセージについて二度尋ねることもありません。その呼び出しは使用量に magpie 自身の呼び出しとして表示されます。何を尋ねるのか、回答がどう使われるのか、失敗したらどうなるのかの詳細はインテントルーティングを参照してください。
• compacting は、エージェントが会話を圧縮するとき（Claude Code の /compact と自動圧縮、Codex、OpenCode、Pi、Gemini CLI、Qwen Code、Kimi Code）に一致します。これにより、会話は元のモデルのまま、要約だけをより安く速いモデルに書かせられます。圧縮は単独で判断されます。圧縮が起きたターンとそのキャッシュは元の送り先に留まります。会話がルールのモデルが受け付けられる長さを超えている場合は、次に一致するルール、またはグループの順序で決まります。
• ルーティングタブには、各ターンをどのルールがどこへ送ったか、分類モデルが何と答えたかが表示されます。

グループの中のグループ

グループのモデルには別のグループも含められます。Add a model の Routing groups の下から選ぶか、ターミナルで models+=group/<id> を使います。中に入ったグループは順序の中でその位置を占め、自分のモデルの間では自分のルーティングとルールに従って振り分けます。たとえば Coder を deepseek-v4-pro、次に Fast とし、Fast は安いモデルを独自の順序で並べる、といった構成ができます。Coder のルールでターンを group/fast に送れば、どのモデルを先にするかは Fast 自身のルールが決めます。

• ループは不可。 グループは、直接でも中のグループ経由でも、自分自身を含められません。Coder が Fast を含んでいるときに、Coder を含む Fast を保存しようとすると拒否され、ピッカーにもそのようなグループは表示されません。入れ子は最大 8 階層です。他のグループに含まれているグループは削除できないので、先にそちらから外してください。
• 各グループは自分のルーティングに従います。 外側のグループのルーティングが何であれ、内側のグループの中には及びません。スマート、持ち回り、使用量の少ない順、週のペースは、内側のグループを 1 つのメンバーとして、内側のグループが最初に試すアカウントやキーで評価します。そこが選ばれると、内側のグループが丸ごと、自分の順序で試されます。Claude（順番どおり）と GPT（順番どおり）を含むスマートの Coder は、両者のアカウントをすべてまとめて比べるのではなく、Claude の先頭と GPT の先頭を比べます。
• フェイルオーバーは通ります。 内側のグループのモデルがすべて失敗すると、他のメンバーと同様に、外側のグループの次のメンバーが応答します。
• 2 回現れるモデル（単独と、中のグループ内）は、最初の位置で一度だけ問い合わせます。

Routing タブには、ゲートウェイの判断がリアルタイムで表示されます。各リクエストに誰が応答したか、そしてその理由です。同じグループをターミナルから扱うと次のとおりです：

magpie groups                        # 自分のグループ、次に magpie が見つけたもの
magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=order stays=session
magpie group set opus-anywhere models+=openrouter/anthropic/claude-opus-5.5
magpie group rule add opus-anywhere use=openrouter/anthropic/claude-opus-5.5 tokens=150k  # 長いターンはまずこれへ
magpie group rule add opus-anywhere use=copilot/claude-opus-5.5 intent="ちょっとした質問" classifier=groq/llama-3.1-8b-instant
magpie group rule add opus-anywhere use=deepseek/deepseek-v4-flash compact  # /compact の要約は安いモデルへ
magpie group set coder models+=group/opus-anywhere  # グループの中のグループ
magpie group rule opus-anywhere      # ルール一覧。rule rm|mv <n>、rule classifier <group> <model>
magpie group rm opus-anywhere        # magpie が見つけたものは非表示に。magpie group restore <id> で戻す
magpie claude group/opus-anywhere    # これを使う

使用量とプロファイル

使用量。 Usage タブでは、ゲートウェイを通ったすべての呼び出しについて、エージェントとモデルごとのトークン、キャッシュヒット、コストを Today、7 days、30 days、All の期間で集計します。上部にはサブスクリプションの利用枠の使用量と、そのリセット時刻が表示されます。エージェントが自分のベンダーへ直接行う呼び出しは magpie を通らないため、集計されません。

プロファイル。 Agents タブの下部にある ＋ Save current で、全エージェントの設定を名前を付けて保存できます。チップをクリックすれば、すべてを一度に元に戻せます。

ターミナルから

magpie tui はターミナルで動くアプリ全体で、上記の各手順にはそれぞれコマンドがあります。magpie help ですべて確認できます。

よくある質問

OPENAI_BASE_URL や ANTHROPIC_BASE_URL を export する必要はありますか？

いいえ。magpie が一覧に表示するエージェントについては、ゲートウェイのアドレスとトークンをエージェント自身の設定ファイルに書き込みます。これらの変数は、ベース URL を設定できる他のツール向けです。Gateway タブの Connect セクションに、コピーボタンとスニペットとして用意されています。

magpie は起動しておく必要がありますか？

magpie 経由のモデルを使うなら必要です。ゲートウェイはアプリと一緒に動きます。ウィンドウを閉じてもメニューバーやトレイで動き続けます。magpie tray はアイコンだけで起動し（ログイン項目に入れておくと便利です）、magpie serve はゲートウェイだけを動かします。エージェント自身のモデルと自身のサインインで動くエージェントは、magpie を通りません。

エージェントを元の状態に戻すには？

ピッカーでエージェント自身のモデルを選ぶか、magpie <agent> default を実行します。magpie は自分が書き込んだものを取り除き、以前に設定していた ANTHROPIC_BASE_URL など、置き換えた値を元に戻します。

モデルを切り替えたのに、エージェントが古いモデルを使い続けます。

実行中のセッションは開始時の設定を使い続けます。新しいセッションを始めてください。Codex の場合は Codex アプリも再起動してください。

エージェントの設定を手で編集すると、何か壊れますか？

いいえ。magpie は毎回ファイルを読み直し、自分が設定するキーだけに触れるので、他の設定やコメントはそのまま残ります。Import… で取り込んだプロバイダはコピーなので、その後エージェント側の設定を変えても再度コピーはされません。

GitHub に届かない環境で、インストールや更新をするには？

インストーラと magpie update にプロキシを渡します：curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890、または magpie update --proxy socks5://127.0.0.1:1080（http・https・socks5・socks5h に対応。HTTPS_PROXY と ALL_PROXY も使われます）。--mirror <prefix> を付けると、指定した GitHub ダウンロードミラーから <prefix>https://github.com/… としてリリースファイルを取得します。magpie update mirror <prefix> でアプリ自身の更新を含め毎回使い、magpie update mirror off で解除します。指定しない限りミラーは使われず、ファイルの SHA-256 はミラーではなく常に usemagpie.ai から取得するので、ミラーが書き換えたファイルはインストールされません。アプリ自身の更新は Settings → Proxy を通ります。

困ったときや、共有したい構成があるときは Discord でどうぞ。ユーザーにすぐ使えるプロバイダを配りたいベンダーの方は magpie に追加 をご覧ください。