> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Magpie

> デスクトップインターフェースからMagpieをAPIYIに接続し、CodexとClaude Codeのモデル、API URL、キーを設定する方法と、CLIの例を使ったトラブルシューティングを説明します。

## MagpieとAPIYIの接続方法

Magpieは、AIコーディングツール向けにモデルとプロバイダーを管理するオープンソースアプリケーションです。MagpieにAPIYIを追加すると、Codex、Claude Codeなどのツールで使用するモデルを1つのインターフェースから選択できます。Magpieは各ツールの設定ファイルに設定を書き込みます。

リクエストは、APIYIに到達する前にローカルゲートウェイを経由します。

```text theme={null}
Coding tool → Magpie gateway → APIYI → Model
```

Magpieの**プロバイダー設定**にAPIYIのURLと実際のAPIキーを入力します。Magpieがコーディングツールをローカルゲートウェイに接続します。ローカルゲートウェイはデフォルトで`127.0.0.1:3425`をリッスンします。ツールを使用している間はMagpieを起動したままにしてください。

プロジェクト: `github.com/yetone/magpie`、公式のスタートガイド: `usemagpie.ai/docs/start`。

## 開始する前に

1. `usemagpie.ai` から macOS、Windows、または Linux 用のデスクトップアプリをダウンロードし、インストールして起動します。
2. 使用するコーディングツールをインストールします。[Codex 設定ガイド](https://docs.apiyi.com/ja/scenarios/programming/codex-cli.md) または [Claude Code 設定ガイド](https://docs.apiyi.com/ja/scenarios/programming/claude-code.md) のインストールセクションを参照してください。
3. [APIYI token ページ](https://api.apiyi.com/token) で APIキーを準備します。アカウントに利用可能な残高があり、token から選択したモデルにアクセスできることを確認してください。

このガイドでは、2つのプロバイダーエントリ、**APIYI** と **APIYI Claude** を扱います。コーディングツールを1つだけ使用する場合は、対応するエントリだけを設定してください。両方のエントリを作成するには、**2つの異なる token** を使用します。1つ目のエントリには GPT モデルにアクセスできる token を、2つ目のエントリには `ClaudeCode` グループの token を使用してください。Magpie は、同じホストで同じキーを使用する設定を重複したプロバイダーとして扱います。

> [!NOTE]
>
> Magpie は、ターミナルの APIキー環境変数を自動的に読み取りません。プロバイダーフォームにキーを貼り付けるか、以下の CLI コマンドで追加してください。

## デスクトップインターフェースで設定する

### Codex用のプロバイダーを設定する

**1. カスタムプロバイダーを追加する**

**プロバイダー → プロバイダーを追加 → カスタムプロバイダー**を開き、次の値を入力します。

| フィールド | 値 |
| - | - |
| 名前 | `APIYI` |
| 主要プロトコル | **OpenAI互換** |
| ベースURL | `https://api.apiyi.com/v1` |
| APIキー | GPTモデル用のAPIYIトークン |

URLは`/v1`で終わるようにします。Magpieがリクエストパスを追加するため、完全な`/chat/completions`パスは入力しないでください。

**2. GPTモデル用のResponsesエンドポイントを追加する**

**その他のエンドポイント**を展開し、**Responses URL**に`https://api.apiyi.com/v1`を設定します。

このガイドでは`gpt-5.4`を使用します。これはAPIYI上でChat CompletionsとResponsesの両方をサポートしています。CodexはMagpie経由でこのモデルにアクセスする際、Responsesエンドポイントを使用できます。

APIYIが選択したモデルのそのプロトコルをサポートしている場合にのみ、エンドポイントを設定してください。MagpieのローカルゲートウェイでResponsesがサポートされていても、APIYI上のすべてのモデルがネイティブResponsesをサポートするとは限りません。

**3. モデルを取得して選択する**

**モデルを取得**をクリックし、モデル一覧から`gpt-5.4`を選択して、プロバイダーを保存します。

初期設定ではこのモデルだけを選択してください。他のGPTモデルを追加する前に、APIYI上で同じエンドポイントをサポートしていることを確認します。画像モデル、embeddingモデル、その他の非チャットモデルをコーディングツールのモデル一覧に追加しないでください。

必要なモデルが一覧にない場合は、**モデル**で正確なモデルIDを手動で追加します。プロバイダーのモデルフィールドには、`apiyi/`プレフィックスを付けずに`gpt-5.4`を入力します。

### Claude Code用のプロバイダーを設定する

`ClaudeCode`グループの別のトークンを使用して、別の**カスタムプロバイダー**を追加します。

| フィールド | 値 |
| - | - |
| 名前 | `APIYI Claude` |
| 主要プロトコル | **Anthropic互換** |
| ベースURL | `https://api.apiyi.com` |
| APIキー | `ClaudeCode`グループの別のAPIYIトークン |
| モデル | `claude-sonnet-4-6` |

このURLには\*\*`/v1`が含まれていません\*\*。Magpieが`/v1/messages`を追加します。モデルを取得したら、使用する予定のClaudeモデルだけを選択します。`claude-sonnet-4-6`を手動で入力してから保存することもできます。

> [!TIP]
>
> プロバイダーエントリを分けることで、モデル、プロトコル、トークングループを個別に管理できます。`ClaudeCode`グループの詳細については、[トークングループ](https://docs.apiyi.com/ja/faq/groups-explained.md)を参照してください。

### 各コーディングツールのモデルを選択する

1. **エージェント**を開き、インストール済みの**Codex**または**Claude Code**ツールを見つけます。
2. ツールで現在選択されているモデルをクリックし、追加したプロバイダーの下にあるモデルを見つけて選択します。Codexでは**APIYI → gpt-5.4**、Claude Codeでは**APIYI Claude → claude-sonnet-4-6**を選択します。
3. ツールの古いセッションを閉じて再起動し、新しいセッションを開きます。これにより、Magpieが書き込んだ設定が読み込まれます。

Magpieは内部でモデルを`provider-id/model-id`として識別します。たとえば`apiyi/gpt-5.4`です。プロバイダーフォームに入力する生のモデルIDと、エージェントで選択する完全な識別子は、それぞれ異なる目的で使用されます。

> [!NOTE]
>
> Magpieは、管理対象のツール用にAPI設定を書き込みます。トラブルシューティングの際は、既存の環境変数、プロジェクト設定、その他の設定マネージャーも確認し、以前のサービスURLが復元されていないことを確認してください。

## 接続を確認する

まずプロバイダーページでテストを実行し、次にコーディングツールから短いリクエストを送信します。例:

```text theme={null}
Reply with only: Connection successful.
```

返信を受け取ったら、Magpie のリクエストまたは使用状況の記録と、[APIYI コンソール](https://api.apiyi.com)の呼び出しログを確認します。リクエストで意図したモデルとプロバイダーが使われたことを確認してください。その後、普段のコーディングワークフローを検証するため、プロジェクト内の小さなファイルについてツールに説明を依頼します。

**モデルの取得に成功しても、モデル一覧のエンドポイントに接続できたことしか確認できません。** チャットリクエストには、対応するモデル、token の権限、リクエストプロトコルも必要です。プロバイダーのテストでは少数の実際の API リクエストが送信され、モデルの使用量に応じて課金されます。

## CLI で設定する

ターミナルを使う場合は、インターフェースからプロバイダーを追加する代わりに、次のコマンドを使用します。まず、`magpie` コマンドがインストールされていることを確認し、デスクトップアプリを起動したままにしてください。

> [!NOTE]
>
> インターフェースからすでにプロバイダーを作成している場合は、`provider add` を再実行しないでください。`magpie providers` を実行して実際のプロバイダー ID を確認し、テストまたはモデル選択のコマンドでその ID を指定してください。インターフェースから作成した ID はプロバイダー名に基づいて生成されます。コマンドで特定の ID を指定するには `id=` を使用します。ID がすでに使用されている場合、Magpie は末尾にサフィックスを追加することがあります。そのため、CLI からプロバイダーを追加した後も、実際の ID を確認してください。

### 2 つのプロバイダーを追加する

最初のコマンドの `sk-your-api-key` を、GPT モデル用の token に置き換えてください。

```bash theme={null}
magpie provider add APIYI id=apiyi url=https://api.apiyi.com/v1 responses=https://api.apiyi.com/v1 key=sk-your-api-key models=gpt-5.4
```

2 つ目のコマンドの `sk-your-api-key` を、`ClaudeCode` グループの別の token に置き換えてください。

```bash theme={null}
magpie provider add "APIYI Claude" id=apiyi-claude anthropic=https://api.apiyi.com key=sk-your-api-key models=claude-sonnet-4-6
```

### モデルを一覧表示してツールを接続する

```bash theme={null}
magpie providers
magpie models
magpie codex model apiyi/gpt-5.4
magpie claude model apiyi-claude/claude-sonnet-4-6
```

インストール済みで設定したいツールのコマンドだけを実行し、そのツールで新しいセッションを開始してください。これらのコマンドは設定を更新します。ツールを使用するときは、Magpie ゲートウェイを引き続き実行しておく必要があります。

### 上流プロバイダーとローカルゲートウェイをテストする

```bash theme={null}
magpie provider test apiyi
magpie provider test apiyi-claude
magpie healthcheck
```

`provider test` は、設定済みの上流エンドポイントに少数の実リクエストを送信します。`healthcheck` はローカルゲートウェイのみを確認するため、それだけでは APIYI へのモデルリクエストが機能することを確認できません。

## トラブルシューティング

> **認証に失敗し、401 または 403 が返される**
>
> Magpie プロバイダーに保存されている API キーが完全で有効であること、APIYI アカウントに利用可能な残高があること、token が対象モデルにアクセスできることを確認してください。Claude Code の設定には、`ClaudeCode` グループの token を使用してください。ターミナルの環境変数を変更しても、Magpie にすでに保存されているキーは自動更新されません。プロバイダーを編集して保存してください。

> **リクエストで 404 またはエンドポイントが見つからないエラーが返される**
>
> 選択したプロトコルに応じた URL を確認してください。OpenAI 互換および Responses には `https://api.apiyi.com/v1` を、Anthropic 互換には `https://api.apiyi.com` を使用します。リクエストパス全体を追加しないでください。対象モデルがそのエンドポイントをサポートしていることを確認し、Chat Completions のみをサポートするモデルに Responses エンドポイントを設定しないでください。

> **モデル一覧は読み込まれるが、Agents にモデルが表示されない**
>
> モデルがプロバイダーで選択され、保存されていることを確認してから、エージェント側で表示するモデルの一覧を確認してください。`magpie models` を実行すると、現在 Magpie が公開しているモデルを確認できます。モデルを手動で追加する場合は、モデルの raw ID を確認してください。ツールで選択する場合は、プロバイダーのプレフィックスと ID を確認してください。

> **2つ目のプロバイダーを追加すると重複の警告が表示される**
>
> Magpie はホストやキーなどの情報を使って、プロバイダーの重複を検出します。このガイドにある2つのエントリーには、異なる2つの APIYI token が必要です。プロバイダー名またはプロトコルだけを変更しても、重複の警告が表示されることがあります。

> **Agents にツールが表示されない、または新しいモデルに古い設定が適用される**
>
> ツールがインストールされていることを確認し、Magpie を再度開いて検出されるか確認してください。モデルを選択した後、ツールで新しいセッションを開始してください。既存の環境変数、プロジェクト設定、その他の設定管理ツールによって設定が上書きされていないか確認してください。ツールのインストール手順については、このサイトの該当するガイドを参照してください。

> **Magpie を終了するとコーディングツールが接続できない**
>
> コーディングツールはローカルゲートウェイに接続するようになっています。他にゲートウェイプロセスが実行されていない場合、Magpie を終了すると転送が停止します。Magpie を再度開き、`magpie healthcheck` を実行してローカルゲートウェイがオンラインか確認してください。

## モデルの選択と関連リソース

このガイドのモデルIDは、設定手順を示す例です。他のモデルを追加する前に、エンドポイントの対応状況とtokenの権限を確認してください。最新のモデルの推奨情報と価格は、以下のページで案内しています。

> **[モデルの推奨情報](https://docs.apiyi.com/ja/api-capabilities/model-info.md)**
>
> コーディングのニーズに合ったモデルを選び、利用に関する推奨事項を確認してください。

> **[モデルの価格](https://docs.apiyi.com/ja/models/index.md)**
>
> 最新のAPIYIのモデル価格と利用可能なモデルを確認してください。

> **[Codexの設定ガイド](https://docs.apiyi.com/ja/scenarios/programming/codex-cli.md)**
>
> ツールのインストール、モデルの設定、利用手順を確認してください。

> **[Claude Codeの設定ガイド](https://docs.apiyi.com/ja/scenarios/programming/claude-code.md)**
>
> インストール、tokenグループ、トラブルシューティングについて確認してください。

公式の設定リファレンス: `github.com/yetone/magpie/blob/main/docs/reference.md`。このガイドの設定手順は、プロジェクトのドキュメントとソースコードに照らして確認済みです。選択したモデルとプロトコルで実際にリクエストを送信し、モデル一覧の取得、ストリーミング、ツール呼び出しを確認してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.