Magpie AI 网关教程：把领取的免费 API 统一接入 Claude Code、Codex 和聊天工具

准备

• 一台 macOS、Windows 或 Linux 电脑，按 Magpie 官网下载对应版本。
• 至少一家平台的 API Key、接口地址和可用模型 ID；先按 新人路线图 领取，并核对额度余额、期限和适用模型。
• 一个要使用的 AI 工具，例如已安装的 Claude Code、Codex、OpenCode，或支持自定义接口的聊天客户端。

步骤

1. 01

   安装 Magpie，让网关在本机运行

   打开 Magpie 官网，下载适合自己系统的版本并启动。它默认在 127.0.0.1:3425 运行网关，不需要先买服务器或部署网站。

   之后的调用路径是：你的 AI 工具 → 本机 Magpie → 你添加的 API 平台。赛博鸡蛋提供优惠信息和领取指南，API Key 要在各平台自己创建。使用网关时请保持 Magpie 运行；关闭窗口后它可继续留在菜单栏或托盘中。

2. 02

   把领到的 API 逐家加入「供应商」

   进入 供应商（Providers）→ 添加供应商。有厂商预设时选对应卡片并填 API Key；没有合适预设或需要指定地域时，选择 自定义（Custom），填名称、该平台的 OpenAI 兼容 Base URL 和密钥，再保存。

   例如百炼北京地域可命名为 bailian-beijing，接口填 https://dashscope.aliyuncs.com/compatible-mode/v1，密钥使用北京地域创建的 Key。名称由你决定，接口地址按平台文档填写，不要把完整的 /chat/completions 请求路径当成 Base URL。

   每领一家就添加一家。展开供应商，先点 测试（Test），再选择允许工具使用的模型。模型没被自动列出时，按平台控制台的实际模型 ID 添加；能列出模型不代表它有免费额度，仍要核对该模型的免费资格。

3. 03

   给 Claude Code、Codex 等 Agent 选模型

   打开 Agent（Agents） 标签页，找到已安装或配置的工具，点击它当前的模型，从刚加入的供应商中选择。网关里的模型通常写作 provider/model，以实际列表为准；这是网关的模型标识，不要拿它替换平台原生接口中的模型 ID。

   Magpie 会更新对应工具的配置，并在需要时转换 OpenAI Chat Completions、Responses、Anthropic Messages 等接口。先选单个模型、开一个新会话，发一句简短问题验证；Codex 切换后还要重启应用和已打开的 CLI 会话。之后在 路由（Routing） 或 用量（Usage） 中查看请求去了哪家平台。

   需要恢复原有接入时，在模型选择列表中选工具自带的模型。协议转换可以帮助接通接口，但工具调用、图片和上下文长度还取决于所选模型，接通后仍要用自己的任务试一下。

4. 04

   聊天客户端也可以只配置一个本地接口

   对于 Magpie 没有自动管理、但支持自定义接口的工具，打开 网关（Gateway）→ 接入（Connect），复制对应协议的设置。以运行在同一台电脑上的 OpenAI 兼容聊天客户端为例：

   • Base URL：默认是 http://127.0.0.1:3425/v1；改过端口就用当前接入页的地址。
   • API Key：本机请求可填 magpie-cherry-studio 这样的客户端标识；这是本机网关使用的值，无需把上游平台密钥再填一遍。
   • 模型：从网关模型列表复制完整的 provider/model，或已经建好的路由组标识。

   下方命令可查看当前网关模型列表，不会发起模型生成。Anthropic 兼容客户端的 Base URL 使用根地址 http://127.0.0.1:3425，不要照搬 OpenAI 的 /v1 后缀。127.0.0.1 指当前电脑，远程服务器或云端客户端不能直接使用这个地址。

   bash复制

   curl http://127.0.0.1:3425/v1/models \
     -H "Authorization: Bearer magpie-guide"

5. 05

   接通后再考虑路由组，先确认备用模型怎么收费

   只想切换模型，直接在 Agent 里选即可。想在某个接口限流、额度耗尽或不可用时尝试另一个模型，可在 路由（Routing）→ 新建组（New group） 添加多个模型，选择 按顺序（In order），再把这个组分配给 Agent。组标识是 group/<id>，请复制实际创建的 ID。

   如果目标是只用免费额度，先逐项确认成员和供应商的备用模型仍有可用免费额度；自动生成的同名模型组也要检查成员。备用接口可能按量收费，网关不能代替平台的额度用尽即停设置。先在上游平台启用停用或预算控制，再做自动切换；没有相应控制时，建议先保持单模型、手动切换。

6. 06

   用量看网关，剩余额度和账单看各平台

   Magpie 的用量页能汇总经过它的调用，适合检查哪个工具用了哪个模型；免费额度还剩多少、何时到期以及最终账单，应到各平台控制台确认。绕过网关直接调用的用量不会计入 Magpie。

   遇到连接失败，先确认 Magpie 正在运行、供应商测试是否成功、切换后是否开启了新会话。如果工具报 502，而路由页没有请求记录，按 官方排障说明 检查代理软件是否让本机地址直连。

注意事项

• Magpie 本身免费开源；添加付费 API 不会把它变成免费 API，各平台的余额、有效期、限流和地域规则仍独立生效。
• 仅限某个 App 或 IDE 内使用的免费模型，不能当作开放 API Key 录入网关。先在优惠详情中确认「API」或「API + 应用」入口。
• 供应商密钥保存在本机配置中；不要把真实密钥或含密钥的配置提交到 GitHub，也不要分享给其他人。

常见问题

相关优惠

• 新人 · 阿里云百炼新人免费额度参与模型通常各 100 万 Tokens，90 天有效（以控制台为准）
• 模型 · GroqGroq 免费 API 限速套餐免费档 30 RPM，主力模型 1000 RPD / 8K TPM / 200K TPD，无需信用卡
• 模型 · OpenRouterOpenRouter 免费模型20 请求/分钟，每日 50 次（累计充值 $10 后提升至每日 1000 次）
• 新人 · 火山引擎火山方舟新用户免费推理额度每个模型 50 万 tokens（以控制台显示为准）
• 额度 · 火山引擎豆包大模型送 50 万 tokens注册送 50 万 tokens
• 额度 · NVIDIA英伟达 NIM 送 1000 点数注册送 1000 credits

信息来源

• Magpie 官网 · 下载与功能说明usemagpie.ai/
• Magpie 官方中文文档 · 快速上手、供应商与路由组usemagpie.ai/docs/zh/start
• Magpie 官方文档 · 网关接口、客户端标识与模型目录usemagpie.ai/docs/integrate
• Magpie 开源仓库github.com/yetone/magpie
• 阿里云百炼 · 获取与配置 API Keyhelp.aliyun.com/zh/model-studio/get-api-key

最后核实日期：2026-10-10 · 政策可能随时调整，请以官方页面为准