> ## 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/scenarios/programming/codex-cli.md) 或 [Claude Code 配置指南](https://docs.apiyi.com/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/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/api-capabilities/model-info.md)**
>
> 按编程需求选择模型，查看使用建议。

> **[模型价格](https://docs.apiyi.com/models/index.md)**
>
> 查看 API易 当前模型价格与可用型号。

> **[Codex 配置指南](https://docs.apiyi.com/scenarios/programming/codex-cli.md)**
>
> 查看工具安装、模型配置及使用说明。

> **[Claude Code 配置指南](https://docs.apiyi.com/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.