跳转到主要内容

​
Magpie 如何连接 API易

Magpie 是一款管理 AI 编程工具模型与供应商的开源应用。把 API易 配置到 Magpie 后，可以在同一个界面为 Codex、Claude Code 等工具选择模型，由 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 配置指南 或 Claude Code 配置指南 的安装部分。
  3. 在 API易令牌页面准备 API Key，并确认账户有可用余额、令牌允许调用所选模型。
本文分别介绍 APIYI 和 APIYI Claude 两个供应商条目，只使用一款工具时，配置对应条目即可。同时建立两个条目时，请创建两把不同的令牌：前者使用可调用 GPT 模型的令牌，后者使用 ClaudeCode 分组令牌。Magpie 会把同一主机下使用相同 Key 的配置判为重复供应商。
Magpie 不会自动读取终端里的 API Key 环境变量。请在供应商表单中粘贴密钥，或通过下文的 CLI 命令添加。

​
通过桌面界面配置

​
配置 Codex 使用的供应商

1

新增自定义供应商

打开 供应商（Providers）→ 添加供应商 → 自定义供应商（Custom provider），填写：地址填写到 /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 分组令牌： 此处地址不带 /v1，Magpie 会追加 /v1/messages。获取模型后只选择本次要使用的 Claude 型号，也可以手动填写 claude-sonnet-4-6，然后保存。
两个供应商分开保存，可以分别管理模型、协议和令牌分组。ClaudeCode 分组的说明见 令牌分组机制。

​
为编程工具选择模型

  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 选中的完整标识属于不同层级。
已通过 Magpie 接管的工具，其 API 配置由 Magpie 写入。排查时同时检查旧的环境变量、项目配置或其他配置管理工具，避免它们把地址重新覆盖到旧服务。

​
验证是否接通

先在供应商页面运行测试，再在编程工具中发送一个简短请求，例如：
收到回复后，查看 Magpie 的请求或用量记录，以及 API易控制台中的调用日志，确认实际请求的模型与供应商符合预期。随后可让工具解释项目中的一个小文件，验证日常编程流程。 获取模型成功只证明模型列表接口可访问；实际对话还需要模型、令牌权限和请求协议匹配。供应商测试会发送少量真实 API 请求，并按模型用量计费。

​
命令行配置方式

如果习惯终端，可以用下面的命令代替界面添加。先确认已安装 magpie 命令，并保持桌面应用运行。
已经在界面建好供应商时，无需重复执行 provider add。先运行 magpie providers 查看实际供应商 ID，再替换测试或选模命令中的 ID。界面创建的 ID 由名称生成；命令中的 id= 指定期望 ID。如果 ID 已被占用，Magpie 可能自动加后缀，添加后同样需要核对实际 ID。

​
添加两个供应商

第一条命令中的 sk-your-api-key 替换为 GPT 令牌：
第二条命令中的 sk-your-api-key 替换为另一把 ClaudeCode 分组令牌：

​
查看模型并连接工具

只执行你已安装、需要配置的工具对应命令，再重新开启该工具的会话。这些命令负责修改配置，实际使用时仍需要 Magpie 网关在线。

​
测试上游与本机网关

provider test 对已配置的上游端点发送少量真实请求；healthcheck 只检查本机网关状态，不能单独证明 API易 的模型调用正常。

​
常见问题

检查 Magpie 供应商里保存的 API Key 是否完整、有效，API易账户是否有余额，以及令牌是否允许调用目标模型。Claude Code 的配置使用 ClaudeCode 分组令牌。修改终端环境变量不会自动更新 Magpie 已保存的 Key，请编辑供应商后保存。
对照协议检查地址：OpenAI 兼容和 Responses 填 https://api.apiyi.com/v1，Anthropic 兼容填 https://api.apiyi.com。不要再追加完整请求路径，并确认目标模型支持该端点。不要给只有 Chat Completions 能力的模型配置 Responses 端点。
检查该模型是否已在供应商里被选中并保存，再检查 Agent 自己的模型可见列表。可运行 magpie models 查看 Magpie 当前暴露的模型。手动添加时检查原始模型 ID；在工具中选用时则检查供应商前缀和 ID。
Magpie 会按主机和 Key 等信息识别重复供应商。本文的两个条目需要两把不同的 API易令牌；仅修改供应商名称或切换协议，仍可能被判为重复。
先确认工具已安装，重新打开 Magpie 检查是否被识别。选好模型后新开工具会话，并排查旧环境变量、项目级设置或其他配置管理工具是否覆盖了配置。工具安装方法见对应的站内指南。
编程工具现在连接的是本机网关。关闭 Magpie 且没有其他网关进程运行时，转发会停止。重新打开 Magpie，再用 magpie healthcheck 检查本机网关是否在线。

​
模型选择与相关资源

本文的模型 ID 用于演示配置方法，新增型号前请确认其端点和令牌权限。最新模型建议与价格统一在以下页面维护。

模型推荐

按编程需求选择模型，查看使用建议。

模型价格

查看 API易 当前模型价格与可用型号。

Codex 配置指南

查看工具安装、模型配置及使用说明。

Claude Code 配置指南

查看安装流程、令牌分组和常见问题。
官方配置参考：github.com/yetone/magpie/blob/main/docs/reference.md。本文根据项目文档与源码核实配置方式；模型列表、流式输出和工具调用是否可用，请以实际所选模型与协议的调用结果为准。