Gateway プロトコル

Gateway WS プロトコルは、OpenClaw の単一のコントロールプレーン + ノードトランスポートです。すべてのクライアント（CLI、Web UI、macOS アプリ、iOS/Android ノード、ヘッドレスノード）は WebSocket で接続し、ハンドシェイク時に自身のロール + スコープを宣言します。

# トランスポート

• WebSocket、JSON ペイロードを含むテキストフレーム。
• 最初のフレームは必ず connect リクエストである必要があります。
• 接続前フレームは 64 KiB に制限されます。ハンドシェイクが成功した後、クライアントは hello-ok.policy.maxPayload と hello-ok.policy.maxBufferedBytes の制限に従う必要があります。診断が有効な場合、サイズ超過の受信フレームと遅い送信バッファは、gateway が閉じるか対象フレームを破棄する前に payload.large イベントを送出します。これらのイベントは、サイズ、制限、サーフェス、安全な理由コードを保持します。メッセージ本文、添付ファイルの内容、生フレーム本文、トークン、Cookie、秘密値は保持しません。

# ハンドシェイク（connect）

Gateway → クライアント（接続前チャレンジ）:

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

クライアント → Gateway:

{
  "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": "…"
    }
  }
}

Gateway → クライアント:

{
  "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
    }
  }
}

Gateway がまだ起動時サイドカーの完了処理中の場合、connect リクエストは details.reason が "startup-sidecars" に設定され、retryAfterMs を含む、再試行可能な UNAVAILABLE エラーを返すことがあります。クライアントはこれを終端的なハンドシェイク失敗として表示するのではなく、自身の全体的な接続予算内で再試行する必要があります。

server、features、snapshot、policy はすべてスキーマ（src/gateway/protocol/schema/frames.ts）で必須です。auth も必須で、ネゴシエートされたロール/スコープを報告します。pluginSurfaceUrls は任意で、canvas などの plugin サーフェス名を、スコープ付きのホスト URL にマッピングします。

スコープ付き Plugin サーフェス URL は期限切れになることがあります。ノードは node.pluginSurface.refresh を { "surface": "canvas" } とともに呼び出し、pluginSurfaceUrls の新しいエントリを受け取れます。実験的な Canvas Plugin リファクタリングは、非推奨の canvasHostUrl、canvasCapability、または node.canvas.capability.refresh 互換パスをサポートしません。現在のネイティブクライアントと gateways は Plugin サーフェスを使用する必要があります。

デバイストークンが発行されない場合、hello-ok.auth はトークンフィールドなしで、ネゴシエートされた権限を報告します。

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

信頼された同一プロセスのバックエンドクライアント（client.id: "gateway-client"、client.mode: "backend"）は、共有 gateway トークン/パスワードで認証する直接ループバック接続では device を省略できます。このパスは内部コントロールプレーン RPC 用に予約されており、古い CLI/デバイスペアリングのベースラインが、サブエージェントセッション更新などのローカルバックエンド作業を妨げないようにします。リモートクライアント、ブラウザ由来クライアント、ノードクライアント、明示的なデバイストークン/デバイス ID クライアントは、引き続き通常のペアリングとスコープアップグレードチェックを使用します。

デバイストークンが発行される場合、hello-ok には次も含まれます。

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

信頼されたブートストラップのハンドオフ中、hello-ok.auth には deviceTokens 内に追加の境界付きロールエントリが含まれることもあります。

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

組み込みのノード/operator ブートストラップフローでは、プライマリノードトークンは scopes: [] のままで、ハンドオフされた operator トークンはブートストラップ operator の許可リスト（operator.approvals、operator.read、operator.talk.secrets、operator.write）に制限されたままです。ブートストラップスコープチェックはロール接頭辞付きのままです。operator エントリは operator リクエストだけを満たし、operator 以外のロールには引き続き自身のロール接頭辞配下のスコープが必要です。

# ノード例

{
  "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": "…"
    }
  }
}

# フレーミング

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

副作用を持つメソッドには冪等性キーが必要です（スキーマを参照）。

# ロール + スコープ

operator スコープモデル全体、承認時チェック、共有シークレットのセマンティクスについては、operator スコープを参照してください。

# ロール

