首页
教程
立即安装
GitHub
English
模型与供应商

配置供应商与 API 接入

支持商业 API Key 接入与 ChatGPT/Claude 网页订阅挂载，最短路径完成供应商配置闭环。

安装好 Magpie AI 之后，首要任务就是接入你的模型供应商（Providers）。一旦供应商就绪，你就可以通过菜单栏或命令行自由将它们分配给不同的 AI 编码代理（如 Claude Code、Codex、Gemini CLI 等）。

Magpie AI 支持两类主流接入方式：

  1. 商业 API 接入：直接配置官方或第三方 API Key（如 Anthropic、OpenAI、DeepSeek、Moonshot/Kimi、智谱 GLM、SiliconFlow 等），或接入任意兼容 OpenAI 协议的自定义中转端点。
  2. 网页订阅共享（Shared Subscriptions）：挂载现有的 ChatGPT Plus / Claude Pro 网页会员或 OAuth 会话，免去单独充值商业 API 的成本。

本教程将详细介绍如何通过 CLI 命令行、交互式 TUI 或菜单栏桌面界面高效完成供应商的添加与验证。

方式一：通过 CLI 命令行极速添加（推荐）

Magpie AI 的命令行工具提供了开箱即用的预设自动补全与极简命令结构：

1. 使用官方预设极速添加常见供应商

针对常见的主流模型供应商，Magpie 内置了端点地址与协议映射规则，你只需要提供供应商名称和你的 API Key 即可：

bash
# 添加 DeepSeek 官方 API
magpie provider add deepseek sk-xxxxxxxxxxxxxxxxxxxxxxxx

# 添加 Moonshot / Kimi API
magpie provider add kimi sk-xxxxxxxxxxxxxxxxxxxxxxxx

# 添加智谱 GLM 开放平台 API
magpie provider add zhipu xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 添加 MiniMax 或 SiliconFlow 硅基流动
magpie provider add siliconflow sk-xxxxxxxxxxxxxxxxxxxx

你可以随时查看 Magpie 支持的所有内置供应商预设：

bash
# 列出所有已知供应商预设及其默认支持的模型列表
magpie presets

2. 添加自定义 OpenAI 兼容接口（中转站 / 私有部署）

如果你使用的是私有部署的开源模型（如 vLLM、Ollama、LocalAI）或第三方 API 中转服务，可以通过参数指定自定义的 Base URL 和模型列表：

bash
# 添加自定义中转供应商，指定基础地址与可用模型
magpie provider add my-custom-relay \
  --base-url https://api.my-relay.com/v1 \
  --key sk-custom-key-123456 \
  --models deepseek-r1,gpt-4o,claude-3-5-sonnet

3. 挂载已有网页订阅（Shared Subscriptions）

如果你已经订阅了 ChatGPT Plus、Claude Pro 或 GitHub Copilot，无需重复购买 API Token，可以直接挂载会话账号：

bash
# 挂载 Claude 订阅会话
magpie accounts add claude

# 挂载 ChatGPT Plus 会话
magpie accounts add chatgpt

终端会弹出登录引导或授权提示，授权完成后，Magpie 会安全存储本地 Session 凭证，并通过本地网关透明分发给本地 CLI 客户端。

方式二：通过 macOS 菜单栏与图形界面添加

如果你更喜欢可视化交互，可以通过系统菜单栏或桌面控制台进行操作：

  1. 呼出添加面板：点击 macOS 菜单栏图标（或主界面侧边栏中的 Providers），点击 「Add Provider」 按钮。
  2. 选择供应商类型：
    • Preset 模板：从下拉列表中选择 Anthropic、OpenAI、DeepSeek、Moonshot、Zhipu 等预设。系统会自动预填官方 Base URL 和推荐模型名称。
    • Custom OpenAI：选择自定义类型，手动填入中转服务商提供的 Base URL 与 API Key。
    • Web Account：选择网页订阅挂载，按照弹窗引导完成浏览器授权绑定。
  3. 设置显示名称与别名：可自定义供应商别名（如 deepseek-prod、kimi-backup），方便在后续多模型调度中快速识别。
  4. 保存并测试连通性：点击 「Test Connection」 验证 API Key 的有效性，绿灯通过后点击 「Save」 保存。

方式三：通过终端 TUI 界面添加与管理

在终端中运行 magpie tui 打开交互式仪表盘：

  1. 按 Tab 键将光标切换至 「Providers」 面板；
  2. 按 a 键（Add）呼出添加供应商对话框；
  3. 使用方向键选择预设类型，粘贴 API Key，按 Enter 键确认保存；
  4. 面板中会即时列出该供应商的连接延迟（Ping）与可用模型列表。

验证与管理已配置的供应商

完成添加后，建议立即执行以下检查，确保供应商处于可用状态：

1. 检查供应商清单

bash
# 查看所有已生效的供应商及其模型清单
magpie providers

终端将清晰列出供应商标识、端点地址、认证状态以及支持的模型列表。

2. 发起可用性测试请求

在将新供应商真正绑定到工作流之前，可以发起一次快速测试探针：

bash
# 测试指定供应商的连通性与模型响应速度
magpie test deepseek

若返回 HTTP 200 及响应延迟（如 182ms），说明网关与上游通道完全通畅。

3. 立即将新供应商分配给 AI 代理

现在，你可以用一条指令直接把这个供应商指派给你的编程工具：

bash
# 让 Claude Code 立即接入刚配好的 DeepSeek 模型
magpie claude deepseek/deepseek-v4-pro

# 让 Codex 立即接入 Kimi 模型
magpie codex kimi/moonshot-v1-auto

常见问题与排错指引

Q：添加第三方中转服务时，提示 401 Unauthorized？

A：请首先确认 API Key 字符串前后没有意外复制多余的空格或换行符；其次确认该中转服务商要求的 Base URL 是否包含 /v1 后缀（如 https://relay.com/v1），Magpie 遵循标准 OpenAPI 规范拼接路径。

Q：我的 API Key 会被同步或上传到云端吗？

A：绝对不会。Magpie AI 坚持 100% 本地化隐私原则，所有 API Key 均采用操作系统原生钥匙串（macOS Keychain / Linux Secret Service / Windows DPAPI）或本地受控加密文件存储，绝不会经过任何第三方远程中转服务器。

Q：添加了网页订阅后，在 CLI 工具中会遇到并发限制吗？

A：网页订阅（Web Subscriptions）本身受 OpenAI 或 Anthropic 官方的账号级频控限制（如 3 小时内 40 条对话）。为了突破单账号频控瓶颈，推荐使用 Magpie 的 虚拟路由组与故障转移 功能，将多个账号组合成轮询负载池。