Provider 接入 · MagicFrog Docs

用你自己的 API key 接入 Anthropic、OpenAI 或任意 OpenAI 兼容端点。

MagicFrog 只有三条模型通道，且每条都是自带密钥（BYOK）：Anthropic、OpenAI 与自定义 OpenAI 兼容端点。没有可浏览的厂商目录，也没有订阅登录路径。你添加的密钥由服务端保存在 SQLite 数据库里，而不是磁盘上的共享文本文件。

添加凭据

在桌面端或网页端，于输入框执行 /connect。对话框会列出该 provider 支持的方式。选择 API key，粘贴密钥，provider、model 与 integration 目录随即刷新。再执行 /model 选择模型。

MagicFrog 网页控制台：现役实例的 Settings → Providers 分区

网页端 Settings → Providers 分区：

在终端里，magicfrog auth login 走同一条接入流程：

magicfrog auth login anthropic
magicfrog auth list

auth list 会打印服务端已知的全部 integration 与凭据，是 provider 没有出现在选择器时的第一项排查。

Anthropic

执行 /connect，选择 Anthropic。
粘贴 Anthropic API key。
执行 /model 选择模型。

OpenAI

执行 /connect，选择 OpenAI。
粘贴 OpenAI API key。
执行 /model 选择模型。

官方 OpenAI 端点同时接受 chat completions（/v1/chat/completions）与 Responses（/v1/responses）两种请求形态。

自定义 OpenAI 兼容端点

大多数 provider 都提供 OpenAI 兼容 API，所以自定义端点只有两步：先存密钥，再声明 provider。

执行 /connect，选择 Other，输入 provider ID（例如 myprovider），粘贴密钥。
把该 provider 写入 magicfrog.json：

magicfrog.json

{
  "$schema": "https://www.magicfrog.ai/config.json",
  "providers": {
    "myprovider": {
      "name": "My AI Provider",
      "package": "@magicfrog/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.myprovider.com/v1",
        "apiKey": "{env:MYPROVIDER_API_KEY}"
      },
      "models": {
        "my-model": {
          "name": "My Model",
          "limit": {
            "context": 200000,
            "output": 65536
          }
        }
      }
    }
  }
}

执行 /model，自定义 provider 与已声明的模型会出现在选择器中。

字段	含义
`package`	provider 实现。chat completions 形态用 `@magicfrog/ai/providers/openai-compatible`；Responses 形态用 `@magicfrog/ai/providers/openai-compatible-responses`。
`name`	模型选择器中的显示名。
`settings.baseURL`	端点根地址。结尾的 `/v1` 会被自动处理。
`settings.apiKey`	密钥；用 `{env:NAME}` 从环境变量读取。已由 `/connect` 存好的凭据可以省略。
`headers`	该 provider 每个请求都会携带的额外请求头。
`models`	该 provider 提供的模型。
`models.<id>.limit.context`	最大输入 token 数。
`models.<id>.limit.output`	最大生成 token 数。

provider 级设置对每个模型生效，模型级设置可以覆盖它。limit 让 MagicFrog 能报告剩余上下文。

同一 provider 下混用两种请求形态

当不同模型需要不同传输形态时，把 provider 级 package 设为通用形态，再在需要差异的模型上覆盖 package。

本地模型

MagicFrog 通过内置预设发现本地推理服务器：

预设	默认端点
LM Studio	`http://127.0.0.1:1234`
Ollama	`http://127.0.0.1:11434`
vLLM	`http://127.0.0.1:8000`

启动本地服务器后，预设会发现它提供的模型，无需凭据即可出现在 /model 选择器中。若端点要求密钥，在 magicfrog.json 里设置 providers.<预设>.settings.apiKey。

配置文件位置

MagicFrog 从项目目录向上查找 magicfrog.json 或 magicfrog.jsonc，并读取全局配置目录。$schema 用于编辑器校验。后加载的来源覆盖先加载的来源，显式传入的配置路径优先级最高。

仍在用 provider.<id>.options.baseURL 的旧配置会在加载时被读取并归一化。新配置应使用 providers.<id>.settings，因为 V1 形态已冻结并标记为弃用。

故障排查

检查凭据：运行 magicfrog auth list。为某个 provider ID 存的密钥不会自动满足另一个 ID。
核对 ID：/connect 里输入的 ID 必须与 magicfrog.json 里 providers 下的键一致。
核对 package 与端点形态：chat completions 用 @magicfrog/ai/providers/openai-compatible；Responses 端点用 @magicfrog/ai/providers/openai-compatible-responses。
检查 baseURL：必须是完整的 http 或 https 地址。路径前缀写错是自定义端点返回 404 的最常见原因。
声明模型：models 为空的 provider 不会列出任何模型，即使密钥有效。