ドキュメント · ガイド

はじめに

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、DevEco Code、Pi、Goose、Cursor CLI、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）、画像を含むもの、推論を求めるもの（オン、または一定レベル以上）、特定のエージェントからのもの、あなたが記述した内容を求めるもの（インテント）、エージェントがコンテキストを圧縮するもの、特定のフォルダ（プロジェクト）で作業しているもの、です。ルールの条件はすべて満たす必要があるので、「~/work/acme 内で、かつ長い」のようにも書けます。メッセージを送ると上から順に評価され、最初に一致したルールのモデルが先頭になり、失敗したときはグループの他のモデルが後に続きます。どのルールにも一致しないターンは、グループの通常のルーティングに従い、それまでの送り先に留まります。

• ルールはターンの開始時に決まり、エージェントがツールの結果を返している間もそのターンは同じモデルに留まるため、ベンダーのキャッシュが途中で失われません。唯一の例外として、ターンがモデルのコンテキストを超えて大きくなった場合は、それを受け付けられるメンバーに移ります。
• トークン数は、リクエストのサイズから推定した値と、会話の直前のリクエストでベンダーが数えた値のうち、大きいほうを使います。余裕を持たせてください。200k のモデルなら、ルールは 199k ではなく 150k にします。
• サブエージェントはそれ自体が独立した会話なので、親のエージェントはそのままに、ルールでサブエージェントだけを別の送り先に送れます。
• インテントは、ユーザーが求めていることを数語で表したものです（「テストを書く・直す」「ちょっとした質問」など）。ターンの開始時に、グループの分類モデル（magpie にある任意のモデル。小さく高速で推論なしのものが最適です）に、一致しうるインテントのうちユーザーのメッセージがどれに当たるかを一度だけ尋ねます。送られるのはそのメッセージだけで、会話全体ではありません。分類モデルが失敗した、設定したタイムアウトを超えた（既定は 8 秒。「設定 → モデル → 応答 → インテント判定のタイムアウト」で変更可能）、または判断できなかった場合は、どのインテントも一致せず、そのターンは他のルールに従います。インテントのないルールでいずれにせよ決まる場合は問い合わせず、同じメッセージについて二度尋ねることもありません。その呼び出しは使用量に magpie 自身の呼び出しとして表示されます。何を尋ねるのか、回答がどう使われるのか、失敗したらどうなるのかの詳細はインテントルーティングを参照してください。
• compacting は、エージェントが会話を圧縮するとき（Claude Code の /compact と自動圧縮、Codex、OpenCode、Pi、Gemini CLI、Qwen Code、Kimi Code）に一致します。これにより、会話は元のモデルのまま、要約だけをより安く速いモデルに書かせられます。圧縮は単独で判断されます。圧縮が起きたターンとそのキャッシュは元の送り先に留まります。会話がルールのモデルが受け付けられる長さを超えている場合は、次に一致するルール、またはグループの順序で決まります。
• 時間帯と曜日。ルールは、このコンピューターの時計で、特定の時間帯や曜日だけ有効にできます（ベンダーのピーク時間など）。その間のターンを別のモデルに送るルールでは、ベンダーのモデルはフォールバックとして後ろに残ります。完全に外すには、ルールの ⋯ メニューから 代わりにモデルを一時停止 を選びます。ルールが有効な間（時間帯、曜日、エージェント）、そのモデルはグループから外れ、先頭にもフォールバックにもならず、会話の継続でも使われません。時間帯が終われば戻ります。一時停止は時間帯、曜日、エージェントだけで判断し、グループのモデルがすべて一時停止中ならエージェントにそう伝えます。
• フォルダ。フォルダ は、エージェントの作業フォルダが指定したフォルダのどれか、またはその中にあるときに一致します。~/work/acme は ~/work/acme/web を含み、~/work/acme-old は含みません。フォルダはエージェントがリクエストでモデルに伝えるもの（Claude Code、Codex、OpenCode、Pi が伝えます）なので、伝えないエージェントはフォルダのルールに一致しません。~ はホームフォルダ、C:\work は WSL の /mnt/c/work と同じで、macOS と Windows では大文字小文字を区別しません。
• 推論。ルールはモデルに求める推論も指定できるので、インテントでモデルと推論の強さを組で選べます。ルールの ⋯ メニューの 推論を指定、またはターミナルで use-effort=low。エージェントの指定にかかわらず、モデルの最も近いレベルでその推論を求めます。magpie がレベルを知らないモデルと、その後ろのフェイルオーバー先のモデルはエージェントの指定どおりです。インテントルーティングを参照してください。
• ルーティングタブには、各ターンをどのルールがどこへ送ったか、分類モデルが何と答えたか、エージェントが伝えた作業フォルダが表示されます。

