Deep Link

当供应商网站、账户控制台或安装指南需要把一份完整配置交给 OcHub 桌面端时，可以使用 Deep Link。

导入模型供应商时，OcHub 会先打开可编辑预览。只有用户点击“导入模型供应商”后才会写入； Manifest 包含 applyTo 时，预览还会列出要配置此供应商的工具，用户可在确认前关闭任意目标。

兼容性与行为

当前协议版本为 v1：

ochub://v1/import?resource=<resource>&...

模型供应商资源可由 macOS 桌面端和 ochcli 处理。桌面端支持冷启动，也支持应用已运行时 接收链接。

OcHub 本地网关配置应使用 resource=model-provider。不要与 resource=provider 混淆；后者表示给一个目标应用导入直接连接。

模型供应商 URL

模型供应商链接除 resource 外只有一个 Query 参数：

ochub://v1/import?resource=model-provider&payload=<base64url-json>

payload 是将 UTF-8 JSON Manifest 编码为无 Padding 的 Base64URL 后得到的内容。 它不是普通 Base64：应使用 URL 安全的 - 和 _，并移除末尾的 =。解码后的 JSON 最大为 64 KiB。

不要把 apiKey 作为单独的明文 Query 参数。应先把它写入 Manifest，再编码完整 Payload。

Manifest 示例

{
  "schema": "io.ochub.model-provider/v1",
  "source": {
    "id": "com.aster/default",
    "revision": "2026-07-01",
    "website": "https://aster.example"
  },
  "name": "Aster API",
  "apiKey": "sk-user-secret",
  "dialects": ["messages", "responses"],
  "models": ["claude-sonnet-4-5", "gpt-5.4"],
  "websocketEnabled": true,
  "endpoints": [
    {
      "baseUrl": "https://api.aster.example"
    },
    {
      "baseUrl": "https://backup.aster.example"
    }
  ],
  "defaultModel": "claude-sonnet-4-5",
  "modelRules": [
    {
      "model": "fast",
      "upstreamModel": "claude-sonnet-4-5",
      "dialect": "messages"
    }
  ],
  "reasoning": {
    "mode": "passthrough"
  },
  "applyTo": [
    { "app": "codex", "preferredModel": "gpt-5.4" },
    { "app": "claude", "preferredModel": "claude-sonnet-4-5" },
    { "app": "opencode" }
  ],
  "enabled": true,
  "requires": []
}

预览页会遮罩 API Key，用户可以在导入前显示或替换。CLI 无法暂停并等待桌面表单输入，因此 通过 CLI 导入时必须提供 apiKey。

Manifest 字段

每个 Endpoint 支持：

每个 Endpoint 只接受 baseUrl。这些地址能力等价，按数组顺序故障切换，并共用供应商 API Key、接口、模型和 WebSocket 能力。websocketEnabled: true 要求启用 responses，并表示所有故障切换地址都原生支持 Responses WebSocket；能力不同的地址 应定义为不同供应商。

OcHub 内部会为每个 Endpoint 和 Dialect 组合创建一个 Channel。一个 Manifest 最多包含 8 个 Endpoint 和 100 条模型规则；单个字符串最大为 4 KiB。重复的供应商 Dialect、 模型或 Endpoint 地址会被拒绝。

应用目标

每个 applyTo 项包含 app 和可选的 preferredModel。支持的应用值为 claude、claude-desktop、codex、grokbuild、opencode、openclaw 和 hermes；同一应用只能出现一次。 供应商 models 非空时，preferredModel 必须匹配其中一个精确名称或通配规则。供应商 必须包含与每个目标兼容的接口；applyTo 非空时，enabled 必须为 true。

桌面预览默认启用 Manifest 请求的所有目标，用户可在确认前取消目标或修改默认模型。 确认后，OcHub 会导入供应商、启动本地 Gateway，并在每个选中工具中创建或切换到由 OcHub 管理的供应商。上游 API Key 只保存在 OcHub；工具配置只接收本地 Gateway 地址 和独立的本地密钥。某个目标失败时，供应商和其他成功目标会保留，并明确报告失败工具。

