メインコンテンツへ移動
AIチュートリアル

MagpieでAIエージェントのモデルとプロバイダーを管理

Magpieのインストール方法、モデルプロバイダーへの接続、Claude CodeやCodexなどのツールで使用するモデルの切り替え、再利用可能なプロファイルの保存、OpenAI・Anthropic・Gemini互換アプリケーションのローカルゲートウェイ経由での接続方法を解説します。

約21分で読了
MagpieでAIエージェントのモデルとプロバイダーを管理

Magpieの機能

Magpieは、コンピューターにインストールされたAIエージェントが使用するモデルを表示・変更するための場所を一つにまとめます。メニューバーアプリケーション、通常のデスクトップウィンドウ、ターミナルユーザーインターフェース、コマンドラインツールとして利用できます。

複数のJSON、TOML、YAML、環境ファイルを手動で編集する代わりに、エージェントを選択し、フィールドを選んでモデルを割り当てられます。Magpieは関連する設定だけを変更し、可能な場合はコメント、順序、インデントを保持します。書き込みはアトミックに行われます。

Magpieは現在、Claude Code、Codex、Gemini CLI、OpenCode、Pi、Goose、Cursor CLI、Copilot CLI、Crushを認識します。インストール済みまたは設定済みのエージェントだけがインターフェースに表示されます。

主な機能

  • 複数のインターフェース: デスクトップアプリケーション、メニューバーパネル、ターミナルUI、通常のCLIを利用できます。
  • 設定を狙い撃ちした編集: 選択したキーだけを変更し、エージェント設定の残りを書き換えません。
  • 統合ローカルゲートウェイ: エージェントは、単一のループバックエンドポイントを通じて複数ベンダーのモデルにアクセスできます。
  • API変換: ゲートウェイは、ストリーミングとツール呼び出しを含む、OpenAI Chat Completions、OpenAI Responses、Anthropic Messages、Google Gemini互換リクエストをサポートします。
  • サブスクリプションの共有: 既存のClaude Code、Codex、Copilotのサインイン情報を、他のエージェントのプロバイダーとして利用できます。
  • 最新のモデルカタログ: プロバイダーからモデル一覧を取得し、models.devのデータで補完します。
  • プロバイダープリセット: Anthropic、OpenAI、Gemini、DeepSeek、Kimi、GLM、MiniMax、Qwen、Mistral、Groq、xAI、OpenRouter、Together、Ollama、LM Studioなどのベンダーやサービス向けプリセットを利用できます。
  • プロファイル: 現在のすべてのエージェント設定を名前付きで保存し、後からまとめて復元できます。
  • 小型のネイティブビルド: デスクトップ版はブラウザーランタイムを同梱せず、オペレーティングシステムのWebViewを使用します。

Magpieのインストール

ビルド済みリリースをインストールする

macOS、Windows、Linux向けのデスクトップアプリケーションをusemagpie.aiからダウンロードできます。インストールスクリプトを実行することもできます。

curl -fsSL https://usemagpie.ai/install.sh | sh

Linuxでは、WebKitGTK 4.1が利用可能な場合はデスクトップアプリケーションを、それ以外の場合はコマンドライン版をインストールします。macOS版は署名および公証済みです。Windows版とLinux版は現在署名されていないため、Windows SmartScreenが初回起動時に警告を表示する場合があります。

Magpieはバックグラウンドで更新を確認します。デスクトップアプリケーションは再起動または終了時に更新をインストールします。ターミナルユーザーは明示的に更新できます。

magpie update

Goソースからインストールする

Goがインストールされている場合は、最新バージョンを直接インストールできます。

go install github.com/yetone/magpie@latest

リポジトリをローカルでビルドする

リポジトリには複数のMakeターゲットがあります。

make build            # デスクトップアプリケーションのバイナリ
make app              # macOSメニューバーアプリケーション
make cli              # cgoを使用しないターミナル専用ビルド
make release          # ネイティブアプリとクロスプラットフォームCLIのビルド
make release-windows  # Windows amd64およびarm64アプリケーションのビルド
make release-linux    # 現在のアーキテクチャ向けLinuxアプリケーション

