magpie 使用教程：给 Claude Code 和 Codex 装本机网关（2026 年 11 月）
截至 2026-11-10，照 magpie 官方文档（usemagpie.ai），让 Claude Code 用上 magpie 只要三步：运行安装命令并启动 magpie；在 Providers 里添加服务商，填入你自己的 API key；运行 magpie claude 加「服务商/模型」选模型，新开会话后生效（Codex 用 magpie codex，并重启 Codex 应用）。magpie（yetone/magpie）是你电脑上的本机网关 127.0.0.1:3425，在 OpenAI Chat、OpenAI Responses、Anthropic Messages 与 Gemini 四种 API 之间转换，MIT 协议开源，不隶属 Apache Magpie。接 QCode 的三个地址与命令见下文。
更新于 2026-11-10
把这个工具接到 QCode 端点：一把 key 调 Claude、GPT 与国产模型。
- 按 token 计费，实时单价见 /models
- 支付宝、微信支付、信用卡、加密货币均可付款
- 充值后自助开通、立刻生效
官方来源里的四条事实
MIT 协议开源，作者 yetone
GitHub 仓库 yetone/magpie 采用 MIT License（Copyright (c) 2026 yetone）。README 末尾写明：magpie 不隶属 Apache Magpie，也不隶属 Apache 软件基金会。
本机网关地址
网关支持 OpenAI Chat、OpenAI Responses、Anthropic Messages 和 Gemini，并在它们之间转换，流式输出、工具调用和推理内容都包括在内。
平台与形态
官方写明：可在 macOS、Windows 和 Linux 上运行（菜单栏应用、窗口、TUI、Web UI 和 CLI），也可以用 Docker 和 Termux。
key 存放位置
key 存在 ~/.config/magpie/providers.json，只有你自己能读。magpie 不读取 shell 环境变量里的 key：你添加的是什么，它用的就是什么。
magpie 是什么？
截至 2026-11-10，magpie 官方文档对它的概括是：在一个地方为你的每个 agent 选模型。你在 magpie 里添加手上已有的服务商，再给每个 agent 选一个模型，magpie 就把它写进该 agent 自己的配置文件。背后是本机 127.0.0.1:3425 上的一个小网关，它支持 OpenAI、Anthropic 和 Gemini 的 API 并在它们之间转换，所以 Claude Code 这样只支持 Anthropic Messages 的 agent，也能用 GPT 或国产模型。作者是 yetone，官网 usemagpie.ai，仓库 yetone/magpie。
安装与卸载命令
截至 2026-11-10，官方安装命令是 curl -fsSL https://usemagpie.ai/install.sh | sh，它把 magpie 命令放进 ~/.local/bin，应用放在 macOS 的 /Applications 或 Linux 的应用菜单；也可以用 go install github.com/yetone/magpie@latest。Windows 上下载最新发布里的 magpie-windows-amd64.exe（ARM 为 magpie-windows-arm64.exe），magpie.exe 接受同样的命令，只要终端版就用 magpie-cli-windows-amd64.exe。另有 Docker 镜像 ghcr.io/yetone/magpie，见官方 Docker 文档。卸载：运行 curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall，magpie 先断开每个 agent 并还原它们原来的配置；~/.config/magpie 里的设置和服务商保留，加 --purge 才一并删除。
时间线
yetone/magpie 仓库在 GitHub 创建。
QCode 文档完成 magpie 接入实测，Claude Code 与 Codex 均通过，整理成 docs.qcode.cc 上的 magpie 接入页。
QCode 用当天的 magpie 终端版重新实测：magpie provider add 一条命令添加 QCode 成功，provider test 三个地址都能应答。同日核对 README、官方文档（Get started、Add to magpie、Docker、Claude Code 与 Codex 的模型页）、参考手册和 GitHub 发布页；官方说明 magpie 一天发版数次。
官方写明了什么，还有什么没说清
官方文档写明的
① 通过 magpie 使用模型时，网关随应用一起运行。② 正在运行的会话保持它启动时的模型；agent 在启动时读取配置，所以新模型从下一个会话开始生效，Codex 还要重启 Codex 应用。③ 选模型只改 agent 配置里 magpie 需要的键，注释、顺序和缩进保留，写入是原子的。④ Claude Code：magpie 写 ~/.claude/settings.json 里的 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，后者是网关的 key，不是你的服务商 key；Codex：写 ~/.codex/config.toml 里的 [model_providers.magpie] 表和模型。⑤ 不需要自己 export OPENAI_BASE_URL 或 ANTHROPIC_BASE_URL。⑥ 导入链接在你按下 Add 之前什么都不保存；同一 id 已被占用时，按钮写的是 Replace。⑦ magpie 的模型也会出现在 Claude Code 和 Codex 自己的 /model 列表里（Claude Code 里标着 via magpie），在 agent 里也能直接切换。
官方没有写清的
截至 2026-11-10：① 官方首页对 macOS 最低版本有两种写法（macOS 12+ 与 macOS 11 or later），以你下载时页面上的要求为准。② README 的支持 agent 清单比 Get started 页列出的长，而且还在增加；你的 agent 能否被识别，以 magpie ls 的输出为准。③ 官方 import 页说不带 models 参数时，magpie 列出服务商 /v1/models 返回的模型；QCode 2026-11-10 实测，不指定 models= 时只放出前 24 个（输出为 24 exposed of 28），所以添加后用 magpie provider models 选出要用的型号。
三种添加服务商的方式
导入链接或 App 界面
导入链接是 magpie://import? 加参数，网页上改用 https://usemagpie.ai/import# 加同样的参数，每个值做 URL 编码。字段有 name（或 preset）、chat、responses、anthropic、gemini、key、models。链接里不带 key 时，由你在对话框里粘贴。App 里的入口是 Providers → Add provider。
终端一条命令
预设厂商只需 magpie provider add 加厂商 id 和 key（官方示例：deepseek 与 sk-…）；自定义地址用 url=（OpenAI 兼容）、anthropic=（Anthropic 兼容）、responses=、models= 和 key=。终端里的 magpie import 加链接会先显示摘要并询问，-y 跳过询问；QCode 文档实测，不带 key 的链接在终端里只预览、不保存，所以终端里直接用 magpie provider add 一步到位。
magpie 使用教程：安装、添加服务商、给 Claude Code 和 Codex 选模型
① 安装：macOS 和 Linux 运行 curl -fsSL https://usemagpie.ai/install.sh | sh，Windows 下载 magpie-windows-amd64.exe；装完启动 magpie，让网关跑起来。② 添加服务商：在 Providers 标签点 ＋ Add provider，预设厂商粘贴 key 即可，其他地址选 Custom · any compatible URL；终端写法见上面的终端卡片，接 QCode 的整条命令见下文。③ 选模型：在 Agents 标签点 agent 的模型，或运行 magpie claude deepseek/deepseek-v4-pro、magpie codex deepseek/deepseek-v4-pro；经 magpie 的模型都写成「服务商/模型」。④ 新开一个会话，agent 才会读到新配置；Codex 还要重启 Codex 应用。⑤ 检查：magpie ls 列出每个 agent 当前的设置，magpie provider test 加服务商 id 会对每种 API 各发一个极小请求并显示延迟。⑥ 回到 agent 原来的设置：magpie claude default 或 magpie codex default。
把 QCode 加进 magpie
截至 2026-11-10，QCode 文档的 magpie 接入页给出三个地址：anthropic 填 https://api.qcode.cc/api，chat 填 https://api.qcode.cc/openai/v1，responses 填 https://api.qcode.cc/openai（magpie 示例里的 responses 以 /v1 结尾，QCode 端点页写明 /openai/responses 与 /openai/v1/responses 等价）。Claude 走 anthropic 地址，GPT 走 chat 与 responses，国产模型走 anthropic 或 chat；亚洲和北美接入点把域名换成 asia.qcode.cc 或 us.qcode.cc，路径不变。最省事的是控制台的「导入到 CC Switch / magpie」按钮：点其中的「导入到 magpie」，Claude 和 GPT 一次配好，然后用 magpie claude qcode/claude-sonnet-5-5 或 magpie codex qcode/gpt-6.1-sol 选模型；只设主模型时 Claude Code 的 opus 槽也用同一个模型，想让它用 Opus 再运行 magpie claude opus qcode/claude-opus-5-5。QCode 的 Key 不区分协议，一把 Key 同时走 Anthropic 与 OpenAI 两种兼容接口，Claude Code、Codex 等工具共用，按 token 计费，各模型单价见 /models。不想包月？按量包 ¥26 起买一笔额度，7 天内用完为止；已有个人套餐的用户额度不够时买加油包。
常见问题
magpie 切换后不生效？
多半是会话还没重开：正在运行的会话保持它启动时的模型，新模型从下一个会话开始生效，Codex 还要重启 Codex 应用。再确认网关在运行：通过 magpie 使用模型时网关随应用一起运行，magpie healthcheck 退出码为 0 说明网关在应答。magpie ls 可以看 agent 当前的设置，magpie provider test 可以检查服务商是否应答；其他报错见 /magpie-errors-and-fixes。
magpie 要一直开着吗？
通过 magpie 使用模型时要，网关随应用运行。关掉窗口后它留在菜单栏或托盘；magpie tray 只启动图标，magpie serve 只运行网关，magpie daemon install 把它装成服务（Linux 用 systemd，macOS 用 launchd）。agent 用它自己的模型时不经过 magpie。
magpie 的 key 存在哪里、安全吗？
key 存在 ~/.config/magpie/providers.json，只有你自己能读，magpie 也不读取 shell 环境变量里的 key。官方说 agent 看不到你的 key：Claude Code 配置里的 ANTHROPIC_AUTH_TOKEN 是网关的 key。网页导入链接把参数放在 # 之后，浏览器不会把它发给服务器。另有隐私遮罩：打开后，提示词里的 key、密码和邮箱会在请求离开电脑前换成占位符，回复里再换回；它默认关闭，在 Settings → Privacy 打开。
magpie 怎么卸载 / 恢复原配置？
恢复原配置：运行 magpie claude default 或 magpie codex default，magpie 会移除它写入的内容，并还原被替换的原值，例如你原来的 ANTHROPIC_BASE_URL。卸载：用安装脚本装的，运行 curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall；设置和服务商保留在 ~/.config/magpie，加 --purge 才一并删除。
magpie 和 CC Switch 能同时用吗？
可以同时安装：magpie 作者 yetone 2026-11-09 在 X 上回复说「两个并用也行」，README 也写明 magpie 的 Import 能导入 CC Switch 里的服务商。两者都会改写 Claude Code 与 Codex 的配置文件，分工和同时使用时要注意的设置见对比页 /magpie-vs-cc-switch。
QCode 在 magpie 里怎么加？
三种方式任选。最快的是控制台的「导入到 magpie」按钮；终端里运行 magpie provider add QCode anthropic=https://api.qcode.cc/api url=https://api.qcode.cc/openai/v1 responses=https://api.qcode.cc/openai key=cr_xxx，QCode 2026-11-10 实测一条添加成功；App 里在 Providers → Add provider 选 Custom，填 OpenAI 兼容地址（chat）、Anthropic 兼容地址（anthropic）和 cr_ 开头的 Key。不指定 models= 时 magpie 只放出前 24 个型号，用 magpie provider models qcode gpt-6.1-sol claude-sonnet-5-5 claude-opus-5-5 claude-haiku-5-5 选出要用的（不带 + 时整表替换）；GPT 型号排在第一个时，magpie provider test 的 chat、responses、anthropic 三行都会显示 ✓。已保存的 QCode 要换 Key，用 magpie provider key 加 qcode 和新 Key。
资料来源
GitHub 上 yetone/magpie 仓库的 README、LICENSE 和参考手册，GitHub API，magpie-releases 的发布信息，官网 usemagpie.ai 首页，官方文档的 Get started、Add to magpie、Docker、Claude Code 模型页和 Codex 模型页，均于 2026-11-10 读取；magpie 作者 yetone 2026-11-09 在 X 上的回复。QCode：docs.qcode.cc 的 magpie 接入页与接入点页面、qcode.cc/models、qcode.cc/pay-as-you-go（2026-11-10 抓取），以及 QCode 2026-11-10 用 magpie 终端版的实测；控制台导入按钮的文案取自 QCode 站点文案。
相关阅读
按量包
不订阅，一次买一笔 7 天有效的额度；各模型单价见 /models。
magpie 和 CC Switch 怎么选？
两者的工作方式、客户端、协议转换、故障切换、隐私遮罩、许可证对照，以及各自接 QCode 的方式。
magpie 不生效、401、405 报错与处理（2026-11）
magpie 常见报错的官方原因与处理：切换后不生效、Docker 里的 401、ZCode 的 405、provider test 的 400、模型看不全。
加密货币充值指南
9 种币、56 条网络，0 平台手续费购买 AI 编程 API 额度。
本页内容于 2026-11-10 对照 magpie 仓库、官网与文档核对，以官方页面为准。核对所用版本：QCode 2026-11-10 的实测用的是 magpie 0.1.3533；magpie 一天发版数次，菜单名称和命令以你安装的版本为准。QCode 的型号以 /models 为准。