magpie：全新模型矩阵路由工具

本页整理自 magpie 官方 README / reference 文档 + 本机实测（v0.1.1278，2026 10 17）。标注「实测」的条目是在这台 Mac 上真跑过的；其余为官方文档描述。命令示例里的模型名…

本页整理自 magpie 官方 README / reference 文档 + 本机实测（v0.1.1278，2026-10-17）。标注「实测」的条目是在这台 Mac 上真跑过的；其余为官方文档描述。命令示例里的模型名请以你本机选择器里的实际列表为准。

0. 一句话结论

magpie 是一个菜单栏小应用（macOS / Windows / Linux，MIT 开源，yetone 出品），同时做三件事：集中管理每个 AI Agent 用哪个模型、在本机跑一个会说 OpenAI / Anthropic / Gemini 三套 API 的本地网关、跟踪每个订阅账号的额度并在用完时自动切换。

要不要用，用一句话判断：只要你用超过一个 Agent、或超过一个 provider、或超过一个账号，它就划算；只用一个 Agent + 它自带的订阅且够用，就不需要。

1. 它替你解决的三个具体痛点

痛点	没有 magpie 时	magpie 的做法
模型锁死在各自的配置文件里	Claude Code 写 `~/.claude/settings.json`、Codex 写 `~/.codex/config.toml`、Hermes 写 `~/.hermes/config.yaml`，格式、键名、base URL 全不一样	一张 Agents 表里点一下，只原子改写那个该改的键；注释、顺序、格式原样保留
花钱买的订阅只能在一个 Agent 里用	Claude 订阅只能喂 Claude Code，ChatGPT 订阅只能喂 Codex	把「你已登录的订阅」当成一个 provider，供所有 Agent 使用
key 和 base URL 散落各处	换供应商要改 N 个文件、N 份 key	key 只存在 magpie，Agent 只认 `provider/model` 和网关地址

额外两个：额度耗尽自动 failover、跨 Agent 的用量与花费统一可见。

2. 它是怎么工作的

Claude Code ┐
Codex       │
Hermes      ├─→ magpie 网关 http://127.0.0.1:3425 ─→ 路由组 / 插件 ─→ Claude 订阅
dsh / 你的  │      （OpenAI Chat · OpenAI Responses ·        ├→ ChatGPT 订阅
脚本 / 任意工具 ┘    Anthropic Messages · Gemini 互转）        ├→ DeepSeek / Kimi / GLM key
                                                             └→ 本地 Ollama / LM Studio

网关只监听回环地址，本机调用 key 随便填（官方文档用 magpie 当占位符）。
网关暴露的路径：/v1/chat/completions、/v1/responses、/v1/messages、/v1/messages/count_tokens、/v1beta/models/{model}:generateContent、/v1/models。
模型一律写作 provider/model，例如 deepseek/deepseek-v4-pro、claude/claude-opus-5-5。
厂商本身就支持 Agent 那套 API 时请求直通；不支持时由 magpie 翻译，流式输出、工具调用、推理内容都包含在内。

3. 安装

三种方式，任选：

# 1) 下载应用（Mac 版已签名+公证，之后自动更新）
open https://usemagpie.ai/zh/

# 2) 脚本安装（受限网络可加 --proxy / --mirror）
curl -fsSL https://usemagpie.ai/install.sh | sh

# 3) 其他：go install github.com/yetone/magpie@latest
#    或 Docker 镜像 ghcr.io/yetone/magpie

装完会有三样东西：应用本体、magpie 命令行、配置目录 ~/.config/magpie/。

本机情况（实测）：用 DMG 装的没把 magpie 放进 PATH，已用软链补上：

ln -sf /Applications/magpie.app/Contents/MacOS/magpie ~/.local/bin/magpie

撤销：rm ~/.local/bin/magpie。只读子命令（ls / providers / accounts / quota / models）可以和正在运行的 app 并存，不会冲突。

4. 第一次跑起来：三件事

加一个 provider — 打开 magpie → Providers → 添加 provider → 选预设、粘 key；或者直接登录一个订阅（Claude / ChatGPT / Copilot / Gemini / Grok）。命令行等价物：magpie provider add deepseek sk-…
给每个 Agent 选模型 — Agents 页点一下要改的值，弹出可搜索的模型列表，选中即可。命令行等价物：magpie claude deepseek/deepseek-v4-pro
确认网关活着 — magpie ls 看每个 Agent 当前的设置；magpie quota 看每个订阅还剩多少额度。