Linuxデスクトップアプリケーションのビルドには、libgtk-3-devとlibwebkit2gtk-4.1-devが必要です。通常のGoビルドではgtk3ビルドタグを使用する必要があります。Windowsでは、オペレーティングシステムに含まれるWebView2ランタイムを使用します。

インターフェースを開く

ワークフローに合ったインターフェースを選択してください。

magpie          # ウィンドウとメニューバーアイコンを開く
magpie tray     # メニューバーアイコンのみを実行
magpie tui      # ターミナルインターフェースを開く
magpie ls       # 検出されたエージェントと現在の設定を一覧表示

デスクトップインターフェースでは、現在の値をクリックすると、絞り込み可能な選択画面が開きます。入力して検索するか、カスタム値を入力し、escを押して選択画面を閉じます。

ターミナルインターフェースでは、矢印キーでエージェントとフィールドを選択し、Enterを押して選択画面を開きます。入力して選択肢を絞り込めます。終了するにはqを押します。

モデルプロバイダーを追加する

利用可能なプリセットを確認する

まず、Magpieが認識しているプロバイダーを一覧表示します。

magpie presets

プリセットはベンダー、リレー、ローカルサービスに分類されています。ホスト型プリセットでは通常、APIキーだけが必要です。

magpie provider add deepseek sk-…

Ollamaなどのローカルプロバイダーにはキーは必要ありません。

magpie provider add ollama

Magpieはシェル環境からプロバイダーキーを読み取りません。アプリケーションまたはプロバイダーコマンドから追加してください。

カスタムOpenAI互換プロバイダーを追加する

カスタムプロバイダーは、名前、ベースURL、キー、明示的なモデル一覧で設定できます。

magpie provider add "My Relay" url=https://relay.example.com/v1 key=sk-… models=gpt-5.5,claude-sonnet-5

カスタムプロバイダーでは、OpenAI互換ベースにurl=、Anthropic互換ベースにanthropic=を使用できます。両方を指定することも可能です。プロバイダーに別個のResponsesエンドポイントがある場合はresponses=を使用します。任意のcatalog=引数を使うと、models.devのプロバイダーからメタデータを借用できます。

プロバイダーを確認・テストする

次のコマンドで、プロバイダーの確認、モデル一覧の更新、APIのテスト、キーのローテーション、エントリの削除を行えます。

magpie providers
magpie provider deepseek
magpie provider models deepseek
magpie provider test deepseek
magpie provider key deepseek sk-…
magpie provider rm deepseek
magpie models

magpie provider test は、サポート対象の各 API に対して小さなリクエストを 1 回ずつ送信し、レイテンシを報告します。デスクトップアプリケーションでは、Providers タブから同等の操作を行えます。キーの変更、公開するモデルの選択、プロバイダーのテスト、エージェントへのモデル割り当てが可能です。

エージェントのモデルを切り替える

ゲートウェイを通じて公開されるモデルは provider/model 形式を使用します。ネイティブのエージェントモデルは、通常の名前でも選択できます。

基本的な CLI 例

magpie claude opus
magpie codex gpt-5.6-sol
magpie codex effort high
magpie codex xhigh
magpie codex deepseek/deepseek-chat
magpie claude moonshot/kimi-k2.5
magpie gemini auth api-key
magpie opencode anthropic/claude-sonnet-5
magpie oc small anthropic/claude-haiku-4-5

エージェント名には、cc、oc、gem などの接頭辞を使用できます。OpenCode、Pi、Goose、Crush などのプロバイダー対応エージェントでは、provider/model 識別子を使用します。

Claude Code のティアを設定する

Claude Code では、opus、sonnet、haiku、fable などのティアごとに別のモデルを割り当てられます。たとえば、DeepSeek モデルを haiku ティアだけに割り当てるには、次のようにします。

magpie claude haiku deepseek/deepseek-v4-flash

そのティア固有の選択を解除し、Claude Code のメインモデルに戻すには、次のようにします。

