magpie

Codex 桌面版接入步骤（macOS / Windows）请参阅 Codex Desktop。

一、产品简介

magpie 是开源的本地模型网关与 Agent 配置管理工具，可将同一套提供方配置用于多个客户端，并在 Chat Completions、Responses 与 Anthropic Messages 等协议之间转换。本文以 WorkBuddy 为例：WorkBuddy 向本机 magpie 发送 Chat Completions 请求，再由 magpie 按模型和上游配置转换协议，转发至 GravitexAI。

环节	地址或协议
WorkBuddy → magpie	`http://127.0.0.1:3425/v1/chat/completions`
magpie → GravitexAI GPT	`/v1/responses`
magpie → GravitexAI Claude	`/v1/messages`
magpie → 支持 Chat Completions 的模型	`/v1/chat/completions`

如果模型可通过 WorkBuddy 的自定义模型直接正常使用，可参考 WorkBuddy 直连指南。需要转换协议时，再按本文接入 magpie。图像生成连接器配置见 WorkBuddy-生图。

二、前置条件

已安装 WorkBuddy，且至少启动过一次。
已在 GravitexAI 控制台创建 API 密钥。
已确认账户可用的模型 ID 和对应接口，见 GravitexAI 模型广场。
magpie 与 WorkBuddy 运行在同一台电脑上；本地网关默认使用 3425 端口。

三、安装 magpie

macOS
Windows

使用官方安装脚本：

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

也可以从 magpie 官网下载 Apple Silicon 或 Intel 对应的安装包。安装后打开 magpie，并在终端验证：

magpie --version
magpie ls

如果提示找不到命令，重新打开终端，或将 ~/.local/bin 加入 Shell 的 PATH。

从 magpie 官网或官方 Releases 下载与系统架构匹配的 Windows 程序：

包类型	适用方式
`magpie-windows-amd64.exe` / `magpie-windows-arm64.exe`	桌面窗口与托盘版
`magpie-cli-windows-amd64.exe` / `magpie-cli-windows-arm64.exe`	纯命令行版

打开桌面版以运行网关。将程序所在目录加入 PATH 后可在 PowerShell 中调用；下文 magpie 命令可对应替换为 magpie.exe。未加入 PATH 时，使用实际可执行文件路径。

本文仅使用 GravitexAI API 密钥，不需要导入 Claude、ChatGPT 或其他客户端的订阅凭据。

四、配置 GravitexAI 提供方

第一步：添加三个协议端点

macOS 终端执行下面的命令，将 sk-你的密钥 替换为实际密钥：

magpie provider add gravitex \
  url=https://api.gravitex.ai/v1 \
  responses=https://api.gravitex.ai/v1 \
  anthropic=https://api.gravitex.ai \
  key=sk-你的密钥 \
  name=GravitexAI

Windows PowerShell 可使用单行写法：

magpie.exe provider add gravitex url=https://api.gravitex.ai/v1 responses=https://api.gravitex.ai/v1 anthropic=https://api.gravitex.ai key=sk-你的密钥 name=GravitexAI

字段	填写内容	用途
`gravitex`	提供方 ID	后续命令以此引用提供方
`url=`	`https://api.gravitex.ai/v1`	Chat Completions 的基础地址
`responses=`	`https://api.gravitex.ai/v1`	Responses 的基础地址
`anthropic=`	`https://api.gravitex.ai`	Anthropic Messages 的基础地址
`key=`	GravitexAI API 密钥	上游认证
`name=`	`GravitexAI`	显示名称

填写的是基础地址：url= 与 responses= 带 /v1，不附加 /chat/completions 或 /responses；anthropic= 不带 /v1，magpie 会补充 Messages 请求路径。

也可以在桌面端的 供应商 页面编辑 GravitexAI，在 Base URL 中分别填写 OpenAI 兼容、OpenAI Responses 和 Anthropic 兼容 的地址，填入 API 密钥后点击保存。下图展示 OpenAI Responses 地址配置。