最容易踩的一点：Agent 只在启动时读配置。已经在跑的会话不会改，必须开新会话才生效。

5. 六个核心概念

概念	是什么	怎么用
Provider	一个模型来源：厂商预设、中转站、本地 Ollama/LM Studio，或你登录的订阅	加一次，它的模型就出现在每个 Agent 的选择器里
Agent	你机器上装了的一个 AI 工具（Claude Code、Codex、Hermes、dsh、OpenCode、Cursor CLI…官方支持 60+ 个）	magpie 只显示实际装了或配过的
`provider/model`	模型的全名	`codex/gpt-5.6-luna`、`claude/claude-haiku-5-5`
方案 Profile	把所有 Agent 当前的设置存成一个名字	`magpie save 省钱` / `magpie use 省钱`
路由组 Group	一组模型当成一个来选，形如 `group/daily`	额度用完自动换账号，Agent 看不到报错
插件 Plugin	跑在 Bun 上的扩展：既能提供新的 provider，也能当「网关中间件」改写请求	`magpie plugin add @magpie-community/middleware-model-map`

还有一个不太起眼但很实用的：资料库 Library —— 把指令、MCP 服务器、技能（skills）写一次，magpie 按每个 Agent 自己的格式写进它的文件，删除时只删自己写进去的那部分。对同时在用 Claude Code / Codex / Hermes 的人来说，这一项省的重复劳动最多。

6. 日常操作：界面 vs 命令行

想做什么	菜单栏界面	命令行
看每个 Agent 现在用什么	Agents 页	`magpie ls`
换某个 Agent 的模型	点那个值 → 搜索 → 选	`magpie claude moonshot/kimi-k2.5`
只换某一档（如 haiku 这一档）	点 haiku 那一行	`magpie claude haiku deepseek/deepseek-v4-flash`
换别的字段（如推理强度）	点对应值	`magpie codex effort high`
存 / 切整套方案	底部方案 chips	`magpie save 省钱` / `magpie use 省钱`
看订阅额度	菜单栏面板	`magpie quota` / `magpie accounts`
看花费 / 会话 / 上下文占用	Usage 页	—（界面专属）
加 provider / 测通不通	Providers 页的 Test	`magpie provider add …` / `magpie provider test deepseek`
建路由组	Routing 页	`magpie group add daily models=… routing=smart`
终端全套界面	—	`magpie tui`
浏览器界面	—	`magpie web`
只要网关、不要窗口	—	`magpie serve`
开机自启	设置里	`magpie autostart on`
备份 / 换机	设置	`magpie backup` / `magpie restore <文件>`

TUI 按键：↑↓ 选 Agent，←→ 选字段，↵ 打开选择器，直接打字过滤，s 存方案，p 应用/删除方案（ctrl+d 删），S 同步模型目录，q 退出。

7. 六个立刻能省时间 / 省钱的用法

7.1 给贵 Agent 换便宜模型（最直接的省钱动作）

magpie claude haiku deepseek/deepseek-v4-flash   # 只改 haiku 这一档
magpie codex deepseek/deepseek-v4-pro            # Codex 整体换厂商
magpie ls                                        # 确认改对了

要点：magpie 只改它该改的那个键，配置里其他内容、注释、顺序都不动。旧值会存进 stash.json，想还原就 magpie <agent> default（整个 Agent 还原），或 magpie <agent> <字段> default（只还原一个字段）。

7.2 两组方案：省钱档 / 火力档

一次调好所有 Agent，然后存成两个名字，之后一键互切：

# 全部调成便宜组合后
magpie save 省钱

# 再把要火力的那几个改强
magpie save 火力

# 之后一条命令整套切
magpie use 省钱

界面里就是底部那两个 chip，点一下切换。方案会连每个 Agent 的「常用模型短名单」一起保存。

7.3 订阅额度用完自动切换（路由组）

magpie group add daily models=claude/claude-haiku-5-5,codex/gpt-5.6-luna routing=smart
magpie claude group/daily

五种调度模式：

模式	作用
`smart`	在还有额度的订阅里，优先用最快重置的那个（重置时浪费最少）
`order`	先用第一个，它答不了再用下一个
`rotate`	每一轮换下一个成员
`usage`	优先用用得最少的成员
`pace`	优先用「距离重置前每小时剩余周额度最多」的账号

