ドキュメント · ガイド

はじめに

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

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

プロバイダ

モデルの提供元です。サインインするサブスクリプション、API キーを持っているベンダー、そして自前のエンドポイント。各モデルは provider/model という名前で呼ばれます。

エージェント

モデルを使うツールです。Claude Code、Codex、Gemini CLI、OpenCode など。1 つにつき 1 行で、設定中のモデルが表示されます。

ゲートウェイ

magpie 経由でモデルを選んだときに、すべてのエージェントの接続先となるローカルのエンドポイントです。各リクエストを、そのモデルを提供する先へ送ります。

ルーティンググループ

任意です。複数のモデルやアカウントを、エージェントが 1 つとして選べるようにまとめたもの(group/<id>)。どれかのクォータが尽きたときに役立ちます。

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

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

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

プロバイダの追加シート:サブスクリプション、ベンダー、中継サービス、このマシン上のもの、カスタム URL プロバイダの追加シート:サブスクリプション、ベンダー、中継サービス、このマシン上のもの、カスタム URL
プロバイダの追加:サブスクリプションにサインインする、ベンダーを選ぶ、または互換性のある任意の URL を指定する。

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

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

ベンダー

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 が変換します。

Claude Code や Codex でプロバイダを設定済みですか? シート上部の Import… は Claude Code の settings.json と Codex の config.toml を読み取り、それらには一切手を加えずに、チェックしたプロバイダを取り込みます。

キーは ~/.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 です。

エージェントタブ:エージェントごとに使用中のモデルを示す行と、下部に保存済みのプロファイル エージェントタブ:エージェントごとに使用中のモデルを示す行と、下部に保存済みのプロファイル
エージェントごとに 1 行。どのプロバイダのモデルでも選べ、プロファイルですべてを一度に切り替えられます。

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

エージェントmagpie 経由のモデルで書き込まれる内容
Claude Code~/.claude/settings.json:env ブロック内の ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN とモデル関連の変数
Codex~/.codex/config.toml:[model_providers.magpie] テーブルとモデル、一覧は magpie-models.json。ChatGPT のサインインには手を加えません
OpenCode、MiMo Code、DevEco Code、Pi、Crushmagpie プロバイダのエントリと magpie/provider/model
Open Code Review~/.opencodereview/config.json:magpie カスタムプロバイダを追加し、ocr が使うものに設定
AtomCode~/.atomcode/config.toml:magpie プロバイダアカウントと、カタログ内の各モデルのエントリ
Snow CLI~/.snow/profiles/magpie.json:magpie プロファイルを作り、使用中のプロファイルにする(Snow App は「Sync Snow CLI API config」で取り込む)
QwenPaw~/.qwenpaw.secret/providers/custom/magpie.json の magpie プロバイダーと、各エージェントの agent.json の active_model。初回の接続後に QwenPaw を再起動
Gemini CLIゲートウェイを指す GOOGLE_GEMINI_BASE_URL、API キー認証、そしてモデル

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

Paseo やエディタ拡張などのフロントエンドで Claude Code や Codex を代わりに動かすものは、同じ CLI を起動し、同じ ~/.claude または ~/.codex の設定を読みます。magpie で一度モデルを設定すれば、それらにも次のセッションから反映されます。
claude-magpie:Claude Code を magpie 経由で、claude はそのまま。ふだんの claude は自分の Claude アカウントのまま、必要なときだけ magpie を通したいなら、Claude Code は接続せずに claude-magpie で起動します。同じ claude を、そのセッションだけ magpie の設定(ゲートウェイ、モデルと各ティア)を自分の設定の上に重ねて起動するので、~/.claude/settings.json は書き換えられません。引数はすべて Claude Code に渡ります:claude-magpie --resume、claude-magpie -p "…"。設定 › コマンドライン で magpie コマンドを追加すると、その隣に置かれます。すでに追加済みなら magpie claude launcher add を一度実行してください。magpie claude run でも同じです。その中で /model で選んだモデルは次の claude-magpie に引き継がれ、自分の claude は元のモデルのままです。magpie が起動している必要があります。

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

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