magpie claude haiku ""

ゲートウェイモデルを選択すると、Magpie は Claude Code の settings.json 内にある Anthropic のベース URL、トークン、モデル変数を管理します。ネイティブモデルを選択すると、Magpie のゲートウェイ設定が削除され、以前の値が復元されます。

切り替え後にエージェントを再起動する

エージェントは起動時に設定を読み込みます。すでに実行中のセッションでは、再起動して新しいセッションを開始するまで以前のモデルが使われ続けます。

これは、起動時にモデルカタログを読み込む Codex では特に重要です。切り替え後は再起動する必要があります。

プロファイルを保存・復元する

プロファイルには、検出されたすべてのエージェントの現在の設定が保存されます。仕事、実験、ローカル推論、コスト重視のタスクなど、設定を分けて管理するのに便利です。

magpie save work
magpie use work
magpie profiles
magpie rm work

デスクトップアプリケーションでは、プロファイルがメインビュー下部のチップとして表示されます。チップをクリックして適用し、削除コントロールで削除するか、+ save current を選択してプロファイルを作成します。

ターミナルインターフェースでは、s を押すと現在の設定を保存でき、p を押すとプロファイルを適用または削除できます。

サインイン済みのエージェントをプロバイダーとして使う

Magpie は、既存の Claude Code、Codex、Copilot のサブスクリプションをプロバイダーとして公開できます。元のエージェントからサインインすると、利用可能なモデルが magpie providers と他のエージェントのモデル選択画面に表示されます。

  • Claude Code のモデルは、claude/claude-sonnet-5 のような識別子を使用します。
  • Codex のサブスクリプションモデルは、codex/gpt-5.5 のような識別子を使用します。
  • Copilot のモデルは、copilot/claude-sonnet-4.5 のような識別子を使用します。

Magpie は必要に応じてエージェントの既存の認証情報を読み取り、自身のプロバイダーストアにはコピーしません。元のエージェントがトークンを更新した場合、Magpie はそのエージェントの更新処理に従い、エージェントが想定する場所に更新後のトークンを書き込みます。サインアウトすると、対応するプロバイダーが削除されます。

Claude のサブスクリプションを使うには、正規のローカル claude バイナリがインストールされ、サインイン済みである必要があります。Magpie はそのバイナリを実行し、MCP を介して呼び出し元のツールを実行中のターンに接続します。Gemini CLI の Google ログイン対応は予定されていますが、現在は共有プロバイダーとして利用できません。

他のアプリケーションをゲートウェイに接続する

Magpie のゲートウェイはデフォルトで 127.0.0.1:3425 をリッスンし、アプリケーションとともに起動します。ゲートウェイだけを実行するには、次のコマンドを使います。

magpie serve

リッスンするアドレスを変更するには、MAGPIE_ADDR を設定します。デフォルトのループバックバインドにより、ゲートウェイはコンピューター内でのみ利用できます。

サポートされる API エンドポイント

  • OpenAI Chat Completions 用の /v1/chat/completions。
  • OpenAI Responses 用の /v1/responses。
  • Anthropic Messages 用の /v1/messages。
  • Anthropic のトークン数カウント用の /v1/messages/count_tokens。
  • Gemini 生成用の /v1beta/models/{model}:generateContent。ストリーミングとトークン数カウントのバリエーションにも対応します。
  • モデルカタログ用の /v1/models と /v1beta/models。

API キーにはリテラル値 magpie を指定できます。デフォルトではゲートウェイがループバックでリッスンするため、どの値でも機能します。モデルは必ず provider/model 形式で指定してください。

OpenAI 互換環境

export OPENAI_BASE_URL=http://127.0.0.1:3425/v1
export OPENAI_API_KEY=magpie

Anthropic 互換環境

export ANTHROPIC_BASE_URL=http://127.0.0.1:3425
export ANTHROPIC_API_KEY=magpie

Gemini 互換環境

export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425
export GEMINI_API_KEY=magpie