细节：对话会留在回答它的那个账号上，只要厂商的 prompt cache 还值得保留；路由组可以嵌套；Routing 页能实时看到每一次路由决策。

7.4 额度、花费、上下文，一处可见

magpie quota —— 每个订阅 / key / 套餐还剩多少，以及额度窗口什么时候重置。
magpie accounts —— 每个账号的 5 小时窗口和 7 天窗口用量（实测本机 Codex 显示 5h 0%、7d 18%、↻5d4h）。
Usage 页 —— token、缓存读写、推理、调用次数，按官方价格折算花费；还能看每个会话的花费与标题，一键在终端里重新打开；每个请求的上下文窗口有多满、多少来自缓存。
菜单栏面板本身也能常显额度。

7.5 让自家脚本和工具复用订阅额度（性价比最高的一招）

任何能填 base URL 的工具都能用这个网关，不用单独配 key：

export OPENAI_BASE_URL=http://127.0.0.1:3425/v1     OPENAI_API_KEY=magpie
export ANTHROPIC_BASE_URL=http://127.0.0.1:3425     ANTHROPIC_API_KEY=magpie
export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425 GEMINI_API_KEY=magpie

意义：你自研的脚本、Hermes、dsh、任何小工具，都可以直接吃你已付费的订阅额度，而不是各自去申请一套 API key。这也是把 magpie 当「本地模型网关」用的正确姿势。

7.6 资料库 Library：指令 / MCP / 技能写一次

在 Library 里写一份 instruction、登记一个 MCP 服务器、放一个 skill，magpie 会自动转成 Claude Code、Codex、Hermes、OpenCode、dsh 各自的格式分别写入。删除时只删自己写进去的部分，不动你原有的内容。

7.7 网关中间件：模型别名、统一系统提示词、敏感词

官方的现成中间件（同类功能对应 New API 的渠道配置）：

包	作用
`model-map`	把模型换个名字发出去，回复里仍是原来请求的名字
`param-override`	按条件设置 / 删除 / 移动 / 改写请求字段，或直接拒绝请求
`system-prompt`	给所有请求，或某些 Agent / 某些模型的请求加上你的系统提示词
`word-guard`	敏感词过滤（请求和回复都管）
`think-tags`	去掉回复里的 `<think>…</think>`，或把 `reasoning_content` 放进回复

magpie plugin add @magpie-community/middleware-model-map
magpie plugin options model-map '{"mapping": {"fast": "deepseek/deepseek-chat"}}'

也可以自己写一段 JS：onRequest 能改写或拒绝请求，onEvent 看到每个流式事件，onResponse 看到完整回复；钩子抛错或超时，请求原样放行。

7.8 局域网共享 / 多机复用

能力	说明
局域网共享	打开后给每个客户端一个命名网关 key，可分别设每天/每周/每月的 token 与花费上限
远程 magpie	笔记本用台式机上那个 magpie 的 provider、账号和路由组，同时照常配置自己的 Agent
Docker	在服务器或 NAS 上跑 `ghcr.io/yetone/magpie`，用 Web 界面管理
同步	备份到文件，或通过 WebDAV（坚果云、Nextcloud）在多台机器间同步

8. 本机实测记录（2026-10-17，v0.1.1278）

项	实测结果
版本 / 形态	0.1.1278，菜单栏应用常驻运行
网关	`http://127.0.0.1:3425`，三套协议互转正常；本机免 key
可用模型	34 个（Claude 17 / Codex 7 / Gemini 10）
配置目录	`~/.config/magpie/`（`settings.json` / `logins.json` / `quotas.json` / `usage.jsonl` / `applied.json` / `stash.json`）
开机自启	默认关闭
Codex 订阅路由	实跑返回正常
Claude 订阅路由	401 `OAuth access token is invalid` —— 见下方坑 1
Hermes 默认模型	被 magpie 改成了 `magpie/claude/claude-opus-5-5`，而该路由正 401 —— 见下方坑 2

坑 1：magpie 里的 Claude 订阅会 401，但 Claude 本体是好的

现象：走网关调 Claude 模型全部 401 OAuth access token is invalid；但本机 claude -p ... --model claude-haiku-4-5 正常返回。
原因：magpie 读的是 ~/.claude/.credentials.json（文件时间戳停留在旧日期，token 已过期），而真正活的凭据在 macOS 钥匙串里。
处理：面板 Providers → Claude → 重新登录（或删掉该账号重新加）。不要因此判断 Claude 本身坏了。