ルーティングタブ:4 つのエージェントが 3 つのルーティンググループを通して同時に送信し、レート制限中のプロバイダは外れている ルーティングタブ:4 つのエージェントが 3 つのルーティンググループを通して同時に送信し、レート制限中のプロバイダは外れている
ルーティンググループ:複数のモデルやアカウントを 1 つの名前にまとめ、スマートまたは順番どおりにフォールバックします。

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

プロバイダの行を開き、使うアカウントやキーをすべてチェックします。Routing はリクエストをそれらにどう振り分けるかを決めます:Smart(デフォルト)、In order、Until used up(使い切ったら次へ移り、前のものが回復しても戻りません)、In turn、Least used first、Use before expiry、By weight(各アカウントやキーが横で設定した重みで取り分を受けます。たとえば Max アカウントは 5、Pro は 1)、Speed first(最近いちばん速く応答したキーが先)。Fallback には、プロバイダのクォータ切れ、レート制限、ダウン時に代わりに使うモデルを並べます。

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

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

何もしなくてもできるグループ。 すでに持っているモデルを提供する 2 つ目のプロバイダを追加すると(Claude サブスクリプションと Copilot の Claude Opus、DeepSeek 自身の API と OpenRouter の DeepSeek など)、magpie はそれを提供するすべてのプロバイダにまたがるグループ auto/<model>(モデル自身の ID。例: auto/claude-opus-4.6。以前の group/auto-… も引き続き使えます)を自動で作ります。名前はベンダーごとの表記の違い(deepseek/deepseek-chat、deepseek-chat)を吸収して照合されます。エージェントにこれを選ぶとリクエストがすべてに分散されます。不要なものは magpie group rm で非表示にできます。
プロバイダ独自の id に自分の id を。 プロバイダによっては deepseek-v4.1-flash-1017 や grok-4.6@500k のような独自の id でモデルを提供します。プロバイダの編集画面の モデル設定 で、同じモデル の隣の 表示 ID に使いたい id を入れて 保存、または magpie model id relay/grok-4.6@500k grok-4.6 を実行します。以後 magpie は一覧、ルーティング、他のプロバイダの grok-4.6 とまとめた auto/grok-4.6 グループ、ゲートウェイキーの制限、使用量の記録をすべて grok-4.6 で行い、プロバイダには grok-4.6@500k で問い合わせます。1 つのプロバイダで 1 つの id は 1 つのモデルです。最後に付けたものが有効で、その間プロバイダ自身のその id のモデルは一覧から外れます。magpie model id relay/grok-4.6 --reset で元に戻し、magpie model ids で一覧を表示します。サインインしたサブスクリプションやプラグインのプロバイダでも同じです(magpie model id cursor/deepseek-v41-flash-1017 deepseek-v4.1-flash)。アカウントやプラグインには引き続き元の id で問い合わせます。
ルーティング先に使われるもの
スマート smartデフォルトです。メンバーのアカウントとキーをまとめて扱い(グループ内のグループは 1 つとして扱います。下記参照)、クォータに余裕のあるサブスクリプションのうち、利用枠が最も早く更新されるもの。基準は週の枠です。週の枠がなく 5 時間枠だけのアカウント(Claude Enterprise)は 5 時間枠で判断されるため、それより後に週の枠が更新されるものすべてより先になります。リセットのないクレジット(WorkBuddy のパッケージはそれぞれの日に失効します)は、残りのうち最も早く失効する時点で判断されるため、クレジットが最も早く失効する WorkBuddy アカウントが先になります。同時に更新されるアカウント(無料アカウントはすべて月末)は、その後に残りのクレジットが先に失効するものが先になります。失敗後に休止中のものは最後に回ります。
順番どおり order最初のモデルが応答できなくなるまでそれを使い、次へ進みます。
使い切ってから次へ drain1 つのアカウントやキーを使い切るまで使い、その後は次へ移ってそのまま使い続けます。その間に前のものが回復しても戻りません。レート制限やエラーのものは休止中だけ飛ばします。
持ち回り rotateメッセージを送るたびに、次のメンバーのアカウントやキーへ回します。そのメッセージのためのツール呼び出しは同じものに残ります。維持を「セッション」にすると、会話全体が一つに留まります。
使用量の少ない順 usage利用枠の残りが最も多いアカウントやキー。
期限前に使い切る pace更新までの 1 時間あたりの週の枠の残りが最も多いアカウント、つまりリセット時に失う分が最も多いもの。これにより各メンバーの週の枠がリセットで無駄になりにくくなります。週の枠がなく 5 時間枠だけのアカウント(Claude Enterprise)は、更新までの 1 時間あたりの 5 時間枠の残りで判断されるので、ほぼ常に最初になります。リセットより早く期限切れになるクレジットがあるアカウントは、最初に期限切れになる分を期限までの 1 時間あたりで数え、そのほうが多ければそれで判断します(WorkBuddy のチェックインで得たクレジットなど)。使用率が 90% 以上のものは、他が応答できなくなるまで待ちます。キーは最近送ったトークン数で判断します。
重み順 weightグループ編集画面で各モデルの横に設定した重み(1〜1000、未設定は 1)に応じてリクエストを分けます。重み 3 のモデルは重み 1 のモデルが 1 件受けるごとに 3 件受け、まとめてではなく均等に散らします。各モデルは自分のプロバイダーのルーティングで自分のアカウントやキーを使い、グループ内のグループは 1 つとして数えます。失敗して休んでいるものはその回から外れ、失敗したときは次のモデルが代わりに答えます。
速度優先 fastこのモデルに最近いちばん速く応答したメンバー、アカウント、キーが先です。最初のトークンまでの時間と出力の速さで比べ、新しい応答ほど重く数えます。差が 1 割以内のものは並び順のままです。1 時間測っていないものには 5 件に 1 件を回すので、一度遅かったチャネルもまた試されます。失敗して休んでいるものは最後です。測るのはストリーミングの応答だけで、再起動すると測り直します。
最安優先 cheapルーティンググループのみ。いまモデルが最も安いメンバーが先です。Usage が数えるのと同じく、この時間帯の入力・出力 100 万トークンあたりの価格で比べます:自分で設定した価格、なければ定価に、プロバイダの価格倍率と時間帯倍率をかけたもの。DeepSeek 公式 API、Command Code と OpenCode Go の DeepSeek モデルはピーク時間帯(平日 UTC 01:00–04:00 と 06:00–10:00)に、Ollama Cloud の DeepSeek V4.1 Flash と V4 Pro は自社のピーク時間帯(平日 UTC 12:00–18:00、それ以外は半額)に 2 倍になるので、2 つのプロバイダにある同じ DeepSeek モデルはその時間に安い方へ送られます。同じ価格のものは順番どおり、価格が分からないものは最後です。
維持会話が、応答したアカウントやキーに留まる期間
自動 autoデフォルトです。ターン内では常に、ターンをまたいでは、ベンダーがキャッシュした内容が保持する価値のある間。
セッション session応答できる限り、セッション全体。ルーティングがスマート、使用量の少ない順、「期限前に使い切る」のとき、新しいセッションは他のセッションが最も少ないアカウントやキーに割り当てられ、同時に開いたセッションはそれぞれ別のものを使います。
ターン内 turnエージェントがツールの結果を返している間。あなたが再び発言すると、ルーティングが改めて決めます。
オフ offリクエストごとに改めてルーティングします。
厳格 strict使用量上限を超えても、他のアカウントやキーへは移りません。レート制限や割り当て切れのときは、エラーがそのままエージェントに渡ります。新しい会話は「セッション」と同じく分散されます。

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

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

