magpie

magpie 快速入门

magpie（yetone/magpie）解决的是多 agent 并存时代的配置碎片化：你机器上同时装着 Claude Code、Codex、Gemini CLI、Cursor、OpenCode……每个 agent 的模型配置散落在各自的 settings.json / config.toml 里，想全局换模型要挨个翻文件。magpie 用一个菜单栏面板把「每个 agent 当前用什么模型」列成一屏，点一下即换；它还跑一个本地网关（127.0.0.1:3425），把 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 三种 API 统一翻译转发，你登录过的 Claude Code / Codex / Copilot 订阅也能作为 provider 给其他 agent 共享。Go + MIT，桌面版 <15MB（系统 webview，无捆绑内核）。2026-09-30 核验（GitHub + 官方 README）：2,563★ / 147 fork，最近 push 2026-09-29（高频活跃），24 名贡献者，411 个 tag。

这是什么？适合谁？

magpie 的核心交互就是一张表：列出本机每个 AI agent 和它当前绑定的模型（如 Claude Code → claude-fable-5-1、Codex → gpt-6-astra effort medium），箭头键选 agent、回车换模型，改动由 magpie 外科手术式写回对应配置文件——只动你改的那一个键，注释、顺序、缩进原样保留，写入原子化。同一个界面有三种形态：菜单栏下拉面板、普通窗口、终端 TUI（magpie tui），另有纯 CLI。

更深一层是它的本地网关：所有 agent 都指向 http://127.0.0.1:3425/v1，从同一个目录选模型，API 方言翻译（含流式与工具调用）在 magpie 内完成。你登录的 Claude Code 订阅、Codex（ChatGPT）账号、Copilot 会显示为 provider，其他 agent 可直接用它们的模型——不复制密钥、无需粘贴 key；magpie 每次实时读 agent 自己的凭据并按 agent 的方式刷新 token。

适合人群：同时使用 3 个以上 agent CLI、被配置文件碎片折磨的开发者；想让一份订阅（如 ChatGPT/Claude 订阅）被所有 agent 共用的个人用户；需要按请求维度核对模型账单（Usage 页有逐请求台账 + CSV 导出）与按人民币实时汇率显示成本的用户。

不适合谁：只用单一 agent 的用户（官方说法：That is the whole app——单 agent 场景直接改它自己的配置就行）；需要服务器端多人网关的团队（magpie 是本机单用户工具）；对「模型配置被第三方工具改写」不放心的用户（虽然写入是外科手术式的）。

准备工作

1. macOS / Linux / Windows 桌面环境（Windows 版是便携单 exe，WebView2 无 cgo；Linux 需 GTK3 + WebKitGTK 4.1）
2. 至少一个已安装且配置过的 AI agent（Claude Code、Codex、Gemini CLI、Cursor、OpenCode、Goose、Hermes、Kimi Code 等 25+，只显示已安装的）
3. （可选）想启用网关共享：一个 provider 的 API key（DeepSeek、Kimi、GLM、MiniMax、Qwen、OpenRouter、Ollama 等 25+ 预置，或自定义 OpenAI/Anthropic 兼容端点），或一个已登录的 Claude Code / Codex / Copilot 订阅
4. 时间预算：安装 3 分钟；跑通第一个模型切换 5 分钟；网关 + provider 配置 15 分钟
5. 零成本：MIT 开源；模型费用产生在各 provider / 订阅侧

核心用法：四步上手

第 1 步：安装

从 GitHub Releases 下载对应平台安装包（macOS dmg / Windows 便携 exe / Linux 包），或 macOS 用 brew install magpie（magpie-releases tap）。装完它在菜单栏出现一个图标。

第 2 步：切换第一个 agent 的模型

点菜单栏图标，面板会自动发现本机已安装的 agent 并列出各自的模型。用 ↑↓ 选 agent、↵ 换模型、s 保存 profile。改动立即写回该 agent 的配置文件（如 ~/.claude/settings.json），重启 agent 后生效。先用一个不重要的 agent 试一次，确认配置文件只改了预期字段。

第 3 步：加一个 provider，体验网关

magpie presets                          # 列出所有预置厂商
magpie provider add deepseek sk-…       # 预置厂商只需一个 key
magpie provider add ollama              # 本地服务连 key 都不要
magpie models                           # agent 看到的模型目录
magpie claude deepseek/deepseek-chat    # 给 Claude Code 换上它
magpie provider test deepseek           # 每个 API 发一个微型请求测延迟