magpie 供应商页面配置 GravitexAI 的 OpenAI Responses 地址

截图中的供应商 ID 为 gravitexai，本文命令示例使用 gravitex。请以自己实际设置的 ID 为准；若使用截图中的 ID，后续模型名称应写为 gravitexai/模型ID。

第二步：已有提供方补充协议

如果已经添加过 gravitex，无需重复创建，补充缺少的端点即可：

magpie provider set gravitex responses=https://api.gravitex.ai/v1 anthropic=https://api.gravitex.ai

对于需要同时使用工具调用与推理的 GPT 模型，应配置 Responses 端点。如果出现 Function tools with reasoning_effort are not supported，优先检查此项，而不是直接关闭模型的推理能力。

第三步：测试与选择模型

magpie provider test gravitex
magpie models workbuddy

缺少目标模型时，可将账户可用模型加入暴露列表：

magpie provider models gravitex +gpt-6-sol +claude-sonnet-5-5 +deepseek-v4-pro

以上模型 ID 为示例，需按账户可用列表替换。测试会向上游发送请求，可能产生少量 API 用量。

五、以 WorkBuddy 为例接入

第一步：确认客户端版本与配置目录

运行 magpie ls，确认识别到了正确的客户端。

客户端	默认配置文件
WorkBuddy 国内版	`~/.workbuddy/models.json`
WorkBuddy AI 国际版	`~/.workbuddy-ai/models.json`
CodeBuddy Code	`~/.codebuddy/models.json`，另有 `settings.json`

下文使用 WorkBuddy 国内版。自定义了 WORKBUDDY_CONFIG_DIR 时，以实际目录为准。Windows 中 ~ 指当前用户主目录。

第二步：退出客户端并备份

先完全退出 WorkBuddy：macOS 按 Cmd + Q；Windows 从托盘退出，并确认进程结束。

macOS
Windows PowerShell

cp ~/.workbuddy/models.json ~/.workbuddy/models.json.bak-$(date +%Y%m%d-%H%M%S)

$workbuddyModels = Join-Path $HOME '.workbuddy/models.json'
Copy-Item $workbuddyModels "$workbuddyModels.bak-$(Get-Date -Format 'yyyyMMdd-HHmmss')"

第三步：选择默认模型并接管

选择一个账户可用模型执行，例如：

magpie workbuddy gravitex/claude-sonnet-5-5

magpie workbuddy gravitex/gpt-6-sol

两条命令选择一条即可。模型使用 提供方 ID/模型 ID 格式；magpie 会将接管配置写入 WorkBuddy 的模型文件。桌面端也可进入 Agent 页面，找到 WorkBuddy，打开右侧的接入开关，并选择 GravitexAI 下的模型。下图展示 Agent 页的布局；截图中未显示 WorkBuddy，需在列表中继续查找。

第四步：重开 WorkBuddy 并选择模型

保持 magpie 运行。
重新打开 WorkBuddy。
在模型选择器中选择 magpie 提供的 gravitex/… 模型。
新建任务，发送简单消息确认有正常回复。
再用一个测试文件夹执行简单工具任务，验证读文件、工具调用与推理是否正常。

下图为 WorkBuddy 使用 gpt-6-luna 的对话示例：发送“你好”后收到正常回复，输入框右下角显示当前模型。基础对话验证通过后，再测试工具任务。

新接管或修改客户端模型列表后，需要完全重启 WorkBuddy。仅修改 magpie 上游端点路由时，通常无需重写客户端模型文件，可直接发起新请求验证。

六、验证与排错

检查本地网关

macOS
Windows PowerShell

lsof -nP -iTCP:3425 -sTCP:LISTEN

无进程监听时，打开 magpie：

open -a magpie

Get-NetTCPConnection -LocalPort 3425 -State Listen

未监听时，打开下载的 magpie 桌面程序。

验证工具调用与推理

