yetone/magpie · 上手攻略
- 仓库：yetone/magpie
- 链接：https://github.com/yetone/magpie
- 分类：开发工具 · AI 模型调度 / 本地网关
- 作者：Tom
- 更新：2026-09-25
这是什么
magpie 是一个菜单栏统一网关，让你在本地同时管理所有 AI Agent 的模型配置——Claude Code、Codex、Gemini CLI、OpenCode、Goose、Cursor CLI、Copilot CLI……每个 Agent 各有不同的配置文件格式（JSON、TOML、YAML），分别对接不同的 API 端点，手动管理既繁琐又容易出错。magpie 用一个本地 HTTP 网关（默认 http://127.0.0.1:3425/v1）把所有 Agent 的请求翻译成对应供应商的实际 API，无论底层是 OpenAI 格式、Anthropic Messages 格式还是 Responses API，magpie 都能透明转发，Agent 本身无需任何改动。
核心定位：一个菜单栏面板 + 一个本地网关 + 一次配置，取代散落在各 Agent 配置文件里的重复密钥和端点。
解决什么问题
- 每个 Agent 要单独配密钥、单独记端点，新增模型要逐个改配置
- 想让 Claude Code 用 DeepSeek，Copilot CLI 用 Kimi，但它们的 API 格式完全不同
- 订阅了某个 Provider（Anthropic / OpenAI / Codex）后，希望所有 Agent 共享同一套凭证
- 需要在多个模型之间快速切换对比效果，而不是登入登出各个 Agent
快速安装
⚠️ magpie 本身不提供预编译 Release（GitHub Releases 页面为空），当前主流安装方式为 Homebrew 或从源码构建。
macOS / Linux（Homebrew）
brew install yetone/tap/magpie
从源码构建（需要 Go 1.21+）
git clone https://github.com/yetone/magpie.git
cd magpie
make build
# 产物在 ./bin/magpie（桌面版）或 ./bin/magpie-tui（终端版）
安装完成后运行：
magpie # 打开菜单栏 GUI
magpie tui # 纯终端版本
⚠️ 版本号：README 和 Releases 均未标注版本号，CLI magpie --version 输出时间待实测确认（建议以实际输出为准，不要硬编码版本）。
快速启动（CLI 模式）
# 添加一个 Provider（只需 key，其他自动获取）
magpie provider add deepseek sk-your-deepseek-key
# 查看当前所有 Provider
magpie providers
# 查看当前可用的模型列表
magpie models
# 测试某 Provider 连通性
magpie provider test deepseek
核心用法
1. Gateway 地址 = 所有 Agent 的统一入口
在各个 Agent 的配置文件里，把 base_url / endpoint 全部指向 http://127.0.0.1:3425/v1（magpie 默认端口），Agent 名称作为 model 字段前缀，格式为 agent-name/model-name，例如：
claude/claude-sonnet-5 → 走 Anthropic
codex/gpt-5.5 → 走 OpenAI Codex
pi/openrouter/z-ai/glm-5.2 → 走 OpenRouter
magpie 会根据前缀路由到对应 Provider，Agent 本身的配置无需改动 key。
2. 导入已有登录（OAuth）
如果 Claude Code、Codex、Copilot CLI 已经登录，这些登录凭证也可以被 magpie 复用为 Provider：
# 从 Claude Code / Codex 导入现有登录
# （需要设置 CLAUDE_CONFIG_DIR / CODEX_HOME 环境变量）
magpie claude deepseek/deepseek-chat # 用 deepseek 测试
3. Profile 快速切换
magpie profile save my-work # 保存当前所有 Agent 配置快照
magpie profile load my-work # 一键恢复
4. Provider 管理（CLI）
| 命令 | 作用 |
|---|---|
magpie presets |
列出所有认识的 Provider 预设 |
magpie provider add <name> <key> |
添加 Provider（预设只需 key） |
magpie provider rm <name> |
删除 Provider |
magpie provider models <name> |
重新拉取某 Provider 的模型列表 |
magpie provider key <name> <key> |
更新 Provider 密钥 |
5. 支持的 Agent 配置文件格式
| Agent | 配置文件 | 改动字段 |
|---|---|---|
| Claude Code | ~/.claude/settings.json |
provider, model |
| Codex | ~/.codex/config.toml |
provider, model, effort |
| Gemini CLI | ~/.gemini/settings.json |
auth, model |
| OpenCode | ~/.config/opencode/opencode.jsonc |
model, small |
| Goose | ~/.config/goose/config.yaml |
model |
| Cursor CLI | ~/.cursor/cli-config.json |
model |
| Copilot CLI | ~/.copilot/settings.json |
model |
典型适用场景
- 多 Agent 共存调试：同时跑 Claude Code + Codex + OpenCode，对比同一个任务在不同模型上的表现，无需反复改配置
- 跨团队模型共享：团队成员共享一个 Provider Key，各自的 Agent 通过 magpie 网关访问，不泄漏密钥
- 快速切换测试环境：用 Profile 在"开发模型集"和"生产模型集"之间一键切换
- 本地离线开发：配合 Ollama / LM Studio 作为本地 Provider，所有 Agent 共享同一个本地端点
坑与注意
⚠️ 1. 默认端口 3425 需确认未被占用
首次启动前检查 lsof -i :3425，如有冲突用 MAGPIE_PORT=xxxx magpie 覆盖。
⚠️ 2. Claude 订阅有特殊处理
Anthropic 将第三方 Agent 的系统提示视为第三方流量，因此 magpie 驱动本地 claude 二进制而非直接调 Anthropic API。Claude Code 登录的会话不会走 OpenAI 兼容端点，导入时需留意此差异。
⚠️ 3. Claude Code 的 model 字段格式
在 Claude Code 的 settings.json 中，model 字段应填 agent 名（如 claude），opus/sonnet/haiku 等通过 magpie 层面的 provider 配置实现切换，不是直接写在 Claude Code 配置里。
⚠️ 4. 国内网络首次拉取模型列表可能超时
Provider 首次添加时 magpie 会从厂商 API 拉取模型列表，网络不稳定时建议提前 magpie provider models <name> 并重试，或配置代理。
⚠️ 5. Codex 端点兼容性
ChatGPT 后端只支持流式，且拒绝部分参数。magpie 会翻译非流式请求，但实测偶发 422 错误，建议先 magpie provider test codex 确认连通性。
⚠️ 6. 配置文件原子写入 magpie 对配置文件的修改是原子写入（写临时文件再 rename），但建议操作前备份原配置，尤其在手动修改过配置文件的场景。
⚠️ 7. 模型名格式必须带 Provider 前缀
在 Agent 的 model 字段里必须写成 provider/model 形式（如 deepseek/deepseek-chat），直接写模型名会导致路由失败。
与同类对比
| 工具 | 定位 | 多 Agent 共享 | API 翻译 | 本地模型 | 安装方式 |
|---|---|---|---|---|---|
| magpie | 菜单栏网关 + Agent 模型切换器 | ✅ 共享订阅 | ✅ OpenAI/Anthropic/Responses 三种 | ✅ Ollama/LM Studio | Homebrew / 源码 |
| Portkey | 云端 AI 网关 + 可观测性 | ✅ 多 Provider | ✅ | ❌ | SaaS |
| Helicone | LLM 可观测性 | ❌ | ✅ | ❌ | 旁路代理 |
| LocalAI | 本地模型部署 | ❌ | ✅ | ✅ | Docker / 二进制 |
| OpenRouter | 模型聚合 + 路由 | ✅ API Key 共享 | ✅ | ❌ | 云端 |
核心差异：magpie 是唯一一个直接面向"多 Agent 并存"场景、且在菜单栏提供可视化切换的工具；Portkey 和 Helicone 更偏可观测性和云端管理；LocalAI 专注本地推理。
一句话推荐结论
如果你同时用 2 个以上的 AI 编程 Agent（Claude Code / Codex / OpenCode 等），magpie 是目前最轻量的统一网关方案——一个本地端口 + 一次配置，让所有 Agent 共用一套凭证和模型目录，无需任何 Agent 改动。