Magpie 是什么,这篇讲什么

Magpie 是开源的本地 AI agent 模型网关:Go 编写、MIT 协议,在本机跑一个监听 127.0.0.1:3425 的网关,让你从一个菜单栏应用给 Claude Code、Codex、Gemini CLI 等所有编码代理统一换模型、复用订阅、接力配额,GitHub 约 1.1 万 Star(2026-10-13 查询,官方 README)。这篇是它的安装与配置教程:三种安装方式、GUI 三步接入、CLI 速查表、订阅接入、任意工具走网关,以及第一批容易踩的坑。背景与定位见 Magpie 是什么。

安装:一条 curl,或 go install,或 Docker

最省事的路径是官方安装脚本(README Quick start 原样命令),在 macOS、Windows、Linux 的终端里各跑一条:

curl -fsSL https://usemagpie.ai/install.sh | sh

另外两条路,适合不同的人:

go install github.com/yetone/magpie@latest   # 已有 Go 环境的开发者
# Docker:服务器或 NAS 上跑 ghcr.io/yetone/magpie,Web UI 管理(README)

防火墙环境(README 与 reference 文档都给了说明):安装脚本和 magpie update 都接受 --proxy(http、https、socks5、socks5h,也可用 MAGPIE_PROXY)与 --mirror(自定义 GitHub 下载镜像前缀,也可用 MAGPIE_MIRROR):

curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890
magpie update --mirror https://mirror.example/

安全与更新的三件事(reference 文档,2026-10-13 抓取):Mac 构建已签名公证;Windows 和 Linux 构建暂未签名,Windows 首次运行可能被 SmartScreen 拦一下,放行即可;每个下载的 SHA-256 校验值始终来自 usemagpie.ai 本站,镜像只替换下载地址,不碰校验。所有构建自动更新——后台下载新版本,重启应用(菜单里的 Restart to Update)或退出时安装,命令行用 magpie update 效果相同。

装完两个补充动作。想在服务器上常驻网关,用 magpie daemon install 把 magpie serve 注册成系统服务(Linux 是 systemd user unit,macOS 是 launch agent,Windows 用 magpie autostart on,WSL 需先开启 systemd,reference 文档);Linux 桌面版依赖 WebKitGTK 4.1,缺了会退化为纯命令行版本。

GUI 三步:加 provider、选模型、重开会话

README Quick start 就是三步,全图形界面,两分钟的事。

  1. Providers → Add provider:选一个 preset 粘上 key(key 从哪来、怎么配,看 Claude Code API key 配置),或直接用订阅登录。preset 清单覆盖 Anthropic、OpenAI、Google Gemini、DeepSeek、Kimi、Zhipu GLM、Qwen、MiniMax、Ollama、LM Studio 等 25 家以上,外加任何 OpenAI/Anthropic 兼容 URL(README 原文)。
  2. Agents 页给每个 agent 挑模型:列表是所有 provider 的所有模型,格式 provider/model,比如给 Claude Code 选 deepseek/deepseek-v4-pro。
  3. 新开会话生效:旧会话保持原模型(reference 文档:agent 启动时读配置),这是下面”坑”一节的第一条。

CLI 速查表:README 原样命令逐条讲

不想点鼠标的,README 给了一组可以直接复制的命令,逐条解释如下。

magpie provider add deepseek sk-…              # 加 DeepSeek,preset 只需 key
magpie claude deepseek/deepseek-v4-pro          # Claude Code 用 DeepSeek
magpie codex moonshot/kimi-k2.5                 # Codex 用 Kimi
magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=smart
magpie claude group/opus-anywhere               # 在订阅间故障转移
magpie save work && magpie use work             # profiles:存档与一键切回
magpie quota                                    # 每个 plan 剩多少
magpie tui                                      # 整个 Magpie,搬进终端
命令干什么备注
magpie provider add加 providerpreset 只需 key;本地 Ollama 连 key 都不要(reference)
magpie claude <model>给 Claude Code 定模型agent 名支持前缀:cc、oc、gem(reference)
magpie codex <model>给 Codex 定模型同上,还能设 magpie codex effort high
magpie group add建路由组详见 Magpie 路由组实战
magpie save / magpie useprofile 存档与切换把所有 agent 的配置存成一个名字
magpie quota看每个订阅/plan/key 的余量还有 magpie quota wait codex 阻塞等额度(reference)
magpie tui终端形态方向键选 agent,回车开选择器

reference 文档里还有几条高频的:magpie ls 列出所有 agent 当前配置;magpie provider test deepseek 对每个 API 发一个小请求测延迟;magpie provider models deepseek +deepseek-v4 -deepseek-chat 增删对外暴露的模型;magpie sync 手动刷新模型目录。

TUI 形态有一套自己的快捷键(reference 文档):