デスクトップアプリケーションの Gateway タブには、シェル、curl、Python、Node 用のコピー可能な設定とスニペットが用意されています。モデル ID と最近の呼び出しも表示されます。

モデルカタログを更新する

Magpie は、設定済みのプロバイダーから実際のモデル一覧を取得します。models.dev カタログは、モデル名、推論レベル、独自のカタログを公開していないプロバイダー向けのフォールバックリストを提供します。

models.dev のデータと、すべての稼働中プロバイダーの一覧を更新するには、完全同期を実行します。

magpie sync

ターミナルインターフェースでは、同じ操作を行うために S を押します。magpie provider models PROVIDER を使えば、1つのプロバイダーだけを更新することもできます。

プロバイダーリンクを安全にインポートする

ベンダーやリレーは、入力済みのプロバイダー定義をインポートリンクで配布できます。Magpieは保存する前に、提案されたプロバイダー名、エンドポイント、接続先ホスト、モデルを表示します。

magpie import 'magpie://import?preset=deepseek&key=sk-…'

カスタムリレーリンクには、OpenAI用とAnthropic用の個別のエンドポイントを含めることができます。

magpie://import?name=Acme%20Relay&chat=https://api.acme.example/v1&anthropic=https://api.acme.example&key=sk-…&models=gpt-5.5,claude-sonnet-5

ユーザーがインポートを確認するまで、何も保存されません。Webページでは、https://usemagpie.ai/import# の後に同じパラメーターを続けて使用できます。値はURLフラグメントに残るため、ブラウザーからWebサイトのサーバーへ送信されることはありません。パラメーターの完全なリファレンスとリンクビルダーについては、Magpieインポートガイドを参照してください。

高度なヒント

公開するモデルを制限する

プロバイダーから返されるすべてのモデルを公開する必要はありません。エージェントのモデル選択欄に表示したいモデルだけを選択してください。これにより、大規模なカタログを管理しやすくし、誤ってモデルを選択するのを防げます。

ゲートウェイの変換を確認する

デバッグログを有効にすると、ゲートウェイが変換する内容を確認できます。

MAGPIE_DEBUG=1 magpie serve

ベンダーが呼び出し元のAPIに対応している場合、リクエストはそのまま通過します。それ以外の場合、Magpieは対応しているストリーミング、ツール呼び出し、推論の動作を維持しながら、リクエストとレスポンスを変換します。

データの保存場所を把握する

  • ~/.config/magpie/profiles.json には保存済みのプロファイルが格納されます。
  • ~/.config/magpie/providers.json には、ファイルモード0600でプロバイダーとそのキーが格納されます。
  • ~/.config/magpie/stash.json には、復元できるよう置き換えられた値が格納されます。
  • ~/.cache/magpie/models.json にはmodels.devのカタログが格納されます。
  • ~/.cache/magpie/models/<provider>.json には、プロバイダーから取得したモデル一覧が格納されます。

MagpieはXDG_CONFIG_HOMEとXDG_CACHE_HOMEを尊重します。

分離した開発用ホームを使用する

コントリビューターは、通常のエージェント設定に触れずに開発ビルドを実行できます。

HOME=/tmp/magpie-home XDG_CONFIG_HOME=/tmp/magpie-home/.config make dev

make dev はinternal/gui/assetsから直接インターフェースを提供し、フロントエンドファイルが変更されると再読み込みします。ゲートウェイはDEV_ADDRを使用し、デフォルトは127.0.0.1:3426なので、通常のMagpieインスタンスと並行して実行できます。パレットを固定するには、MAGPIE_THEME=lightまたはMAGPIE_THEME=darkを設定します。

まとめ

Magpieは、分散していたモデル設定を一貫した1つのワークフローに置き換えます。インストール後、プロバイダーを追加するか既存のエージェントサブスクリプションを使用し、各エージェントのモデルを選択して、便利な組み合わせをプロファイルとして保存できます。また、ローカルゲートウェイを使えば、OpenAI、Anthropic、Gemini互換の他のツールでも同じプロバイダーカタログを共有でき、各アプリケーションにベンダーの認証情報を保存する必要がなくなります。