> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# magpie

> magpie 集成指南：配置 GravitexAI 多协议网关，以 WorkBuddy 为例接入 Claude 与 GPT 模型

> [!NOTE]
>
> Codex 桌面版接入步骤（macOS / Windows）请参阅 [Codex Desktop](https://docs.gravitex.ai/cn/integrations/codex-desktop.md)。

## 一、产品简介

**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` |

> [!NOTE]
>
> 如果模型可通过 WorkBuddy 的自定义模型直接正常使用，可参考 [WorkBuddy 直连指南](https://docs.gravitex.ai/cn/integrations/workbuddy.md)。需要转换协议时，再按本文接入 magpie。图像生成连接器配置见 [WorkBuddy-生图](https://docs.gravitex.ai/cn/integrations/workbuddy-image-generation.md)。

## 二、前置条件

* 已安装 WorkBuddy，且至少启动过一次。
* 已在 [GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys) 创建 API 密钥。
* 已确认账户可用的模型 ID 和对应接口，见 [GravitexAI 模型广场](https://maas.gravitex.ai/#/api-models)。
* magpie 与 WorkBuddy 运行在同一台电脑上；本地网关默认使用 `3425` 端口。

## 三、安装 magpie

> [tab] macOS
>
> 使用官方安装脚本：
>
> ```bash theme={null}
> curl -fsSL https://usemagpie.ai/install.sh | sh
> ```
>
> 也可以从 [magpie 官网](https://usemagpie.ai/) 下载 Apple Silicon 或 Intel 对应的安装包。
>
> 安装后打开 magpie，并在终端验证：
>
> ```bash theme={null}
> magpie --version
> magpie ls
> ```
>
> 如果提示找不到命令，重新打开终端，或将 `~/.local/bin` 加入 Shell 的 PATH。

> [tab] Windows
>
> 从 [magpie 官网](https://usemagpie.ai/) 或[官方 Releases](https://github.com/yetone/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 时，使用实际可执行文件路径。

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

## 四、配置 GravitexAI 提供方

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

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

```bash theme={null}
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 可使用单行写法：

```powershell theme={null}
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` | 显示名称 |

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

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

![magpie 供应商页面配置 GravitexAI 的 OpenAI Responses 地址](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/magpie-provider.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=9eb8729dedb6ce51f789ff58a5c961b7)

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

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

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

```bash theme={null}
magpie provider set gravitex responses=https://api.gravitex.ai/v1 anthropic=https://api.gravitex.ai
```

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

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

```bash theme={null}
magpie provider test gravitex
magpie models workbuddy
```

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

```bash theme={null}
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` |

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

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

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

> [tab] macOS
>
> ```bash theme={null}
> cp ~/.workbuddy/models.json ~/.workbuddy/models.json.bak-$(date +%Y%m%d-%H%M%S)
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $workbuddyModels = Join-Path $HOME '.workbuddy/models.json'
> Copy-Item $workbuddyModels "$workbuddyModels.bak-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
> ```

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

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

```bash 使用 Claude theme={null}
magpie workbuddy gravitex/claude-sonnet-5-5
```

```bash 使用 GPT theme={null}
magpie workbuddy gravitex/gpt-6-sol
```

两条命令选择一条即可。模型使用 `提供方 ID/模型 ID` 格式；magpie 会将接管配置写入 WorkBuddy 的模型文件。

桌面端也可进入 **Agent** 页面，找到 **WorkBuddy**，打开右侧的接入开关，并选择 GravitexAI 下的模型。下图展示 Agent 页的布局；截图中未显示 WorkBuddy，需在列表中继续查找。

![magpie Agent 页面中的接入开关与模型选择器](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/magpie-agents.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=cd688814d6f5bf73982985cabbd48919)

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

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

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

![WorkBuddy 选择 gpt-6-luna 并正常收到回复](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/magpie-workbuddy-chat.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=3a53795d7e0d5ac43e30ddc062b490e7)

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

## 六、验证与排错

### 检查本地网关

> [tab] macOS
>
> ```bash theme={null}
> lsof -nP -iTCP:3425 -sTCP:LISTEN
> ```
>
> 无进程监听时，打开 magpie：
>
> ```bash theme={null}
> open -a magpie
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> Get-NetTCPConnection -LocalPort 3425 -State Listen
> ```
>
> 未监听时，打开下载的 magpie 桌面程序。

### 验证工具调用与推理

如果基础对话正常，但工具任务返回 400，检查错误是否涉及 `tools` 与 `reasoning_effort`。确认 `responses=` 已配置为 `https://api.gravitex.ai/v1`，并检查所用模型是否支持 Responses。

判断接入成功时，不应只看模型是否出现在列表中；还要确认一次实际对话和工具任务均正常。推理模型出现 HTTP 200 但回复为空时，也需检查输出预算是否不足。

> [accordion] WorkBuddy 模型列表没有变化？
>
> 完全退出 WorkBuddy 后重开；确认接管的是国内版 workbuddy，而不是国际版或 CodeBuddy Code。运行 magpie ls 检查识别结果与实际配置目录。

> [accordion] 选择 magpie 模型后连接失败？
>
> 检查 magpie 是否运行、3425 端口是否监听，以及客户端代理是否拦截了 127.0.0.1 请求。本地网关与 GravitexAI 仍需分别保持可连接。

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

> [accordion] GPT 工具调用与推理一起使用时报 400？
>
> 给提供方补充 responses=[https://api.gravitex.ai/v1。确认目标模型和账户支持](https://api.gravitex.ai/v1。确认目标模型和账户支持) Responses，避免仍将该请求转发至不支持这一组合的 Chat Completions 接口。

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

> [accordion] 目标模型没有出现在列表中？
>
> 确认账户可用该模型，再运行 magpie provider models gravitex +模型ID 将其加入暴露列表。必要时重新接管 WorkBuddy 并完全重启客户端。

## 七、回退与日常维护

### 取消 WorkBuddy 接管

```bash theme={null}
magpie workbuddy default
```

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

### 开机自启

```bash theme={null}
magpie autostart on
```

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

## 八、相关资源

* 工具官网：[usemagpie.ai](https://usemagpie.ai/)
* 官方项目：[yetone/magpie](https://github.com/yetone/magpie)
* 入门说明：[magpie Docs](https://usemagpie.ai/docs/start)
* 参数与客户端配置参考：[官方 Reference](https://github.com/yetone/magpie/blob/main/docs/reference.md)
* WorkBuddy 直连配置：[WorkBuddy](https://docs.gravitex.ai/cn/integrations/workbuddy.md)
* 密钥管理：[GravitexAI 控制台](https://maas.gravitex.ai/#/api-keys)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.