Magpie 实战教程：一个本地网关，让 Claude Code 跑 Kimi、Codex 跑 DeepSeek
先看一组命令：
magpie provider add deepseek sk-… # 加一个 DeepSeek key
magpie claude deepseek/deepseek-v4-pro # Claude Code 改用 DeepSeek
magpie codex moonshot/kimi-k2.5 # Codex 改用 Kimi
magpie save cheap && magpie use cheap # 存成方案，下次一键切回
四行命令，没有手改一行 settings.json，没有 export ANTHROPIC_BASE_URL。开一个新的 Claude Code 会话，背后已经是 DeepSeek。
这就是 magpie。它是 yetone 做的开源项目，仓库 2026 年 9 月 23 日创建，到 11 月 4 日 GitHub Star 已经 2.9 万，最新 tag 是 v0.1.2906。增长这么快，是因为它解决的是一个每个多 Agent 用户都在忍的问题：
每个 Agent 都把模型写在自己的配置文件里，格式各不相同，key 和 base URL 各管各的。花钱买的订阅只能在一个 Agent 里用。
读完这篇你能做到：
- 装好 magpie，十分钟内让 Claude Code / Codex / Gemini CLI 用上任意厂商的模型；
- 用「方案」在省钱配置和主力配置之间一键切换；
- 用「路由组」把多个账号、多个厂商合成一个模型，额度用完自动换号；
- 用「意图路由」让简单问题走便宜模型、写测试走强模型；
- 打开本地脱敏，让 .env 里的 key 不出你的电脑；
- 知道哪些地方会踩坑。
一、先搞清楚它是什么：一个本地网关 + 一个配置管理器
magpie 做两件事：
第一，在 127.0.0.1:3425 跑一个网关。 这个网关同时讲四种 API：OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini，并且能互相转换，流式输出、工具调用、推理过程都保留。所以 Claude Code（只会讲 Anthropic 协议）可以用 DeepSeek，Codex（讲 Responses）可以用 Claude 订阅。
第二，替你改 Agent 的配置文件。 你在界面里点一个模型，magpie 只改那个 Agent 配置里需要的几个键，注释、顺序、缩进原样保留，写入是原子的。具体改了什么，文档写得很清楚：
两个推论：
- 不需要自己 export 环境变量。 magpie 管理的 Agent，网关地址和令牌直接写进配置。
- 随时能撤。 magpie <agent> default 会删掉它写入的内容，并恢复被它替换掉的值，比如你原来的 ANTHROPIC_BASE_URL。
几个术语后面会反复出现，先对齐：
它适合你吗？ README 自己给了判断标准：用不止一个 Agent、不止一个 provider 或不止一个账号，就适合。只用一个 Agent、只用它自家订阅且够用，就不需要。
二、安装
2.1 三种装法
桌面版（推荐）：去 usemagpie.ai 下载。支持 macOS 12+（Apple Silicon 和 Intel）、Windows 10+、Linux（需要 GTK 3 和 WebKitGTK 4.1）。Mac 版已签名公证，每个版本自动更新。
一行脚本：
curl -fsSL https://usemagpie.ai/install.sh | sh
Linux 上脚本会判断：有桌面就装桌面版（缺 WebKitGTK 4.1 会调包管理器装，要 sudo 密码）；没桌面就装终端版。想自己选，加 --gui 或 --tui。
其他方式：go install github.com/yetone/magpie@latest，或者用 Docker 镜像 ghcr.io/yetone/magpie（第九节讲）。
2.2 国内网络
安装脚本和更新都要访问 GitHub。连不上时加代理或镜像：
# 走本地代理
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890
# 更新时走代理（支持 http、https、socks5、socks5h）
magpie update --proxy socks5://127.0.0.1:1080
# 之后每次更新都走某个 GitHub 下载镜像
magpie update mirror <前缀>
magpie update mirror off # 取消
镜像只负责下文件，SHA-256 始终从 usemagpie.ai 取，镜像改过的文件会被拒绝安装。
2.3 卸载
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall
~/.config/magpie 里的设置会保留，加 --purge 才会断开所有 Agent 并一起删除。或者直接 magpie uninstall：先把每个 Agent 还原，再删 magpie 的服务和文件。
装完跑一下：
$ magpie --version
magpie 0.1.2906
三、十分钟上手：给 Agent 换模型
主线只有三步：加 provider → 给 Agent 选模型 → 开新会话。
3.1 加 provider
打开 magpie，进入 Providers → 添加 provider。
provider 分四类：
① 厂商预设：粘贴 key 就行。 magpie presets 列出全部预设，这是 v0.1.2906 的部分输出：
$ magpie presets
vendors
Anthropic anthropic magpie provider add anthropic <key>
OpenAI openai magpie provider add openai <key>
Google Gemini google magpie provider add google <key>
DeepSeek deepseek magpie provider add deepseek <key>
Kimi (China) moonshot-cn magpie provider add moonshot-cn <key>
Zhipu GLM zhipu magpie provider add zhipu <key>
MiniMax (China) minimax-cn magpie provider add minimax-cn <key>
Qwen (China) qwen-cn magpie provider add qwen-cn <key>
Volcengine Ark volcengine magpie provider add volcengine <key>
...
relays
OpenRouter openrouter magpie provider add openrouter <key>
SiliconFlow siliconflow magpie provider add siliconflow <key>
ModelScope modelscope magpie provider add modelscope <key>
...
注意 Kimi、MiniMax、Qwen 都分国际版和国内版（-cn），国内 key 记得选带 -cn 的。
模型列表是直接问厂商要的，名称和推理档位从 models.dev 补全。厂商早上发了新模型，下次刷新就出现在选择器里。
② 订阅：登录即可，不用 key。 Claude（Pro / Max / Team）、ChatGPT（Plus / Pro / Business）、GitHub Copilot、Gemini（Code Assist）、Antigravity。点卡片，magpie 在浏览器里打开厂商自己的登录页，登完账号就出现。本机已经登录过的 Agent 会自动显示为「已登录 …」。
订阅里的模型在其他 Agent 里写作 claude/…、codex/…、copilot/…。也就是说，你的 ChatGPT 订阅可以给 Claude Code 用，Claude 订阅可以给 Codex 用。
③ 本机模型： Ollama、LM Studio，不用 key。
④ 自定义：任意兼容地址。 填名称、OpenAI 兼容地址（以 /v1 结尾）或 Anthropic 兼容地址（根地址，即 ANTHROPIC_BASE_URL 的值），或两个都填。中转站基本都走这里。
已经在别处配过？ 面板顶部的「导入…」能读 CC Switch、Claude Code 的 settings.json、Codex 的 config.toml 和 Alma 里的 provider，只读不改，勾选导入。
key 保存在 ~/.config/magpie/providers.json，只有你自己可读。magpie 不读 shell 环境变量里的 key，你加什么它用什么。
命令行版本：
magpie provider add deepseek sk-xxxx # 预设只需要 key
magpie provider add moonshot-cn sk-xxxx
magpie accounts add codex # 再登录一个 ChatGPT 订阅
magpie providers # 看看加了哪些
magpie models # 所有能选的模型，provider/model 格式
3.2 给每个 Agent 选模型
进入 Agents 页。本机装了的 Agent 各占一行（magpie 只显示你装了的）。
点模型会弹出可搜索的列表，分三组：Agent 自带的、你的路由组、你加的每个 provider。也能直接输入列表里没有的模型 ID。
几个隐藏开关值得知道：
- 推理强度：Agent 支持时（Codex 的推理强度、Pi 的思考），列表下方有滑块。
- 快速模式：支持的模型旁边有个闪电按钮，点了这个 Agent 发给这个模型的请求都带 service_tier: "priority"（Claude 是 speed: "fast"）。更快，也更贵。
- Claude Code 分档：经 magpie 使用模型时，opus、sonnet、haiku 三档可以分别指定模型，默认跟随主模型。
命令行：
magpie ls # 列出所有 Agent 和当前设置
magpie claude deepseek/deepseek-v4-pro # 主模型
magpie claude haiku deepseek/deepseek-v4-flash # 单独给 haiku 档配便宜模型
magpie claude haiku "" # haiku 档回到跟随主模型
magpie codex moonshot/kimi-k2.5
magpie codex effort high # 改其他字段
magpie gemini zhipu/glm-5.3
Agent 名支持前缀简写，比如 cc、oc、gem。
3.3 开新会话验证
已经在跑的会话保持它启动时的模型。 Agent 启动时读配置，所以改动从下一个会话生效。Codex 还要额外注意：它在启动时生成模型列表，切换后要重启 Codex 应用和已打开的 codex 会话。
3.4 还原
magpie claude default # Claude Code 回到接入 magpie 之前的样子
magpie codex effort default # 只把某个字段还原
在选择列表里选 Agent 自带的模型（opus、sonnet 等），效果一样。
3.5 第一个坑：Claude Code 的 claude.ai 登录
这条官方参考文档里写了，但很容易忽略：
magpie 往 ANTHROPIC_AUTH_TOKEN 写入 key 后，Claude Code 在经 magpie 运行期间会从 claude.ai 登出：/usage 里的套餐额度、connectors、语音、/teleport 都不可用。
如果你想保留 claude.ai 登录，把 Claude Code 的登录方式设为「claude.ai 登录」。这时 magpie 把 token 写成空值，Claude Code 把自己的 claude.ai 凭据发给 magpie，magpie 不会把它转发给别的厂商。Remote Control 和 ultrareview 仍然不可用，因为 Claude Code 只在 Anthropic 官方地址上开放这两个功能。
四、方案：一键切换整套配置
你可能有这样几套配置：
- 省钱：Claude Code 用 DeepSeek，Codex 用 Kimi；
- 主力：Claude Code 用 Claude 订阅，Codex 用 ChatGPT 订阅；
- 离线：全部走本机 Ollama。
方案把所有 Agent 的设置存成一个名字：
magpie save cheap # 当前所有 Agent 的设置存为 cheap
magpie save main
magpie use cheap # 一键切回
magpie profiles # 列出方案
magpie rename cheap budget
magpie rm budget
界面里在 Agents 页底部点「＋ 保存当前」。正在用的方案带 ✓，菜单栏的「方案」按钮也显示它的名字。之后手动改了任何设置，✓ 会消失，提醒你已经偏离方案。
五、路由组：多账号、多厂商，额度用完不断流
方案解决「手动切」，路由组解决「自动切」。
5.1 不用建的路由组：auto/
你加了两个都提供同名模型的 provider，比如 Claude 订阅和 Copilot 都有 Claude Opus，DeepSeek 官方和 OpenRouter 都有 DeepSeek，magpie 会自动组一个 auto/<模型> 路由组。名字按各家写法匹配，deepseek/deepseek-chat 和 deepseek-chat 算同一个。
给 Agent 选这个组，请求就分摊到所有提供这个模型的 provider 上。不想要的用 magpie group rm 隐藏。
5.2 手动建一个
magpie group add "Opus anywhere" \
models=claude/claude-opus-5-5,copilot/claude-opus-5.5 \
routing=smart
magpie claude group/opus-anywhere # Claude Code 用这个组
Claude 订阅额度用完，请求自动落到 Copilot 上，Agent 看不到报错。
一个前提：只有一个账号又没建路由组时，没有可换的，报错会原样回给 Agent。
5.3 路由模式怎么选
magpie help 里列出的全部模式：smart|order|rotate|usage|pace|weight|free|fast|cheap|drain。常用的几个：
cheap 有个细节：它会考虑分时计价。文档举的例子是 DeepSeek 官方 API 在高峰时段双倍计价，同一个 DeepSeek 模型挂在两个 provider 上时，magpie 会交给这个时段更便宜的那个。
5.4 会话保持：别让缓存白白失效
换账号最大的隐性成本是丢 prompt cache。路由组默认 stays=auto：一轮之内总是留在同一个账号上，跨轮则在厂商缓存还值得保留时继续留着。
5.5 规则：把某类对话交给指定模型
路由组可以挂规则，条件包括 token 数、带图片、要求推理、来自某些 Agent、意图、压缩上下文、时段、项目文件夹。每次你发新消息时从上往下检查，第一条命中的规则把它的模型排第一，其余成员排后面做故障转移。
几个实用写法，全部来自官方文档：
# 长对话交给大上下文模型
magpie group rule add opus-anywhere use=openrouter/anthropic/claude-opus-5.5 tokens=150k
# /compact 的总结交给便宜模型，对话本身不动
magpie group rule add opus-anywhere use=deepseek/deepseek-v4-flash compact
# 这些项目里的对话先发给 Kimi
magpie group rule add opus-anywhere use=kimi/kimi-k2.6 folders=~/oss,"~/My Project"
# 工作日下午这段时间不用 Copilot
magpie group rule add opus-anywhere pause=copilot/claude-opus-5.5 time=14:00-18:00 days=mon-fri
# 查看、调整顺序、删除
magpie group rule opus-anywhere
magpie group rule mv opus-anywhere 3 1
magpie group rule rm opus-anywhere 2
两个容易忽略的细节：
- 规则只在一轮开始时决定。 Agent 回传工具结果的过程中不会半途换模型，避免丢缓存。唯一例外是这一轮涨到超过当前模型的上下文。
- token 阈值留余量。 给 200k 的模型设 150k，而不是 199k。
compact 这条特别划算：Claude Code 的 /compact 和自动压缩、Codex、OpenCode 等的压缩请求都能识别，让便宜模型写总结，主对话留在原来的模型和缓存上。
5.6 路由组可以嵌套
路由组的成员可以是另一个路由组：
magpie group set coder models+=group/opus-anywhere
每一层按自己的路由方式和规则分配，最多嵌套 8 层，不会出现循环包含（magpie 会拒绝）。
六、意图路由：简单问题走便宜模型，写测试走强模型
这是 magpie 我觉得最有意思的功能。它的原理一段话就能说清：
每一轮你发消息时，magpie 把带编号的意图列表和你最新一条消息，发给你指定的一个小模型，让它回答一个数字。magpie 用这个数字从上往下匹配规则。没有向量嵌入、没有关键词表、不需要训练。
6.1 配一个 Coder 组
官方文档里的例子：
# 第一条规则顺便指定意图判断模型（classifier），只需要第一次
magpie group rule add coder use=deepseek/deepseek-v4-flash \
intent="a quick question" classifier=groq/llama-3.1-8b-instant
magpie group rule add coder use=deepseek/deepseek-v4-pro \
intent="writing or fixing tests"
# 同一个模型，用 low 推理强度处理简单修改
magpie group rule add coder use=deepseek/deepseek-v4-pro use-effort=low \
intent="a simple edit"
magpie group rule coder # 看规则和判断模型
magpie group rule classifier coder groq/llama-3.1-8b-instant # 换判断模型
意图用中文写也行，比如 intent="写测试或修测试"。
6.2 一轮是怎么走的
假设 Coder 组有三条规则：
- 2 万 tokens 的一轮：规则 1 不成立，规则 2、3 的意图都是候选，问判断模型。
- 15 万 tokens 的一轮：规则 1 不带意图且成立，直接发给 Kimi，根本不问判断模型，不产生费用。
- 判断模型回答 0（都不是）：没有规则命中，按组本来的路由走。
官方截图里一个真实请求：判断模型 deepseek-flash 用 964 毫秒判断为 "writing or fixing tests"，请求被路由到对应模型，5.6 秒完成回答。
6.3 成本和风险
- 判断模型只看这一条消息，不看整段对话。同一条消息、同一组意图的回答缓存 10 分钟。
- 一轮只判断一次，Agent 调工具的过程中不再判断。
- 超时默认 8 秒，在「设置 → 模型 → 回复 → 意图判断超时」调整（8/15/30/60 秒）。判断模型出错、超时或答非所问时，所有意图都不命中，按没有这些规则的方式路由，不会卡住。
- 判断模型建议选小而快、不带推理的。它的调用在用量里显示为 magpie 自己的调用。
七、隐私脱敏：key 不出你的电脑
Agent 会把读到的东西塞进提示词：一个 .env、一份配置、一段带 token 的日志。这些都会发给厂商。
magpie 的做法是在请求离开电脑前，把敏感值换成占位符，回复里再换回来。
7.1 看效果
打开「脱敏密钥」和「脱敏个人信息」，并在脱敏词里填 Nightjar。Agent 发出：
Deploy Nightjar with OPENAI_API_KEY=sk-proj-8fK2mQx7Lp4Rt9Vw3Yz6Ab1Cd, then mail li.wei@acme-corp.cn or call 13800138000.
厂商收到：
Deploy {{TERM_5hmsrhdc}} with OPENAI_API_KEY={{API_KEY_srhjgvja}}, then mail {{EMAIL_eh5um6mb}} or call {{PHONE_uf7iy2qq}}.
模型回复「我已在 .env 里把 OPENAI_API_KEY 设为 {{API_KEY_srhjgvja}}」时，Agent 读到的是真实的 key。流式文本和工具调用参数里都会换回，所以 Agent 写进文件的也是真 key。
7.2 打开它
默认关闭。进入 设置 → 隐私：
- 脱敏密钥：API key、私钥、Token、密码；
- 脱敏个人信息（按需）：邮箱、手机号、身份证号、银行卡号（校验位对得上的才算）；
- 脱敏词：项目代号、人名、内网主机名，每行一个；
- 试一试：粘一段文字，看厂商实际会收到什么。
没有窗口时（magpie serve、Docker）直接写 ~/.config/magpie/settings.json，每个请求都会重新读：
{
"redact": true,
"redactPersonal": true,
"redactWords": ["Nightjar", "db.acme-corp.cn"]
}
也可以用命令行：magpie settings set redactWords acme,globex。
7.3 它为什么不会把对话搞坏
- 占位符稳定：「类型 + 8 位带密钥的哈希」，同一个值每次得到同一个占位符。对话上下文、提示词缓存、thinking 签名都不受影响。
- 原值不落盘：只在内存里。记录只留类型、长度和开头几个字符，保存在 ~/.config/magpie/masking，30 天。
- 失败即不发送：脱敏打开却运行不了时，请求返回 503，绝不退回成明文发出。
除了规则，还可以加一个本地模型找规则找不到的人名、地址：默认是 AstrLink Guard（中英文，39 MB，在 Mac 上用神经网络引擎跑），也可以换成 OpenAI 的 Privacy Filter（1.6 GB）。
7.4 代价
- 模型看到的是 {{API_KEY_…}}，所以针对值本身的任务做不了，比如「这个 token 为什么被拒」。这类值加进「从不脱敏」。
- 图片原样发送，截图里的文字不会被遮。
- 只覆盖经过 magpie 的请求。Agent 用自家模型直连厂商时不在范围内。
- 本机 Ollama 这类 provider 可以设为不脱敏：magpie provider set ollama unmasked=yes。
每种类型命中后可以选「脱敏」「提醒」或「拦截」。拦截时返回 400，消息里不含原值。
八、用量和额度：钱花在哪了
magpie usage 7d # 按 Agent 和模型统计 token 与费用
magpie quota # 每个订阅、套餐、key 还剩多少
magpie quota wait codex # 阻塞到某个 Codex 账号恢复额度
用量页按 Agent 和模型统计 token、缓存读写、推理和调用次数，按官方价格换算成美元或人民币，任何模型都能自定义价格。
「上下文」标签页值得单独看一眼：它拆出每个 Agent 的提示词里装了什么（系统提示词、工具定义、指令文件与 skills、读入的文件、对话），各占上下文窗口多少，还给一个百分制得分和「MCP 偏重」之类的标签。如果你怀疑某个 MCP 服务器吃掉了大半上下文，这里一眼能看出来。
注意：Agent 直连自家厂商的请求不经过 magpie，不计入。
九、进阶：把 magpie 用到更多地方
9.1 不在列表里的工具，也能接网关
任何能填 base URL 的工具都能用：
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
你自己写的脚本、LangChain 项目，改一下 base URL 就能用上 magpie 里所有的模型和路由组。网关页有 shell、curl、Python、Node 的现成代码片段。
9.2 后台常驻
关掉窗口后 magpie 仍在菜单栏。想开机就跑、不要窗口：
magpie daemon install # Linux 用 systemd，Mac 用 launchd
magpie daemon install --web # 同时提供浏览器管理页
magpie daemon status
9.3 一台机器配好，全家用：远程 magpie
在保存 provider 的那台机器上：设置 → 网络与共享 → 局域网共享 → 开启，然后给每台电脑发一个网关密钥：
magpie gateway-key add "Laptop" # 打印 sk-magpie-key-…
每个密钥可以单独设每日、每周、每月的 token 和花费上限，以及可用模型。
在笔记本上把它加成 provider：
magpie provider add remote-magpie sk-magpie-key-… url=http://192.168.1.20:3425 id=office
magpie models # office/… 就是台式机上的模型
台式机上的路由组以 office/group/… 出现。笔记本上的 magpie 照样配置自己的 Agent，只是模型来自另一台。
9.4 Docker / NAS
docker run -d --name magpie --restart unless-stopped \
-p 127.0.0.1:3425:3425 -p 127.0.0.1:3430:3430 \
-e MAGPIE_WEB_KEY=$(openssl rand -hex 16) \
-v magpie-config:/config \
ghcr.io/yetone/magpie:latest web --addr 0.0.0.0:3430 --no-open
docker logs magpie # 日志里有带 key 的管理页地址
3425 是网关
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。