Magpie 实战教程：一个本地网关，让 Claude Code 跑 Kimi、Codex 跑 DeepSeek

Yue的AI工坊
0 阅读22分钟

Magpie 实战教程：一个本地网关，让 Claude Code 跑 Kimi、Codex 跑 DeepSeek

cover.png

先看一组命令：

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 里用。

读完这篇你能做到：

  1. 装好 magpie，十分钟内让 Claude Code / Codex / Gemini CLI 用上任意厂商的模型；
  2. 用「方案」在省钱配置和主力配置之间一键切换；
  3. 用「路由组」把多个账号、多个厂商合成一个模型，额度用完自动换号；
  4. 用「意图路由」让简单问题走便宜模型、写测试走强模型；
  5. 打开本地脱敏，让 .env 里的 key 不出你的电脑；
  6. 知道哪些地方会踩坑。

一、先搞清楚它是什么：一个本地网关 + 一个配置管理器

official-architecture-zh.png

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 配置里需要的几个键，注释、顺序、缩进原样保留，写入是原子的。具体改了什么，文档写得很清楚：

Agent写入位置改了什么
Claude Code~/.claude/settings.jsonenv 里的 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 和模型变量
Codex~/.codex/config.toml一个 [model_providers.magpie] 表 + 模型；模型列表写到 ~/.codex/magpie-models.json
Gemini CLI~/.gemini/settings.json、~/.gemini/.envGOOGLE_GEMINI_BASE_URL 指向网关、API key 认证、模型
OpenCode / Pi / Crush各自的配置文件一个 magpie provider 条目，模型写作 magpie/provider/model

两个推论：

  • 不需要自己 export 环境变量。 magpie 管理的 Agent，网关地址和令牌直接写进配置。
  • 随时能撤。 magpie <agent> default 会删掉它写入的内容，并恢复被它替换掉的值，比如你原来的 ANTHROPIC_BASE_URL。

几个术语后面会反复出现，先对齐：

术语含义
Provider（供应商）模型从哪来：API key、登录的订阅、本地模型。每个模型写作 provider/model
Agent用模型的工具：Claude Code、Codex、Gemini CLI、OpenCode……
方案（Profile）所有 Agent 当前设置的快照，一键切回
路由组（Group）多个模型或账号合成一个，Agent 当作一个模型选：group/<id>

它适合你吗？ 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。

official-add-zh-light.png

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 只显示你装了的）。

official-agents-zh-light.png

点模型会弹出可搜索的列表，分三组：Agent 自带的、你的路由组、你加的每个 provider。也能直接输入列表里没有的模型 ID。

official-panel-light.png

official-picker-light.png

几个隐藏开关值得知道：

  • 推理强度：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 看不到报错。

official-routing-zh-light.png

一个前提：只有一个账号又没建路由组时，没有可换的，报错会原样回给 Agent。

5.3 路由模式怎么选

magpie help 里列出的全部模式：smart|order|rotate|usage|pace|weight|free|fast|cheap|drain。常用的几个：

模式行为适合
smart（默认）有余量的订阅里，额度最先重置的排第一多个订阅账号，不想浪费额度
order先用第一个，答不了再用下一个主力 + 备胎
drain一个用到额度耗尽再换，且不切回想把某个账号榨干
rotate每一轮换下一个成员均摊负载
usage剩余额度最多的排第一均衡消耗
pace每周剩余额度 ÷ 距重置小时数最高的排第一周额度制订阅，少浪费
weight按权重分请求Max 账号 5、Pro 账号 1 这种
fast最近首字时间和输出速度最快的先用对延迟敏感
cheap当前时段最便宜的先用（仅路由组）同一模型挂在多个 provider 上

cheap 有个细节：它会考虑分时计价。文档举的例子是 DeepSeek 官方 API 在高峰时段双倍计价，同一个 DeepSeek 模型挂在两个 provider 上时，magpie 会交给这个时段更便宜的那个。

5.4 会话保持：别让缓存白白失效

换账号最大的隐性成本是丢 prompt cache。路由组默认 stays=auto：一轮之内总是留在同一个账号上，跨轮则在厂商缓存还值得保留时继续留着。

stays=行为
auto（默认）一轮内保持；跨轮在缓存值得保留时保持
session整个会话保持，只要它还能回答
turn只在一轮内保持
off每个请求重新路由
strict绝不换号，额度用完直接把错误交给 Agent

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 组有三条规则：

#条件先发给
1≥ 128000 tokenskimi/kimi-k2.5
2意图是 "a quick question"deepseek/deepseek-v4-flash
3意图是 "writing or fixing tests"deepseek/deepseek-v4-pro
  • 2 万 tokens 的一轮：规则 1 不成立，规则 2、3 的意图都是候选，问判断模型。
  • 15 万 tokens 的一轮：规则 1 不带意图且成立，直接发给 Kimi，根本不问判断模型，不产生费用。
  • 判断模型回答 0（都不是）：没有规则命中，按组本来的路由走。

official-intent-trace-zh-light.png

官方截图里一个真实请求：判断模型 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 打开它

默认关闭。进入 设置 → 隐私：

  1. 脱敏密钥：API key、私钥、Token、密码；
  2. 脱敏个人信息（按需）：邮箱、手机号、身份证号、银行卡号（校验位对得上的才算）；
  3. 脱敏词：项目代号、人名、内网主机名，每行一个；
  4. 试一试：粘一段文字，看厂商实际会收到什么。

没有窗口时（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 它为什么不会把对话搞坏