• operator = コントロールプレーンクライアント（CLI/UI/自動化）。
• node = ケイパビリティホスト（camera/screen/canvas/system.run）。

# スコープ（operator）

一般的なスコープ:

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

includeSecrets: true を伴う talk.config には operator.talk.secrets（または operator.admin）が必要です。

Plugin 登録の gateway RPC メソッドは独自の operator スコープを要求できますが、予約済みのコア管理接頭辞（config.*、exec.approvals.*、wizard.*、update.*）は常に operator.admin に解決されます。

メソッドスコープは最初のゲートにすぎません。chat.send を通じて到達する一部のスラッシュコマンドは、その上により厳格なコマンドレベルチェックを適用します。たとえば、永続的な /config set と /config unset の書き込みには operator.admin が必要です。

node.pair.approve には、基本メソッドスコープに加えて、承認時の追加スコープチェックもあります。

• コマンドなしリクエスト: operator.pairing
• 非 exec ノードコマンドを含むリクエスト: operator.pairing + operator.write
• system.run、system.run.prepare、または system.which を含むリクエスト: operator.pairing + operator.admin

# ケイパビリティ/コマンド/権限（ノード）

ノードは接続時にケイパビリティ要求を宣言します。

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

Gateway はこれらを要求として扱い、サーバー側の許可リストを強制します。

# プレゼンス

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

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

ノードは event: "node.presence.alive" とともに node.event を呼び出し、ペアリング済みノードが接続済みとしてマークされることなく、バックグラウンドウェイク中に 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\"}"
}

trigger は閉じた列挙型です: background、silent_push、bg_app_refresh、significant_location、manual、または connect。未知の trigger 文字列は、永続化の前に gateway によって background に正規化されます。このイベントは、認証済みノードデバイスセッションに対してのみ永続的です。デバイスなし、または未ペアリングのセッションは handled: false を返します。

成功した gateways は構造化された結果を返します。

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

古い gateways は node.event に対して { "ok": true } を返す場合があります。クライアントはこれを永続的なプレゼンス永続化ではなく、確認済み RPC として扱う必要があります。

# ブロードキャストイベントのスコープ制御

サーバーからプッシュされる WebSocket ブロードキャストイベントはスコープでゲートされるため、ペアリングスコープのみ、またはノード専用のセッションがセッション内容を受動的に受信することはありません。

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

各クライアント接続は自身のクライアントごとのシーケンス番号を保持するため、異なるクライアントがイベントストリームのスコープフィルター済みサブセットを見ている場合でも、ブロードキャストはそのソケット上で単調な順序を維持します。

# 一般的な RPC メソッドファミリー

