跳到主要内容
AI教程

使用 Magpie 管理 AI 代理模型和提供商

了解如何安装 Magpie、连接模型提供商、为 Claude Code 和 Codex 等工具切换模型、保存可复用配置，并通过其本地网关为兼容 OpenAI、Anthropic 和 Gemini 的应用提供路由。

AI我搜编辑部阅读约 15 分钟
使用 Magpie 管理 AI 代理模型和提供商

Magpie 的功能

Magpie 提供统一界面，用于查看和更改计算机上安装的 AI 代理所使用的模型。它可作为菜单栏应用、常规桌面窗口、终端用户界面和命令行工具使用。

无需手动编辑多个 JSON、TOML、YAML 和环境文件，你只需选择代理、选择字段并指定模型。Magpie 只修改相关设置，并在适用时保留注释、顺序和缩进。所有写入操作都是原子的。

Magpie 目前识别 Claude Code、Codex、Gemini CLI、OpenCode、Pi、Goose、Cursor CLI、Copilot CLI 和 Crush。界面中只会显示已安装或已配置的代理。

主要功能

  • 多种界面：使用桌面应用、菜单栏面板、终端界面或普通 CLI。
  • 精准配置编辑：Magpie 只修改选中的键，不会重写代理配置的其余部分。
  • 统一本地网关：代理可通过单一回环端点访问多个供应商提供的模型。
  • API 转换：网关支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和兼容 Google Gemini 的请求，包括流式传输和工具调用。
  • 共享订阅：现有的 Claude Code、Codex 和 Copilot 登录状态可以作为其他代理的供应商。
  • 实时模型目录：Magpie 从供应商获取模型列表，并使用 models.dev 的数据进行补充。
  • 供应商预设：支持 Anthropic、OpenAI、Gemini、DeepSeek、Kimi、GLM、MiniMax、Qwen、Mistral、Groq、xAI、OpenRouter、Together、Ollama 和 LM Studio 等供应商与服务。
  • 配置档案：将当前所有代理设置以名称保存，之后可以一并恢复。
  • 小型原生构建：桌面版本使用操作系统的 WebView，而不是捆绑浏览器运行时。

安装 Magpie

安装预构建版本

从 usemagpie.ai 下载适用于 macOS、Windows 或 Linux 的桌面应用。也可以运行安装脚本：

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

在 Linux 上，如果系统提供 WebKitGTK 4.1，安装程序会选择桌面应用，否则会安装命令行版本。macOS 版本已签名并经过公证。Windows 和 Linux 版本目前尚未签名，因此 Windows SmartScreen 可能会在首次启动时显示警告。

Magpie 会在后台检查更新。桌面应用会在重启或退出时安装更新，终端用户则可以显式更新：

magpie update

从 Go 源代码安装

如果已安装 Go，可以直接安装最新版本：

go install github.com/yetone/magpie@latest

在本地构建仓库

仓库提供了多个 Make 目标：

make build            # 桌面应用二进制文件
make app              # macOS 菜单栏应用
make cli              # 不使用 cgo 的纯终端版本
make release          # 原生应用和跨平台 CLI 构建
make release-windows  # Windows amd64 和 arm64 应用构建
make release-linux    # 当前架构的 Linux 应用

构建 Linux 桌面应用需要 libgtk-3-dev 和 libwebkit2gtk-4.1-dev。普通 Go 构建必须使用 gtk3 构建标签。Windows 使用操作系统自带的 WebView2 运行时。

打开界面

选择适合你工作流程的界面：

magpie          # 打开窗口和菜单栏图标
magpie tray     # 仅运行菜单栏图标
magpie tui      # 打开终端界面
magpie ls       # 列出检测到的代理及当前设置

在桌面界面中，点击任意当前值即可打开筛选选择器。输入文字进行搜索或输入自定义值，并按 esc 关闭选择器。

在终端界面中，使用方向键选择代理和字段，按 Enter 打开其选择器，然后输入文字筛选可用选项。按 q 退出。

添加模型供应商

查看可用预设

首先列出 Magpie 已知的供应商：

magpie presets

预设分为供应商、中继服务和本地服务。托管预设通常只需要 API 密钥：

magpie provider add deepseek sk-…