グループの中のグループ

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

グループの中にグループがある ルーティングタブ:Coder には deepseek-v4-pro とグループ Fast があり、Fast の下に deepseek-v4-flash と kimi-k2.5 が並ぶ。応答したのは Kimi グループの中にグループがある ルーティングタブ:Coder には deepseek-v4-pro とグループ Fast があり、Fast の下に deepseek-v4-flash と kimi-k2.5 が並ぶ。応答したのは Kimi
Coder のルールがちょっとした質問をグループ Fast に送り、Fast 自身のルールがそこで Kimi を先頭にしました。トレースには、各グループのルールと分類モデルが何を決めたかが表示されます。

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 rule add opus-anywhere use=deepseek/deepseek-v4-flash when="effort is off" when="not subagent"  # 推論オフでサブエージェントでないリクエスト
magpie group rule add opus-anywhere use=deepseek/deepseek-v4-flash when="system matches ^你是对话标题命名"  # システムプロンプトでタイトル生成リクエストを見分ける
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 を通らないため、集計されません。

使用量タブ:残高、トークンとコストの合計、30 日間のグラフ 使用量タブ:残高、トークンとコストの合計、30 日間のグラフ
ゲートウェイを通ったすべての呼び出しの残高、トークン、キャッシュヒット、コスト。