グループの中のグループ

グループのモデルには別のグループも含められます。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 set opus-anywhere routing=weight weight=claude/claude-opus-5-5=3  # 4 件に 3 件をこれに
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 rule add opus-anywhere use=kimi/kimi-k2.6 folders=~/oss,"~/My Project"  # これらのプロジェクトのターンはまずこのモデルへ
magpie group rule add opus-anywhere pause=copilot/claude-opus-5.5 time=14:00-18:00 days=mon-fri  # その時間帯は外す
magpie group rule add opus-anywhere pause=claude/claude-opus-5-5 except-folders=~/big-task  # ~/big-task のタスク専用：ほかのフォルダでは外す
magpie group set coder models+=group/opus-anywhere  # グループの中のグループ
magpie group rule opus-anywhere      # ルール一覧。rule rm|mv <n>、rule classifier <group> <model>
magpie group copy opus-anywhere "Opus test"  # モデル・ルーティング・ルールが同じ複製。別々に変更できる
magpie group rm opus-anywhere        # magpie が見つけたものは非表示に。magpie group restore <id> で戻す
magpie claude group/opus-anywhere    # これを使う

使用量とプロファイル

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

コンテキスト。 Usage の Context タブでは、ゲートウェイを通るときに読み取った各エージェントのプロンプトの中身を表示します。システムプロンプト、ツール定義（MCP サーバーのツールはまとめて 1 つ）、指示ファイルと skills、ツールが読み込んだファイル、ツールのその他の出力、会話が、モデルのコンテキストウィンドウのどれだけを占めるかがわかります。各エージェントには 100 点満点のスコア（プロンプトのうちキャッシュから読まれた割合、スタートの軽さ、埋まる速さ、失敗の頻度）と、スコアの根拠を示す「軽いスタート」「MCP が重い」などのタグが付きます。セッションを開くと最新リクエストのウィンドウをマスごとに見られ、Routing ページでも選んだリクエストについて同じものが表示されます。部分・マス・項目をクリックすると、magpie が送ったままの本文を読めます（マスクがオンならマスク済み）。本文は直近 10 件のリクエスト分だけ、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 daemon install はそれをサービス（Linux は systemd、Mac は launchd）として登録し、ログインや起動時からウィンドウなしで動かし続けます。magpie daemon install --web ならブラウザのページも同じサービスが提供し、magpie daemon status がページのリンクを表示します。エージェント自身のモデルと自身のサインインで動くエージェントは、magpie を通りません。

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

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

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

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

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

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

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

インストーラと magpie update にプロキシを渡します：curl -fsSL https://magpie-daily-3gj.pages.dev/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 はミラーではなく常に magpie-daily-3gj.pages.dev から取得するので、ミラーが書き換えたファイルはインストールされません。アプリ自身の更新は Settings → Proxy を通ります。

magpie は何を送信しますか？

