Magpie 接入 ModelGo：配置与排障

Magpie 可以为 Claude Code、Codex、OpenCode 等 Agent 统一配置模型。将 ModelGo 添加为自定义供应商后，即可为不同 Agent 选择 ModelGo 提供的模型。

1. 准备 API Key 和模型

安装 Magpie，并准备好需要接入的 Agent。在 ModelGo 控制台创建 API Key，确认账户余额、Key 预算和目标模型的调用权限。

模型名称使用 ModelGo 的平台逻辑模型名。可以在模型广场查看，也可以查询当前 Key 有权调用的模型：

bash

export MODELGO_API_KEY="mgk_替换为你的API_Key"
curl https://api.modelgo.ai/v1/models \
  -H "Authorization: Bearer $MODELGO_API_KEY"

使用响应中 data[].id 的值作为模型名称。此环境变量仅用于终端验证；Magpie 的密钥仍需在供应商配置中填写。

打开「供应商」标签页，点击「＋添加供应商」，选择底部的「自定义」。

*官方界面示例：通过「自定义」添加 ModelGo。*

保存配置。OpenAI 地址包含 /v1，Anthropic 地址使用根地址，不要添加 /chat/completions 或 /messages。所选模型需支持 Agent 使用的入口协议，具体见模型协议与参数。

在 ModelGo 供应商下查看模型列表，选择要提供给 Agent 的模型。进入「Agent」标签页，找到目标 Agent，在右侧模型选择器中选择 ModelGo 下的模型。

*官方界面示例：图中模型仅演示选择器位置，实际请选择 ModelGo 供应商下的目标模型。*

配置后新建 Agent 会话；Codex 还需要重启应用。Magpie 会将本地网关地址和模型配置写入对应 Agent 的配置文件，通过它调用模型时需要保持 Magpie 运行；关闭窗口后可继续驻留菜单栏或托盘。

在新会话中发送「请用一句话介绍你能帮助我完成哪些任务」。收到回复后，在 Magpie「路由」页面确认请求由 ModelGo 下的目标模型处理，也可到 ModelGo 控制台查看调用日志。文件处理、图片理解和工具调用需分别用对应任务验证。

问题	处理方式
`401`	检查供应商配置中的 API Key 是否完整、有效，是否含多余空格或换行。
`402`	检查账户余额，以及工作空间、成员和 Key 的额度与预算。
`403`	根据错误原因检查模型权限或账号状态。
`404`	检查两种协议的 Base URL，避免重复拼接 `/v1` 或填写完整请求路径。
`model_protocol_not_offered`	所选模型未开放当前入口，请换用支持相应协议的模型。
`429`	触发限流，按 `Retry-After` 等待，或退避后重试。
切换后仍使用旧模型	新建 Agent 会话；Codex 同时重启应用。
连接失败且没有路由记录	确认 Magpie 正在运行，并检查代理是否拦截本机 `127.0.0.1:3425` 的请求。

排查时保留 X-Request-ID，具体含义见错误码与限流。