Gateway プロトコル

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

トランスポート

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

​

ハンドシェイク（connect）

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

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "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": {
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

{
  "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": 3,
    "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 = コントロールプレーンクライアント（CLI/UI/自動化）。
• node = capability ホスト（camera/screen/canvas/system.run）。

​

スコープ（operator）

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

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

​

caps/commands/permissions（node）

• caps: camera、canvas、screen、 location、voice、talk などの高レベル capability カテゴリ。
• commands: invoke 用のコマンド許可リスト。
• permissions: 粒度の細かい切り替え（例: screen.record、camera.capture）。

​

プレゼンス

• system-presence はデバイス ID でキー付けされたエントリを返します。
• プレゼンスエントリには deviceId、roles、scopes が含まれるため、UI はデバイスごとに 1 行だけ表示できます。 operator と node の両方として接続している場合でも同様です。
• node.list には任意の lastSeenAtMs と lastSeenReason フィールドが含まれます。接続中の node は 現在の接続時刻を lastSeenAtMs として報告し、理由は 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、ツール結果フレーム（ストリーミングされる agent イベントとツール呼び出し結果を含む）には、少なくとも operator.read が必要です。operator.read のないセッションでは、これらのフレームは完全にスキップされます。
• Plugin 定義の plugin.* ブロードキャストは、Plugin が登録した方法に応じて、operator.write または operator.admin にゲートされます。
• ステータスイベントとトランスポートイベント（heartbeat、presence、tick、connect/disconnect ライフサイクルなど）は制限されないままです。これにより、すべての認証済みセッションからトランスポートの健全性を観測できます。
• 不明なブロードキャストイベントファミリは、登録済みハンドラが明示的に緩和しない限り、デフォルトでスコープゲートされます（fail-closed）。

​

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

​

共通イベントファミリー

• chat: chat.inject などの UI チャット更新、および transcript 専用のその他のチャットイベント。
• session.message と session.tool: 購読中の session 向けの transcript/event-stream 更新。
• sessions.changed: session index またはメタデータが変更されました。
• presence: システム presence スナップショット更新。
• tick: 定期的な keepalive / liveness イベント。
• health: gateway health スナップショット更新。
• heartbeat: Heartbeat イベントストリーム更新。
• cron: Cron 実行/job 変更イベント。
• shutdown: gateway shutdown 通知。
• node.pair.requested / node.pair.resolved: node pairing ライフサイクル。
• node.invoke.request: node invoke request broadcast。
• device.pair.requested / device.pair.resolved: paired-device ライフサイクル。
• voicewake.changed: wake-word trigger config が変更されました。
• exec.approval.requested / exec.approval.resolved: exec 承認ライフサイクル。
• plugin.approval.requested / plugin.approval.resolved: plugin 承認ライフサイクル。

​

Node ヘルパーメソッド

• Nodes は、自動許可チェック用に skill 実行可能ファイルの現在の一覧を取得するため、skills.bins を呼び出すことができます。

​

タスク台帳 RPC

• tasks.list には operator.read が必要です。
  • Params: 省略可能な status（"queued"、"running"、"completed"、"failed"、"cancelled"、"timed_out"）、またはそれらの status の配列、省略可能な agentId、省略可能な sessionKey、1 から 500 までの省略可能な limit、および省略可能な文字列 cursor。
  • Result: { "tasks": TaskSummary[], "nextCursor"?: string }。
• tasks.get には operator.read が必要です。
  • Params: { "taskId": string }。
  • Result: { "task": TaskSummary }。
  • 存在しない task id は、Gateway の not-found error shape を返します。
• tasks.cancel には operator.write が必要です。
  • Params: { "taskId": string, "reason"?: string }。
  • Result: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }。
  • found は、台帳に一致するタスクがあったかどうかを報告します。cancelled は、runtime がキャンセルを受け入れたか、または記録したかどうかを報告します。

​

Operator ヘルパーメソッド

• Operators は、agent の runtime command inventory を取得するため、commands.list（operator.read）を呼び出すことができます。
  • agentId は省略可能です。default agent workspace を読み取るには省略します。
  • scope は、primary name がどの surface を対象にするかを制御します。
    • text は先頭の / なしで primary text command token を返します
    • native と default の both path は、利用可能な場合 provider-aware native names を返します
  • textAliases は /model や /m などの正確な slash aliases を保持します。
  • nativeName は、存在する場合に provider-aware native command name を保持します。
  • provider は省略可能で、native naming と native plugin command availability にのみ影響します。
  • includeArgs=false は、レスポンスから serialized argument metadata を省略します。
• Operators は、agent の runtime tool catalog を取得するため、tools.catalog（operator.read）を呼び出すことができます。レスポンスには grouped tools と provenance metadata が含まれます。
  • source: core または plugin
  • pluginId: source="plugin" の場合の plugin owner
  • optional: plugin tool が optional かどうか
• Operators は、session の runtime-effective tool inventory を取得するため、tools.effective（operator.read）を呼び出すことができます。
  • sessionKey は必須です。
  • gateway は、caller-supplied auth または delivery context を受け入れるのではなく、session server-side から trusted runtime context を導出します。
  • レスポンスは session-scoped であり、core、plugin、channel tools を含め、active conversation が今使用できるものを反映します。
• Operators は、/tools/invoke と同じ gateway policy path を通じて利用可能なツール 1 つを呼び出すため、tools.invoke（operator.write）を呼び出すことができます。
  • name は必須です。args、sessionKey、agentId、confirm、idempotencyKey は省略可能です。
  • sessionKey と agentId の両方が存在する場合、解決された session agent は agentId と一致する必要があります。
  • レスポンスは SDK-facing envelope で、ok、toolName、省略可能な output、および型付きの error fields を含みます。Approval または policy refusals は、gateway tool policy pipeline をバイパスするのではなく、payload 内で ok:false を返します。
• Operators は、agent の visible skill inventory を取得するため、skills.status（operator.read）を呼び出すことができます。
  • agentId は省略可能です。default agent workspace を読み取るには省略します。
  • レスポンスには eligibility、missing requirements、config checks、および raw secret values を公開しない sanitized install options が含まれます。
• Operators は、ClawHub discovery metadata のために skills.search と skills.detail（operator.read）を呼び出すことができます。
• Operators は、private skill archive をインストール前に stage するため、skills.upload.begin、skills.upload.chunk、skills.upload.commit（operator.admin）を呼び出すことができます。これは trusted clients 向けの独立した admin upload path であり、通常の ClawHub skill install flow ではありません。skills.install.allowUploadedArchives が有効でない限り、デフォルトで無効です。
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) は、その slug と force value に紐づく upload を作成します。
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) は、正確な decoded offset に bytes を追加します。
  • skills.upload.commit({ uploadId, sha256? }) は、final size と SHA-256 を検証します。Commit は upload を finalizes するだけで、skill はインストールしません。
  • Uploaded skill archives は、SKILL.md root を含む zip archives です。archive の internal directory name が install target を選択することはありません。