按键动作
↑ / ↓选 agent
← / →切字段(model、effort、small 等)
回车打开模型选择器
s把当前配置存成 profile
p应用或删除 profile
S同步模型目录
q退出

两个进阶用法也在这层:magpie claude haiku deepseek/deepseek-v4-flash 给 haiku 档单独指定模型,主模型不动;magpie web 把 Magpie 窗口开进浏览器,WSL 与 SSH 服务器场景用(reference)。

让任意工具走网关:三个环境变量

任何能配 base URL 的工具都能接 Magpie,README 给的三行环境变量原样如下,key 填 magpie 即可(reference 文档:网关只监听 loopback,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

网关本身讲四种协议——OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini——并在它们之间互译,流式、工具调用、推理内容都在翻译范围内(README 事实)。主要端点:/v1/chat/completions、/v1/responses、/v1/messages、/v1beta/models/{model}:generateContent,模型目录在 /v1/models(reference 文档)。也就是说,一个只讲 Anthropic 协议的工具可以调一个只讲 OpenAI 协议的模型,翻译这一层 Magpie 替你做了。

订阅接入与隐私开关

Magpie 通过读取 agent 的登录态发现你的订阅——Claude Code 与 Codex 的本地文件、macOS 的 Keychain(README 原文)。发现后,已登录的订阅会作为 provider 出现在所有 agent 的选择器里。不想让它读登录态,三种关法任选:

magpie accounts discovery off   # 关闭发现,on 打回
MAGPIE_NO_ACCOUNTS=1 magpie     # 只关这一次,不改保存的设置

第三种在图形界面:Settings → Privacy 关掉 Subscription accounts。纯 API key 的 provider 完全不受这些开关影响(README 原文)。

导入既有配置,别手动重敲

先导再配能省十分钟。打开 Providers 页时,Magpie 会自动检查 Alma、CC Switch、Claude Code、Codex 的本地 provider 配置,列出可导入项;你确认后才写入,不确认不动(reference 文档)。另有三个入口:

  • Add to magpie 链接:部分 provider 官网放了一键递交配置的按钮(README);
  • 自定义中转:magpie provider add "My Relay" url=https://relay.example.com/v1 key=sk-… models=gpt-5.5,claude-sonnet-5,自定义 provider 支持 url=(OpenAI 兼容)、anthropic=(Anthropic 兼容)、models= 等参数(reference 文档);
  • 独立代理:每个 key、每个账号可走各自的 proxy(README),中转与直连混用时有用。

模型可用性不用你操心:模型列表来自厂商,名称与推理档位从 models.dev 补全(README)——“今天早上发布的模型,下次刷新就在选择器里”,magpie sync 随时手动刷。

常见配置坑

这几条都来自官方 reference 文档与 README(2026-10-13 抓取),细节以官方文档为准。

  • 改了模型,旧会话没变。 agent 启动时才读配置,正在跑的会话保持旧模型,新开会话即生效(reference)。
  • Windows 首次运行被拦。 Windows/Linux 构建暂未签名,SmartScreen 会问一次;Mac 构建已签名公证(reference)。
  • 中转或编码 plan 拒绝请求。 只服务自家 agent 的编码 plan(Kimi Code、GLM Coding Plan 这类)会按 User-Agent 认人,用 magpie provider set <id> user-agent=agent 让请求带上 agent 原本的 User-Agent(reference)。中转站本身怎么选,参考 LLM API 中转成本。
  • Docker 里好好的,宿主机连不上。 从容器外访问必须带一个已启用的 gateway key,否则 401(reference 文档,Docker 一节)。
  • 端口冲突。 网关默认 127.0.0.1:3425,环境变量 MAGPIE_ADDR 可改监听地址(reference)。

常见问题

claude code 中转怎么配置?

两条路:中转站是 Anthropic 兼容的,直接把 ANTHROPIC_BASE_URL 指到中转地址;或接进 Magpie——magpie provider add "My Relay" url=中转地址 key=sk-…,再 magpie claude my-relay/模型名。后者多代理共用一份中转配置,还能挂路由组做故障转移;与同类工具的取舍见 Magpie vs CC Switch vs LiteLLM vs AgentDock。

claude code api 中转站怎么接入 Magpie?

用自定义 provider:OpenAI 兼容的中转用 url= 参数,Anthropic 兼容的用 anthropic= 参数,models= 指定暴露哪些模型(reference 文档)。配完跑 magpie provider test <id> 测一遍各协议延迟,再在 Agents 页或用 magpie claude 命令选它的模型。

Magpie 怎么安装最快?

一条 curl -fsSL https://usemagpie.ai/install.sh | sh(官方 README),Mac 构建已签名公证并自动更新;有 Go 环境可 go install github.com/yetone/magpie@latest,服务器与 NAS 用 Docker 镜像。防火墙环境给脚本加 --proxy 或 --mirror 参数即可。