コンテキスト。 Usage の Context タブでは、ゲートウェイを通るときに読み取った各エージェントのプロンプトの中身を表示します。システムプロンプト、ツール定義(MCP サーバーのツールはまとめて 1 つ)、指示ファイルと skills、ツールが読み込んだファイル、ツールのその他の出力、会話が、モデルのコンテキストウィンドウのどれだけを占めるかがわかります。各エージェントには 100 点満点のスコア(プロンプトのうちキャッシュから読まれた割合、スタートの軽さ、埋まる速さ、失敗の頻度)と、スコアの根拠を示す「軽いスタート」「MCP が重い」などのタグが付きます。セッションを開くと最新リクエストのウィンドウをマスごとに見られ、Routing ページでも選んだリクエストについて同じものが表示されます。部分・マス・項目をクリックすると、magpie が送ったままの本文を読めます(マスクがオンならマスク済み)。本文は直近 10 件のリクエスト分だけ、magpie の実行中にメモリに置かれます。保存するのは名前だけで、プロンプトの本文は保存せず、どこにも送りません。

プロファイル。 Agents タブの下部にある + Save current で、全エージェントの設定を名前を付けて保存できます。チップをクリックすれば、すべてを一度に元に戻せます。使用中のプロファイルには ✓ が付き、トレイパネルの プロファイル ボタンにもその名前が表示されます。その後に設定を手で変えると ✓ は外れます。

ターミナルから

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

コマンド内容
magpie ls見つかったすべてのエージェントとその設定
magpie presetsmagpie が知っているベンダー
magpie provider add deepseek sk-…プリセットをキー付きで追加
magpie accounts add codexClaude または ChatGPT のサブスクリプションをもう 1 つサインイン
magpie accounts switch claude nextClaude Code(または codex)を、まだ余裕のある次のアカウントに切り替え。どれも上限近くなら、残りが最も多いアカウントへ
magpie accounts discovery offエージェントのサインイン(Claude Code と Codex のファイル、キーチェーン)を読み取らない。on で再び読み取る
magpie providersプロバイダ一覧:ホスト、キー、モデル、使っているエージェント
magpie modelsエージェントが選べるすべてのモデル(provider/model 形式)
magpie claude codex/gpt-5.5エージェントのモデルを設定
claude-magpieこのセッションだけ Claude Code を magpie 経由で起動、ふだんの claude は自分のアカウントのまま(magpie claude run、magpie claude launcher add で PATH に追加)
magpie codex effort high他の項目を設定
magpie codex defaultエージェント自身のデフォルトに戻し、magpie の設定を取り除く
magpie save work · use workプロファイルを保存・適用
magpie usage 7dエージェントとモデルごとのトークンとコスト
magpie tools · magpie tool generate_image "…" -o hero.pngmagpie が MCP でエージェントに渡すツール(画像生成、画像認識、Web 検索、プラグインのツール)を一覧し、直接呼び出す。生成した画像はファイルに保存
magpie trayメニューバーのアイコンだけで起動
magpie log · magpie log -fmagpie のログの場所。不具合の報告に添えます。-n 200 でアプリのログの末尾を表示、-f で追いかけます

複数のコンピュータで magpie を同期:WebDAV・S3・GitHub

