Gateway プロトコル

Gateway WS プロトコルは、OpenClaw の単一のコントロールプレーン兼 Node トランスポートです。 オペレーターおよび Node クライアント（CLI、Web UI、macOS アプリ、iOS/Android Node、 ヘッドレス Node）は WebSocket 経由で接続し、ハンドシェイク時に ロール と スコープ を 宣言します。

npm パッケージ

これらのパッケージは OpenClaw のリリース系列に含まれます。初期ロールアウト中は、 パッケージを含む最初のリリースが公開されるまで、npm が E404 を返す場合があります。

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

アプリケーションのライフサイクルに関するガイダンスについては、 Gateway クライアントの構築を参照してください。Gateway を 子プロセスとして監視するアプリについては、 OpenClaw の埋め込みを参照してください。

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

• 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, message, details?, retryable?, retryAfterMs? } を使用します。 クライアントは code と details.code に基づいて分岐する必要があります。message は人間が読める形式のままであり、 互換性に関する注記で別途規定されている場合を除き、変更される可能性があります。メソッドレベルの 認可エラーでは、構造化された不足スコープの詳細とともに、トップレベルの code: "FORBIDDEN" を使用します。

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

クライアントは最初に details を読み、従来のメッセージは互換性のための フォールバックとしてのみ使用する必要があります。readMissingScopeError と readMissingScopeErrorDetails は @openclaw/gateway-protocol/gateway-error-details からエクスポートされます。ブラウザーセーフな Gateway クライアントは、 これらを @openclaw/gateway-client/browser から再エクスポートします。

スキーマは @openclaw/gateway-protocol/schema から GatewayErrorDetailsSchema、 MissingScopeErrorDetailsSchema としてエクスポートされます。 HTTP スコープエラーでは、error.details の下に MISSING_SCOPE オブジェクトを反映し、 HTTP ステータス 403 を使用します。

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

ハンドシェイク

Gateway は接続前チャレンジを送信します。

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

クライアントは connect で応答します。