之后所有指向 http://127.0.0.1:3425/v1 的 agent 都从同一目录选模型；今天早上新发布的模型，在下一次目录刷新后就会出现在选择器里（模型列表实时问厂商要，不内置编译）。

第 4 步：看用量与成本

打开窗口版的 Usage 页：按 agent / 模型汇总的调用与标价成本、Sessions 页回看会话、Requests 页是逐请求台账（请求模型 vs 实际服务模型、token 细分、时长、状态），可导出 CSV 与厂商账单核对。Settings 里可把计价切到人民币（open.er-api.com 实时汇率，离线回落最后已知汇率或 7.2）。

常见踩坑

1. 症状：面板里看不到某个 agent。 根因：magpie 只显示已安装/已配置的 agent，且部分 agent 需要配置文件已存在（如 ~/.codex/config.toml）。解决：先正常启动一次该 agent 让它生成配置；GUI 从 Finder/Dock 启动时还会自动补齐 nvm/bun/volta 等自定义 PATH 下安装的 agent。
2. 症状：换了模型 agent 报错「provider 已关闭」。 根因：该模型所属 provider 被关掉或 key 失效，agent 配置里还留着旧模型。解决：升级到新版 magpie——它现在会在 provider 关闭/移除时自动把相关 agent 迁移到仍在线的同名模型或默认模型，并在状态行说明迁移到了什么。
3. 症状：Windows 便携版首次运行后开始菜单搜不到。 根因：便携 exe 没有安装器。解决：新版每次启动桌面版会自动在开始菜单创建快捷方式（MAGPIE_NO_SHORTCUT=1 可跳过）；Win+R 输入 magpie 也可（App Paths 已注册）。
4. 症状：订阅共享时 Claude 请求被 Anthropic 判为第三方流量。 根因：Anthropic 把非 Claude Code 系统提示的 OAuth 请求归类为第三方。解决：这是平台政策限制，README 有专门说明——把该模型当 provider 用时遵循其条款口径；必要时用 API key 的 provider 替代订阅共享。
5. 症状：担心 API key 安全。 根因：网关类工具天然接触凭据。解决：magpie 明确「不从 shell 环境变量读 key」（只存自己的配置）、订阅凭据每次实时读 agent 自己的存储、token 刷新写回原处；但你仍应把 magpie 的配置目录当敏感数据对待。

常见问题 FAQ

Q1: magpie 和 LiteLLM / one-api 这类网关有什么区别？

A: 定位不同：LiteLLM/one-api 是服务器端代理（多人、部署在远端、生态在运维侧）；magpie 是本机单用户桌面工具，核心是一屏管理本机 agent 的模型绑定 + 订阅共享，网关只是支撑能力，不追求多租户。

Q2: 它会改坏我的配置文件吗？

A: 官方口径是外科手术式编辑：只改你动的那个键，注释、顺序、缩进保留，写入原子化。稳妥起见首次使用前对 ~/.claude/、~/.codex/ 等目录做个备份，用 git dotfiles 管理的用户可以直接 diff 验证。

Q3: 支持哪些 agent？

A: README 列了 25+：Claude Code / Claude Desktop、Codex、Gemini CLI、OpenCode、MiMo Code、Pi、Goose、Cursor CLI、Copilot CLI、Crush、dsh、Command Code、fx、omp、Devin、Hermes Agent、Kimi Code、Cline、Qoder、Grok Build、ZCode、WorkBuddy、OpenHanako、Alma 等。只显示已安装的。

Q4: 路由分组（routing group）是什么？

A: 把多个模型（可跨 provider）打包成一个 group/<id> 供 agent 当单模型选；网关按策略路由：smart（默认，优先配额最快恢复的订阅）、order（顺序故障转移）、rotate（轮转）、usage（最少使用优先）；stays= 控制会话粘性以保住厂商缓存。

Q5: 免费吗？有什么隐藏成本？

A: 工具本身 MIT 开源免费。成本产生在模型侧：你接的 API key 按量计费、共享的订阅消耗其自身配额（magpie 的 quota 页会显示各订阅额度与重置时间）。

参考链接

• 官方仓库 yetone/magpie
• 官网 usemagpie.ai
• GitHub Releases
• Discord 社区

本文章基于公开资料整理，AI 辅助生成，独立实测与数据核验日期 2026-09-30（GitHub 实时抓取 stars/fork/push/license；未在本机做安装实测）。