Gateway プロトコル

​

npm パッケージ

• @openclaw/gateway-protocol は、スキーマ、バリデーター、TypeScript 型、軽量なフレームおよびエラー ヘルパー、バージョン定数を公開します。その tarball には、生成された機械可読な protocol.schema.json コントラクトが含まれます。
• @openclaw/gateway-client は、リファレンス Node クライアントと、@openclaw/gateway-client/browser にある ブラウザーセーフなエントリを公開します。

​

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

• 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?}

• 不足スコープ：{ code: "MISSING_SCOPE", missingScope, requiredScopes }。 requiredScopes は、要求された操作について既知のスコープをすべて含む完全なセットです。 従来の missing scope: <scope> メッセージは古いクライアント向けに維持されています。

​

ハンドシェイク

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

​

ワーカーロールと閉じたプロトコル

​

クライアント機能

• tool-events：構造化されたツールライフサイクルイベントを受け入れます。
• inline-widgets：ホストされたインラインウィジェットのツール結果をレンダリングできます。

​

Node 接続の例

{
  "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：呼び出し用のコマンド許可リスト。
• permissions：細粒度の切り替え（例：screen.record、camera.capture）。

​

ロールとスコープ

• operator：コントロールプレーンクライアント（CLI/UI/自動化）。
• node：機能ホスト（camera/screen/canvas/system.run）。
• worker：専用の閉じたワーカープロトコル上のクラウド実行ホスト。

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

​

機能／コマンド／権限（Node）

• caps: camera、canvas、screen、 location、voice、talk などの上位レベルの機能カテゴリ。
• commands: 呼び出し用のコマンド許可リスト。
• permissions: 詳細な切り替え（例: screen.record、camera.capture）。

​

プレゼンス

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

​

Node のバックグラウンド生存イベント

{
  "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、接続／切断ライフサイクル）は制限されないため、認証済みのすべてのセッションからトランスポートの健全性を監視できます。
• 未知のブロードキャストイベントファミリーは、登録済みのハンドラーが明示的に制限を緩和しない限り、デフォルトでスコープによって制限されます（フェイルクローズ）。

​

RPC メソッドファミリー

​

共通イベントファミリー

• chat：chat.inject などの UI チャット更新、およびトランスクリプトのみに関係するその他のチャット イベント。プロトコル v4 では、差分ペイロードに deltaText が含まれます。message は引き続き、 アシスタントの累積スナップショットです。接頭辞ではない置換では replace=true が設定され、置換テキストとして deltaText が使用されます。
• session.message、session.operation、session.tool：購読中のセッションに関するトランスクリプト、実行中の セッション操作、およびイベントストリームの更新。
• session.approval：明示的にオプトインした完全一致セッション購読者向けの、サニタイズ済みの保留中および終了済み承認の正確な状態。 子承認は永続化された祖先のオーディエンスを使用します。イベントがトランスクリプトを変更したり、エージェントをウェイクしたりすることはありません。
• 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：ウェイクワードトリガー設定が変更されました。
• config.changed：設定の書き込みが永続化されました（ペイロードには設定パス、 新しいスナップショットハッシュ、およびタイムスタンプが含まれます。設定内容は決して含まれません）。オペレーター読み取り スコープです。クライアントは config.get を介して更新します。
• exec.approval.requested / exec.approval.resolved：exec 承認の ライフサイクル。
• plugin.approval.requested / plugin.approval.resolved：Plugin 承認の ライフサイクル。

​

Node ヘルパーメソッド

​

監査台帳 RPC

• パラメーター：オプションの完全一致 agentId、sessionKey、または runId。オプションの kind （"agent_run"、"tool_action"、または "message"）。オプションの status （"started"、"succeeded"、"failed"、"cancelled"、"timed_out"、 "blocked"、または "unknown"）。オプションのメッセージ direction（"inbound" または "outbound"）と完全一致 channel。オプションの包含的な after / before Unix ミリ秒境界。1 から 500 までのオプションの limit。および前のページから取得したオプションの 文字列 cursor。
• 結果：{ "events": AuditActivityEventV1[], "nextCursor"?: string }。

• conversationKind：direct、group、channel、または unknown。
• 受信 outcome：completed、skipped、または failed。オプションの reasonCode：duplicate、reply_operation_active、 reply_operation_aborted、fast_abort、plugin_bound_handled、 plugin_bound_unavailable、plugin_bound_declined、plugin_bound_error、 before_dispatch_handled、acp_dispatch_completed、acp_dispatch_failed、 acp_dispatch_empty、または acp_dispatch_aborted。
• 送信 outcome：sent、suppressed、failed、または unknown。オプションの reasonCode：cancelled_by_message_sending_hook、 cancelled_by_reply_payload_sending_hook、 empty_after_message_sending_hook、empty_after_reply_payload_sending_hook、 または no_visible_payload。プラットフォーム ID を返さないアダプターは unknown です。外部への副作用がなかったことを証明できないためです。
• deliveryKind：text、media、または other。failureStage： platform_send、queue、または unknown。

​

タスク台帳 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 は、呼び出し元が指定した認証または配信コンテキストを受け入れるのではなく、 サーバー側のセッションから信頼済みランタイムコンテキストを導出します。
  • レスポンスは、有効な一覧をセッションスコープでサーバーが導出した投影であり、 コア、Plugin、チャンネル、および検出済みの 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 などの所有者専用コアラッパーでは、 tools.invoke 自体が operator.write であっても、 所有者／管理者のアイデンティティ（operator.admin）が必要です。
  • レスポンスは、ok、toolName、オプションの output、および型付き error フィールドを持つ SDK 向けエンベロープです。承認またはポリシーによる拒否は、 Gateway のツールポリシーパイプラインを迂回せず、ペイロード内で ok:false を返します。
• skills.status（operator.read）は、エージェントに表示される Skills 一覧を 取得します。
  • agentId はオプションです。デフォルトのエージェントワークスペースを読み取るには省略します。
  • レスポンスには、生のシークレット値を公開することなく、適格性、不足している要件、設定チェック、 およびサニタイズされたインストールオプションが含まれます。
• skills.search と skills.detail（operator.read）は、ClawHub の検出メタデータを返します。
• skills.upload.begin、skills.upload.chunk、および skills.upload.commit （operator.admin）は、プライベートな Skills アーカイブをインストール前にステージングします。これは、 信頼済みクライアント用の独立した管理者アップロード経路であり、通常の ClawHub Skills インストールフローではありません。skills.install.allowUploadedArchives が有効でない限り、 デフォルトでは無効です。
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) は、 そのスラッグと force 値にバインドされたアップロードを作成します。
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) は、 正確なデコード済みオフセットにバイトを追加します。
  • skills.upload.commit({ uploadId, sha256? }) は、最終サイズと SHA-256 を検証します。コミットはアップロードを確定するだけで、Skills をインストールしません。
  • アップロードされる Skills アーカイブは、SKILL.md ルートを含む zip アーカイブです。 アーカイブ内部のディレクトリ名がインストール先を選択することはありません。