{  "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 は hello-ok で応答します。

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

server、features、snapshot、policy、auth はすべて HelloOkSchema（packages/gateway-protocol/src/schema/frames.ts）で必須です。auth は、 デバイストークンが発行されない場合でも、ネゴシエーションされたロールとスコープを報告します（上記の形式）。 pluginSurfaceUrls は省略可能で、Plugin サーフェス名（例： canvas）をスコープ付きのホスト URL にマッピングします。有効期限が切れる場合があるため、 Node は新しいエントリを取得するために { "surface": "canvas" } を指定して node.pluginSurface.refresh を呼び出します。 非推奨の canvasHostUrl / canvasCapability / node.canvas.capability.refresh パスはサポートされていません。Plugin サーフェスを使用してください。 スナップショットの省略可能な appliedConfigHash は、アクティブな Gateway ランタイムが受け入れた、 解決済みのソース設定リビジョンです。クライアントはこれを config.get.configRevisionHash と比較し、より新しく保存された設定で再起動が引き続き 必要かどうかを判断できます。config.get.hash は、設定書き込みの競合ガードで使用される 生のルートファイルリビジョンのままです。

Gateway が起動時のサイドカーの処理をまだ完了していない間、connect は details.reason: "startup-sidecars" と retryAfterMs を伴う、再試行可能な UNAVAILABLE エラーを返す場合があります。これを最終的なハンドシェイク失敗として扱わず、 接続予算内で再試行してください。

デバイストークンが発行されると、hello-ok.auth に追加されます。

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

組み込みの QR/セットアップコードによるブートストラップは、モバイルへの引き継ぎ経路です。 ベースラインのセットアップコード接続に成功すると、プライマリ Node トークンと、範囲が限定された オペレータートークンが 1 つ返されます。

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

このオペレーターへの引き継ぎは意図的に範囲が限定されています。Talk の設定読み取り用の operator.talk.secrets を含め、モバイルオペレーターのループとネイティブセットアップを 開始するには十分ですが、ペアリング変更スコープと operator.admin は含まれません。 より広範なペアリング/管理者アクセスには、別途承認されたペアリングまたはトークンフローが必要です。 ブートストラップ認証が信頼されたトランスポート（wss:// または loopback/ローカルペアリング）を介して実行された場合にのみ、hello-ok.auth.deviceTokens を永続化してください。

信頼された同一プロセスのバックエンドクライアント（client.id: "gateway-client"、 client.mode: "backend"）は、共有 Gateway トークン/パスワードで認証する場合、 直接 loopback 接続で device を省略できます。この経路は 内部コントロールプレーン RPC（例：サブエージェントのセッション更新）専用であり、 古い CLI/デバイスのペアリングベースラインがローカルバックエンド作業を妨げることを回避します。 リモート、ブラウザーオリジン、Node、および明示的なデバイストークン/デバイス ID クライアントは、 引き続き通常のペアリングとスコープアップグレードのチェックを通過します。

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

クラウドワーカーは、Gateway が所有し、ホストキーが固定された SSH トンネルを介して、 専用の loopback イングレスを使用します。このイングレスはワーカー ID のみを受け入れ、 一般認証、Node イベント、オペレーター RPC、Plugin メソッドを決してディスパッチしません。 厳格な connect は、保存時にハッシュ化された、環境、バンドルハッシュ、 所有者エポック、RPC セットバージョン、有効期限、および null 許容の 1 セッションに 紐付けられた短期クレデンシャルを検証します。また、現在のバージョンと機能セットを個別に確認します。 成功時には最小限の worker-hello-ok が返されます。機能ネゴシエーションは、 一般プロトコルのバージョンとは独立しています。フレームは 64 KiB 未満に保たれますが、 ネゴシエーションされた worker.inference.start フレームのみ最大 25 MiB まで許可されます。 閉じた許可リストには worker.heartbeat、worker.transcript.commit、 worker.live-event、worker.inference.start、worker.inference.cancel が含まれます。

トランスクリプトのコミットでは、所有者エポックによるフェンシング、Gateway が所有するセッションバインディング、 ベースリーフの compare-and-swap、永続的なシーケンス再生を使用します。Gateway は通常のセッションライターを介して、 トランスクリプトエントリ ID と親 ID を生成します。所有権と有効期限は RPC ごとに再確認されます。

クライアント機能

オペレータークライアントは、connect.params.caps で省略可能な機能を通知できます。

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

クライアント機能は、認可ではなく、接続されているクライアントについて記述します。エージェントツールは必要な機能を宣言できます。起点となるクライアントの caps にすべての要件が含まれていない場合、Gateway はそれらのツールを除外します。チャネル起点の実行には Gateway クライアント機能がないため、ツールポリシーで明示的に許可されている場合でも、機能によって制限されたツールは利用できません。

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

Node は接続時に機能要求を宣言します。

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

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

ロールとスコープ

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

ロール：

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

オペレータースコープ（src/gateway/operator-scopes.ts）の完全な閉集合：

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

includeSecrets: true を指定した talk.config には、operator.talk.secrets（または operator.admin）が必要です。シークレットが含まれる場合は、アクティブな Talk プロバイダーの クレデンシャルを talk.resolved.config.apiKey から読み取ります。talk.providers.<id>.apiKey は ソースの形式を維持し、SecretRef オブジェクトまたは墨消しされた文字列である場合があります。

Plugin が登録した Gateway RPC メソッドは独自のオペレータースコープを要求できますが、 次の予約済みコアプレフィックスは常に operator.admin （src/shared/gateway-method-policy.ts）に解決されます：config.*、exec.approvals.*、 wizard.*、update.*。

メソッドスコープは最初のゲートにすぎません。chat.send 経由で到達する一部の スラッシュコマンドには、より厳格なコマンドレベルのチェックが適用されます。すでに低位の オペレータースコープを保持している Gateway クライアントであっても、永続的な /config set と /config unset の書き込みには operator.admin が必要です。

node.pair.approve には、基本メソッドスコープ（operator.pairing）に加えて、 保留中のリクエストで宣言された commands（src/infra/node-pairing-authz.ts）に基づく、 承認時の追加スコープチェックがあります。

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

Node は接続時に機能の宣言を行います。

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

Gateway はこれらを宣言として扱い、サーバー側の許可リストを適用します。 接続済みの Node は、接続または再接続が成功した後に、node.pluginTools.update を使用して、任意のエージェント可視 Plugin または MCP ツールの 記述子を公開できます。ヘッドレス Node ホストでは、宣言的な MCP インベントリの 変更を適用するために再起動します。この更新メソッドが唯一の公開経路であり、Plugin ツール記述子は connect パラメーターでは受け付けられません。各記述子は、プロバイダーで安全に使用できるツール name を使用し、Node の現在のコマンド許可リストにある command を指定する必要があります。Gateway はペアリングされた Node からの記述子 メタデータを信頼し、承認済みのコマンド範囲外にある記述子をフィルタリングし、 Node の切断時に削除し、別の Node のカタログを変更しようとする オペレーターの操作を拒否します。Node が公開した記述子を無視するには、gateway.nodes.pluginTools.enabled: false を設定します。

接続済みの Node ホストは、node.skills.update を使用して、完全な Skills 置換カタログを公開します。 この Node ロールのメソッドが Node の Skills を公開する唯一の経路であり、 Skills は connect パラメーターでは受け付けられません。各記述子には、 安全な名前、説明、およびサイズが制限された SKILL.md コンテンツが含まれます。Gateway はその コンテンツを通常の Skills ローダーで解析し、Node の接続中はエージェントの Skills スナップショットに 含め、切断時に削除します。Node が公開した Skills を無視するには、 gateway.nodes.allowSkills: false を設定します。

プレゼンス

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

ネイティブ macOS Node は、入力アイドル時間を制限した、認証済みの node.presence.activity イベントも送信できます。 Gateway は自身のクロックでアクティビティのタイムスタンプを生成し、 node.list と node.describe を通じて、接続中で最も新しい Mac を公開し、 node.presence の更新を読み取りスコープを持つクライアントにブロードキャストします。 ユーザーがアクティビティ共有を無効にすると、アプリは { "action": "clear" } を送信します。 Gateway は、その認証済み Node 接続に完全に一致するタイムスタンプのみを消去します。 この確認済みアクションより前の Gateway は未処理として返すため、Mac Node は一度再接続し、切断時のクリーンアップによって古い接続状態を削除します。 選択、プライバシー、モデルコンテキスト、および通知ルーティングの動作については、 アクティブなコンピューターのプレゼンスを参照してください。

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

Node は、ペアリングされた Node を接続済みとしてマークせずに、バックグラウンド復帰中に 稼働していたことを記録するため、event: "node.presence.alive" を指定して node.event を呼び出します。

{  "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 からなる閉じた列挙型です。不明な値は background（src/shared/node-presence.ts）に正規化されます。このイベントは、 認証済みの Node デバイスセッションに対してのみ永続化されます。デバイスのないセッションまたはペアリングされていないセッションは、 handled: false を返します。

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

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

古い Gateway では、node.event に対して { "ok": true } のみが返される場合があります。これは永続的なプレゼンスの保存ではなく、確認済みの RPC として扱ってください。

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

サーバーからプッシュされるブロードキャストイベントはスコープによって制限されるため、ペアリングスコープまたは Node 専用のセッションがセッション内容を受動的に受信することはありません （src/gateway/server-broadcast.ts）：

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

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

RPC メソッドファミリー

hello-ok.features.methods は、src/gateway/server-methods-list.ts と、読み込まれた Plugin／チャンネルのメソッドエクスポートから構築される控えめな検出リストです。これはすべてのメソッドを生成して列挙したものではなく、一部のメソッド（たとえば push.test、web.login.start、web.login.wait、sessions.usage）は実在して呼び出し可能であっても、意図的に検出対象から除外されています。これは src/gateway/server-methods/*.ts の完全な列挙ではなく、機能検出として扱ってください。

共通イベントファミリー

• 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 ヘルパーメソッド

Node は、自動許可チェック用の Skills 実行可能ファイルの現在の一覧を取得するために、skills.bins を呼び出せます。

監査台帳 RPC

audit.activity.list は、エージェント実行、ツールアクション、およびオプトインされたメッセージのライフサイクルメタデータを、オペレータークライアント向けに安定した新しい順のビューで提供します。 operator.read が必要です。クエリは 30 日より古いレコードを除外し、共有 SQLite 台帳は 100,000 レコードに制限されます。期限切れの行は、 Gateway の起動時、1 時間ごとのメンテナンス時、および以降の書き込み時に削除されます。データモデルとプライバシーのセマンティクスについては、 監査履歴を参照してください。

• パラメーター：オプションの完全一致 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 }。

名前付き V1 結果ユニオンには、エージェント実行、ツールアクション、受信メッセージ、 および送信メッセージ用の個別のスキーマがあります。eventType 判別子はそれぞれ agent_run、tool_action、inbound_message、または outbound_message です。kind と メッセージ direction は、引き続きフィルタリングと表示に使用できます。すべてのイベントには 整数の schemaVersion: 1 があります。メッセージ ID 参照は正確な hmac-sha256:v1:<32 hex key id>:<64 hex digest> 形式を使用します。チャンネル送信者のアクター ID も同じ形式を使用します。

すべてのバリアントには、eventType、schemaVersion、eventId、sequence、 sourceSequence、occurredAt、kind、action、status、actor、および redaction が必要です。バリアントフィールドは次のとおりです。

閉じたメッセージ列挙型は次のとおりです。

• 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。

終了フィールドは相互に関連しており、個別にオプションではありません。

各アクティビティイベントには、安定したイベント ID、単調増加する台帳シーケンス、 ソースイベントシーケンス、タイムスタンプ、アクター、アクション、ステータス、整数の schemaVersion: 1、および redaction: "metadata_only" が含まれます。実行レコードとツールレコードには エージェントと実行の来歴が必要であり、セッションの来歴が含まれる場合もあります。メッセージ レコードにはエージェント ID と実行 ID が含まれる場合がありますが、意図的に sessionKey または sessionId は含まれません。そのため、sessionKey クエリフィルターは 実行行とツール行にのみ適用されます。ツールイベントには、ツール呼び出し ID とツール名が含まれる場合があります。

メッセージレコードは message.inbound.processed または message.outbound.finished を使用し、方向、チャンネル、会話の種類、 正規化された結果に加えて、オプションの配信種類、失敗ステージ、所要時間、 結果件数、理由コード、およびインストール環境固有のキーで生成された アカウント／会話／メッセージ／ターゲットの仮名を追加します。これらの仮名は 相関分析に役立ちますが、匿名化ではありません。状態データベースにはそのキーが含まれますが、 RPC および CLI のエクスポートには含まれません。台帳には、プロンプト、メッセージ本文、 ツール引数、ツール結果、コマンド出力、または生のエラーテキストは保存されません。 実行／ツールの sessionKey 値は生の相関メタデータのままであり、 プラットフォームのアカウント ID またはピア ID を含む場合があります。メッセージレコードではセッションキーを省略します。

受信行では、durationMs はコアディスパッチからその終了までを測定し、 resultCount は確定済みのキュー投入ツール、ブロック、および返信ペイロードを数えます。 送信行では、durationMs は配信所有権の取得から確認応答、 デッドレター、または照合まで（キューでの待機時間を含む）を対象とし、resultCount は 識別された物理的なプラットフォーム送信を数えます。deliveryKind が存在する場合は、 フックとレンダリング後の実効ペイロードを示します。抑制された行、または クラッシュにより結果が曖昧な行では省略されます。

現在のメッセージ対象範囲には、コアディスパッチに到達した受理済みの受信メッセージが含まれ、 コアでの重複／終了結果も含まれます。送信側では、共有の永続的な 配信に到達した元の論理返信ペイロードごとに、終了行を 1 行書き込みます。チャンク化と アダプターのファンアウトは resultCount に集約されます。キューに投入された 再試行可能または結果が曖昧な送信は、確認応答、デッドレター、 または照合の後にのみ記録されます。これらの共有境界を迂回する Plugin ローカルおよび 直接送信の経路は、まだ対象外です。上限付きワーカーキューはベストエフォートであり、 障害や飽和時にレコードが欠落する可能性があるため、この機能は 損失のないコンプライアンスアーカイブではありません。

記録はデフォルトで有効であり、 audit.enabled で制御します。メッセージ記録は audit.messages で個別に制御され、デフォルトは "off" です。 記録を無効にしても、audit.activity.list は以前に書き込まれたレコードを 有効期限が切れるまで引き続き提供します。

出荷済みの audit.list リクエスト、結果、および AuditEvent スキーマは 変更されておらず、エージェント実行およびツールアクションのレコードのみを返します。新しい運用クライアントは、 Gateway が audit.activity.list を公開している場合にそれを呼び出す必要があります。古い Gateway は、unknown method: audit.activity.list、または出荷済みバージョンでは メソッド検索より前に認可が行われていたため、読み取りスコープのリクエストに対して missing scope: operator.admin を報告する場合があります。後者をメソッド不在として扱うのは、 そのメソッドが公開されていなかった場合に限ります。その後、クライアントはフィルターが メッセージ種類、方向、またはチャンネルのサポートを必要としない場合に限り、 audit.list を再試行できます。

テキストクエリと上限付き JSON エクスポートには、openclaw audit を使用します。

タスク台帳 RPC

運用クライアントは、タスク台帳 RPC（packages/gateway-protocol/src/schema/tasks.ts）を介して Gateway のバックグラウンドタスクレコードを検査およびキャンセルします。これらは 生のランタイム状態ではなく、サニタイズされたタスク概要を返します。

• 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 は、 ランタイムがキャンセルを受理または記録したかどうかを示します。

TaskSummary には、id、status、およびオプションのメタデータとして kind、 runtime、title、agentId、sessionKey、childSessionKey、ownerKey、 runId、taskId、flowId、parentTaskId、sourceId、タイムスタンプ、進捗、 終了概要、およびサニタイズされたエラーテキストが含まれます。agentId はタスクを実行する エージェントを識別し、sessionKey と ownerKey はリクエスターおよび制御の コンテキストを保持します。

運用ヘルパーメソッド

• 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 ビュー

models.list は、オプションの view パラメーター （src/agents/model-catalog-visibility.ts）を受け入れます。

• 省略または "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

クライアント定数

リファレンスクライアントの実装は packages/gateway-client/src/ にあります （OpenClaw は薄い src/gateway/client.ts ファサードを介してこれをラップします）。これらの デフォルト値はプロトコル v4 全体で安定しており、サードパーティークライアントに期待される基準値です。

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

保留中のすべてのリクエストに期限が設定されている場合、リファレンスクライアントでは、有限のリクエストが 設定された期限を管理します。有限の timeoutMs がない expectFinal リクエスト、timeoutMs: null を持つリクエスト、または有限リクエストと 無期限リクエストの混在がある場合、tick ウォッチドッグは有効なままになります。受信イベントと レスポンスが tick タイムアウトのしきい値を超えてもない場合、クライアントは コード 4000 でソケットを閉じ、保留中のすべてのリクエストを拒否して再接続します。 再接続後に拒否されたリクエストを再実行することはありません。

認証

• 共有シークレットによる 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 は 安定した error.details.reason とともに、error.details.code の下で DEVICE_AUTH_* 詳細コードを 返します。

一般的な移行エラー：

移行先：

• 常に 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 証明書のフィンガープリントを任意でピン留めできます。

スコープ

このプロトコルは、ステータス、チャンネル、モデル、チャット、 エージェント、セッション、Node、承認など、Gateway API の全機能を公開します。正確な対象範囲は、 packages/gateway-protocol/src/schema.ts から再エクスポートされる TypeBox スキーマによって定義されます。

関連項目

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