徹底解説：1つのキーですべてのエージェントを接続、オープンソースのmagpieでAPIゲートウェイを一元化（Claude Code、Codex、Pi、Hermesを例に）

作者注：この記事は、手順どおりに進めれば最後まで完了できるチュートリアルです。読んで実際に試せば、「APIキーは1つ、ゲートウェイアドレスは1つ。インストールしたAgentをまとめて接続」という構成ができあがります。今後モデルを変更したり、APIキーをローテーションしたりするときも、変更するのは1か所だけです。

始める前に、作業内容を確認しましょう

• 目標：パソコン上のすべてのコーディングAgentで、同じAPIキーと同じ上流アドレスを使います（この記事ではClaude Code、Codex、Pi、Hermesの4つを例にします。インストール済みのものを接続してください）
• 所要時間：約30分（登録とネットワーク経由のダウンロード時間を除く）
• 前提条件：APIYIのトークン（OpenAI／Anthropic互換のAPI中継サービス、または公式APIキーでも可）、コマンドラインを使えるパソコン、少なくとも1つのAgentがインストール済みであること
• 難易度：★★☆☆☆。マウス操作とコピー＆ペーストができれば大丈夫です。コマンド入力は不要です。

チュートリアルの流れ

3分でわかる：magpieは何をしているのか

「手順だけ知りたい」という方は、このセクションを読み飛ばしても大丈夫です。ただ、3分だけ目を通しておくと、あとでトラブルが起きたときに原因を見つけやすくなります。

Agentによって、接続先のモデルに求める仕様は大きく異なります。手作業で設定すると、ツールをいくつもインストールするたびに、それぞれの設定を管理しなければなりません。ここでは、よく使われる4つのツールを例に見てみましょう。

magpie（リポジトリ：github.com/yetone/magpie、スローガン：「Every agent’s model. One place.」）は、こうした手間を解消します。「どのAgentにどのモデルを使わせるか」「どのAPIキーを使うか」を一元管理し、各ツールのネイティブ設定に反映します。

役割分担を一言でまとめると、次のとおりです。

• magpieは振り分けを担当：Claude CodeやCodexで使うモデルを決める
• ゲートウェイはプロトコル変換を担当：Anthropic / OpenAI / Geminiの各形式のリクエストを、実際のモデル提供元へ転送する

接続先のゲートウェイは、複数プロトコルに対応しているのが理想

理想的な組み合わせは、「magpieが振り分けを担当し、ゲートウェイがプロトコルを担当する」形です。ゲートウェイがOpenAI互換形式にしか対応していない場合、Claude Codeを使うには別途プロトコル変換を挟む必要があります。経路が長くなるうえ、ツール呼び出しの形式に不整合が起きる可能性も高まります。

APIYIでは、1つのトークンで3つの主要プロトコルに対応しています。OpenAI互換、Anthropicネイティブ、Gemini形式のいずれも、同じAPIキーで呼び出せます（対応範囲の詳細はコンソールの案内をご確認ください）。magpieの接続先を1つにまとめられるため、すべてのAgentを直接接続でき、モデル提供元ごとにアカウントや請求を管理する必要もありません。

3つの方法を比較

手動設定は最もシンプルですが、ツールが増えるとAPIキーが複数のファイルに分散し、ローテーションやトラブルシューティングの手間が増えます。環境変数スクリプトなら依存関係なしで数十行ほどで済みますが、Agentごとに異なるモデルを割り当てることはできません。「Claude CodeにはClaude、CodexにはGPT、Hermesには低コストのモデル」といった使い分けには、magpieのような一元管理の仕組みが便利です。

ステップ 1：キーを取得してコピーするだけ

1.1 APIYIのコンソールでトークンを作成する

APIYIのコンソール（apiyi.com）でトークンを作成し、コピーします。