よくある質問

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://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 も使われます)。リリースファイルは usemagpie.ai(Cloudflare R2)から取得し、失敗したときは github.com から取得します。--mirror <prefix> を付けると、サイトからの取得に失敗したとき、指定した GitHub ダウンロードミラーから <prefix>https://github.com/… としてリリースファイルを取得します。magpie update mirror <prefix> でアプリ自身の更新を含め毎回使い、magpie update mirror off で解除します。指定しない限りミラーは使われず、ファイルの SHA-256 はミラーではなく常に usemagpie.ai から取得するので、ミラーが書き換えたファイルはインストールされません。アプリ自身の更新は Settings → Proxy を通ります。

ダウンロードしたファイルが GitHub Actions でビルドされたものか確認するには?

yetone/magpie-releases の各ファイルには SLSA ビルド来歴(build provenance)の証明が付いています。GitHub Actions の実行自身の ID で Sigstore を通して署名されており、こちらの鍵は使いません。GitHub CLI で確認します:gh attestation verify magpie-darwin-arm64.dmg -R yetone/magpie-releases。ビルドした workflow と実行が表示され、その実行が作っていないファイルは失敗します。yetone/magpie の Releases にあるコピーにも同じコマンドが使えます。v0.1.3891 以降が対象です。証明が指すのは magpie-releases リポジトリとそのコミットで、yetone/magpie のソースのコミットではありません。アプリ自身の更新は両方を検証します:リリースの SHA-256 一覧に付いた ed25519 署名を magpie に組み込まれた鍵で確認し(オフラインでも usemagpie.ai のミラーからでも有効)、v0.1.3891 以降はさらにそのファイルの証明を確認し、証明が無いファイルや、このリポジトリのリリース workflow によるものではない証明のファイルはインストールしません。usemagpie.ai からダウンロードしたファイルは証明も usemagpie.ai から(下の attestations.jsonl)取得し、ミラーに無いときは GitHub から取得します。どこから取得しても magpie に組み込まれた Sigstore のルートで同じように検証するので、ミラーは運ぶだけです。証明を取得できないときは署名だけで更新を続け、ログに記録します。 同じ証明は usemagpie.ai にも、ミラーしたファイルの隣に置かれており、GitHub が使えないときも取得できます:https://usemagpie.ai/files/v<バージョン>/attestations.jsonl には、そのリリースの全ファイル分のバンドルが 1 行に 1 つ入っています。ファイルと一緒にダウンロードすれば、証明 API を使わずに確認できます:gh attestation verify magpie-darwin-arm64.dmg -R yetone/magpie-releases --bundle attestations.jsonl(バンドルは Sigstore バンドルです。ミラーには新しいリリースだけが残るので、古いものは上のコマンドを使ってください)。

Linux ではインストーラはどのビルドを入れますか?

GTK 3 と WebKitGTK 4.1 が入っていればデスクトップアプリ(ウィンドウ、トレイアイコン、アプリメニューの項目)です。デスクトップがあってもそれらが無いときは、パッケージマネージャー(apt、dnf、pacman、zypper)で sudo を通して WebKitGTK 4.1 を入れ(sudo がパスワードを尋ねます)、それからアプリを入れます。パスワードを尋ねる前に何を入れるかを表示します。端末が無いとき(CI、Dockerfile)、sudo が無いとき、知らないディストリビューションやインストールに失敗したときはターミナル版(magpie tui、magpie web と CLI)を入れ、最後に入れるコマンドを表示します。Debian・Ubuntu なら sudo apt install libwebkit2gtk-4.1-0、Fedora なら sudo dnf install webkit2gtk4.1 です。入れたあとインストーラをもう一度実行するとアプリになります。デスクトップ上で実行しても ssh 越しでも、グラフィカルなセッション、あなたのグラフィカルなログイン、ログインできるデスクトップ環境のどれかがあればデスクトップありと判断します。デスクトップの無いサーバーにはターミナル版です。自分で選ぶには --gui(ライブラリを今入れられなくてもアプリ)か --tui(ターミナル版、パッケージは入れない)を付けます:curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --tui。

magpie をアンインストールするには?