プロンプト、返答、キー、アカウントは、使っているプロバイダーにだけ送られます。間に magpie 自身のサーバーはありません。リリース版の magpie は 1 日 1 回、使われていることを知らせます。何人が使っていて、何を優先して面倒を見るべきかを知るためです。送るのは、このコンピュータで作ったランダムな ID、magpie のバージョンとシステム、そして使っているエージェント、プロバイダー、モデルを magpie 自身の ID（claude、deepseek、deepseek/deepseek-v4）で、それぞれの数とともに。自分で追加したプロバイダーとそのモデルは custom とだけ記録します。プロバイダー追加シートの先頭に載るパートナーについては、1 日に表示された回数、開かれた回数、追加された回数も送ります（回数のみ）。名前、Base URL、アカウント、キー、プロンプト、使用量は送りません。設定 → プライバシー → 使っているエージェント、プロバイダー、モデルを共有 でエージェント、プロバイダー、モデルとパートナーの回数を外せます。ユーザー数に含める、DO_NOT_TRACK=1、MAGPIE_NO_STATS=1 のどれかですべてオフになります。ソースからのビルドは送信しません。パートナーの公式サイトと「キーを取得」のリンクは magpie-daily-3gj.pages.dev/go/… を経由し、移動の前にクリックを 1 回数えます（どのパートナーか、どのリンクか、国）。magpie-daily-3gj.pages.dev はパートナー一覧が取得された回数も数えます。これはサーバー自身が見るもので、どの Web サイトのアクセス集計とも同じく、上の設定には左右されません。ID、IP アドレス、アカウントは記録しません。プラグイン、インポートリンク、ライブラリが示すアイコンは magpie-daily-3gj.pages.dev/api/icon を経由して取得するので、アイコンのあるサーバーに見えるのはあなたの IP ではなく Cloudflare のアドレスです。このサーバーは画像を中継するだけで、数えることも記録することもしません。magpie が自分から送るものすべては、毎日のカウントの例、手元に残すファイル、各スイッチとともにプライバシーのページに挙げています。

エージェントが 502 を返す、または接続できず、magpie の Routing タブに何も出ない？

プロキシアプリ（Surge、Clash、mihomo など。システムプロキシ、TUN、拡張モードのいずれかが有効）が、エージェントから http://127.0.0.1:3425 へのリクエストを横取りして別の場所へ送っているため、magpie に届いていません。除外リスト（skip-proxy、バイパス）に 127.0.0.1 を書くだけでは足りないことがあります。Codex など一部のエージェントは、それでもプロキシを通します。ローカルアドレスを直結にするルールを、他のルールより前に追加してください：

IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
IP-CIDR6,::1/128,DIRECT,no-resolve

Clash / mihomo の設定では、同じ行を rules: の下に、それぞれ先頭に - を付けて書きます。そのあと、エージェントからもう一度リクエストを送ってください。

DeepSeek Harness の DeepSeek 行をそのまま使い、magpie を通せますか？

手で設定すればできます。dsh を接続すると magpie は自分のルートを足すだけで、dsh の DeepSeek 行（llm-deepseek）は dsh に任せます。この行は、セッションの途中でプロンプトやツールが変わっても DeepSeek のキャッシュを保ちます。magpie を通すには ~/.dsh/profiles/<profile>/cordis.patch.yml に次を足します：

- id: llm-deepseek
  config:
    baseURL: http://127.0.0.1:3425
    apiKeyEnv: MAGPIE_DS_KEY
    maxInlineRequestImageBytes: 67108864
    models:
      - id: deepseek/deepseek-flash
        name: DeepSeek V4.1 Flash (magpie)
        contextWindow: 1000000
        inputModalities: [text, image]
        systemPromptUpdate: in-history
        toolUpdate: addition-only
      - id: deepseek/deepseek-v4-pro
        name: DeepSeek V4 Pro (magpie)
        contextWindow: 1000000

baseURL に /anthropic は付けません。モデル id は magpie のもの（magpie models）で、models を書くと dsh の既定の一覧が置き換わるので、更新方法の 2 行も残してください。MAGPIE_DS_KEY には DeepSeek のキーではなくゲートウェイのキー（このコンピュータでは magpie）を入れます。export するか、~/.dsh/.env に書くか、dsh のモデルページの DeepSeek 行に入力します。モデルは dsh で選びます。magpie で接続を解除してもこの設定は残ります。magpie には Files API がないため、dsh は画像を毎ターン base64 でインライン送信します。上限は maxInlineRequestImageBytes（既定 20 MiB、上の例では 64 MiB）です。この行では DeepSeek 自身のモデルだけを使ってください。詳しくはリファレンスへ。

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