このステップでは、コマンドを入力する必要はありません。 このあとの手順でキーを使うのは一度だけです。ステップ3で、magpieの「プロバイダー」パネルに貼り付けます。貼り付けると、各Agentの設定ファイルは自動で作成されます。環境変数を export したり、config.toml や settings.json などを編集したりする必要はありません。

🚀 まだトークンをお持ちでない方へ：APIYI（apiyi.com）に登録して、まずはテスト枠を利用できます。トークンを1つ使って、普段使うツールをいくつか動かしてみてから、長く使うモデルを選ぶのがおすすめです。

1.2 2つのURLを手元に控える

ステップ3でプロバイダーを設定するときに、用途に合ったURLを入力します。

✅ このステップの完了条件：トークンをクリップボードにコピーし、ステップ3でどちらのURLを入力すればよいか確認できていること。

ステップ 2：magpieをインストールして、2つの画面を確認する

magpieのソースコード、インストール方法、設定形式については、公式リポジトリのREADME（github.com/yetone/magpie）を参照してください。プロジェクトの更新は比較的頻繁で、インストールコマンドやフィールド名がバージョンによって変わる場合があります。一方、以下で紹介する画面と操作の流れは、長く使える部分です。

インストールして起動すると、左側にナビゲーションがあるウィンドウが表示されます。このチュートリアルで使うのは、Agent（どのAgentがどのモデルを使うか）とプロバイダー（キーを登録する場所）の2つの画面だけです。

① 左側のナビゲーションにある Agent は、すべてのAgentを管理する「メインパネル」です。

図1 · Agentページ：ツールごとに1行で表示され、右側のスイッチでmagpieへの接続を切り替えます。スイッチの横にあるドロップダウンでモデルを選択できます。

この画面では、次の3つを確認しましょう。

② 左側のナビゲーションにある プロバイダー は、上流サービスのキーを登録する場所です（詳しくは次のセクションで説明します）。

magpieの設定ファイルの形式を先に把握しておきたい場合は、公式READMEの providers／agents の構造を見てみるとよいでしょう。大まかには、「上流サービスに名前を付け、base_urlとキーを設定し、各Agentに使うモデルを割り当てる」という仕組みです。ただし、普段の操作はすべてウィンドウ上で行えます。magpieが各ツールのネイティブ設定を作成してくれるため、YAMLを手作業で編集するより安心です。

✅ このステップの完了条件：ウィンドウが開き、左側に「Agent」と「プロバイダー」が表示されていること。

ステップ 3：「プロバイダー」にAPIキーを登録する

3.1 プロバイダーページを開く

左側の プロバイダー（図 2 の赤枠①）をクリックし、ページを開いたら右上の + プロバイダーを追加（赤枠②）をクリックします。

図 2 · プロバイダーページ：左側のナビゲーションから「プロバイダー」を開き、右上の「+ プロバイダーを追加」をクリックします

登録済みのプロバイダーは、カード形式でここに表示されます。カードの2行目には、接続先のアドレスと利用可能なモデル数（例：api.apiyi.com · 11 個のモデル）が表示されます。実際に使えるか確認するときは、まずこの行に数字が表示されているかを見てください。

3.2 どの種類のプロバイダーを選ぶか

「+ プロバイダーを追加」をクリックすると、いくつかのグループに分かれた選択パネルが表示されます（図 3）。

図 3 · プロバイダー追加パネル：サブスクリプション、プロバイダー、中継、ローカル、別のコンピューター上の magpie の5種類

パネル内のグループは、APIキーの種類に応じて5つに分かれています。

APIYI を使う場合、OpenAI 互換エンドポイントは標準的な中継サービスとして利用できます。中継グループから該当する項目を選んでください。OpenAI / Anthropic 互換のカスタムAPIキーを使う場合は、一番下の + カスタムプロバイダー（図 3 の赤枠）をクリックして、接続先アドレスとAPIキーを入力します。アドレスには https://api.apiyi.com/v1 を入力してください（Anthropic ネイティブのリクエストの場合は https://api.apiyi.com）。

