Magpie AI ゲートウェイをセルフホスト：Claude Code や Codex などのエージェントでモデルを自由に切り替える

Claude Code は標準で Anthropic のモデルを、Codex は OpenAI のモデルを呼び出します。Claude Code で DeepSeek を試したいときや、あるプロバイダーの利用枠が尽きたときに別のプロバイダーへ移りたいときは、ツールごとに設定ファイルのアドレスとキーを書き換える必要があります。

Magpie は、この手間をなくすためのオープンソース（MIT ライセンス）の AI ゲートウェイです。プロバイダーを Magpie に接続すれば、エージェントは Magpie のアドレスだけを知っていれば済みます。OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini の各形式に対応し、形式間の変換も行うため、Claude Code から Anthropic 以外のモデルも使えます。ほかにも次の機能があります。

• フェイルオーバーとルーティンググループ：モデルがエラーを返したり利用枠が尽きたりすると、予備のモデルや別のアカウントに自動で切り替わり、エージェント側にはエラーが見えません。
• 使用量とコスト：トークン数、キャッシュヒット率、推定コストをモデル別・クライアント別に集計します。
• ゲートウェイキー：クライアントごとに専用のキーを発行し、利用枠と使えるモデルを個別に設定できます。

Magpie は通常、自分のパソコンにインストールして使います。この記事では Zenavo の Magpie テンプレートでサーバーにデプロイし、ノートパソコン、デスクトップ、チームメンバーのパソコンで同じ設定を共有します。チーム全体にメンバーごとの API キーと利用枠を配りたい場合は、New API も参考にしてください。New API はチームの API キーを一元管理するためのもの、Magpie は各エージェントが好きなモデルを選べるようにするためのものです。

サーバー、Zenavo、モデル API の料金はそれぞれ別に発生します。Magpie はリクエストを転送して集計するだけで、モデルの呼び出しが安くなるわけではありません。

Magpie をデプロイする

まず Zenavo に Linux サーバーを接続し、Magpie テンプレートを開いて、サーバーを選んでデプロイします。

現在のテンプレートの設定は次のとおりです。

設定	値・用途
イメージ	ghcr.io/yetone/magpie:latest
起動コマンド	web --addr 0.0.0.0:3430 --no-open（ブラウザ管理画面を起動）
HTTP ポート	3430。管理画面とエージェントが呼び出す API の両方がこのポートを使います
永続ボリューム	/config。プロバイダー、ゲートウェイキー、サインイン情報、使用量の記録を保存します
MAGPIE_WEB_KEY	プロジェクト作成時に自動生成される、管理画面へのサインイン用キー
メモリ	512 MB を推奨

latest は上流の更新に追従します。長く使う前に、サービスの Settings にある Source で、動作を確認した固定バージョンのタグか、Magpie が週に1回更新する stable チャネルに変更してください。

ドメインを設定してサインインする

magpie サービスの Networking タブで、ポート 3430 にドメイン（例：magpie.example.com）を割り当てます。DNS にサーバーを指す A レコードを追加し、HTTPS が有効になるのを待ちます。手順はドメインのドキュメントをご覧ください。

次に、magpie サービスの Variable タブで MAGPIE_WEB_KEY の値をコピーし、https://magpie.example.com を開いて、画面の指示に従ってキーを貼り付けます。ブラウザはサインイン状態を保持します。

このキーは Magpie の管理者パスワードと同じです。 持っている人はすべての設定を変更でき、登録したプロバイダーのキーも見られます。そのため、

• モデルを呼び出すだけの人には渡さないでください。その人に必要なのは、後述のゲートウェイキーです。
• スクリーンショット、チャット、リポジトリに含めないでください。
• 漏れた可能性があるときは、Variable で新しいランダムな値（英数字と - . _ ~ で16文字以上）に変更し、保存してサービスを再起動してください。

Magpie の公式ドキュメントは、管理画面を自分のパソコン内か VPN の中に置くことを推奨しています。公開ドメインで使う場合、管理画面を守るのはこのキーだけなので、上記のとおり厳重に管理してください。

公開アドレスを設定する

Variable に MAGPIE_PUBLIC_URL を追加し、値を https://magpie.example.com にして保存し、再起動します。Magpie はコンテナ内で動くため、コンテナ自身の内部アドレスしか分かりません。この変数を設定すると、画面に表示される接続先や設定例が自分のドメインになります。

プロバイダーを追加する

管理画面の Providers ページでプロバイダーを追加します。Anthropic、OpenAI、Google Gemini、DeepSeek、Kimi、Zhipu GLM、Qwen、Mistral、xAI、OpenRouter などのプリセットがあり、OpenAI 互換または Anthropic 互換の任意の URL も使えます。プロバイダーの API キーを入力して保存し、モデル一覧に使えるモデルが表示されることを確認します。

Magpie のモデル名は プロバイダー/モデル の形式です（例：deepseek/deepseek-v4-pro）。ルーティンググループを作ることもできます。複数のモデルをまとめ、順番に、交互に、または使用量に応じてリクエストを振り分け、エラーが出たら次のモデルに移ります。エージェントからはグループ名をモデル名として指定します。