坑 2：装完 magpie，别的工具的默认模型会被它改掉

applied.json 记录显示 magpie 把 Hermes 的默认模型改成了 magpie/claude/claude-opus-5-5，而这条路由正好 401，于是 Hermes 只能走 fallback 兜底。
规则：每次动完 magpie，都要用「一次真实网关调用 + magpie ls」确认改对了，不要只看界面显示。原值存在 stash.json，magpie <agent> default 可以还原。

其他实测/文档差异提醒

Claude Code 那一档的推理强度：magpie 面板上可以设 effort，如果设成最大档，等于主动加速烧额度——省钱目标下要检查这里。
Gemini 订阅：Google 已不再为个人账号提供 Gemini CLI 服务，该路由会报错；需要迁移到 Antigravity，或改用有 Cloud 项目的账号。
模型名会随厂商更新（选择器里的列表来自厂商 + models.dev 目录，后台自动刷新），所以别把本文的模型名当成固定值。

9. 隐私与安全

项	说明	怎么关
读取各 Agent 的登录信息	它靠读 Claude Code / Codex 的登录文件和钥匙串来发现订阅	设置 → 隐私 → 关闭「订阅账号」，或 `magpie accounts discovery off`；`MAGPIE_ACCOUNTS=0` 只对单次运行生效
每日匿名统计	每天一次，只发随机 ID、版本、系统、用了哪些 agent/provider/model（自定义 provider 只记作 `custom`），不发提示词、URL、账号、key、用量	设置 → 隐私，或 `DO_NOT_TRACK=1`
局域网共享	打开后网关监听所有网卡，网关 key 明文存在 `settings.json` 里	只在可信内网开；否则关掉
密钥存放	provider key 存在 `providers.json`（0600），不进 Agent 的配置文件	—

10. 命令速查卡

# 看现状
magpie ls                       # 每个 Agent 当前的模型/字段
magpie providers                # provider、key、暴露的模型、谁在用
magpie quota / magpie accounts  # 额度与账号用量
magpie models [<agent>]         # 某个 Agent 可以选哪些模型

# 改模型
magpie claude moonshot/kimi-k2.5
magpie claude haiku deepseek/deepseek-v4-flash   # 只改一档
magpie codex effort high
magpie <agent> default          # 还原成 magpie 接管前的值

# 方案 / 路由
magpie save 省钱 && magpie use 省钱
magpie profiles / magpie rm 省钱
magpie group add daily models=a,b routing=smart
magpie claude group/daily

# provider / 插件
magpie provider add deepseek sk-…
magpie provider test deepseek
magpie plugin add @magpie-community/middleware-model-map
magpie plugin options model-map '{"mapping":{"fast":"deepseek/deepseek-chat"}}'

# 界面形态
magpie tui / magpie web / magpie serve

# 备份与同步
magpie backup / magpie restore <文件>
magpie sync                     # 刷新 models.dev 目录和各家模型列表

11. 常见问题

改了模型，正在跑的会话没变？ 正常。Agent 只在启动时读配置，开新会话才生效。

想在别的电脑用这台机器的订阅额度？ 开「在局域网共享」，给那台机器发一个网关 key；或者用「远程 magpie」让它直接用本机的 provider 和路由组。

怎么完全卸载 / 回到装之前？ 先把每个 Agent 还原：magpie <agent> default（原值都在 stash.json）。再关掉开机自启 magpie autostart off，退出应用。配置目录 ~/.config/magpie/ 保存着 key 和方案，卸载前建议先 magpie backup。

magpie 会不会改坏我的配置文件？ 它只改该改的那个键，并且改写前会留 .bak 备份、旧值进 stash.json。但路由不通时它会静默降级（见坑 2），所以改完要实测一次。

12. 参考

官网 / 下载：https://usemagpie.ai/zh/
中文文档入口：https://usemagpie.ai/docs/zh/start
完整参考（英文，含每个 Agent 的配置文件、每个 provider 选项、网关接口、CLI 全命令、magpie 自己的所有文件）：https://github.com/yetone/magpie/blob/main/docs/reference.md
插件社区：https://github.com/magpie-community/plugins
Discord：https://discord.gg/vGSnD3ZKQF
许可证：MIT