こちらがプロバイダーを開いたときの設定画面です。関係するのは次の4項目です。

図 4 · APIYI プロバイダーの設定画面：Base URL でプロトコルを選んでからアドレスを入力し、Accounts にAPIキーを登録、Models で Agent に公開するモデルを選びます

この画面を見ると、「1つのトークンで複数のプロトコルを使える」という説明がよくわかります。アドレスはどれも https://api.apiyi.com です。Anthropic 互換を選ぶと Claude Code 用のネイティブエンドポイントに、OpenAI 互換を選ぶと Codex / Pi / Hermes 用の /v1 エンドポイントに接続できます。Gemini 互換も同様です。プロバイダーを3つ登録したり、APIキーを3つ管理したりする必要はありません。

入力して保存したら、プロバイダー一覧に戻って2点を確認します。カードの2行目にモデル数が表示されていること、そしてスイッチがオンになっていることです。· N 個のモデル と表示されていれば、APIキーとアドレスが正しく接続されています。これで設定の確認もできるため、別途コマンドを実行する必要はありません。

✅ このステップの確認：プロバイダー一覧に自分のカードが表示され、· N 個のモデル のようにモデル数が表示されていること。「未設定」と表示されていないことを確認します。

ステップ 4：インストール済みの Agent を1つずつ接続する

Agent ページに戻り、インストール済みの各ツールについて、同じ3つの操作を行います。このページには、magpie が接続できるすべての Agent が表示されます（対応 Agent は順次追加されています）。インストールされていないツールには「CLI が見つかりません」と表示されます。インストールしたツールだけ接続すれば大丈夫です。下の表では、よく使われる4つのツールを例にしています。

1. 右側のスイッチをオンにする（グレーから点灯状態に切り替わります）
2. スイッチの右側でモデルを選ぶ（選ばない場合はデフォルトが使われます。ここで選んだモデルは、そのツールの設定に反映されます）
3. 案内に従ってツールを再起動する（Codex、Claude Code、Pi、Hermes は、新しい設定を読み込むためにプロセスの再起動が必要な場合がほとんどです）

図 5 · モデル選択メニューを開いた状態：最初の「デフォルト」を選ぶと、その Agent に組み込まれているモデルが使われ、magpie は経由しません。その下の各項目には「magpie 経由」と表示され、選んだモデルが上流プロバイダーの接続先として使われます

よくあるステータスを紹介します。次のように表示されていれば、設定は正しい方向に進んでいます。

• 接続済み：設定は書き込み済みです。ツールを再起動すると反映されます
• 未接続 · XXX 独自の設定を使用：スイッチがオフか、モデルが選択されていません
• XXX 独自のモデルのみ利用可能。magpie は接続できません：Cursor など、このツールが独自のモデルのみを許可している状態です。設定ミスではなく、仕様上の制限です
• CLI が見つかりません：ツールがインストールされていないか、PATH に含まれていません。インストールするか、PATH を設定してから、もう一度試してください

💡 Agent ごとに異なるモデルを設定することもできます（Claude Code には Claude、Codex には GPT、Hermes には低コストのモデルなど）。このステップで各 Agent にモデルを割り当ててください。これが、magpie が「環境変数を設定するスクリプト」よりも便利な点のひとつです。

✅ このステップの確認：インストール済みツールのスイッチがすべてオンになり、ステータス欄が「未接続」ではなくなっていることを確認します。

ステップ5：各エージェントで一文ずつ実行して動作確認

設定を書いただけでは完了ではありません。実際に動かして確認しましょう。各ツールで、最も簡単なタスクを一つ実行します。

リクエストが実際にゲートウェイを経由しているか確認するには、APIYIのコンソールで、このトークンの使用状況やログを確認するのが手軽です。新しい呼び出し記録があれば、すべてのエージェントのリクエストが同じキーに集約されていることを確認できます。

