Magpie：在 macOS 菜单栏统一切换多种 LLM 代理

yetone/magpie

magpie ， 一处搞定所有 agent 的模型选择：在菜单栏中为 Codex 选用 DeepSeek、为 Claude Code 选用 Kimi、为 Gemini CLI 选用 GLM。

magpie 是一个单屏界面，列出你机器上的每一个 AI agent 及其当前设置的模型。点击数值，即可挑选模型。这就是整个应用的全部。

它常驻菜单栏：点击图标即可下拉出面板；同一界面也能以普通窗口形式打开（magpie，或在托盘菜单中选择 Open magpie）；此外还有终端版本（magpie tui）和纯 CLI 版本。

◉ magpie
▸ Claude Code   claude-fable-5-1[1m]                        ~/.claude/settings.json
  Codex         gpt-6-astra   effort medium
  Gemini CLI    gemini-3.1-pro
  OpenCode      anthropic/claude-sonnet-5   small anthropic/claude-haiku-4-5
  Pi            openrouter/z-ai/glm-5.2:batch
  Goose         anthropic/claude-sonnet-5
  Cursor        auto
  Copilot CLI   claude-fable-5

↑↓ agent  ·  ←→ field  ·  ↵ change  ·  s save profile  ·  p profiles  ·  q quit

一个极小的二进制文件

桌面应用体积不到 15 MB（通过 Wails 调用系统 webview，未捆绑任何东西），仅终端版本仅 7 MB。支持 macOS、Linux 和 Windows。

精准修改配置文件

仅触及你所改动的那一个键值；settings.json、config.toml、opencode.jsonc 或 config.yaml 的其余内容保持原样。写入操作是原子的（atomic）。

统一的端点，服务所有 agent

magpie 在本地运行一个网关（gateway），同时支持 OpenAI chat completions、OpenAI Responses 以及 Anthropic Messages API，并将请求转发到提供对应模型的 vendor。Codex、Claude Code、OpenCode 等都指向 http://127.0.0.1:3425/v1，并从一个统一的模型目录中挑选模型；不同 API 之间的转换在 magpie 内部完成，包括流式响应（streaming）和工具调用（tool calls）。

共享你的订阅

一旦在 Codex 或 Copilot 上登录，该登录身份就会作为一个 provider 出现：其他所有 agent 都可通过网关使用其下的模型，既无需复制，也不用粘贴密钥。

一个字段即可配置 provider

选择一个预设（preset）（Anthropic、OpenAI、Gemini、DeepSeek、Kimi、GLM、MiniMax、Qwen、Mistral、Groq、xAI、OpenRouter、Together、Fireworks、SiliconFlow、AiHubMix、302.AI、Ollama、LM Studio……），粘贴密钥，即告完成。自定义 vendor 只需提供名称和 base URL。magpie 绝不会从你的 shell 环境中读取密钥。

真实的模型列表，无任何内嵌硬编码

拿到密钥后，magpie 会向 vendor 查询其所提供的模型，并仅展示这些模型；models.dev 目录会补齐模型名称、推理强度（reasoning effort）等信息，以及那些本身没有模型列表的 vendor 的列表；一旦过期，它会在后台自动刷新。你可以选择每个 provider 暴露哪些模型，也可以全部暴露 ， 今天早上刚刚发布的模型，下一次刷新后就会出现在选择器中。

配置快照（Profiles）

将每个 agent 的设置以一个名字保存为快照，一键即可全部切换回去。

真实的品牌图标，无需任何框架

在系统 webview 上使用纯 HTML；品牌图标来自 lobehub/icons。

Agents

| Agent | 配置文件 | 字段 |
| --- | --- | --- |
| Claude Code | ~/.claude/settings.json | provider, model, opus/sonnet/haiku/fable（由 magpie 处理） |
| Codex | ~/.codex/config.toml | provider, model, effort |
| Gemini CLI | ~/.gemini/settings.json, ~/.gemini/.env | auth, model |
| OpenCode | ~/.config/opencode/opencode.json(c) | model, small |
| Pi | ~/.pi/agent/settings.json | model |
| Goose | ~/.config/goose/config.yaml | model |
| Cursor CLI | ~/.cursor/cli-config.json | model |
| Copilot CLI | ~/.copilot/settings.json | model |
| Crush | ~/.config/crush/crush.json | large, small |按 provider 作用域管理的 agent（OpenCode、Pi、Goose、Crush）采用 provider/model 的格式。