スクリプトでインストールした場合:curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall は、まず magpie にすべてのエージェントの接続を外させて元の設定に戻し、それからスクリプトが置いたものを取り除きます。magpie コマンド、macOS ではアプリ、Linux ではメニュー項目・アイコン・magpie:// のハンドラ、それに Linux ではもう無い magpie を起動してしまうサービスとログイン時の起動です。~/.config/magpie の設定・プロバイダ・使用量は残るので、再インストールすれば戻ります。--purge を付けるとそれも削除します(magpie uninstall --yes)。ほかの方法でインストールした場合は、magpie uninstall または Settings → magpie をアンインストール が --purge と同じことを行い、プログラム本体は手動で削除します。

magpie をもう削除した(アプリをゴミ箱に入れた、フォルダーを消した)のに、エージェントが接続できないと言う場合:macOS と Linux では同じ --uninstall の行を実行してください。magpie が見つからないと最新版を一時フォルダーにダウンロードし(インストールと同じく検証します)、~/.config/magpie に各エージェントの元の設定が残っているうちに、それが元に戻します。Windows では magpie をもう一度ダウンロードして Settings → magpie をアンインストール を使います。Codex を手で戻すには、Codex を終了し、~/.codex/config.toml で # magpie: コメントの下の行(openai_base_url、model_provider = "magpie"、model_catalog_json)を削除して、model を Codex 自身のモデルに戻します。magpie で始めたスレッドを残さないなら [model_providers.magpie] の表も消せます。~/.codex/magpie-models.json を削除し、Codex を開き直します。

magpie のファイルを別のディスクに置いて、システムを再インストールしても失わないようにできますか?

インストール版の magpie は、設定・プロバイダ・使用量・ライブラリを ~/.config/magpie(Windows では C:\Users\<ユーザー>\.config\magpie)に保存します。1 日 1 回自動でバックアップしますが、その保存先は同じフォルダ内の auto-backups なので、システムを再インストールするとバックアップも一緒に失われます。設定 → 同期とバックアップ の バックアップフォルダ の下にもそう表示されます。そこで 変更… を押し、別のディスク上のフォルダ(D:\magpie-backups など)か、クラウドドライブが同期するフォルダを選んでください。再インストール後は magpie を入れ、同じ場所で同じフォルダを選び、最新の版を 復元… します。バックアップに API キーは含まれません。バックアップにサインインを含める を有効にすると、サブスクリプションのアカウントとプラグインのサインインもパスフレーズで暗号化して含めます。キーも持ち出すには、同じ場所で WebDAV フォルダ、S3 バケット、GitHub リポジトリへの同期をパスフレーズ付きで設定してください。

magpie 自身のファイルをそのディスク(外付け SSD など)に置くなら、同じ場所の データフォルダ の 移動… を押し、そのディスク上のフォルダを選びます。magpie は再起動し、ファイルとキャッシュをその中の magpie フォルダに移し、元の場所にリンクを残すので、ほかは何も変わりません。ディスクはつないだままにしてください。外すと、戻すまで magpie は開きません。元に戻す で元の場所に戻ります。ターミナルでは magpie data move <フォルダ> で同じことができます。

すべてをそのディスクに置くなら、ポータブルで使います。magpie.exe をそのディスク上のフォルダに置き、隣に data という空のフォルダを作ります(D:\magpie\magpie.exe と D:\magpie\data)。magpie はキャッシュやログも含めてすべてを data に保存し、ユーザーフォルダには自分のファイルを書きません。設定 → 情報 → 設定フォルダ にポータブルと表示されます。それを開き、上の手順でバックアップを復元します。再インストール後は D:\magpie\magpie.exe をもう一度開くだけです。各エージェント自身の設定(~/.claude、~/.codex…)は、それぞれが読む場所に残ります。

magpie のログはどこにありますか?