✅ このステップの完了条件：すべてのエージェントが正常に応答し、コンソールに対応する呼び出し記録が表示されること。

補足：モデルの選び方（迷ったときのデフォルト）

💡 同じタスクを複数のエージェントとモデルで実行してみるのがおすすめです。共通のトークンを使えば、モデル名を変えるだけで切り替えられるため、コストを簡単に比較できます。

第 6 歩（任意）：magpie が実際に設定している内容

このセクションは動作確認には影響せず、必須の手順でもありません。普段使う分には、これらのファイルを触る必要はありません。第 4 歩でスイッチをオンにした時点で、magpie が以下の内容をすでに設定しています。ここで紹介するのは、問題が起きたときにどの層を確認すればよいか分かるようにするためと、いつか magpie を使わなくなったときに、そのまま設定を流用できるようにするためです。

Claude Code：ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_BASE_URL="https://api.apiyi.com"   # Anthropic のネイティブエンドポイント
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# 任意：デフォルトモデルを指定（コンソールのモデル一覧を確認してください）
# export ANTHROPIC_MODEL="<Claude モデル名>"
claude

~/.claude/settings.json の env フィールドに記述することもできます。そうすれば、ターミナルのセッションに依存しません。

Codex：~/.codex/config.toml の provider セクション

# ~/.codex/config.toml
model = "<GPT 系モデル名>"
model_provider = "apiyi"

