---
title: "Magpie AI ゲートウェイをセルフホスト：Claude Code や Codex などのエージェントでモデルを自由に切り替える"
description: "Zenavo で Magpie を自分のサーバーにデプロイし、DeepSeek、Kimi、Anthropic、OpenAI などのプロバイダーを1か所で管理します。パソコンごとにゲートウェイキーを発行し、Claude Code と Codex CLI から接続する方法を説明します。"
date: 2026-11-12
language: ja-JP
url: https://zenavo.app/ja-JP/blog/self-host-magpie
---

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

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

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

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

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

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

## Magpie をデプロイする

まず Zenavo に [Linux サーバーを接続](https://docs.zenavo.app/ja-JP/servers/add-a-server)し、[Magpie テンプレート](https://zenavo.app/deploy?template=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 が有効になるのを待ちます。手順は[ドメインのドキュメント](https://docs.zenavo.app/ja-JP/networking/domains)をご覧ください。

次に、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 ドキュメント](https://usemagpie.ai/docs/docker)に説明があります。先に各プロバイダーの利用規約を確認してください。個人のサブスクリプションは通常本人専用なので、ゲートウェイを通じて他人と共有しないでください。

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

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

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

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

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

## Claude Code から接続する

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

```bash
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 プロジェクトをデプロイ・デバッグする](https://zenavo.app/ja-JP/blog/claude-code-deploy-debug)もご覧ください。

## Codex CLI から接続する

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

```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](https://zenavo.app/ja-JP/blog/self-host-open-webui) や [LobeHub](https://zenavo.app/ja-JP/blog/self-host-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 テンプレート](https://zenavo.app/deploy?template=magpie)から始めましょう。ドメインを設定してサインイン用キーを安全に保管し、プロバイダーを追加してゲートウェイキーを配り、Claude Code と Codex の接続先にします。