official-masking-zh-light.png

  • 占位符稳定：「类型 + 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，消息里不含原值。

八、用量和额度：钱花在哪了

official-usage-zh-light.png

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 是网关，3430 是 Web 管理页。容器外的请求必须带网关密钥。官方特别提醒：拿到管理页链接的人能看到所有 key，3430 只放在回环地址或 VPN 上，远程访问用 SSH 隧道：ssh -L 3430:127.0.0.1:3430 you@nas。

9.5 给沙箱和 CI 发短期密钥

magpie gateway-key issue --ttl 1h --name sandbox-1 --models office/codex/gpt-5 --tokens 200000

有效期 1 分钟到 30 天，可限模型、限 token、限花费。GitHub Actions 还能用 OIDC token 换短期密钥，仓库 secrets 里不用放网关密钥（见远程 magpie 文档）。

9.6 网关中间件

一段 JavaScript 就能改写经过网关的每个请求：

// alias.middleware.js — magpie plugin add ./alias.middleware.js
export function onRequest(body, ctx) {
  if (body.model === "fast") return { ...body, model: "deepseek/deepseek-chat" };
}

onRequest 改写或拒绝请求，onEvent 看每个流式事件，onResponse 看完整回复。钩子抛错或超时，请求原样放行。社区有现成的 model-map、system-prompt、think-tags 等，大多对应 New API 的渠道功能：

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

9.7 其他顺手的功能

  • 资料库：指令、MCP 服务器、skills、子代理写一次，magpie 按每个 Agent 的格式写进它的文件。
  • 任何模型都能联网搜索：不能搜的模型由 magpie 代搜，支持 Tavily、Brave、Exa、SearXNG、火山引擎豆包搜索等。
  • 直接调工具：magpie tool generate_image "一只喜鹊，水彩" -o hero.png。
  • 多机同步：magpie webdav（坚果云、Nextcloud）、magpie s3、magpie github（加密仓库）。

十、踩坑清单

现象原因处理
换了模型，Agent 还在用旧的已在运行的会话保持启动时的模型开新会话；Codex 要重启应用
Claude Code 的 /usage、connectors 不见了ANTHROPIC_AUTH_TOKEN 让它登出了 claude.ai把登录方式设为 claude.ai 登录（见 3.5）
关了 magpie，Agent 全报错网关随应用运行保持菜单栏常驻，或 magpie daemon install
额度用完直接报错，没切号只有一个账号且没建路由组加第二个账号，或建路由组
手动改了 Agent 配置，担心冲突—不会冲突，magpie 每次重读文件，只动它管的键
导入的 provider 后来在 Agent 里改了，magpie 没跟着变导入是一次性拷贝在 magpie 里改，或重新导入
不想让 magpie 读 Claude Code / Codex 的登录信息默认会从文件和钥匙串发现订阅magpie accounts discovery off，或设置 → 隐私关掉「订阅账号」
不想上报使用统计正式版每天上报一次（随机 ID、版本、系统、用了哪些 Agent/provider/模型，不含 key 和提示词）设置 → 隐私关闭，或 DO_NOT_TRACK=1
报 bug 不知道给什么—magpie log -n 200 附上；去 Discord 反馈（仓库不接受 PR）

关于订阅共享，多说一句。 把 Claude、ChatGPT、Antigravity 等订阅给其他 Agent 用，是否符合各家的服务条款，需要你自己判断。官方文档明确提醒：Google 可能封禁在 Antigravity 之外使用的 Antigravity 账号，请用丢了也不心疼的账号。主力账号上线前，先读一遍厂商条款。

十一、三套可以直接抄的配置

配置 A：只想省钱（一个 DeepSeek key）

magpie provider add deepseek sk-xxxx
magpie claude deepseek/deepseek-v4-pro
magpie claude haiku deepseek/deepseek-v4-flash
magpie codex deepseek/deepseek-v4-pro
magpie save cheap

配置 B：多个订阅轮着用，额度不浪费

magpie accounts add claude        # 登第一个
magpie accounts add claude        # 再登一个
magpie group add "Opus pool" models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=pace
magpie group rule add opus-pool use=deepseek/deepseek-v4-flash compact
magpie claude group/opus-pool
magpie save main

pace 优先用「周额度到重置时最可能作废」的那个账号，compact 规则让上下文压缩走便宜模型。

配置 C：按任务自动选模型

magpie group add coder models=deepseek/deepseek-v4-pro,deepseek/deepseek-v4-flash routing=order
magpie group rule add coder use=deepseek/deepseek-v4-flash intent="一个简单问题，不需要写代码" classifier=groq/llama-3.1-8b-instant
magpie group rule add coder use=deepseek/deepseek-v4-pro intent="写测试或修测试"
magpie claude group/coder

在「路由」页看每一轮被哪条规则送到了哪里，跑一天再调意图描述。

上面的模型 ID 取自官方文档示例。你账号里实际能用哪些，以 magpie models 的输出为准。

总结

magpie 的价值不在「又一个 API 中转」，而在三件事：

  1. 配置收口：几十个 Agent 的模型配置，收进一个界面、一套命令，并且随时能 default 撤回；
  2. 额度编排：路由组 + 规则 + 意图路由，把多账号、多厂商、多价位的模型当成一个池子用；
  3. 本地可控：网关跑在你自己的机器上，脱敏在请求出门前完成，失败就不发。

上手建议：先只做第三节，给一个 Agent 换一个模型，跑一天；有了第二个账号再上路由组；处理含密钥的项目前再打开脱敏。

参考

avatar
文章
阅读
粉丝