文档 · 指南

快速上手

magpie 是给你所有编程 Agent 统一选模型的地方。先把你有的供应商加进来，再给每个 Agent 选一个模型；magpie 会把它写进那个 Agent 自己的配置文件。

背后是一个跑在你本机 127.0.0.1:3425 的小网关。它同时支持 OpenAI、Anthropic 和 Gemini 三种 API，并在它们之间互相转换（流式输出、工具调用都支持），所以任何 Agent 都能用任何供应商的模型：Claude Code 用 ChatGPT 订阅里的 GPT 模型，Codex 用 DeepSeek，OpenCode 用你的 Claude 订阅。

供应商

模型从哪里来：登录的订阅、有 API 密钥的厂商、你自己的接口地址。每个模型都写作 provider/model。

Agent

使用模型的工具：Claude Code、Codex、Gemini CLI、OpenCode 等。每个一行，显示它当前用的模型。

网关

通过 magpie 选模型时，Agent 指向的本地地址。它把每个请求转给提供该模型的供应商。

路由组

可选。把多个模型或账号合成一个给 Agent 选，group/<id>，一个额度用完时换下一个。

  1. 添加供应商登录你的订阅，粘贴 API 密钥。只需做一次。
  2. 给每个 Agent 选模型点 Agent 的模型，选一个。magpie 改写那个 Agent 的配置。
  3. 开一个新会话Agent 启动时读取配置，下一个会话就用上新模型。

1 · 添加供应商

打开 供应商 标签页，点 ＋ 添加供应商。点选一个卡片，或输入厂商名字查找。

添加供应商面板：订阅、厂商、中转、本机和自定义 URL 添加供应商面板：订阅、厂商、中转、本机和自定义 URL
添加供应商：登录订阅、选厂商，或填任意兼容的 URL。

订阅 · 登录即可，无需密钥

Claude（Pro、Max、Team）、ChatGPT（Plus、Pro、Business）、Cursor、Grok（SuperGrok）、Copilot 和 Devin。点卡片后 magpie 会在浏览器里打开厂商自己的登录页，登录完成后账号立刻出现（Copilot 会给你一个验证码，在 GitHub 页面上输入）。订阅是在 magpie 里添加的，不需要先去别的 Agent 里登录。

供应商（厂商预设）

Anthropic、OpenAI、Google Gemini、DeepSeek、Kimi、Zhipu GLM、MiniMax、Qwen、Mistral、Groq、xAI 等。选一个，粘贴密钥（获取密钥 ↗ 会打开厂商的密钥页面），保存。magpie 会向厂商询问它提供哪些模型并列出来；展开供应商那一行可以选择给 Agent 暴露哪些模型，或点 测试。

本机

Ollama 和 LM Studio，无需密钥。

自定义 · 任意兼容的 URL

其他接口都走这里：填 名称、OpenAI 兼容 地址（以 /v1 结尾）、Anthropic 兼容 地址（根地址，即 ANTHROPIC_BASE_URL 的值），或两个都填，再填密钥。接口支持几种 API 就填几种；每个 Agent 用它原生的那种，其余由 magpie 转换。

之前在 Claude Code 或 Codex 里配过供应商？面板顶部的 导入… 会读取 Claude Code 的 settings.json 和 Codex 的 config.toml，不改动它们，把你勾选的供应商导入进来。

密钥保存在 ~/.config/magpie/providers.json，只有你自己可读。magpie 从不读取 shell 环境变量里的密钥：你添加什么，它就用什么。

2 · 给每个 Agent 选模型

Agent 标签页里，本机装了或配置过的每个 Agent 各占一行。magpie 支持 Claude Code、Codex、Gemini CLI、OpenCode、Pi、Goose、Cursor、Copilot CLI、Crush、DeepSeek Harness、Command Code、omp、Devin、Hermes Agent 和 Grok Build。

Agent 页：每个 Agent 一行，显示当前模型，底部是保存的方案 Agent 页：每个 Agent 一行，显示当前模型，底部是保存的方案
每个 Agent 一行，可以选任意供应商的模型；方案一键切换全部设置。

选好的模型会写进 Agent 自己的配置文件。只改 magpie 需要的那几个键；注释、顺序、缩进都保留，写入是原子的。

Agent通过 magpie 选模型时写入什么
Claude Code~/.claude/settings.json：env 里的 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 和模型变量
Codex~/.codex/config.toml：一个 [model_providers.magpie] 表和模型，模型列表写在 magpie-models.json。你的 ChatGPT 登录不受影响
OpenCode、Pi、Crush一个 magpie 供应商条目，以及 magpie/provider/model
Gemini CLIGOOGLE_GEMINI_BASE_URL 指向网关、API 密钥认证，以及模型

已在运行的会话保持它启动时的模型。Agent 启动时读取配置，所以改动从下一个会话生效。Codex 也在启动时生成模型列表：切换后请重启 Codex 应用和已打开的 codex 会话。

Paseo、编辑器插件等替你运行 Claude Code 或 Codex 的前端，启动的是同一个 CLI，读的也是同一份 ~/.claude 或 ~/.codex 配置。在 magpie 里设一次模型，它们从下一个会话起也会用上。

3 · 可选：路由组

每个供应商只有一个账号时可以跳过这一步。等你有了多个——比如两个 ChatGPT 账号，或者同一个模型既有订阅又有密钥——再来设置。