公開 WS サーフェスは、上記のハンドシェイク/認証例よりも広範です。これは生成されたダンプではありません。hello-ok.features.methods は、src/gateway/server-methods-list.ts に加え、ロード済みの Plugin/channel メソッドエクスポートから構築される保守的な検出リストです。これは機能検出として扱い、src/gateway/server-methods/*.ts の完全な列挙として扱わないでください。

# 一般的なイベントファミリー

• chat: chat.inject などの UI チャット更新、およびその他のトランスクリプト専用チャットイベント。
• session.message と session.tool: サブスクライブ済みセッションのトランスクリプト/イベントストリーム更新。
• sessions.changed: セッションインデックスまたはメタデータが変更されました。
• presence: システムプレゼンススナップショットの更新。
• tick: 定期的な keepalive / liveness イベント。
• health: Gateway ヘルススナップショットの更新。
• heartbeat: Heartbeat イベントストリームの更新。
• cron: Cron 実行/ジョブ変更イベント。
• shutdown: Gateway シャットダウン通知。
• node.pair.requested / node.pair.resolved: ノードペアリングのライフサイクル。
• node.invoke.request: ノード呼び出しリクエストのブロードキャスト。
• device.pair.requested / device.pair.resolved: ペアリング済みデバイスのライフサイクル。
• voicewake.changed: ウェイクワードトリガー設定が変更されました。
• exec.approval.requested / exec.approval.resolved: exec 承認のライフサイクル。
• plugin.approval.requested / plugin.approval.resolved: plugin 承認のライフサイクル。

# ノードヘルパーメソッド

• ノードは skills.bins を呼び出して、自動許可チェック用の現在のスキル実行可能ファイル一覧を取得できます。

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

• オペレーターは 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、チャンネルツールを含め、アクティブな会話が現在使用できるものを反映します。
• オペレーターは tools.invoke（operator.write）を呼び出して、/tools/invoke と同じ Gateway ポリシーパスを介して、利用可能なツールを 1 つ呼び出せます。
  • name は必須です。args、sessionKey、agentId、confirm、idempotencyKey は任意です。
  • sessionKey と agentId の両方が存在する場合、解決されたセッションエージェントは agentId と一致する必要があります。
  • レスポンスは SDK 向けエンベロープで、ok、toolName、任意の output、型付きの error フィールドを含みます。承認またはポリシー拒否は、Gateway ツールポリシーパイプラインを迂回するのではなく、ペイロード内で ok:false を返します。
• オペレーターは skills.status（operator.read）を呼び出して、エージェントに表示されるスキルインベントリを取得できます。
  • agentId は任意です。デフォルトのエージェントワークスペースを読み取るには省略します。
  • レスポンスには、適格性、不足している要件、設定チェック、生のシークレット値を公開しないサニタイズ済みインストールオプションが含まれます。
• オペレーターは skills.search と skills.detail（operator.read）を呼び出して、ClawHub 検出メタデータを取得できます。
• オペレーターは skills.install（operator.admin）を 2 つのモードで呼び出せます。
  • ClawHub モード: { source: "clawhub", slug, version?, force? } は、デフォルトのエージェントワークスペースの skills/ ディレクトリにスキルフォルダーをインストールします。
  • Gateway インストーラーモード: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } は、Gateway ホスト上で宣言済みの metadata.openclaw.install アクションを実行します。
• オペレーターは skills.update（operator.admin）を 2 つのモードで呼び出せます。
  • ClawHub モードは、デフォルトのエージェントワークスペース内の、追跡中の slug 1 つまたは追跡中のすべての ClawHub インストールを更新します。
  • Config モードは、enabled、apiKey、env などの skills.entries.<skillKey> 値にパッチを適用します。

# models.list ビュー

models.list は任意の view パラメーターを受け入れます。

• 省略または "default": 現在のランタイム動作です。agents.defaults.models が設定されている場合、レスポンスは許可済みカタログになります。そうでない場合、レスポンスは完全な Gateway カタログになります。
• "configured": ピッカー向けサイズの動作です。agents.defaults.models が設定されている場合は引き続き優先されます。そうでない場合、レスポンスは明示的な models.providers.*.models エントリを使用し、設定済みモデル行が存在しない場合にのみ完全なカタログにフォールバックします。
• "all": 完全な Gateway カタログで、agents.defaults.models をバイパスします。通常のモデルピッカーではなく、診断と検出 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 コンテキストとして再利用します。
• 呼び出し元が準備から最終承認済み system.run 転送までの間に command、rawCommand、cwd、agentId、または sessionKey を変更した場合、Gateway は変更されたペイロードを信頼せず、その実行を拒否します。

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

• agent リクエストには、アウトバウンド配信を要求するために deliver=true を含めることができます。
• bestEffortDeliver=false は厳格な動作を維持します。解決できない配信ターゲットまたは内部専用配信ターゲットは INVALID_REQUEST を返します。
• bestEffortDeliver=true は、外部配信可能ルートを解決できない場合（例: 内部/webchat セッションや曖昧なマルチチャンネル設定）に、セッション専用実行へのフォールバックを許可します。

# バージョニング

• PROTOCOL_VERSION は src/gateway/protocol/version.ts にあります。
• クライアントは minProtocol + maxProtocol を送信します。サーバーは不一致を拒否します。
• スキーマ + モデルは TypeBox 定義から生成されます。
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

# クライアント定数

src/gateway/client.ts のリファレンスクライアントは、これらのデフォルトを使用します。値はプロトコル v4 全体で安定しており、サードパーティクライアントの想定ベースラインです。

定数	デフォルト	ソース
PROTOCOL_VERSION	4	src/gateway/protocol/version.ts
リクエストタイムアウト（RPC ごと）	30_000 ms	src/gateway/client.ts (requestTimeoutMs)
事前認証 / 接続チャレンジタイムアウト	15_000 ms	src/gateway/handshake-timeouts.ts（config/env でペアリング済みサーバー/クライアントの予算を引き上げ可能）
初期再接続バックオフ	1_000 ms	src/gateway/client.ts (backoffMs)
最大再接続バックオフ	30_000 ms	src/gateway/client.ts (scheduleReconnect)
デバイストークンクローズ後の高速リトライクランプ	250 ms	src/gateway/client.ts
terminate() 前の強制停止猶予	250 ms	FORCE_STOP_TERMINATE_GRACE_MS
stopAndWait() のデフォルトタイムアウト	1_000 ms	STOP_AND_WAIT_TIMEOUT_MS
デフォルト tick 間隔（hello-ok 前）	30_000 ms	src/gateway/client.ts
tick タイムアウトクローズ	無音が tickIntervalMs * 2 を超えた場合の code 4000	src/gateway/client.ts
MAX_PAYLOAD_BYTES	25 * 1024 * 1024 (25 MB)	src/gateway/server-constants.ts

サーバーは有効な policy.tickIntervalMs、policy.maxPayload、policy.maxBufferedBytes を hello-ok で広告します。クライアントはハンドシェイク前のデフォルトではなく、これらの値に従う必要があります。

# 認証

• 共有シークレットの Gateway 認証は、設定された認証モードに応じて 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 で返され、今後の接続のためにクライアントが 永続化する必要があります。
• クライアントは、成功した接続の後にプライマリ hello-ok.auth.deviceToken を永続化する必要があります。
• その 保存済み デバイストークンで再接続する場合、そのトークンに対して保存済みの 承認済みスコープセットも再利用する必要があります。これにより、すでに許可された 読み取り/プローブ/ステータスアクセスが保持され、再接続が暗黙の管理者専用スコープへ 黙って狭められることを避けられます。
• クライアント側の connect 認証組み立て (selectConnectAuth in src/gateway/client.ts):
  • auth.password は直交しており、設定されている場合は常に転送されます。
  • auth.token は優先順位に従って設定されます。明示的な共有トークンが最優先で、 次に明示的な deviceToken、その次に保存済みのデバイス単位トークン (deviceId + role をキーにしたもの) です。
  • auth.bootstrapToken は、上記のいずれも auth.token を解決しなかった場合にのみ 送信されます。共有トークン、または解決された任意のデバイストークンがある場合は抑制されます。
  • 1 回限りの AUTH_TOKEN_MISMATCH リトライで保存済みデバイストークンを自動昇格する処理は、 信頼済みエンドポイントのみ に制限されます。つまり、ループバック、または ピン留めされた tlsFingerprint を持つ wss:// です。ピン留めのない公開 wss:// は該当しません。
• 追加の hello-ok.auth.deviceTokens エントリは、ブートストラップ引き渡しトークンです。 wss:// やループバック/local ペアリングなど、信頼済みトランスポート上でブートストラップ認証を 使用して接続した場合にのみ永続化してください。
• クライアントが 明示的な deviceToken または明示的な scopes を指定した場合、 その呼び出し元が要求したスコープセットが引き続き authoritative です。キャッシュされたスコープは、 クライアントが保存済みのデバイス単位トークンを再利用している場合にのみ再利用されます。
• デバイストークンは device.token.rotate と device.token.revoke (operator.pairing スコープが必要) でローテーション/失効できます。
• device.token.rotate はローテーションメタデータを返します。同じデバイストークンですでに認証されている 同一デバイスからの呼び出しの場合にのみ、置換用ベアラートークンをエコーします。これにより、 トークンのみのクライアントは再接続前に置換トークンを永続化できます。共有/管理者ローテーションでは ベアラートークンはエコーされません。
• トークンの発行、ローテーション、失効は、そのデバイスのペアリングエントリに記録された 承認済みロールセットの範囲内に保たれます。トークン変更によって、ペアリング承認で付与されていない デバイスロールへ拡張したり、それを対象にしたりすることはできません。
• ペアリング済みデバイストークンセッションでは、呼び出し元が operator.admin も持っていない限り、 デバイス管理は自己スコープに限定されます。非管理者の呼び出し元は、自分自身の デバイスエントリだけを 削除/失効/ローテーションできます。
• device.token.rotate と device.token.revoke は、対象 operator トークンのスコープセットも、 呼び出し元の現在のセッションスコープと照合します。非管理者の呼び出し元は、自分がすでに保持しているものより 広い operator トークンをローテーションまたは失効できません。
• 認証失敗には 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)
• AUTH_TOKEN_MISMATCH に対するクライアント動作:
  • 信頼済みクライアントは、キャッシュされたデバイス単位トークンで 1 回だけ制限付きリトライを試みることができます。
  • そのリトライが失敗した場合、クライアントは自動再接続ループを停止し、operator の対応ガイダンスを表示する必要があります。

# デバイス ID + ペアリング

• ノードは、鍵ペアのフィンガープリントから導出された安定したデバイス ID (device.id) を含める必要があります。
• Gateway はデバイス + ロールごとにトークンを発行します。
• ローカル自動承認が有効でない限り、新しいデバイス ID にはペアリング承認が必要です。
• ペアリングの自動承認は、直接の local loopback 接続を中心とします。
• OpenClaw には、信頼済み共有シークレットのヘルパーフロー向けに、狭いバックエンド/コンテナローカルの自己接続パスもあります。
• 同一ホストの tailnet または LAN 接続も、ペアリングでは引き続きリモートとして扱われ、 承認が必要です。
• WS クライアントは通常、connect 中に device ID を含めます (operator + ノード)。デバイスなしの operator 例外は、明示的な信頼パスのみです。
  • localhost 専用の安全でない HTTP 互換性のための gateway.controlUi.allowInsecureAuth=true。
  • 成功した gateway.auth.mode: "trusted-proxy" operator Control UI 認証。
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (緊急時用、重大なセキュリティ低下)。
  • 共有 Gateway トークン/パスワードで認証された、direct-loopback の gateway-client バックエンド RPC。
• すべての接続は、サーバーが提供した connect.challenge nonce に署名する必要があります。

# デバイス認証移行診断

チャレンジ前署名の挙動をまだ使用しているレガシークライアント向けに、connect は現在、 安定した error.details.reason とともに、error.details.code の下で DEVICE_AUTH_* 詳細コードを返します。

一般的な移行失敗:

メッセージ	details.code	details.reason	意味
device nonce required	DEVICE_AUTH_NONCE_REQUIRED	device-nonce-missing	クライアントが device.nonce を省略しました (または空で送信しました)。
device nonce mismatch	DEVICE_AUTH_NONCE_MISMATCH	device-nonce-mismatch	クライアントが古い/誤った nonce で署名しました。
device signature invalid	DEVICE_AUTH_SIGNATURE_INVALID	device-signature	署名ペイロードが v2 ペイロードと一致しません。
device signature expired	DEVICE_AUTH_SIGNATURE_EXPIRED	device-signature-stale	署名済みタイムスタンプが許可されたずれの範囲外です。
device identity mismatch	DEVICE_AUTH_DEVICE_ID_MISMATCH	device-id-mismatch	device.id が公開鍵フィンガープリントと一致しません。
device public key invalid	DEVICE_AUTH_PUBLIC_KEY_INVALID	device-public-key	公開鍵の形式/正規化に失敗しました。

移行先:

• 常に connect.challenge を待ちます。
• サーバー nonce を含む v2 ペイロードに署名します。
• 同じ nonce を connect.params.device.nonce で送信します。
• 推奨される署名ペイロードは v3 です。これは、デバイス/クライアント/ロール/スコープ/トークン/nonce フィールドに加えて、 platform と deviceFamily をバインドします。
• 互換性のためレガシー v2 署名は引き続き受け入れられますが、ペアリング済みデバイスの メタデータピン留めが、再接続時のコマンドポリシーを引き続き制御します。

# TLS + ピン留め

• TLS は WS 接続でサポートされています。
• クライアントは任意で Gateway 証明書フィンガープリントをピン留めできます (gateway.tls 設定に加えて gateway.remote.tlsFingerprint または CLI --tls-fingerprint を参照)。

# スコープ

このプロトコルは 完全な Gateway API (ステータス、チャネル、モデル、チャット、 エージェント、セッション、ノード、承認など) を公開します。正確な対象範囲は src/gateway/protocol/schema.ts の TypeBox スキーマで定義されています。

# 関連

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