面向中转站运营方

对接规范

中转站可以在自己的控制台放一个「一键添加到 AI Switch」按钮，指向下面这个 scheme 链接。用户点击后 AI Switch 会被唤起，弹出确认框，确认后直接生成一个 API 账号，不需要手抄 base URL 和密钥。

URL 结构

aiswitch://scheme，固定

v1协议版本，只接受 v1

/import路径，固定

?resource=provider资源类型，只接受 provider

&app=…目标平台

&name=…账号显示名

&endpoint=…base URL

&apiKey=…API 密钥

scheme、版本段、路径三者是固定值，写错任何一个都会被拒绝解析。所有参数值必须做 URL 百分号编码。

参数

参数必填说明

resource必填只接受 provider。其他值会返回「暂不支持的 resource」。

app必填目标平台，取值见下方对照表。opencode / openclaw / hermes 虽然是合法平台名，但不支持深链接导入，会被能力校验拒绝。

name必填账号在列表里的显示名。会做 trim，trim 后不能为空。建议直接写站点名，便于用户识别。

endpoint必填中转站的 API base URL，必须是 http 或 https。可以用逗号分隔写多个候选，取第一个能解析成 http(s) 的；其余会被忽略。

apiKey必填API 密钥。trim 后不能为空。确认框里只显示掩码（首 4 位 + *** + 末 4 位），不会明文展示。

model可选单模型映射，用于 codex / gemini / grok。填中转站真实可用的模型 ID。

haikuModel · sonnetModel · opusModel可选Claude 的三档模型映射，可以只填其中一个或两个。app 不是 claude 时这三个参数会被忽略。

homepage · notes可选会被解析，但当前版本的确认框不展示、导入时也不落库。填了不报错，但也不会有任何效果。

app 与上游协议的对应关系

上游协议不是 URL 参数，由 app 直接决定，链接里不用也不能指定。这意味着一个中转站如果对某个平台只兼容另一种接口格式，就不能用深链接接入，得让用户手动建账号。

app 取值平台上游协议

codex · openai · chatgptCodexopenai-responses

claude · anthropic · claude-code · claude-desktopClaude Codeanthropic

gemini · google · gemini-cliGemini CLIgemini

grok · xai · x-ai · x.aiGrokopenai

别名匹配前会先 trim、转小写，并把空格和连字符统一成下划线，所以 Claude-Code 和 claude_code 等价。

模型映射怎么填

模型参数写的是「上游真实模型 ID」，AI Switch 会把客户端固定请求的那个模型名映射到它。左边是客户端请求名，右边是你填进去的值。

app=claude

claude-haiku-alias→haikuModel

claude-sonnet-alias→sonnetModel

claude-opus-alias→opusModel

app=codex / gemini / grok

gpt-5→modelapp=codex

gemini-2.5-flash→modelapp=gemini

grok-3→modelapp=grok

模型参数可以完全不填，导入后由用户自己在账号里加映射。留空不影响导入成功。

示例

Claude Code，两档模型映射

aiswitch://v1/import?resource=provider&app=claude&name=Example%20Relay&endpoint=https%3A%2F%2Fapi.example.com%2Fv1&apiKey=sk-xxxxxxxx&sonnetModel=claude-sonnet-alias&opusModel=claude-opus-alias

Codex，单模型映射

aiswitch://v1/import?resource=provider&app=codex&name=Example%20Relay&endpoint=https%3A%2F%2Fapi.example.com%2Fv1&apiKey=sk-xxxxxxxx&model=gpt-5.6-sol

用户点下去之后发生什么

系统按注册的 scheme 唤起 AI Switch；应用已在运行则复用现有窗口并前置。
解析链接。任何一步校验不过，弹出错误提示，不会创建任何东西。
弹出确认框，列出平台、名称、base URL、密钥掩码、模型映射条数与来源 scheme。
确认框里有「导入后加入算力池」勾选项，默认勾选。用户确认后才落库。

限制

一条链接只能导入一个账号。没有批量格式，多个账号就给多个按钮。
只能建 API 类型账号，不能导入官方登录态账号。
自定义请求头、自定义密钥字段名、1M 上下文开关都不在协议里，需要这些的账号只能手动建。
aiswitch:// 由桌面端注册，Web 服务模式下打开的页面不会响应这个 scheme。
另有 ccswitch:// 兼容导入协议，默认关闭，需要用户自己在设置里开启，且仅 Windows 与 Linux 可用。中转站请一律用 aiswitch://。