アプリ(ウィンドウ、メニューバーやトレイのアイコン、パネル。どう開いたかによらず)は app.log を書きます。macOS では ~/Library/Logs/magpie/app.log、Windows では %LOCALAPPDATA%\magpie\logs\app.log、Linux では ~/.local/state/magpie/app.log($XDG_STATE_HOME が設定されていれば $XDG_STATE_HOME/magpie)、ポータブル版ではデータフォルダーの logs です。設定 → 情報 → ログにパスがあり、開くでそのフォルダーを表示します。magpie log はパスを表示し、magpie log -f は追いかけます。5 MiB に達すると隣の app.old.log になり、残るのは最大 2 ファイルです。記録されるのは magpie がしたことと出会ったエラー(プロバイダーがリクエストを断った、再試行した、プラグインが起動しなかった)で、キー、プロンプト、返答は含みません。キーやトークンに見えるものも伏せられます。サービスとして動く magpie serve のログは別の場所です。macOS では ~/Library/Logs/magpie/serve.log、Linux では journalctl --user -u magpie。magpie log はそれも示します。

magpie は何を送信しますか?

プロンプト、返答、キー、アカウントは、使っているプロバイダーにだけ送られます。間に magpie 自身のサーバーはありません。リリース版の magpie は 1 日 1 回、使われていることを知らせます。何人が使っていて、何を優先して面倒を見るべきかを知るためです。送るのは、このコンピュータで作ったランダムな ID、magpie のバージョンとシステム、そして使っているエージェント、プロバイダー、モデルを magpie 自身の ID(claude、deepseek、deepseek/deepseek-v4)で、それぞれの数とともに。自分で追加したプロバイダーとそのモデルは custom とだけ記録します。プロバイダー追加シートの先頭に載るパートナーについては、1 日に表示された回数、開かれた回数、追加された回数も送ります(回数のみ)。名前、Base URL、アカウント、キー、プロンプト、使用量は送りません。設定 → プライバシー → 使っているエージェント、プロバイダー、モデル、プラグインを共有 でエージェント、プロバイダー、モデル、パートナーの回数、Discover のどのプラグインを入れているか、ライブラリのマーケットのどの MCP サーバーを使っているか(利用者数といいねの集計用)を外せます。ユーザー数に含める、DO_NOT_TRACK=1、MAGPIE_NO_STATS=1 のどれかですべてオフになります。ソースからのビルドは送信しません。パートナーの公式サイトと「キーを取得」のリンクは usemagpie.ai/go/… を経由し、移動の前にクリックを 1 回数えます(どのパートナーか、どのリンクか、国)。usemagpie.ai はパートナー一覧が取得された回数も数えます。これはサーバー自身が見るもので、どの Web サイトのアクセス集計とも同じく、上の設定には左右されません。ID、IP アドレス、アカウントは記録しません。プラグイン、インポートリンク、ライブラリが示すアイコンは usemagpie.ai/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 など一部のエージェントは、それでもプロキシを通します。ローカルアドレスを直結にするルールを、他のルールより前に追加してください:

Surge
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 に次を足します:

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 自身のモデルだけを使ってください。詳しくはリファレンスへ。

Trae / Trae CN で magpie のモデルを使えますか?

この方法で動いたという報告があります。Trae はカスタムモデルを Trae アカウント(Trae のサーバー側)に保存するため、magpie からワンクリックで設定することはできず、Trae から 127.0.0.1 に届かないこともあります。手順:

  1. magpie で 設定 → ネットワークと共有 → ローカルネットワークで共有 をオンにし、表示される アドレス を控えます。
  2. ゲートウェイキーを用意します(ゲートウェイ → ゲートウェイキー、または magpie gateway-key add "Trae")。
  3. Trae のカスタムモデル設定で、アドレスにそのアドレスを、API キーにそのゲートウェイキーを入力します。

モデル id は magpie のもの(magpie models)です。共有をオンにすると、同じネットワークのほかのコンピューターもゲートウェイキーで接続できます。リモート magpie を参照してください。

ゲートウェイのエラーは よくあるエラーの直し方 を参照してください。困ったときや、共有したい構成があるときは Discord でどうぞ。Cherry Studio でチャットする場合は Cherry Studio ですべてのモデルを使うを参照してください。ユーザーにすぐ使えるプロバイダを配りたいベンダーの方は magpie に追加 をご覧ください。