Gateway プロトコル

​

トランスポートとフレーミング

• WebSocket、テキストフレーム、JSON ペイロード。
• 最初のフレームは 必ず connect リクエストである必要があります。
• 接続前フレームは 64 KiB（MAX_PREAUTH_PAYLOAD_BYTES）に制限されます。ハンドシェイク後は hello-ok.policy.maxPayload と hello-ok.policy.maxBufferedBytes に従います。診断が有効な場合、過大な受信フレームと低速な送信バッファは、Gateway がフレームを閉じるかドロップする前に payload.large イベントを発行します。これらのイベントには surface、バイトサイズ、制限、安全な理由コードが含まれますが、メッセージ本文、添付ファイルの内容、生フレームバイト、トークン、Cookie、シークレットは含まれません。

• リクエスト: {type:"req", id, method, params}
• レスポンス: {type:"res", id, ok, payload|error}
• イベント: {type:"event", event, payload, seq?, stateVersion?}

​

ハンドシェイク

{
  "type": "event",
  "event": "connect.challenge",
  "payload": { "nonce": "…", "ts": 1737264000000 }
}

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "maxProtocol": 4,
    "client": {
      "id": "cli",
      "version": "1.2.3",
      "platform": "macos",
      "mode": "operator"
    },
    "role": "operator",
    "scopes": ["operator.read", "operator.write"],
    "caps": [],
    "commands": [],
    "permissions": {},
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-cli/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 4,
    "server": { "version": "…", "connId": "…" },
    "features": { "methods": ["…"], "events": ["…"] },
    "snapshot": { "…": "…" },
    "auth": {
      "role": "operator",
      "scopes": ["operator.read", "operator.write"]
    },
    "policy": {
      "maxPayload": 26214400,
      "maxBufferedBytes": 52428800,
      "tickIntervalMs": 15000
    }
  }
}

