Deep Link

プロバイダーの Web サイト、アカウントコンソール、セットアップガイドから、確認可能な 完成済み設定を OcHub デスクトップアプリへ渡す場合に Deep Link を使用します。

モデルプロバイダーでは編集可能なプレビューが開き、ユーザーが「モデルプロバイダーを インポート」を選ぶまで書き込みません。Manifest に applyTo がある場合、プレビューには このプロバイダーを設定するツールも表示され、確認前に任意の対象を解除できます。

互換性と動作

現在のプロトコルバージョンは v1 です。

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

モデルプロバイダーは macOS デスクトップアプリと ochcli で処理できます。デスクトップ アプリはコールドスタートと起動中のリンク受信の両方に対応します。

OcHub ローカルゲートウェイには resource=model-provider を使用します。 resource=provider は対象アプリ 1 つの直接接続をインポートする別のリソースです。

モデルプロバイダー URL

モデルプロバイダーリンクでは、resource のほかに 1 つの 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 キーがマスクされ、インポート前に表示または置換できます。CLI は デスクトップフォームへの入力を待てないため、CLI インポートでは apiKey が必要です。

Manifest フィールド

各 Endpoint では次を指定できます。

各 Endpoint は baseUrl のみを受け付けます。これらは同等のフェイルオーバー先で、 配列順に試され、プロバイダーの API キー、インターフェース、モデル、WebSocket 機能を共有します。websocketEnabled: true には responses が必要で、すべての フェイルオーバー先がネイティブ Responses WebSocket に対応することを意味します。 機能が異なるアドレスは別のプロバイダーとして定義してください。

OcHub は内部で Endpoint と Dialect の組み合わせごとに Channel を作成します。Manifest は最大 8 Endpoint、100 モデルルールで、文字列 1 つは最大 4 KiB です。重複する プロバイダー Dialect、モデル、Endpoint アドレスは拒否されます。

適用先

各 applyTo 項は app と任意の preferredModel を受け付けます。対応する値は claude、claude-desktop、codex、grokbuild、opencode、openclaw、 hermes です。同じアプリを複数回指定することはできません。 プロバイダーの models が空でない場合、preferredModel はその完全名または ワイルドカード項目のいずれかに一致する必要があります。プロバイダーには各対象と互換性の あるインターフェースが必要で、applyTo が空でない場合は enabled が true で なければなりません。

デスクトップのプレビューでは要求された適用先が既定で有効になり、確認前に解除したり 優先モデルを変更したりできます。確認後、OcHub はプロバイダーをインポートし、 ローカル Gateway を起動して、選択した各ツールに OcHub 管理のプロバイダーを作成・ 切り替えます。上流 API キーは 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 にインポート」ボタンのリンク先にします。公開 Web サイトでは 認証後にのみ個人リンクを生成し、リンクにユーザーの API キーが含まれることを明示します。

検証とテスト

書き込まずに解析・検証：

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 も受け付けます。

新しいローカルゲートウェイ連携では、直接接続の provider URL ではなく、常に model-provider とバージョン付き Manifest を使用してください。

セキュリティとエラー

Base64URL はエンコードであり、暗号化ではありません。リンクを得た人は API キーを復元 できるため、URL 全体を API キーと同じように扱います。

• 分析、Referrer ログ、Issue、チャット、ソース管理へ書き込まない。
• 必要なときだけ生成し、認証済みのキー所有者にだけ表示する。
• リンクが漏れた場合はプロバイダー側で API キーをローテーションする。
• 生の URL やデコードした Payload をログに残さない。

Scheme、プロトコルバージョン、パス、Schema、Base64URL、JSON、URL、Dialect、重複、 サイズ制限、または未対応の requires が不正な場合、OcHub は拒否します。拒否された リンクによって不完全なプロバイダー状態が書き込まれることはありません。