ochcli deeplink import 没有确认界面，会在导入供应商后立即应用所有 applyTo 目标。 成功结果包含 appliedTo 和 applyFailures；任一目标失败时，命令会返回包含相同详情的 部分失败错误。

思考配置

省略 reasoning 等价于：

{
  "reasoning": {
    "mode": "passthrough"
  }
}

支持以下模式：

自动映射可以携带明确预算：

{
  "reasoning": {
    "mode": "auto",
    "lowBudget": 4096,
    "mediumBudget": 10000,
    "highBudget": 16000,
    "maxBudget": 32000
  }
}

预算必须为正数，并满足 lowBudget ≤ mediumBudget ≤ highBudget ≤ maxBudget。默认值依次为 4096、10000、 16000 和 32000。用户仍可以在导入预览中修改模式和预算。

生成链接

Node.js：

const manifest = {
  schema: "io.ochub.model-provider/v1",
  name: "Aster API",
  apiKey: "sk-user-secret",
  dialects: ["messages", "responses"],
  models: ["claude-sonnet-4-5", "gpt-5.4"],
  websocketEnabled: true,
  applyTo: [
    { app: "codex", preferredModel: "gpt-5.4" }
  ],
  endpoints: [
    {
      baseUrl: "https://api.aster.example"
    }
  ]
};

const payload = Buffer.from(
  JSON.stringify(manifest),
  "utf8"
).toString("base64url");

const url =
  `ochub://v1/import?resource=model-provider&payload=${payload}`;

浏览器 JavaScript：

function encodeBase64Url(value) {
  const bytes = new TextEncoder().encode(JSON.stringify(value));
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary)
    .replaceAll("+", "-")
    .replaceAll("/", "_")
    .replace(/=+$/, "");
}

const payload = encodeBase64Url(manifest);
const url =
  `ochub://v1/import?resource=model-provider&payload=${payload}`;

可以把生成的 URL 用作“导入 OcHub”按钮的目标地址。公开网站只能在用户完成身份认证后生成 个人链接，并应明确提示链接中包含用户的 API Key。

校验与测试

只解析和校验，不写入：

ochcli deeplink parse "$URL"

从自动化流程预演写入：

ochcli --dry-run deeplink import "$URL"

跳过桌面确认并直接写入：

ochcli deeplink import "$URL"

解析和演练输出默认会脱敏。不要在日志、CI 和共享终端中使用 --show-secrets。 非演练导入还会立即应用所有 applyTo 目标。

在 macOS 上测试桌面端：

open "$URL"

需要分别验证冷启动和应用已运行时的链接传递。桌面预览可以取消，取消后数据库不会变化。

其他资源类型

同一个协议外壳也支持现有资源：

provider 的 app 可为 claude|codex|grokbuild|opencode|openclaw|hermes，还支持 可选的 homepage、endpoint、apiKey、model、notes、角色模型字段、配置字段 和用量查询字段。mcp.apps 是逗号分隔列表，config 使用此资源原有的 Base64 编码。 skill 还支持 directory 和 branch。

新的本地网关集成应始终使用 model-provider 及其带版本 Manifest，不要拼接直接连接 provider URL。

安全与错误

Base64URL 只是编码，不是加密。拿到链接的人可以还原 API Key，因此完整 URL 应与 API Key 采用相同的保护级别：

• 不要把它写入分析系统、Referrer 日志、问题追踪、聊天或源代码。
• 按需生成链接，并且只向已经认证的 Key 所有者展示。
• 链接泄露后立即在供应商后台轮换 API Key。
• 不要记录原始 URL 或解码后的 Payload。

Scheme、协议版本、路径、Schema、Base64URL、JSON、URL、Dialect、重复字段或长度限制 不合法，以及 requires 包含尚不支持的能力时，OcHub 都会拒绝导入。被拒绝的链接不会写入 不完整的供应商状态。