{
  "auth": {
    "deviceToken": "…",
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

{
  "auth": {
    "deviceToken": "…",
    "role": "node",
    "scopes": [],
    "deviceTokens": [
      {
        "deviceToken": "…",
        "role": "operator",
        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]
      }
    ]
  }
}

​

ノード接続の例

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "maxProtocol": 4,
    "client": {
      "id": "ios-node",
      "version": "1.2.3",
      "platform": "ios",
      "mode": "node"
    },
    "role": "node",
    "scopes": [],
    "caps": ["camera", "canvas", "screen", "location", "voice"],
    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
    "permissions": { "camera.capture": true, "screen.record": false },
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-ios/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

• caps: camera、canvas、screen、location、voice、talk などの高レベルカテゴリ。
• commands: invoke 用のコマンド許可リスト。
• permissions: きめ細かなトグル（例: screen.record、camera.capture）。

​

ロールとスコープ

• operator: コントロールプレーンクライアント（CLI/UI/自動化）。
• node: capability ホスト（camera/screen/canvas/system.run）。

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

​

Presence

• system-presence は、deviceId、roles、scopes を含む、デバイス ID をキーにしたエントリを返します。そのため UI は、デバイスが operator と node の両方として接続している場合でも、デバイスごとに 1 行を表示できます。
• node.list には任意の lastSeenAtMs と lastSeenReason が含まれます。接続中のノードは理由 connect で現在の接続時刻を報告します。ペアリング済みノードは、信頼済みノードイベント経由で永続的なバックグラウンド presence も報告できます。

​

ノードバックグラウンド alive イベント

{
  "event": "node.presence.alive",
  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"
}

{
  "ok": true,
  "event": "node.presence.alive",
  "handled": true,
  "reason": "persisted"
}

​

ブロードキャストイベントのスコープ設定

• チャット、エージェント、ツール結果フレーム（ストリーミングされた agent イベント、ツール結果イベント）には少なくとも operator.read が必要です。それを持たないセッションは、これらのフレームを完全にスキップします。
• Plugin 定義の plugin.* ブロードキャストは、デフォルトで operator.write または operator.admin にゲートされます。plugin.approval.requested / plugin.approval.resolved などの明示的なエントリは、代わりに operator.approvals を使用します。
• ステータス/トランスポートイベント（heartbeat、presence、tick、接続/切断ライフサイクル）は制限なしのままなので、すべての認証済みセッションがトランスポートの健全性を観測できます。
• 不明なブロードキャストイベントファミリーは、登録済みハンドラーが明示的に緩和しない限り、デフォルトでスコープゲートされます（fail-closed）。

​

RPC メソッドファミリー

​

共通イベントファミリー

• chat: chat.inject などの UI チャット更新、およびトランスクリプト専用のその他のチャット イベント。プロトコル v4 では、差分ペイロードは deltaText を運び、message は 累積されたアシスタントのスナップショットのままです。非プレフィックス置換は replace=true を設定し、deltaText を置換テキストとして使用します。
• session.message、session.operation、session.tool: 購読中セッションのトランスクリプト、進行中の セッション操作、およびイベントストリーム更新。
• sessions.changed: セッションインデックスまたはメタデータが変更されました。
• presence: システムプレゼンスのスナップショット更新。
• tick: 定期的なキープアライブ/生存確認イベント。
• health: Gateway ヘルススナップショット更新。
• heartbeat: Heartbeat イベントストリーム更新。
• cron: Cron 実行/ジョブ変更イベント。
• shutdown: Gateway シャットダウン通知。
• node.pair.requested / node.pair.resolved: Node ペアリングライフサイクル。
• node.invoke.request: Node 呼び出しリクエストのブロードキャスト。
• device.pair.requested / device.pair.resolved: ペアリング済みデバイスのライフサイクル。
• voicewake.changed: ウェイクワードトリガー設定が変更されました。
• exec.approval.requested / exec.approval.resolved: exec 承認 ライフサイクル。
• plugin.approval.requested / plugin.approval.resolved: plugin 承認 ライフサイクル。

​

Node ヘルパーメソッド

​

監査台帳 RPC

• パラメータ: 任意の完全一致 agentId、sessionKey、または runId; 任意の kind ("agent_run" または "tool_action"); 任意の status ("started"、 "succeeded"、"failed"、"cancelled"、"timed_out"、"blocked"、または "unknown"); 任意の包含的な after / before Unix ミリ秒境界; 1 から 500 までの任意の limit; および前ページからの任意の文字列 cursor。
• 結果: { "events": AuditEvent[], "nextCursor"?: string }。

​

タスク台帳 RPC

• tasks.list には operator.read が必要です。
  • パラメータ: 任意の status ("queued"、"running"、"completed"、 "failed"、"cancelled"、または "timed_out") またはそれらのステータスの配列、 任意の agentId、任意の sessionKey、1 から 500 までの任意の limit、および任意の文字列 cursor。
  • 結果: { "tasks": TaskSummary[], "nextCursor"?: string }。
• tasks.get には operator.read が必要です。
  • パラメータ: { "taskId": string }。
  • 結果: { "task": TaskSummary }。
  • 存在しないタスク ID は、Gateway の not-found エラー形状を返します。
• tasks.cancel には operator.write が必要です。
  • パラメータ: { "taskId": string, "reason"?: string }。
  • 結果: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }。
  • found は、台帳に一致するタスクがあったかどうかを報告します。cancelled は、 ランタイムがキャンセルを受け入れたか、または記録したかを報告します。

​

オペレーターヘルパーメソッド

• commands.list (operator.read) は、エージェントのランタイムコマンドインベントリを 取得します。
  • agentId は任意です。省略するとデフォルトのエージェントワークスペースを読み取ります。
  • scope は、プライマリ name が対象とするサーフェスを制御します。text は 先頭の / なしのプライマリテキストコマンドトークンを返します。native と デフォルトの both パスは、利用可能な場合、プロバイダー対応のネイティブ名を返します。
  • textAliases は /model や /m などの完全一致スラッシュエイリアスを運びます。
  • nativeName は、存在する場合にプロバイダー対応のネイティブコマンド名を運びます。
  • provider は任意で、ネイティブ命名とネイティブ plugin コマンドの可用性にのみ影響します。
  • includeArgs=false は、シリアライズ済み引数メタデータをレスポンスから省略します。
