文档 · 接入

Add to magpie

给用户一个链接，你的模型就会出现在他们用的每个 Agent 里：Claude Code、Codex、OpenCode、Gemini CLI、Pi、Crush。不用改配置文件，不用设环境变量，也不用手动复制 base URL。

快速开始

1. 生成链接用 URL 参数描述你的服务：名称、你支持的每种 API 的 base URL，还可以带上用户的密钥和要提供的模型。
2. 放到按钮后面放在控制台里、刚生成的密钥旁边：Add to magpie。
3. 用户确认magpie 打开后，会清楚列出提示词和密钥将发往哪里，用户同意后才添加这个供应商。之后每个 Agent 都能直接用。

https://usemagpie.ai/import#name=Acme%20Relay&chat=https://api.acme.example/v1&anthropic=https://api.acme.example&key=sk-…&models=gpt-5.5,claude-sonnet-5

链接格式

magpie 会向系统注册 magpie:// 协议。导入链接就是这个协议，加上 import 和一串查询参数：

在网页上，请改用 usemagpie.ai/import，把同样的参数放在 # 后面：

每个值都要做 URL 编码，URLSearchParams 或 urlencode 的结果即可。空格写成 %20 或 + 都行。

参数

链接要么指定 magpie 的某个预设（预设已经知道该厂商的地址），要么从头描述一个供应商：一个名称，加至少一个 base URL。

不用预设时，chat、responses、anthropic 至少要填一个；你支持几种 API 就填几个，每个 Agent 会用它原生支持的那一种。Base URL 必须是 https，只有指向 localhost、回环地址、内网地址和 *.local 时可以用 http，因为本地模型服务通常不配 TLS。地址里不能带查询参数、# 片段或账号密码。

预设

magpie 已经内置的厂商。magpie presets 会打印当前的列表。

有预设的厂商只需带上密钥：magpie://import?preset=deepseek&key=sk-…。想加入列表？提个 issue。

链接生成器

填上你的服务信息，链接、按钮代码和 Markdown 会随输入实时生成。所有内容都只在这个页面里，不会发送出去。

自己的服务预设

预设 区域 名称 Id 可选 OpenAI Chat base URL Anthropic base URL OpenAI Responses base URL 可选 models.dev 目录 可选 API 密钥 可选 模型 逗号分隔 网站 可选 密钥页面 可选 图标 可选，https

网页链接复制

应用链接复制

HTML复制

Markdown复制

试一下会打开 magpie；你确认之前不会添加任何东西。

按钮

两个现成的徽章，一个用于浅色页面，一个用于深色页面。把它链接到你的导入链接即可；也可以自己画按钮，Add to magpie 字样和这只鸟都可以随意使用。

<a href="https://usemagpie.ai/import#preset=deepseek&key=sk-…">
  <img src="https://usemagpie.ai/img/add-to-magpie.svg" alt="Add to magpie" width="176" height="40">
</a>

[![Add to magpie](https://usemagpie.ai/img/add-to-magpie.svg)](https://usemagpie.ai/import#preset=deepseek)

深色页面请用 add-to-magpie-light.svg。README 这类公开页面绝不能带密钥：去掉 key，让用户粘贴自己的。

在后端生成

按钮最适合放在展示新密钥的那个页面。在拿到密钥的地方生成链接：

const params = new URLSearchParams({
  name: "Acme Relay",
  chat: "https://api.acme.example/v1",
  anthropic: "https://api.acme.example",
  key: apiKey,
  models: ["gpt-5.5", "claude-sonnet-5"].join(","),
  icon: "https://acme.example/logo.svg",
});
const href = "https://usemagpie.ai/import#" + params;

from urllib.parse import urlencode

href = "https://usemagpie.ai/import#" + urlencode({
    "name": "Acme Relay",
    "chat": "https://api.acme.example/v1",
    "anthropic": "https://api.acme.example",
    "key": api_key,
    "models": "gpt-5.5,claude-sonnet-5",
    "icon": "https://acme.example/logo.svg",
})

magpie import 'magpie://import?preset=deepseek&key=sk-…'   # 会先询问；加 -y 跳过

安全

导入链接只是一个建议，决定权在用户手里。

• 总是要确认。magpie 会显示名称、提示词和密钥将发往的每个地址，以及模型列表；用户点「添加」之前什么都不保存。用户还可以先改名或换掉密钥。
• 不会悄悄覆盖。id 已被占用时，对话框会说明，按钮也会变成「替换」。
• 只接受 https。除了本机和局域网，一律拒绝 http；file:、URL 里带账号密码以及其他协议直接拒绝。
• 只读一次。在应用里，链接内容只交给窗口一次；刷新后对话框不会再出现。
• 图标是下载的，不是嵌入的。icon= 地址由 magpie 自己下载，只在用户确认导入之后，只走 https，只存进它自己的图标目录，最大 1 MB，并校验类型。域名在连接时解析，落到回环、内网、链路本地或保留地址时 magpie 拒绝连接，所以指回用户本机的域名（或 DNS 重绑定）都会被拒绝。页面和对话框从不直接加载远程图片。
• 密钥不经过服务器。网页链接把参数放在 # 片段里。密钥最终只存在 ~/.config/magpie/providers.json，只有用户本人可读。

平台支持

导入链接需要 magpie 0.1.8 或更新版本。magpie 已在运行时，链接会交给那个实例，并把它的窗口调到前台。