Ollama 等本地供应商不需要密钥：

magpie provider add ollama

Magpie 不会读取 shell 环境中的供应商密钥。请通过应用或供应商命令添加密钥。

添加自定义 OpenAI 兼容供应商

可以使用名称、基础 URL、密钥和明确的模型列表配置自定义供应商：

magpie provider add "My Relay" url=https://relay.example.com/v1 key=sk-… models=gpt-5.5,claude-sonnet-5

自定义供应商可以使用 url= 指定 OpenAI 兼容基础地址，使用 anthropic= 指定 Anthropic 兼容基础地址，也可以同时指定两者。如果供应商有单独的 Responses 端点，请使用 responses=。可选的 catalog= 参数可以借用 models.dev 供应商的元数据。

查看和测试供应商

使用以下命令查看供应商、刷新模型列表、测试 API、轮换密钥或删除条目：

magpie providers
magpie provider deepseek
magpie provider models deepseek
magpie provider test deepseek
magpie provider key deepseek sk-…
magpie provider rm deepseek
magpie models

magpie provider test 会针对每个受支持的 API 发起一个小型请求并报告延迟。在桌面应用中，Providers 标签页提供了等效控件，可用于更改密钥、选择公开的模型、测试提供商，以及将其模型分配给代理。

切换代理模型

通过网关公开的模型使用 provider/model 格式。也可以使用原生代理模型的常用名称进行选择。

CLI 基本示例

magpie claude opus
magpie codex gpt-5.6-sol
magpie codex effort high
magpie codex xhigh
magpie codex deepseek/deepseek-chat
magpie claude moonshot/kimi-k2.5
magpie gemini auth api-key
magpie opencode anthropic/claude-sonnet-5
magpie oc small anthropic/claude-haiku-4-5

代理名称支持 cc、oc 和 gem 等前缀。OpenCode、Pi、Goose 和 Crush 等按提供商区分的代理使用 provider/model 标识符。

配置 Claude Code 层级

Claude Code 可以为 opus、sonnet、haiku 和 fable 等层级分别分配模型。例如，仅将 DeepSeek 模型分配给 haiku 层级：

magpie claude haiku deepseek/deepseek-v4-flash

清除该层级的专用选择，使其恢复使用 Claude Code 的主模型：

magpie claude haiku ""

选择网关模型后，Magpie 会在 Claude Code 的 settings.json 中管理 Anthropic 基础 URL、令牌和模型变量。选择原生模型会移除 Magpie 的网关设置，并恢复之前的值。

切换后重启代理

代理会在启动时读取配置。已经运行的会话会继续使用之前的模型，直到启动新会话。

这对 Codex 尤其重要，因为它会在启动时读取模型目录，切换后必须重启。

保存和恢复配置档案

配置档案会记录每个已检测代理的当前设置。这适合为工作、实验、本地推理或注重成本的任务维护不同配置。

magpie save work
magpie use work
magpie profiles
magpie rm work

在桌面应用中，配置档案会以标签形式显示在主视图底部。点击标签即可应用，使用删除控件将其移除，或选择 + save current 创建配置档案。

在终端界面中，按 s 保存当前设置，按 p 应用或删除配置档案。

将已登录代理用作提供商

Magpie 可以将现有的 Claude Code、Codex 和 Copilot 订阅公开为提供商。通过原始代理完成登录后，其可用模型会显示在 magpie providers 以及其他代理的模型选择器中。

  • Claude Code 模型使用类似 claude/claude-sonnet-5 的标识符。
  • Codex 订阅模型使用类似 codex/gpt-5.5 的标识符。
  • Copilot 模型使用类似 copilot/claude-sonnet-4.5 的标识符。

Magpie 会在需要时读取代理已有的凭据，不会将其复制到自己的提供商存储中。如果原始代理轮换令牌，Magpie 会遵循该代理的刷新流程，并将轮换后的令牌写入代理预期的位置。退出登录会移除对应的提供商。

Claude 订阅要求安装真实的本地 claude 二进制文件并完成登录。Magpie 会运行该二进制文件，并通过 MCP 将调用方工具桥接到实时交互中。Gemini CLI 的 Google 登录支持已列入计划，但目前还不能作为共享提供商使用。