只显示已安装或已配置的 agent。

Provider 与网关（Gateway）

每个 agent 可选的模型都以 provider/model 的形式书写，并由 magpie 的网关提供，因此 agent 自身不持有 vendor 密钥或 vendor URL。新增一个 provider，其模型就会出现在每个 agent 的选择器中：

magpie presets                  # magpie 已知的 vendor，按 vendors、relays、local 分组
magpie provider add deepseek sk-…  # 预设仅需密钥
magpie provider add ollama      # 本地服务无需密钥
magpie provider add "My Relay" \
  url=https://relay.example.com/v1 \
  key=sk-… \
  models=gpt-5.5,claude-sonnet-5

magpie providers                # host、密钥、暴露的模型、被谁使用
magpie provider deepseek        # 查看单个 provider 详情
magpie provider models deepseek # 重新拉取 vendor 的模型列表（追加 id 可选择要暴露哪些）
magpie provider test deepseek   # 每个 API 发送一次小型请求，并显示延迟
magpie provider key deepseek sk-…  # 替换密钥
magpie provider rm deepseek

magpie models                   # agent 可见的目录
magpie claude deepseek/deepseek-chat  # 直接使用

自定义 provider 需要传入 url=（兼容 OpenAI 的 base URL）、anthropic=（兼容 Anthropic 的 base URL），或两者兼有；若 vendor 提供独立的 Responses 端点则加 responses=；若要借用 models.dev 的列表则加 catalog=；若要指定要暴露的模型则加 models=。预设中未涵盖的任何参数，都可按相同方式覆盖。

已登录的 agent 也可作为 Provider

你登录过的某个 agent 就是一个背后带有模型的订阅，因此 magpie 也将其作为 provider 提供。Claude Code（macOS Keychain 或 ~/.claude/.credentials.json 中的 OAuth 登录）、Codex（~/.codex/auth.json 中的 ChatGPT 登录）以及 Copilot（~/.config/github-copilot/apps.json 中的 GitHub 登录）都会出现在 magpie providers 列表以及 Providers 标签页中，显示为 signed in as …，其模型在其他每个 agent 的选择器中以 claude/claude-sonnet-5、codex/gpt-5.5 或 copilot/claude-sonnet-4.5 的形式列出。magpie 每次都会读取 agent 自身的凭证，并以该 agent 的方式刷新令牌 ， 将轮换后的令牌写回 agent 能找到的位置 ， 同时除了你的模型选择之外不存储任何东西；从 agent 中退出登录，该 provider 就会消失。模型列表也来自 vendor 自身：magpie 使用同一登录信息向 Anthropic、Copilot 或 Codex 的 API 查询，因此上游新加入的模型在下次刷新后就会出现。

ChatGPT 后端仅支持流式输出，并会拒收部分参数，因此 magpie 会将非流式请求进行转换，并丢弃那些会被拒收的参数。

Claude 订阅则有所不同：Anthropic 会将另一个 agent 的系统提示归类为第三方流量，即便 OAuth 请求看起来与 Claude Code 别无二致。因此对于每一次 Claude 订阅的生成，magpie 都通过真正的本地 claude 二进制来执行。调用方的工具通过 MCP 被桥接到这一实时会话中，工具结果在同一个 Claude Code 进程中继续流转；Pi、OpenCode 以及其他所有 agent 都会自动走这条路径。

这种方式生成的 harness 避开了 Anthropic 的系统提示分类器，而其指令仍然作为用户上下文的一部分存在。这要求 Claude Code 已安装并登录。Gemini CLI 的 Google 登录正在规划中。

连接其他一切

网关监听 127.0.0.1:3425（可通过 MAGPIE_ADDR 更改），随应用启动；magpie serve 可单独运行它。它暴露以下端点：

| 路径 | API |
| --- | --- |
| /v1/chat/completions | OpenAI chat completions |
| /v1/responses | OpenAI Responses |
| /v1/messages | Anthropic Messages |
| /v1/messages/count_tokens | Anthropic token counting |
| /v1beta/models/{model}:generateContent | Google Gemini（另有 streamGenerateContent、countTokens） |
| /v1/models、/v1beta/models | 模型目录 |当 vendor 直接支持 agent 所使用的 API 时，请求会原样穿透，否则由 magpie 进行转换，包括流式响应、工具调用以及推理内容。密钥就是 magpie（任意值均可，网关仅监听 loopback），模型命名为 provider/model。任何带有 base URL 设置的工具都可以使用它：