• skills.install（operator.admin）には 3 つのモードがあります。
  • ClawHub モード: { source: "clawhub", slug, version?, force? } は、 Skills フォルダーをデフォルトのエージェントワークスペースの skills/ ディレクトリにインストールします。
  • アップロードモード: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } は、 コミット済みアップロードをデフォルトのエージェントワークスペースの skills/<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 モードは、デフォルトのエージェントワークスペースにある追跡対象スラッグ 1 件、 または追跡対象のすべての ClawHub インストールを更新します。
  • 設定モードは、enabled、 apiKey、env などの skills.entries.<skillKey> 値にパッチを適用します。

​

models.list ビュー

• 省略または "default": agents.defaults.modelPolicy.allow が設定されている場合、 レスポンスは許可されたカタログとなり、provider/* エントリの 動的に検出されたモデルも含まれます。それ以外の場合、レスポンスは Gateway の 完全なカタログです。
• "configured": ピッカー向けの動作です。agents.defaults.modelPolicy.allow が 設定されている場合は、provider/* エントリのプロバイダースコープ検出を含め、 引き続きそれが優先されます。許可リストがない場合、レスポンスは明示的な models.providers.<provider>.models エントリを使用し、設定済みのモデル行が存在しない場合に限り 完全なカタログへフォールバックします。
• "provider-config": ソースで定義された models.providers.*.models 一覧であり、 ピッカーの許可リストから独立しています。行には公開モデル機能と ルートを考慮した可用性が含まれますが、プロバイダーのエンドポイント、認証情報、および ランタイムリクエスト設定は省略されます。
• "all": agents.defaults.modelPolicy.allow を迂回する Gateway の完全なカタログです。 通常のモデルピッカーではなく、診断／検出 UI に使用します。

​

実行の承認

• 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 を信頼できるコマンド/cwd/セッションコンテキストとして再利用します。
• 呼び出し元が準備から最終的に承認された system.run の転送までの間に、 command、rawCommand、cwd、agentId、または sessionKey を変更した場合、Gateway は変更されたペイロードを信頼せず、実行を拒否します。

​

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

• agent リクエストには、外部への配信を要求するために deliver=true を含めることができます。
• bestEffortDeliver=false（デフォルト）は厳密な動作を維持します。解決できない、または 内部専用の配信先に対しては INVALID_REQUEST を返します。
• bestEffortDeliver=true を指定すると、外部配信可能なルートを解決できない場合（たとえば、内部/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 Node プロトコル（現在は v3）を使用できます。軽量な再起動プローブも 同じ N-1 ウィンドウを使用します。この互換性ウィンドウによって、デバイス認証、ペアリング、スコープ、コマンドポリシー、および exec の承認は変更されません。Plugin が所有する Node の ケイパビリティとコマンドは、それらをホストするサーフェスが N-1 契約に含まれないため、Node が現在の プロトコルへアップグレードするまで提供されません。
• スキーマとモデルは 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" など、アイデンティティを伴うモードでは、connect.params.auth.* の代わりにリクエストヘッダーから 接続認証チェックを満たします。
• プライベートイングレスの gateway.auth.mode: "none" では、共有シークレットによる接続認証を 完全にスキップします。このモードを公開または信頼されていないイングレスに公開しないでください。
• ペアリング後、Gateway は接続のロールとスコープに限定されたデバイストークンを発行し、 hello-ok.auth.deviceToken で返します。クライアントは、接続に成功するたびに それを永続化する必要があります。
• 保存したデバイストークンで再接続する場合は、そのトークンについて保存済みの 承認済みスコープセットも再利用する必要があります。これにより、すでに付与された読み取り、プローブ、ステータスへのアクセスが 維持され、再接続時に暗黙の管理者専用スコープへ気付かないまま狭められることを 防止できます。
• クライアント側の接続認証の組み立て（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:// は 対象になりません。
• 組み込みのセットアップコードによるブートストラップは、信頼済みモバイルへの引き渡し用に、 プライマリ Node の 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 を永続化するのは、接続が wss:// やループバック／ローカルペアリングなどの 信頼済みトランスポート上でブートストラップ認証を使用した場合に限ります。
• クライアントが明示的な deviceToken または明示的な scopes を指定した場合、 呼び出し元が要求したそのスコープセットが引き続き優先されます。キャッシュ済みスコープが 再利用されるのは、クライアントが保存済みのデバイスごとのトークンを再利用する場合のみです。
• デバイストークンは、device.token.rotate および device.token.revoke（operator.pairing が必要）を使用してローテーションまたは失効できます。 Node またはその他の非オペレーターロールをローテーションまたは失効する場合は、operator.admin も必要です。
• device.token.rotate はローテーションのメタデータを返します。置換後の Bearer トークンを返すのは、そのデバイストークンですでに認証されている 同一デバイスからの呼び出しの場合のみです。これにより、トークンのみを使用するクライアントは、再接続前に置換トークンを永続化できます。 共有／管理者によるローテーションでは、Bearer トークンは返されません。
• トークンの発行、ローテーション、失効は、そのデバイスのペアリングエントリに記録された 承認済みロールセットの範囲内に制限されます。トークンの変更によって、ペアリング承認で一度も付与されていない デバイスロールへ拡張したり、そのロールを対象にしたりすることはできません。
• ペアリング済みデバイスのトークンセッションでは、呼び出し元が operator.admin も持っていない限り、デバイス管理は自身に限定されます。管理者以外の呼び出し元が管理できるのは、 自身のデバイスエントリのオペレータートークンのみです。Node およびその他の非オペレータートークンの 管理は、呼び出し元自身のデバイスであっても管理者専用です。
• device.token.rotate と device.token.revoke は、対象の オペレータートークンのスコープセットも、呼び出し元の現在のセッションスコープと照合します。 管理者以外の呼び出し元は、自身がすでに保持しているものより広いオペレータートークンを ローテーションまたは失効できません。
• 認証エラーには、error.details.code と復旧のヒントが含まれます：
  • error.details.canRetryWithDeviceToken（真偽値）
  • 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 は、デバイストークンが認識されたものの、要求された ロール／スコープを満たしていないことを意味します。これを不正なトークンとして表示せず、 再ペアリングするか、より狭い／広いスコープ契約を承認するようオペレーターに促してください。

​

デバイスアイデンティティとペアリング

• Node は、キーペアのフィンガープリントから導出された安定したデバイスアイデンティティ （device.id）を含める必要があります。
• Gateway はデバイスとロールの組み合わせごとにトークンを発行します。
• ローカルでの自動承認が有効でない限り、新しいデバイス ID には ペアリングの承認が必要です。
• ペアリングの自動承認は、直接の local loopback 接続を中心に適用されます。
• OpenClaw には、信頼済みの共有シークレットヘルパーフロー向けに、 バックエンド／コンテナローカルで自己接続する限定的な経路もあります。
• 同一ホストの tailnet または LAN 接続もペアリング上はリモートとして扱われ、 承認が必要です。
• WS クライアントは通常、connect の際に device アイデンティティを含めます （オペレーター + Node）。デバイスなしのオペレーターに対する唯一の例外は、次の明示的な信頼経路です：
  • gateway.auth.mode: "trusted-proxy" によるオペレーター向け Control UI 認証の成功。
  • 予約済みの内部ヘルパー経路での、直接ループバック gateway-client バックエンド RPC。
• デバイスアイデンティティを省略すると、スコープに影響します。デバイスなしの オペレーター接続が明示的な信頼経路によって許可されている場合でも、その経路に 名前付きのスコープ保持例外がない限り、OpenClaw は自己申告されたスコープを空のセットに クリアします。その後、スコープで制限されたメソッドは missing scope で失敗します。
• 予約済みの直接ループバック gateway-client バックエンドヘルパー経路が スコープを保持するのは、内部のローカルコントロールプレーン RPC に限られます。カスタムバックエンド ID には この例外は適用されません。
• すべての接続は、サーバーから提供された connect.challenge nonce に署名する必要があります。

​

デバイス認証移行の診断

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

​

TLS とピン留め

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

​

スコープ

​

関連項目

• Gateway クライアントの構築
• OpenClaw の埋め込み
• ブリッジプロトコル
• Gateway ランブック