路由页：四个 Agent 同时经三个路由组发请求，被限流的供应商暂时让开 路由页：四个 Agent 同时经三个路由组发请求，被限流的供应商暂时让开
路由组：多个模型或账号合成一个名字，按智能或顺序切换。

一个供应商里的多个账号或密钥

展开供应商那一行，勾选要用的每个账号或密钥。路由 决定请求怎么分给它们：智能（默认）、按顺序、轮流 或 用量少的优先。备用 里列出这个供应商额度用完、被限流或不可用时改用的模型。

跨供应商的同一个模型

路由组是几个模型（来自一个或多个供应商），Agent 把它当作一个来选：group/<id>，在选择列表的 路由组 下面。两个供应商用同一个名字提供的模型会自动成组；在 路由 标签页点 新建组 可以把任意模型组到一起。排第一的模型决定这个组对外的能力。

不用手动建的组。再加一个供应商，只要它提供的模型和已有的同名（比如 Claude 订阅和 Copilot 都有 Claude Opus，DeepSeek 官方 API 和 OpenRouter 都有 DeepSeek），magpie 就会自动把它们组成一个路由组：group/auto-<模型>，包含所有提供这个模型的供应商。名字按各家不同的写法匹配（deepseek/deepseek-chat 和 deepseek-chat 算同一个）。给 Agent 选这个组，请求就会分摊到这些供应商上；不想要的可以用 magpie group rm 隐藏。
路由谁排在前面
智能 smart默认。把所有成员的账号和 Key 放在一起排：还有余量的订阅里，额度最先重置的排第一；失败后在休息的排最后。
按顺序 order先用第一个模型，它答不了再换下一个。
轮流 rotate会话的每一轮交给下一个成员的账号或 Key，均摊负载。
最少使用 usage剩余额度最多的账号或 Key 排第一。
会话保持会话在回答过它的账号或 Key 上留多久
自动 auto默认。一轮之内总是保持，跨轮则在厂商缓存还值得保留时保持。
整个会话 session整个会话，只要它还能回答。
一轮之内 turnAgent 回传工具结果时不换；你再次发言时，路由重新决定。
关闭 off每个请求都重新路由。

路由 标签页实时显示网关的决定：每个请求由谁回答、为什么。在终端里也能管理路由组：

终端 
magpie groups                        # 先列你建的，再列 magpie 自动发现的
magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=order stays=session
magpie group set opus-anywhere models+=openrouter/anthropic/claude-opus-5.5
magpie group rm opus-anywhere        # 自动发现的组会被隐藏；magpie group restore <id> 恢复
magpie claude group/opus-anywhere    # 使用它

用量与方案

用量。用量 标签页按 Agent 和模型统计每次经过网关的调用的 token、缓存命中和费用，可选 今天、7 天、30 天 或 全部；最上面是各订阅已用的额度和重置时间。Agent 直接发给自己厂商的请求不经过 magpie，不会计入。

用量页：剩余余额、token 与费用汇总，以及 30 天趋势图 用量页：剩余余额、token 与费用汇总，以及 30 天趋势图
经过网关的每次调用的余额、token、缓存命中和费用。

方案。在 Agent 标签页底部点 ＋ 保存当前，把所有 Agent 的设置存成一个方案；之后点这个方案就能一键全部切回。

命令行

magpie tui 是终端里的完整界面，上面每一步也都有对应命令。magpie help 列出全部命令。

命令作用
magpie ls列出找到的每个 Agent 及其设置
magpie presetsmagpie 内置的厂商预设
magpie provider add deepseek sk-…用密钥添加一个预设
magpie accounts add codex再登录一个 Claude 或 ChatGPT 订阅
magpie providers你的供应商：地址、密钥、模型、谁在用
magpie modelsAgent 能选的所有模型，写作 provider/model
magpie claude codex/gpt-5.5设置 Agent 的模型
magpie codex effort high设置其他字段
magpie codex default恢复 Agent 自己的默认值，移除 magpie 的接入
magpie save work · use work保存、应用方案
magpie usage 7d按 Agent 和模型统计 token 与费用
magpie tray只启动菜单栏图标

常见问题

需要自己 export OPENAI_BASE_URL 或 ANTHROPIC_BASE_URL 吗？

不需要。对 magpie 列出的 Agent，它会把网关地址和令牌直接写进 Agent 自己的配置文件。这些环境变量只用于 magpie 不管理的、带 base URL 设置的其他工具：网关 标签页的 接入 部分有一键复制和示例代码。

magpie 必须一直开着吗？

通过 magpie 使用的模型需要：网关随应用一起运行。关掉窗口后它仍留在菜单栏或托盘里；magpie tray 只启动图标（可以放进登录项），magpie serve 只运行网关。Agent 用它自己的模型和自己的登录时，不经过 magpie。

怎么把 Agent 恢复原样？

在选择列表里选 Agent 自带的模型，或运行 magpie <agent> default。magpie 会删掉它写入的内容，并恢复被它替换掉的值，比如你原来的 ANTHROPIC_BASE_URL。

换了模型，Agent 还在用旧的？

已在运行的会话保持启动时的模型。开一个新会话；如果是 Codex，也请重启 Codex 应用。

手动改 Agent 的配置会冲突吗？

不会。magpie 每次都重新读取文件，只动它设置的那几个键，你的其他设置和注释都会保留。用 导入… 带进来的供应商是一份拷贝：之后在 Agent 里的改动不会再同步过来。

遇到问题，或者有值得分享的配置？来 Discord 聊。想给自己的用户一键添加供应商的厂商，请看 Add to magpie。