Claude や ChatGPT などのサブスクリプションをプロバイダーとして使うこともできます。サーバー上でサインインするには追加の手順が必要で、Magpie の Docker ドキュメントに説明があります。先に各プロバイダーの利用規約を確認してください。個人のサブスクリプションは通常本人専用なので、ゲートウェイを通じて他人と共有しないでください。

ゲートウェイキーを発行する

サーバー上の Magpie は、有効なゲートウェイキーが付いたリクエストだけを受け付け、キーのないリクエストには 401 を返します。管理画面で Gateway → Gateway keys を開き、パソコンごと・人ごとにキーを作成してコピーします。キー全体が表示されるのは作成時だけです。

キーごとに次の設定ができます。

• 利用枠：日・週・月・合計ごとのトークン数と推定コスト
• 使えるモデル：例えば deepseek/* だけ
• 有効・無効：キーが漏れたら、他のクライアントに影響を与えず、上流プロバイダーのキーも変えずに、無効化またはローテーションできます

ゲートウェイキーを受け取った人は https://magpie.example.com/me を開いて自分のキーを入力すると、自分の利用枠、使用量、使えるモデル、Claude Code と Codex 用のコピーできる設定例を確認できます。他のキーやプロバイダーは見えません。

Claude Code から接続する

自分のパソコンで次を設定します。

export ANTHROPIC_BASE_URL="https://magpie.example.com"
export ANTHROPIC_AUTH_TOKEN="Magpie で作成したゲートウェイキー"
export ANTHROPIC_MODEL="deepseek/deepseek-v4-pro"
claude

ANTHROPIC_BASE_URL はドメインだけを書き、/v1 は付けません。Claude Code が /v1/messages を付け足します。ANTHROPIC_MODEL は Magpie に表示されるモデル名かルーティンググループ名に置き換えてください。Claude Code の中で /model を使って切り替えることもできます。また、Claude Code から MCP や Skills を使って Zenavo サービスのログ確認、デプロイ、ロールバックまで行いたい場合は、Claude Code から Zenavo プロジェクトをデプロイ・デバッグするもご覧ください。

Codex CLI から接続する

Codex CLI では ~/.codex/config.toml にカスタムプロバイダーを定義します。

model = "deepseek/deepseek-v4-pro"
model_provider = "magpie"

[model_providers.magpie]
name = "magpie"
base_url = "https://magpie.example.com/v1"
model_catalog_url = "https://magpie.example.com/v1/codex/models"
env_key = "MAGPIE_API_KEY"
wire_api = "responses"
supports_websockets = false

ターミナルで export MAGPIE_API_KEY="ゲートウェイキー" を設定してから codex を起動します。Claude Code とは違い、ここの base_url には /v1 を付けます。model_catalog_url を設定すると、Codex はこのキーで使えるモデル一覧を Magpie から読み込みます。

そのほかの OpenAI 互換 Web UI やクライアント（セルフホストした Open WebUI や LobeHub など）では、Base URL に https://magpie.example.com/v1、API キーにゲートウェイキーを指定します。

バックアップとアップグレード

/config ボリュームには、プロバイダーの API キー、サブスクリプションのサインイン情報、ゲートウェイキーが含まれます。バックアップはキーそのものと同じように厳重に管理してください。

メンテナンスの時間帯にプロジェクトを停止し、magpie サービスの Backup & Restore タブでボリュームをバックアップしてから、プロジェクトを起動し、コピーをダウンロードして保管します。アップグレードの前には Magpie のリリースノートを読み、バックアップを取ってからイメージのバージョンを変更してください。

よくある質問

エージェントが 401 を返す リクエストにゲートウェイキーが付いていないか、キーが無効になっています。サーバー上の Magpie は、ローカル版で使える仮の magpie キーを受け付けません。MAGPIE_WEB_KEY ではなくゲートウェイキーを使っているかも確認してください。

Claude Code が 404 を返す、または接続できない ANTHROPIC_BASE_URL の末尾に余分な /v1 が付いていないか確認してください。

モデルが存在しない、または拒否される（403） モデル名は プロバイダー/モデル の形式で、このゲートウェイキーで使えるモデルである必要があります。キーを付けて https://magpie.example.com/v1/models にリクエストすると、使えるモデルの一覧が分かります。

コードは誰に送られますか？ リクエストの内容は、選んだ上流プロバイダーに送られます。ゲートウェイを自分のサーバーに置いても、データがそこに留まるわけではありません。Magpie には任意のプライバシーマスキング機能があり、キー、パスワード、メールアドレスを送信前にプレースホルダーに置き換えます。Settings → Privacy で有効にできます。Magpie は1日1回、匿名の統計（プロンプト、キー、使用量は含みません）を送信します。同じページでオフにするか、Variable で DO_NOT_TRACK=1 を設定してください。

小さなサーバーで足りますか？ Magpie 自体は軽量で、テンプレートは 512 MB のメモリを推奨しています。負荷の大部分は同時に流れるストリーミングリクエストから来るため、複数人で長時間使う場合はサーバーのメモリと帯域に注意してください。

Magpie テンプレートから始めましょう。ドメインを設定してサインイン用キーを安全に保管し、プロバイダーを追加してゲートウェイキーを配り、Claude Code と Codex の接続先にします。