• tools.catalog (operator.read) は、エージェントのランタイムツールカタログを 取得します。レスポンスには、グループ化されたツールと由来メタデータが含まれます:
  • source: core または plugin
  • pluginId: source="plugin" の場合の plugin 所有者
  • optional: plugin ツールが任意かどうか
• tools.effective (operator.read) は、セッションのランタイム有効ツール インベントリを取得します。
  • sessionKey は必須です。
  • Gateway は、呼び出し元が提供する認証や配信コンテキストを受け入れるのではなく、 サーバー側のセッションから信頼済みランタイムコンテキストを導出します。
  • レスポンスは、アクティブなインベントリのセッションスコープのサーバー導出プロジェクションであり、 core、plugin、channel、およびすでに検出済みの MCP サーバーツールを含みます。
  • tools.effective は MCP に対して読み取り専用です。ウォームセッション MCP カタログを最終ツールポリシー経由で投影することはありますが、MCP ランタイムの作成、 トランスポート接続、または tools/list の発行は行いません。一致するウォームカタログが 存在しない場合、レスポンスには mcp-not-yet-connected、 mcp-not-yet-listed、または mcp-stale-catalog などの通知が含まれる場合があります。
  • 有効なツールエントリは source="core"、source="plugin"、 source="channel"、または source="mcp" を使用します。
• tools.invoke (operator.write) は、/tools/invoke と同じ Gateway ポリシーパスを通じて、利用可能なツールを 1 つ呼び出します。
  • name は必須です。args、sessionKey、agentId、confirm、および idempotencyKey は任意です。
  • sessionKey と agentId の両方が存在する場合、解決されたセッションエージェントは agentId と一致する必要があります。
  • cron、gateway、nodes などの owner 専用 core ラッパーには、 tools.invoke 自体は operator.write であっても、owner/admin ID (operator.admin) が必要です。
  • レスポンスは SDK 向けエンベロープで、ok、toolName、任意の output、および型付き error フィールドを含みます。承認またはポリシー拒否は、 Gateway ツールポリシーパイプラインを迂回せず、ペイロード内の ok:false として返されます。
• skills.status (operator.read) は、エージェントに表示されるスキルインベントリを 取得します。
  • agentId は任意です。省略するとデフォルトのエージェントワークスペースを読み取ります。
  • レスポンスには、適格性、不足している要件、設定チェック、 および生のシークレット値を公開しないサニタイズ済みインストールオプションが含まれます。
• skills.search と skills.detail (operator.read) は ClawHub 検出メタデータを返します。
• skills.upload.begin、skills.upload.chunk、および skills.upload.commit (operator.admin) は、インストール前にプライベートスキルアーカイブをステージングします。これは 信頼済みクライアント向けの別個の admin アップロードパスであり、通常の ClawHub スキルインストールフローではありません。また、 skills.install.allowUploadedArchives が有効でない限りデフォルトで無効です。
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) は、その slug と force 値に紐づいたアップロードを作成します。
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) は、正確なデコード済みオフセットに バイトを追加します。
  • skills.upload.commit({ uploadId, sha256? }) は、最終サイズと SHA-256 を検証します。commit はアップロードを完了するだけで、スキルはインストールしません。
  • アップロードされたスキルアーカイブは、ルート SKILL.md を含む zip アーカイブです。アーカイブの 内部ディレクトリ名がインストール先を選択することはありません。
• skills.install (operator.admin) には 3 つのモードがあります:
  • ClawHub モード: { source: "clawhub", slug, version?, force? } は、 スキルフォルダーをデフォルトのエージェントワークスペースの skills/ ディレクトリにインストールします。
  • アップロードモード: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } は、コミット済みアップロードをデフォルトのエージェントワークスペースの skills/<slug> ディレクトリにインストールします。slug と force 値は、 元の skills.upload.begin リクエストと一致する必要があります。 skills.install.allowUploadedArchives が有効でない限り拒否されます。この設定は ClawHub インストールには影響しません。
  • Gateway インストーラーモード: { name, installId, timeoutMs? } は、 Gateway ホスト上で宣言済みの metadata.openclaw.install アクションを実行します。古いクライアントは まだ dangerouslyForceUnsafeInstall を送信する場合があります。このフィールドは非推奨で、 プロトコル互換性のためにのみ受け入れられ、無視されます。オペレーター所有のインストール判断には security.installPolicy を使用してください。
