Gateway プロトコル

Gateway の WS プロトコルは OpenClaw の唯一のコントロールプレーン + ノードトランスポート層です。すべてのクライアント（CLI、Web UI、macOS アプリ、iOS/Android ノード、ヘッドレスノード）は WebSocket 経由で接続し、ハンドシェイクフェーズでroleとscopeを宣言します。

- WebSocket、JSON ペイロードを含むテキストフレームを使用。

- 最初のフレームは''必須''で、''connect'' リクエストである必要があります。

Gateway → Client（接続前チャレンジ）：

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

Client → Gateway：

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "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 → Client：

{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
}

デバイストークンが発行されると、''hello-ok'' には以下も含まれます：

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

#

- ''Request''：''{type:"req", id, method, params}''

- ''Response''：''{type:"res", id, ok, payload|error}''

- ''Event''：''{type:"event", event, payload, seq?, stateVersion?}''

副作用のあるメソッドにはべき等キー（idempotency keys）が必要です（schema を参照）。

#

- ''operator'' = コントロールプレーンクライアント（CLI/UI/automation）

- ''node'' = ケーパビリティホスト（camera/screen/canvas/system.run）

#

一般的な scopes：

- ''operator.read''

- ''operator.write''

- ''operator.admin''

- ''operator.approvals''

- ''operator.pairing''

#

ノードは接続時にケーパビリティクレームを宣言します：

- ''caps''：高レベルのケーパビリティカテゴリ

- ''commands''：呼び出し可能なコマンドの許可リスト

- ''permissions''：より細かいトグル（例：''screen.record''、''camera.capture''）

Gateway はこれらをクレームとして扱い、サーバー側でさらに許可リストを適用します。

- ''system-presence'' はデバイス ID をキーとするエントリを返します。

- Presence エントリには ''deviceId''、''roles''、''scopes'' が含まれるため、同じデバイスが''operator''と''node''として同時に接続していても、UI は 1 行のみ表示できます。

#

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

- exec が承認を必要とする場合、gateway は ''exec.approval.requested'' をブロードキャストします。

- operator クライアントは ''exec.approval.resolve'' 経由で承認/拒否を行います（''operator.approvals'' scope が必要）。

- ''PROTOCOL_VERSION'' は ''src/gateway/protocol/schema.ts'' にあります。

- クライアントは ''minProtocol'' + ''maxProtocol'' を送信します。サーバーは不一致を拒否します。

- Schemas + models は TypeBox 定義から生成されます：

- Schemas + models are generated from TypeBox definitions:

- ''pnpm protocol:gen''

- ''pnpm protocol:gen:swift''

- ''OPENCLAW_GATEWAY_TOKEN''（または ''--token''）が設定されている場合、''connect.params.auth.token'' は一致する必要があり、そうでない場合ソケットは閉じられます。

- ペアリングが完了すると、Gateway は device + role + scopes で制約された''デバイストークン''を発行し、''hello-ok.auth.deviceToken'' で返します。クライアントはそれを永続化し、後続の接続に使用する必要があります。

- デバイストークンは ''device.token.rotate'' と ''device.token.revoke'' でローテーション/取り消しできます（''operator.pairing'' scope が必要）。

- ノードは安定したデバイス ID（''device.id''）を含める必要があります。通常、キーペアのフィンガープリントから導出されます。

- Gateway は各 device + role の組み合わせに対してトークンを発行します。

- 新しいデバイス ID はペアリングの承認が必要です。ただし、ローカル自動承認が有効な場合を除きます。

- ローカル接続にはループバックおよび gateway ホスト自身の tailnet アドレスが含まれます（そのため、同マシンの tailnet バインドでも自動承認できます）。

- All WS clients must include ''device'' identity during ''connect'' (operator + node). Control UI can omit it ''only'' when ''gateway.controlUi.allowInsecureAuth'' is enabled (or ''gateway.controlUi.dangerouslyDisableDeviceAuth'' for break-glass use).

- Non-local connections must sign the server-provided ''connect.challenge'' nonce.

- 非ローカル接続は、サーバーから発行された ''connect.challenge'' nonce に署名する必要があります。

- WS 接続は TLS をサポートします。

- クライアントはオプションで gateway 証明書のフィンガープリントをピンできます（''gateway.tls'' 設定、および ''gateway.remote.tlsFingerprint'' または CLI ''--tls-fingerprint'' を参照）。

このプロトコルは''完全な gateway API''（status、channels、models、chat、agent、sessions、nodes、approvals など）を公開します。実際のサーフェスは ''src/gateway/protocol/schema.ts'' の TypeBox schemas で定義されています。