将其他应用连接到网关

Magpie 的网关默认监听 127.0.0.1:3425，并随应用一起启动。若只运行网关，请使用：

magpie serve

设置 MAGPIE_ADDR 可更改监听地址。默认绑定到回环地址，可使网关仅在本机运行。

支持的 API 端点

  • /v1/chat/completions，用于 OpenAI Chat Completions。
  • /v1/responses，用于 OpenAI Responses。
  • /v1/messages，用于 Anthropic Messages。
  • /v1/messages/count_tokens，用于 Anthropic 令牌计数。
  • /v1beta/models/{model}:generateContent，用于 Gemini 生成，并支持流式传输和令牌计数变体。
  • /v1/models 和 /v1beta/models，用于模型目录。

API 密钥可以使用字面值 magpie；由于网关默认监听回环地址，任何值都可以使用。始终以 provider/model 格式指定模型。

兼容 OpenAI 的环境

export OPENAI_BASE_URL=http://127.0.0.1:3425/v1
export OPENAI_API_KEY=magpie

兼容 Anthropic 的环境

export ANTHROPIC_BASE_URL=http://127.0.0.1:3425
export ANTHROPIC_API_KEY=magpie

兼容 Gemini 的环境

export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425
export GEMINI_API_KEY=magpie

桌面应用的 Gateway 标签页提供了可复制的 shell、curl、Python 和 Node 设置及代码片段。该页面还会显示模型 ID 和最近的调用。

刷新模型目录

Magpie 会从已配置的提供商获取真实的模型列表。models.dev 目录为不发布自有目录的提供商提供名称、推理级别和备用列表。

需要刷新 models.dev 数据和所有实时提供商列表时，请运行完整同步：

magpie sync

在终端界面中，按 S 可执行相同操作。你也可以仅使用 magpie provider models PROVIDER 刷新某个提供商。

安全导入提供商链接

供应商和中继服务可以通过导入链接分发预填充的提供商定义。Magpie 会在保存任何内容之前，显示拟使用的提供商名称、端点、目标主机和模型。

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

自定义中继链接可以分别包含 OpenAI 和 Anthropic 端点：

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

只有在用户确认导入后，任何内容才会被存储。网页可以使用 https://usemagpie.ai/import#，后面接相同的参数。由于这些值保留在 URL 片段中，浏览器不会将其发送到网站服务器。完整的参数参考和链接构建器请参阅 Magpie 导入指南。

高级技巧

限制公开的模型

你不必公开提供商返回的每个模型。只选择你希望出现在智能体选择器中的模型。这样可以让大型目录更易于管理，并有助于防止意外选择模型。

检查网关转换

启用调试日志，查看网关转换的内容：

MAGPIE_DEBUG=1 magpie serve

当供应商已经支持调用方的 API 时，请求会直接传递。否则，Magpie 会转换请求和响应，同时保留受支持的流式传输、工具调用和推理行为。

了解数据存储位置

  • ~/.config/magpie/profiles.json 存储已保存的配置文件。
  • ~/.config/magpie/providers.json 存储提供商及其密钥，文件模式为 0600。
  • ~/.config/magpie/stash.json 存储被替换的值，以便恢复。
  • ~/.cache/magpie/models.json 存储 models.dev 目录。
  • ~/.cache/magpie/models/<provider>.json 存储从提供商获取的模型列表。

Magpie 遵循 XDG_CONFIG_HOME 和 XDG_CACHE_HOME。

使用隔离的开发环境

贡献者可以运行开发版本，而不影响正常的智能体配置：

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

make dev 直接从 internal/gui/assets 提供界面，并在前端文件发生变化时重新加载。其网关使用 DEV_ADDR，默认为 127.0.0.1:3426，因此可以与普通 Magpie 实例并行运行。设置 MAGPIE_THEME=light 或 MAGPIE_THEME=dark 可强制使用相应配色。

结语

Magpie 以一致的工作流程取代分散的模型配置。安装后，添加提供商或使用现有的智能体订阅，为每个智能体选择模型，并将有用的组合保存为配置文件。其本地网关还允许其他兼容 OpenAI、Anthropic 和 Gemini 的工具共享同一提供商目录，而无需在每个应用中存储供应商凭据。