| 协议 | Base URL | 环境变量 |
| --- | --- | --- |
| OpenAI | http://127.0.0.1:3425/v1 | OPENAI_BASE_URL、OPENAI_API_KEY=magpie |
| Anthropic | http://127.0.0.1:3425 | ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY=magpie |
| Gemini | http://127.0.0.1:3425 | GOOGLE_GEMINI_BASE_URL、GEMINI_API_KEY=magpie |应用中的 Gateway 标签页提供了上述各项的复制按钮，以及各 API 现成的代码片段（shell、curl、Python、Node），还有模型 id 列表与最近的调用记录；设置 MAGPIE_DEBUG=1 可在终端中记录每次调用。

Claude Code 会接收 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 以及模型相关变量，写入 settings.json 的 env 块中；选择原生模型（opus、sonnet……）会移除这些设置并恢复原本的内容。

Codex 会接收一个 [model_providers.magpie] 表，以及指向 ~/.codex/magpie-models.json 的 model_catalog_json（由目录写入，因此这些模型会出现在 Codex 自身的列表中），并设置一个有效的 model/effort；选择原生模型会移除所有这些设置。你的 ChatGPT 登录信息永远不会被触碰。

Codex 在启动时读取其模型列表，因此切换后需要重启它。

OpenCode、Pi、Crush 会获得一个 magpie provider 条目以及 magpie/provider/model。

Gemini CLI 在 API key、Google 账号和 Vertex 之间切换认证方式；API key 写入 ~/.gemini/.env。选择目录中的模型时，会将 GOOGLE_GEMINI_BASE_URL 指向网关（它支持 Gemini API），将认证设置为使用网关令牌的 API key，并在 settings.json 中指定模型名；选择原生模型则会恢复先前的认证方式。

导入链接（Import Links）

vendor 或 relay 可以通过链接向用户提供一个现成的 provider：

magpie://import?preset=deepseek&key=sk-…

magpie://import?name=Acme%20Relay&chat=https://api.acme.example/v1&anthropic=https://api.acme.example&key=sk-…&models=gpt-5.5,claude-sonnet-5

打开这样的链接，magpie 会显示该链接将要添加的内容：名称、你的提示和密钥将发往的主机、模型。除非你按下 Add，否则不会保存任何内容。

magpie import <link> 在终端中完成同样的操作。

| 参数 | 含义 |
| --- | --- |
| preset | preset id（magpie presets）；使用其端点 |
| region | 对于有 region 的 preset，指定使用哪一个 |
| name | provider 的名称；在没有 preset id 时必填 |
| id | 其 id；当缺失时由 name 派生 |
| key | API 密钥；缺失时由用户粘贴 |
| chat | OpenAI Chat Completions 的 base URL（…/v1） |
| responses | OpenAI Responses 的 base URL（…/v1） |
| anthropic | Anthropic Messages 的 base URL（根路径，不含 /v1） |
| models | 要暴露的模型 id，逗号分隔 |
| catalog | models.dev provider id，用于模型名与推理等级 |
| website、keys | vendor 的网站及其 API key 页面（https） |Base URL 必须使用 https（仅本机或本地网络才允许使用明文 http）。网页和 GitHub 并不能可靠地链接自定义协议，因此请改用 https://usemagpie.ai/import#<same parameters> 形式的链接：它会打开 magpie，并在未安装时提示下载。参数保留在 URL fragment 中，浏览器永远不会将其发送给服务器。完整指南及链接生成器请见：https://usemagpie.ai/docs/import。

安装

前往 usemagpie.ai，或通过终端安装（在 Linux 上，若已安装 WebKitGTK 4.1 则安装桌面应用，否则安装命令行版本）：

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

Mac 版本已签名并经过公证；Windows 和 Linux 版本尚未签名（Windows SmartScreen 可能会在首次运行前提示）。每个版本都会保持自身更新：应用会在后台下载新版本，并在你重启（在菜单中选择 Restart to Update）或退出时完成安装；magpie update 可在终端中完成相同的操作。每个版本均发布在 yetone/magpie-releases。

从源码安装：