如果基础对话正常，但工具任务返回 400，检查错误是否涉及 tools 与 reasoning_effort。确认 responses= 已配置为 https://api.gravitex.ai/v1，并检查所用模型是否支持 Responses。判断接入成功时，不应只看模型是否出现在列表中；还要确认一次实际对话和工具任务均正常。推理模型出现 HTTP 200 但回复为空时，也需检查输出预算是否不足。

WorkBuddy 模型列表没有变化？

完全退出 WorkBuddy 后重开；确认接管的是国内版 workbuddy，而不是国际版或 CodeBuddy Code。运行 magpie ls 检查识别结果与实际配置目录。

选择 magpie 模型后连接失败？

检查 magpie 是否运行、3425 端口是否监听，以及客户端代理是否拦截了 127.0.0.1 请求。本地网关与 GravitexAI 仍需分别保持可连接。

Claude 请求 404？

检查提供方的 anthropic 地址是否为 https://api.gravitex.ai，不带 /v1。不要只配置 url= 后就假定原生 Messages 请求已正确路由。

GPT 工具调用与推理一起使用时报 400？

给提供方补充 responses=https://api.gravitex.ai/v1。确认目标模型和账户支持 Responses，避免仍将该请求转发至不支持这一组合的 Chat Completions 接口。

401 / 403 怎么处理？

区分本地网关认证与 GravitexAI 上游认证。上游密钥错误时，可运行 magpie provider key gravitex sk-新的密钥更新，再测试提供方。手动请求本地网关时应使用对应的网关凭据，而不是将上游密钥当作本地凭据。

目标模型没有出现在列表中？

确认账户可用该模型，再运行 magpie provider models gravitex +模型ID 将其加入暴露列表。必要时重新接管 WorkBuddy 并完全重启客户端。

七、回退与日常维护

取消 WorkBuddy 接管

magpie workbuddy default

执行后完全重启 WorkBuddy。也可在客户端完全退出时，用之前的备份恢复 models.json。

开机自启

magpie autostart on

使用 magpie 模型时，本地网关需要持续运行。保留原有能正常使用的直连模型，便于按需切回。

八、相关资源

工具官网：usemagpie.ai
官方项目：yetone/magpie
入门说明：magpie Docs
参数与客户端配置参考：官方 Reference
WorkBuddy 直连配置：WorkBuddy
密钥管理：GravitexAI 控制台

对话型 AI

编程开发

AI Agent

技术工程

翻译场景

一、产品简介

二、前置条件

三、安装 magpie

四、配置 GravitexAI 提供方

第一步：添加三个协议端点

第二步：已有提供方补充协议

第三步：测试与选择模型

五、以 WorkBuddy 为例接入

第一步：确认客户端版本与配置目录

第二步：退出客户端并备份

第三步：选择默认模型并接管

第四步：重开 WorkBuddy 并选择模型

六、验证与排错

检查本地网关

验证工具调用与推理

七、回退与日常维护

取消 WorkBuddy 接管

开机自启

八、相关资源

​一、产品简介

​二、前置条件

​三、安装 magpie

​四、配置 GravitexAI 提供方

​第一步：添加三个协议端点

​第二步：已有提供方补充协议

​第三步：测试与选择模型

​五、以 WorkBuddy 为例接入

​第一步：确认客户端版本与配置目录

​第二步：退出客户端并备份

​第三步：选择默认模型并接管

​第四步：重开 WorkBuddy 并选择模型

​六、验证与排错

​检查本地网关

​验证工具调用与推理

​七、回退与日常维护

​取消 WorkBuddy 接管

​开机自启

​八、相关资源

一、产品简介

二、前置条件

三、安装 magpie

四、配置 GravitexAI 提供方

第一步：添加三个协议端点

第二步：已有提供方补充协议

第三步：测试与选择模型

五、以 WorkBuddy 为例接入

第一步：确认客户端版本与配置目录

第二步：退出客户端并备份

第三步：选择默认模型并接管

第四步：重开 WorkBuddy 并选择模型

六、验证与排错

检查本地网关

验证工具调用与推理

七、回退与日常维护

取消 WorkBuddy 接管

开机自启

八、相关资源