• skills.update (operator.admin) には 2 つのモードがあります:
  • ClawHub モードは、デフォルトのエージェントワークスペース内の追跡対象 slug 1 つ、または追跡対象のすべての ClawHub インストールを更新します。
  • 設定モードは、enabled、 apiKey、env などの skills.entries.<skillKey> 値にパッチを適用します。

​

models.list ビュー

• 省略または "default": agents.defaults.models が設定されている場合、 レスポンスは許可済みカタログになり、provider/* エントリについて 動的に検出されたモデルを含みます。それ以外の場合、レスポンスは Gateway カタログ全体です。
• "configured": ピッカーサイズの挙動です。agents.defaults.models が 設定されている場合、provider/* エントリのプロバイダースコープ検出を含め、 それが引き続き優先されます。許可リストがない場合、レスポンスは明示的な models.providers.<provider>.models エントリを使用し、設定済みモデル行が存在しない場合にのみ カタログ全体にフォールバックします。
• "all": agents.defaults.models を迂回する Gateway カタログ全体。通常のモデルピッカーではなく、 診断/検出 UI に使用します。

​

Exec 承認

• exec リクエストに承認が必要な場合、Gateway は exec.approval.requested をブロードキャストします。
• オペレータークライアントは、exec.approval.resolve を呼び出して解決します (operator.approvals が必要)。
• host=node の場合、exec.approval.request には systemRunPlan (正規の argv/cwd/rawCommand/セッションメタデータ) を含める必要があります。 systemRunPlan がないリクエストは拒否されます。
• 承認後、転送された node.invoke system.run 呼び出しは、その 正規の systemRunPlan を、信頼できる command/cwd/session コンテキストとして再利用します。
• 呼び出し元が prepare と最終承認済み system.run 転送の間に command、rawCommand、cwd、agentId、または sessionKey を変更した場合、Gateway は変更されたペイロードを信頼せず、実行を拒否します。

​

エージェント配信フォールバック

• agent リクエストには、外部配信を要求するために deliver=true を含められます。
• bestEffortDeliver=false (デフォルト) は厳格な挙動を維持します。解決不能または 内部専用の配信先は INVALID_REQUEST を返します。
• bestEffortDeliver=true は、外部に配信可能なルートを解決できない場合 (たとえば internal/webchat セッションやあいまいなマルチチャンネル設定) に、 セッション専用実行へのフォールバックを許可します。
• 最終的な agent 結果には、配信が要求された場合に result.deliveryStatus が含まれる場合があり、 openclaw agent --json --deliver で文書化されているものと同じ sent、suppressed、partial_failed、および failed ステータスを使用します。

​

バージョニング

• PROTOCOL_VERSION、MIN_CLIENT_PROTOCOL_VERSION、 MIN_NODE_PROTOCOL_VERSION、MIN_PROBE_PROTOCOL_VERSION は packages/gateway-protocol/src/version.ts にあります。
• クライアントは minProtocol + maxProtocol を送信します。オペレーターおよび UI クライアントは その範囲に現在のプロトコルを含める必要があります。現在のクライアントとサーバーは プロトコル v4 で動作します。
• role: "node" と client.mode: "node" の両方を持つ認証済みクライアントは、 N-1 ノードプロトコル（現在は v3）を使用できます。軽量な再起動プローブは 同じ N-1 ウィンドウを使用します。デバイス認証、ペアリング、スコープ、コマンドポリシー、exec 承認は、この互換性ウィンドウによって変更されません。Plugin 所有のノード 機能とコマンドは、そのホスト面が N-1 コントラクトの一部ではないため、ノードが現在の プロトコルへアップグレードされるまで保留されます。
• スキーマとモデルは TypeBox 定義から生成されます:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

クライアント定数

​

認証

• 共有シークレットの Gateway 認証は、設定された gateway.auth.mode ("none" | "token" | "password" | "trusted-proxy") に応じて、 connect.params.auth.token または connect.params.auth.password を使用します。
• Tailscale Serve (gateway.auth.allowTailscale: true) や 非ループバックの gateway.auth.mode: "trusted-proxy" などの ID 付きモードは、 connect.params.auth.* ではなくリクエストヘッダーから connect 認証チェックを満たします。
• プライベートイングレスの gateway.auth.mode: "none" は、共有シークレットの connect 認証を 完全にスキップします。そのモードを公開/信頼されていないイングレスで公開しないでください。
• ペアリング後、Gateway は接続ロール + スコープに限定されたデバイストークンを発行し、 hello-ok.auth.deviceToken で返します。クライアントは connect が成功したら必ずこれを永続化する必要があります。
• 保存済みのそのデバイストークンで再接続する場合は、そのトークンに対して保存済みの 承認済みスコープセットも再利用する必要があります。これにより、すでに付与された 読み取り/プローブ/ステータスアクセスが維持され、再接続が暗黙の管理者専用スコープへ 黙って狭められることを避けられます。
• クライアント側の connect 認証組み立て（ packages/gateway-client/src/client.ts の selectConnectAuth）:
  • auth.password は直交しており、設定されている場合は常に転送されます。
  • auth.token は優先順位に従って設定されます。まず明示的な共有トークン、 次に明示的な deviceToken、最後に保存済みのデバイス別トークン（ deviceId + role でキー付け）です。
  • auth.bootstrapToken は、上記のどれも auth.token を解決しなかった場合にのみ送信されます。共有トークンまたは解決済みのデバイストークンがあれば これを抑制します。
  • 1 回限りの AUTH_TOKEN_MISMATCH リトライで保存済みデバイストークンを自動昇格する処理は、 信頼済みエンドポイントのみに制限されます。つまりループバック、 または固定された tlsFingerprint を持つ wss:// です。固定なしの公開 wss:// は 条件を満たしません。
• 組み込みのセットアップコードブートストラップは、主要ノードの hello-ok.auth.deviceToken に加えて、信頼済みモバイル引き渡し用の限定オペレータートークンを hello-ok.auth.deviceTokens で返します。オペレータートークンには ネイティブ Talk 設定読み取り用の operator.talk.secrets が含まれますが、 ペアリング変更スコープと operator.admin は除外されます。
• 非ベースラインのセットアップコードブートストラップが承認待ちの間、 PAIRING_REQUIRED 詳細には recommendedNextStep: "wait_then_retry"、 retryable: true、pauseReconnect: false が含まれます。リクエストが承認されるか トークンが無効になるまで、同じブートストラップトークンで再接続を続けてください。
• hello-ok.auth.deviceTokens は、connect が wss:// やループバック/local ペアリングなどの 信頼済みトランスポート上でブートストラップ認証を使用した場合にのみ永続化してください。
• クライアントが明示的な deviceToken または明示的な scopes を提供した場合、 その呼び出し元が要求したスコープセットが引き続き権威になります。キャッシュされたスコープは、 クライアントが保存済みのデバイス別トークンを再利用している場合にのみ再利用されます。
• デバイストークンは device.token.rotate と device.token.revoke でローテーション/失効できます（operator.pairing が必要）。ノードまたはその他の 非オペレーターロールのローテーションまたは失効には、operator.admin も必要です。
• device.token.rotate はローテーションメタデータを返します。同じデバイストークンで すでに認証済みの同一デバイス呼び出しにのみ、置換用 bearer トークンをエコーします。これにより、 トークンのみのクライアントは再接続前に置換トークンを永続化できます。共有/管理者ローテーションは bearer トークンをエコーしません。
• トークンの発行、ローテーション、失効は、そのデバイスのペアリングエントリに記録された 承認済みロールセットに限定されます。トークン変更は、ペアリング承認が付与していない デバイスロールを拡張したり対象にしたりできません。
• ペアリング済みデバイストークンセッションでは、呼び出し元が operator.admin も持たない限り、 デバイス管理は自身のスコープに限定されます。非管理者の呼び出し元が管理できるのは、 自分自身のデバイスエントリのオペレータートークンのみです。ノードおよびその他の非オペレータートークン管理は、 呼び出し元自身のデバイスであっても管理者専用です。
• device.token.rotate と device.token.revoke は、対象の オペレータートークンスコープセットも、呼び出し元の現在のセッションスコープに照らしてチェックします。 非管理者の呼び出し元は、自分がすでに保持している範囲より広いオペレータートークンを ローテーションまたは失効できません。
• 認証失敗には error.details.code と復旧ヒントが含まれます:
  • error.details.canRetryWithDeviceToken（boolean）
  • error.details.recommendedNextStep: retry_with_device_token、 update_auth_configuration、update_auth_credentials、 wait_then_retry、review_auth_configuration のいずれか （packages/gateway-protocol/src/connect-error-details.ts）。
• AUTH_TOKEN_MISMATCH に対するクライアント動作:
  • 信頼済みクライアントは、キャッシュされたデバイス別 トークンで 1 回の限定リトライを試行できます。
  • そのリトライが失敗した場合、自動再接続ループを停止し、オペレーター向けの 対処ガイダンスを表示します。
• AUTH_SCOPE_MISMATCH は、デバイストークンは認識されたが、要求されたロール/スコープを カバーしていないことを意味します。これを不正なトークンとして提示しないでください。オペレーターに 再ペアリングするか、より狭い/広いスコープコントラクトを承認するよう促してください。

​

デバイス ID とペアリング

• ノードは、キーペアフィンガープリントから派生した安定したデバイス ID（device.id）を 含める必要があります。
• Gateway はデバイス + ロールごとにトークンを発行します。
• local 自動承認が有効でない限り、新しいデバイス ID にはペアリング承認が必要です。
• ペアリング自動承認は、直接の local loopback connect を中心にしています。
• OpenClaw には、信頼済み共有シークレットヘルパーフロー向けの狭いバックエンド/コンテナローカル 自己接続パスもあります。
• 同一ホストの tailnet または LAN connect も、ペアリングでは引き続きリモートとして扱われ、 承認が必要です。
• WS クライアントは通常、connect 時に device ID を含めます（オペレーター + ノード）。デバイスなしのオペレーター例外は、明示的な信頼パスのみです:
  • localhost 専用の安全でない HTTP 互換性のための gateway.controlUi.allowInsecureAuth=true。
  • 成功した gateway.auth.mode: "trusted-proxy" オペレーター Control UI 認証。
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true（緊急回避、重大な セキュリティ低下）。
  • 予約済み内部ヘルパーパス上の direct-loopback gateway-client バックエンド RPC。
• デバイス ID を省略するとスコープに影響します。デバイスなしの オペレーター接続が明示的な信頼パスを通じて許可された場合でも、OpenClaw は そのパスに名前付きのスコープ保持例外がない限り、自己宣言スコープを空セットにクリアします。 その後、スコープで保護されたメソッドは missing scope で失敗します。
• gateway.controlUi.dangerouslyDisableDeviceAuth=true は、Control UI の 緊急回避スコープ保持パスです。任意のカスタムバックエンドまたは CLI 形状の WebSocket クライアントに スコープを付与するものではありません。
• 予約済みの direct-loopback gateway-client バックエンドヘルパーパスは、 内部 local コントロールプレーン RPC にのみスコープを保持します。カスタムバックエンド ID は この例外を受けません。
• すべての接続は、サーバー提供の connect.challenge nonce に署名する必要があります。

​

デバイス認証移行診断

• 常に connect.challenge を待つ。
• サーバー nonce を含む v2 ペイロードに署名する。
• 同じ nonce を connect.params.device.nonce で送信する。
• 推奨される署名ペイロードは v3 （packages/gateway-client/src/device-auth.ts の buildDeviceAuthPayloadV3）で、 device/client/role/scopes/token/nonce フィールドに加えて platform と deviceFamily をバインドする。
• レガシー v2 署名は互換性のため引き続き受け入れられるが、ペアリング済みデバイスの メタデータピン留めは再接続時のコマンドポリシーを引き続き制御する。

​

TLS とピン留め

• WS 接続では TLS がサポートされる（gateway.tls 設定）。
• クライアントは任意で、gateway.remote.tlsFingerprint または CLI --tls-fingerprint によって Gateway 証明書フィンガープリントをピン留めできる。

​

範囲

​

関連

• ブリッジプロトコル
• Gateway ランブック