go install github.com/yetone/magpie@latest

或在本地构建：

make build               # ./magpie 桌面应用（需要 cgo + 平台 webview）
make app                 # macOS：magpie.app，菜单栏应用，无 Dock 图标
make cli                 # 仅终端版本，无需 cgo，可交叉编译到任意平台
make release             # dist/：原生应用构建 + 各平台的 cli 构建
make release-windows      # dist/：Windows 应用，amd64 与 arm64（交叉编译）
make release-linux       # dist/：适用于本机架构的 Linux 应用

Linux 上的应用构建需要 libgtk-3-dev 和 libwebkit2gtk-4.1-dev（Makefile 会添加 gtk3 tag；若使用纯 go build，需传入 -tags gtk3）；Windows 使用操作系统自带的 WebView2 runtime。

开发

make dev 使用 -tags dev 构建，并直接从 internal/gui/assets 提供 UI 来启动应用：保存 app.css、app.js 或 index.html，窗口会自动重新加载。安装 fswatch 后（brew install fswatch），Go 文件的更改也会触发重新构建与重启。开发构建使用独立的网关端口（DEV_ADDR，默认为 127.0.0.1:3426），因此你已有的 magpie 可以继续为你的 agent 提供服务。可将其指向一个临时的 home 目录，以避免影响真实的 agent 配置：

HOME=/tmp/magpie-home XDG_CONFIG_HOME=/tmp/magpie-home/.config make dev

MAGPIE_THEME=light|dark 可强制指定主题，MAGPIE_DEBUG=1 会打印网关所做的一切转换。

使用

magpie                          # 打开应用：一个窗口加菜单栏图标
magpie tray                     # 仅菜单栏图标（可用于登录项）
magpie tui                      # 同一功能，在终端中
magpie ls                       # 列出每个 agent 及其当前设置
magpie claude opus              # 设置一个模型（agent 名称支持前缀：cc、oc、gem……）
magpie codex gpt-5.6-sol
magpie codex effort high        # 其他字段
magpie codex xhigh              # 裸的 effort 等级也能识别
magpie codex deepseek/deepseek-chat  # 通过网关使用任意目录中的模型
magpie claude moonshot/kimi-k2.5
magpie claude haiku deepseek/deepseek-v4-flash  # 单独指定某一层
magpie claude haiku ""          # 清除
magpie gemini auth api-key
magpie opencode anthropic/claude-sonnet-5
magpie oc small anthropic/claude-haiku-4-5

magpie save work                # 将全部设置保存为配置快照
magpie use work                 # 切换回去
magpie profiles
magpie rm work
magpie sync                     # 刷新 models.dev 目录以及所有实时的模型列表

在应用中，点击任意值即可打开一个过滤后的列表；输入文本可搜索或填入列表外的值；按 esc 关闭面板。配置快照是底部的按钮：点击应用，× 删除，+ save current 以新增。

窗口中的 Providers 标签页列出了你的 provider 以及每个 provider 上的 agent；点击一行可修改密钥或暴露的模型、对其进行测试，或点击 agent 图标以将对应 agent 指向它的一个模型。

Add provider 会以瓦片形式展示预设：选择一个，粘贴密钥即可。

终端版本中的按键

| 按键 | 作用 |
| --- | --- |
| ↑↓ | 选择 agent |
| ←→ | 选择字段（model、effort、small……） |
| ↵ | 打开选择器；输入过滤内容；回车接受自定义值 |
| s | 将当前配置保存为快照 |
| p | 应用或删除快照（ctrl+d） |
| S | 同步模型目录 |
| q | 退出 |Agent 在启动时读取其配置，因此已运行的会话会一直保留其原有模型，直到你开启新的会话。

文件

- ~/.config/magpie/profiles.json ， 已保存的配置快照
- ~/.config/magpie/providers.json ， 你的 provider，包含密钥（权限 0600）
- ~/.config/magpie/stash.json ， magpie 所替换的值，切换回原配置时恢复
- ~/.cache/magpie/models.json ， models.dev 目录（若存在 OpenCode 在 ~/.cache/opencode/models.json 的缓存，则优先使用）
- ~/.cache/magpie/models/<provider>.json ， 从 vendor 处获取的模型列表XDG_CONFIG_HOME 与 XDG_CACHE_HOME 均受尊重。

许可证

MIT。参见 LICENSE。