[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1"   # OpenAI 互換エンドポイント
env_key = "APIYI_API_KEY"
wire_api = "responses"                   # 選択したモデルが Responses に対応していない場合は "chat" に変更

wire_api は特につまずきやすいポイントです。新しいバージョンの Codex はデフォルトで Responses プロトコルを使用します。ゲートウェイ側でそのモデルが Chat Completions のみをサポートしている場合は、chat に変更する必要があります。

Pi と Hermes：カスタムの OpenAI 互換 provider を定義する

基本的な考え方は同じです。base_url に https://api.apiyi.com/v1 を指定し、Key は APIYI_API_KEY を参照します。設定の構造はバージョンによって異なるため、各ツールの公式ドキュメントを確認してください。

// Pi：カスタムモデル設定で provider を定義（構造は Pi の公式ドキュメントを参照）
{
  "providers": {
    "apiyi": {
      "baseUrl": "https://api.apiyi.com/v1",
      "api": "openai-completions",
      "apiKey": "APIYI_API_KEY",
      "models": [{ "id": "<モデル名>" }]
    }
  }
}

# Hermes：hermes model を実行し、カスタムの OpenAI 互換エンドポイントを選択します。
# 画面の指示に従って以下の情報を入力します（または Hermes の設定ディレクトリにある .env / config に記述します）。
#   Base URL : https://api.apiyi.com/v1
#   API Key  : $APIYI_API_KEY
#   Model    : <モデル名>

#!/usr/bin/env bash
# agents-env.sh —— magpie を使わない場合の代替手段：1つの Key ですべての Agent を利用
# 使い方：source agents-env.sh
: "${APIYI_API_KEY:?先に export APIYI_API_KEY を実行してください}"

# Claude Code（Anthropic プロトコル）
export ANTHROPIC_BASE_URL="https://api.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"

# Codex / Pi / Hermes など、OpenAI 互換ツールで共通の変数
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"

# 接続確認
curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ すべての Agent が同じゲートウェイを参照しています"

curl -s "https://api.apiyi.com/v1/models" \
  -H "Authorization: Bearer sk-あなたのトークン" | head -c 300

問題が起きたらまず確認：よくある4つのエラー

確認は必ず下位の層から上位の層へ進めてください。まずゲートウェイとトークンが正常か（プロバイダーカードに · N 個のモデル と表示されているか）を確認し、次に各 Agent のネイティブ設定、最後に magpie のマッピング層を確認します。この3段階で、問題が上流、ツール本体、統一設定のどこにあるかを切り分けられます。

よくある質問（FAQ）

5分でわかる要点

• 役割分担：magpieはモデルの割り当てを管理し、ゲートウェイはプロトコルに応じてリクエストを転送します。それぞれが一つの役割に専念します。
• キーは1つ：複数のプロトコルに対応した上流サービスを選べば、すべてのエージェントで同じキーと請求を利用できます。
• 設定の手順：コンソールでキーを作成 → 「プロバイダー」に貼り付け → Agentのスイッチをオン → 一つずつ動作確認（すべて画面上の操作で完結し、コマンドは不要です）
• トラブルシューティングの順序：ゲートウェイ → エージェントのネイティブ設定 → magpieのマッピング層の順に、下から確認します。
• Claude Codeのポイント：ANTHROPIC_AUTH_TOKEN を使い、base_urlの末尾に /v1 を付けません。
• Codexのポイント：wire_api は、モデルが対応するプロトコルと一致させる必要があります。
• 代替方法：環境変数を設定するスクリプト（agents-env.sh）を使っても、すべてのエージェントで同じキーを共有できます。

3つ以上のエージェントを使っているなら、30分ほどかけてこの設定を整えておく価値があります。モデルを切り替えたり、キーをローテーションしたりするときも、一か所を変更するだけで済みます。APIYI（apiyi.com）でテスト用クレジットを受け取り、まずは普段使うツールをいくつか動かしてみましょう。その後、用途に応じて各エージェントのモデルを割り当てるのがおすすめです。

関連記事

• 📘 Workbuddy は Claude のネイティブ形式で呼び出せる？3つの原因と6種類の content エラーを実測で検証：Anthropic のネイティブ形式と OpenAI 互換形式の違いを知りたい方は、こちらをご覧ください。この記事のステップ2「Claude Code はネイティブエンドポイントを使う必要がある」理由も解説しています。
• 📊 claude-sonnet-5-5 と claude-opus-5-5 を比較：Opus は速く、Sonnet は安いだけ？6つのデータで企業向け長文脈 Agent の最適な組み合わせを解説：ステップ4で Agent ごとにモデルを割り当てる前に、こちらをご覧ください。どの Agent に Opus を使い、どれに安価なモデルを使うか判断できます。
• ⚠️ gemini-4-argon AI Studio の同時実行数は？429エラーが頻発する5つの原因と6ステップの解決策：複数の Agent が同じ Key を同時に使ってレート制限に達した場合は、こちらの6ステップで原因を確認できます。
• 🧭 OpenAI で model not found エラーが発生？GPT-5.5 は10月14日に ChatGPT から提供終了、5ステップの確認方法と代替案：ステップ5の検証時に「モデルが存在しない」と表示されたら、まずそのモデル名がまだ有効か確認してください。

📚 参考資料

1. GitHub – magpie：プロジェクト公式リポジトリ
2. リンク： github.com/yetone/magpie
3. 説明：インストール方法、設定形式、バージョン更新については、README をご確認ください。
4. Claude Code 公式ドキュメント：環境変数と settings の設定
5. リンク： docs.anthropic.com/en/docs/claude-code
6. 説明：ANTHROPIC_BASE_URL などの変数に関する公式情報です。
7. OpenAI Codex CLI リポジトリ：config.toml と model_providers の設定
8. リンク： github.com/openai/codex
9. 説明：カスタム provider と wire_api パラメーターについて説明しています。
10. APIYI ドキュメントセンター：複数のプロトコルに対応したエンドポイントとモデル一覧
11. リンク： docs.apiyi.com
12. 説明：OpenAI / Anthropic などのプロトコルを利用する方法を解説しています。

著者：APIYI 技術チーム
技術交流：magpie の設定例をコメント欄でぜひ共有してください。詳しい接続資料は、APIYI docs.apiyi.com のドキュメントセンターをご覧ください。