> ## 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 桌面介面連線 API易，為 Codex 和 Claude Code 配置模型、API 地址與金鑰，附命令列示例和排障步驟

## Magpie 如何連線 API易

Magpie 是一款管理 AI 程式設計工具模型與供應商的開源應用。把 API易 配置到 Magpie 後，可以在同一個介面為 Codex、Claude Code 等工具選擇模型，由 Magpie 將配置寫入各工具的配置檔案。

請求經過本機閘道轉發到 API易：

```text theme={null}
程式設計工具 → Magpie 本機閘道 → API易 → 模型
```

API易 的地址和真實 API Key 填在 Magpie 的**供應商配置**中。程式設計工具由 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/zh-Hant/scenarios/programming/codex-cli.md) 或 [Claude Code 配置指南](https://docs.apiyi.com/zh-Hant/scenarios/programming/claude-code.md) 的安裝部分。
3. 在 [API易令牌頁面](https://api.apiyi.com/token)準備 API Key，並確認賬戶有可用餘額、令牌允許呼叫所選模型。

本文分別介紹 **APIYI** 和 **APIYI Claude** 兩個供應商條目，只使用一款工具時，配置對應條目即可。同時建立兩個條目時，請建立**兩把不同的令牌**：前者使用可呼叫 GPT 模型的令牌，後者使用 `ClaudeCode` 分組令牌。Magpie 會把同一主機下使用相同 Key 的配置判為重複供應商。

> [!NOTE]
>
> Magpie 不會自動讀取終端裡的 API Key 環境變數。請在供應商表單中貼上金鑰，或通過下文的 CLI 命令新增。

## 通過桌面介面配置

### 配置 Codex 使用的供應商

**1. 新增自定義供應商**

開啟 **供應商（Providers）→ 新增供應商 → 自定義供應商（Custom provider）**，填寫：

| 欄位 | 填寫內容 |
| - | - |
| 名稱（Name） | `APIYI` |
| 主協議 | **OpenAI 相容（OpenAI compatible）** |
| API 地址（Base URL） | `https://api.apiyi.com/v1` |
| API 金鑰（API key） | 你的 API易 GPT 令牌 |

地址填寫到 `/v1` 即可，Magpie 會追加請求路徑，不要填寫完整的 `/chat/completions`。

**2. 為 GPT 模型補充 Responses 端點**

展開 **更多端點（More endpoints）**，將 **Responses 地址（Responses URL）** 填為 `https://api.apiyi.com/v1`。

本文使用 `gpt-5.4` 演示，該模型在 API易 支援 Chat Completions 和 Responses。Codex 通過 Magpie 使用此模型時，可以走 Responses 端點。

僅為 API易 確實支援相應協議的模型配置端點。Magpie 本機閘道支援 Responses，不代表 API易 的所有模型都支援原生 Responses。

**3. 獲取並選擇模型**

點選 **獲取模型（Fetch models）**，在模型列表中選擇 `gpt-5.4`，然後儲存供應商。

首次配置先只選擇這個模型；後續新增其他 GPT 模型前，先確認它們在 API易 支援相同的端點。不要把圖片、嵌入等非對話模型加入程式設計工具的模型列表。

如果列表沒有所需型號，可在 **模型（Models）** 中手動新增準確的模型 ID。供應商的模型框填寫 `gpt-5.4`，不加 `apiyi/` 字首。

### 配置 Claude Code 使用的供應商

再新增一個**自定義供應商**，使用另一把 `ClaudeCode` 分組令牌：

| 欄位 | 填寫內容 |
| - | - |
| 名稱（Name） | `APIYI Claude` |
| 主協議 | **Anthropic 相容（Anthropic compatible）** |
| API 地址（Base URL） | `https://api.apiyi.com` |
| API 金鑰（API key） | 另一把 API易 `ClaudeCode` 分組令牌 |
| 模型（Models） | `claude-sonnet-4-6` |

此處地址**不帶 `/v1`**，Magpie 會追加 `/v1/messages`。獲取模型後只選擇本次要使用的 Claude 型號，也可以手動填寫 `claude-sonnet-4-6`，然後儲存。

> [!TIP]
>
> 兩個供應商分開儲存，可以分別管理模型、協議和令牌分組。`ClaudeCode` 分組的說明見 [令牌分組機制](https://docs.apiyi.com/zh-Hant/faq/groups-explained.md)。

### 為程式設計工具選擇模型

1. 開啟 **Agent（Agents）** 頁面，找到已安裝的 **Codex** 或 **Claude Code**。
2. 點選該工具當前的模型，搜尋並選擇剛新增的供應商下的型號：Codex 選 **APIYI → gpt-5.4**，Claude Code 選 **APIYI Claude → claude-sonnet-4-6**。
3. 關閉該工具的舊會話，重新啟動並開啟新會話，讓它讀取 Magpie 寫入的配置。

Magpie 內部用 `供應商ID/模型ID` 標識模型，例如 `apiyi/gpt-5.4`。供應商表單中填寫的原始模型 ID 與 Agent 選中的完整標識屬於不同層級。

> [!NOTE]
>
> 已通過 Magpie 接管的工具，其 API 配置由 Magpie 寫入。排查時同時檢查舊的環境變數、專案配置或其他配置管理工具，避免它們把地址重新覆蓋到舊服務。

## 驗證是否接通

先在供應商頁面執行測試，再在程式設計工具中傳送一個簡短請求，例如：

```text theme={null}
請只回復：連線成功。
```

收到回覆後，檢視 Magpie 的請求或用量記錄，以及 [API易控制台](https://api.apiyi.com)中的呼叫日誌，確認實際請求的模型與供應商符合預期。隨後可讓工具解釋專案中的一個小檔案，驗證日常程式設計流程。

**獲取模型成功只證明模型列表介面可訪問**；實際對話還需要模型、令牌權限和請求協議匹配。供應商測試會發送少量真實 API 請求，並按模型用量計費。

## 命令列配置方式

如果習慣終端，可以用下面的命令代替介面新增。先確認已安裝 `magpie` 命令，並保持桌面應用執行。

> [!NOTE]
>
> 已經在介面建好供應商時，無需重複執行 `provider add`。先執行 `magpie providers` 檢視實際供應商 ID，再替換測試或選模命令中的 ID。介面建立的 ID 由名稱生成；命令中的 `id=` 指定期望 ID。如果 ID 已被佔用，Magpie 可能自動加字尾，新增後同樣需要核對實際 ID。

### 新增兩個供應商

第一條命令中的 `sk-your-api-key` 替換為 GPT 令牌：

```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
```

第二條命令中的 `sk-your-api-key` 替換為**另一把** `ClaudeCode` 分組令牌：

```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` 只檢查本機閘道狀態，不能單獨證明 API易 的模型呼叫正常。

## 常見問題

> **認證失敗，返回 401 或 403**
>
> 檢查 Magpie 供應商裡儲存的 API Key 是否完整、有效，API易賬戶是否有餘額，以及令牌是否允許呼叫目標模型。Claude Code 的配置使用 `ClaudeCode` 分組令牌。修改終端環境變數不會自動更新 Magpie 已儲存的 Key，請編輯供應商後儲存。

> **返回 404 或提示介面不存在**
>
> 對照協議檢查地址：OpenAI 相容和 Responses 填 `https://api.apiyi.com/v1`，Anthropic 相容填 `https://api.apiyi.com`。不要再追加完整請求路徑，並確認目標模型支援該端點。不要給只有 Chat Completions 能力的模型配置 Responses 端點。

> **模型列表能獲取，但 Agent 中找不到模型**
>
> 檢查該模型是否已在供應商裡被選中並儲存，再檢查 Agent 自己的模型可見列表。可執行 `magpie models` 檢視 Magpie 當前暴露的模型。手動新增時檢查原始模型 ID；在工具中選用時則檢查供應商字首和 ID。

> **新增第二個供應商時提示重複**
>
> Magpie 會按主機和 Key 等資訊識別重複供應商。本文的兩個條目需要兩把不同的 API易令牌；僅修改供應商名稱或切換協議，仍可能被判為重複。

> **工具不在 Agent 頁面，或更換模型後仍使用舊配置**
>
> 先確認工具已安裝，重新開啟 Magpie 檢查是否被識別。選好模型後新開工具會話，並排查舊環境變數、專案級設定或其他配置管理工具是否覆蓋了配置。工具安裝方法見對應的站內指南。

> **關閉 Magpie 後，程式設計工具無法連線**
>
> 程式設計工具現在連線的是本機閘道。關閉 Magpie 且沒有其他閘道程序執行時，轉發會停止。重新開啟 Magpie，再用 `magpie healthcheck` 檢查本機閘道是否線上。

## 模型選擇與相關資源

本文的模型 ID 用於演示配置方法，新增型號前請確認其端點和令牌權限。最新模型建議與價格統一在以下頁面維護。

> **[模型推薦](https://docs.apiyi.com/zh-Hant/api-capabilities/model-info.md)**
>
> 按程式設計需求選擇模型，檢視使用建議。

> **[模型價格](https://docs.apiyi.com/zh-Hant/models/index.md)**
>
> 檢視 API易 當前模型價格與可用型號。

> **[Codex 配置指南](https://docs.apiyi.com/zh-Hant/scenarios/programming/codex-cli.md)**
>
> 檢視工具安裝、模型配置及使用說明。

> **[Claude Code 配置指南](https://docs.apiyi.com/zh-Hant/scenarios/programming/claude-code.md)**
>
> 檢視安裝流程、令牌分組和常見問題。

官方配置參考：`github.com/yetone/magpie/blob/main/docs/reference.md`。本文根據專案文件與原始碼核實配置方式；模型列表、流式輸出和工具呼叫是否可用，請以實際所選模型與協議的呼叫結果為準。


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