• Operators は、3 つのモードで skills.install（operator.admin）を呼び出すことができます。
  • ClawHub mode: { source: "clawhub", slug, version?, force? } は、skill folder を default agent workspace の skills/ directory にインストールします。
  • Upload mode: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } は、committed upload を default agent workspace の skills/<slug> directory にインストールします。slug と force value は、元の skills.upload.begin request と一致する必要があります。このモードは、 skills.install.allowUploadedArchives が有効でない限り拒否されます。この設定は ClawHub installs には影響しません。
  • Gateway installer mode: { name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } は、gateway host 上で宣言済みの metadata.openclaw.install action を実行します。
• Operators は、2 つのモードで skills.update（operator.admin）を呼び出すことができます。
  • ClawHub mode は、default agent workspace 内の tracked slug 1 つ、または tracked ClawHub installs すべてを更新します。
  • Config mode は、enabled、apiKey、env などの skills.entries.<skillKey> values に patch を適用します。

​

models.list views

• 省略または "default": 現在の runtime behavior。agents.defaults.models が設定されている場合、レスポンスは allowed catalog になり、provider/* entries に対して dynamically discovered models も含まれます。それ以外の場合、レスポンスは full Gateway catalog です。
• "configured": picker-sized behavior。agents.defaults.models が設定されている場合は引き続き優先され、provider/* entries に対する provider-scoped discovery も含まれます。allowlist がない場合、レスポンスは explicit models.providers.*.models entries を使用し、configured model rows が存在しない場合にのみ full catalog にフォールバックします。
• "all": full Gateway catalog。agents.defaults.models をバイパスします。通常の model pickers ではなく、diagnostics と discovery UIs に使用してください。

​

Exec 承認

• exec request に承認が必要な場合、gateway は exec.approval.requested を broadcast します。
• Operator clients は、exec.approval.resolve を呼び出して解決します（operator.approvals scope が必要）。
• host=node の場合、exec.approval.request は systemRunPlan（canonical argv/cwd/rawCommand/session metadata）を含む必要があります。systemRunPlan がない request は拒否されます。
• 承認後、forwarded node.invoke system.run calls は、その canonical systemRunPlan を authoritative command/cwd/session context として再利用します。
• caller が prepare と最終的な承認済み system.run forward の間で command、rawCommand、cwd、agentId、または sessionKey を変更した場合、gateway は mutated payload を信頼せず、run を拒否します。

​

Agent delivery fallback

• agent requests は、outbound delivery を要求するために deliver=true を含めることができます。
• bestEffortDeliver=false は strict behavior を維持します。未解決または internal-only delivery targets は INVALID_REQUEST を返します。
• bestEffortDeliver=true は、external deliverable route が解決できない場合（たとえば internal/webchat sessions や ambiguous multi-channel configs）に session-only execution への fallback を許可します。
• Final agent results は、delivery が request されていた場合に result.deliveryStatus を含むことがあります。これは openclaw agent --json --deliver で文書化されているものと同じ sent、suppressed、partial_failed、failed statuses を使用します。

​

バージョニング

• PROTOCOL_VERSION は src/gateway/protocol/version.ts にあります。
• Clients は minProtocol + maxProtocol を送信します。server は、現在の protocol を含まない ranges を拒否します。Native clients は v3 lower bound を使用するため、additive v4 clients は v3 gateways にも到達できます。
• Schemas + models は TypeBox definitions から生成されます。
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

Client constants

​

認証

• 共有シークレットの Gateway 認証は、設定された認証モードに応じて connect.params.auth.token または connect.params.auth.password を使用します。
• Tailscale Serve（gateway.auth.allowTailscale: true）や非ループバックの gateway.auth.mode: "trusted-proxy" などの ID を持つモードでは、 connect.params.auth.* ではなくリクエストヘッダーから接続認証チェックを満たします。
• プライベートイングレスの gateway.auth.mode: "none" は共有シークレットの接続認証を 完全にスキップします。このモードを公開または信頼されていないイングレスに公開しないでください。
• ペアリング後、Gateway は接続 role + scopes にスコープされた device token を発行します。 これは hello-ok.auth.deviceToken で返され、今後の接続のために クライアントで永続化する必要があります。
• クライアントは、接続が成功するたびに主要な hello-ok.auth.deviceToken を永続化する必要があります。
• その保存済み device token で再接続する場合は、その token に対して保存済みの 承認済み scope セットも再利用する必要があります。これにより、すでに許可された read/probe/status アクセスが維持され、再接続が暗黙の admin-only scope だけに 静かに縮小されることを避けられます。
• クライアント側の接続認証の組み立て（src/gateway/client.ts の selectConnectAuth）:
  • auth.password は独立しており、設定されている場合は常に転送されます。
  • auth.token は優先順位に従って設定されます。明示的な共有 token が最初、 次に明示的な deviceToken、次に保存済みのデバイスごとの token（deviceId + role でキー付け）です。
  • auth.bootstrapToken は、上記のいずれも auth.token に解決されなかった場合にのみ送信されます。 共有 token または解決済みの device token がある場合は抑制されます。
  • ワンショットの AUTH_TOKEN_MISMATCH 再試行で保存済み device token を自動昇格する処理は、 信頼済みエンドポイントのみ に制限されます。つまり、ループバック、または 固定された tlsFingerprint を持つ wss:// です。ピン留めなしの公開 wss:// は該当しません。
• 追加の hello-ok.auth.deviceTokens エントリは bootstrap 引き渡し token です。 接続が wss:// やループバック/local ペアリングなどの信頼済み transport 上で bootstrap 認証を使用した場合にのみ永続化してください。
• クライアントが明示的な deviceToken または明示的な scopes を指定した場合、 その呼び出し元が要求した scope セットが権威を持ちます。キャッシュされた scopes は、 クライアントが保存済みのデバイスごとの token を再利用する場合にのみ再利用されます。
• Device tokens は device.token.rotate と device.token.revoke でローテート/失効できます （operator.pairing scope が必要）。
• device.token.rotate はローテーションメタデータを返します。置換後の bearer token は、 その device token ですでに認証されている同一デバイスからの呼び出しの場合にのみ エコーします。これにより、token-only クライアントは再接続前に置換 token を永続化できます。 共有/admin ローテーションでは bearer token をエコーしません。
• token の発行、ローテーション、失効は、そのデバイスのペアリングエントリに記録された 承認済み role セットに制限されます。token の変更によって、ペアリング承認で許可されていない デバイス role を拡張したり対象にしたりすることはできません。
• ペアリング済みデバイスの token セッションでは、呼び出し元が operator.admin も持つ場合を除き、 デバイス管理は自己スコープです。admin ではない呼び出し元は、自分自身の デバイスエントリだけを削除/失効/ローテートできます。
• device.token.rotate と device.token.revoke は、対象 operator token の scope セットも 呼び出し元の現在のセッション scopes と照合します。admin ではない呼び出し元は、 自分がすでに保持しているものより広い operator token をローテートまたは失効できません。
• 認証失敗には 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 に対するクライアント動作:
  • 信頼済みクライアントは、キャッシュされたデバイスごとの token で 1 回だけ上限付き再試行を試みることができます。
  • その再試行が失敗した場合、クライアントは自動再接続ループを停止し、operator の対応ガイダンスを表示する必要があります。
• AUTH_SCOPE_MISMATCH は、device token は認識されたものの、要求された role/scopes をカバーしていないことを意味します。 クライアントはこれを不正な token として提示しないでください。 operator に再ペアリングするか、より狭い/広い scope 契約を承認するよう促してください。

​

デバイス ID + ペアリング

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

​

デバイス認証移行診断

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

​

TLS + ピン留め

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

​

スコープ

​

関連

• Bridge プロトコル
• Gateway runbook