OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Fundamentals

Gateway アーキテクチャ

概要

  • 単一の長時間稼働する Gateway が、すべてのメッセージングサーフェス（Baileys 経由の WhatsApp、grammY 経由の Telegram、Slack、Discord、Signal、iMessage、WebChat）を管理します。

  • コントロールプレーンのクライアント（macOS アプリ、CLI、Web UI、自動化）は、設定されたバインドホスト上の WebSocket（デフォルトは 127.0.0.1:18789）を介して Gateway に接続します。

  • Node（macOS/iOS/Android/ヘッドレス）も WebSocket 経由で接続しますが、 明示的な caps/commands とともに role: node を宣言します。

  • ホストごとに Gateway は 1 つです。WhatsApp セッションを開くのは Gateway だけです。

  • キャンバスホストは、Gateway HTTP サーバーによって次のパスで提供されます。

    • /__openclaw__/canvas/（エージェントが編集可能な HTML/CSS/JS）
    • /__openclaw__/a2ui/（A2UI ホスト）

    Gateway と同じポート（デフォルトは 18789）を使用します。

コンポーネントとフロー

Gateway（デーモン）

  • プロバイダー接続を維持します。
  • 型付き WS API（リクエスト、レスポンス、サーバープッシュイベント）を公開します。
  • 受信フレームを JSON Schema に照らして検証します。
  • agent、chat、presence、health、heartbeat、cron などのイベントを発行します。

クライアント（Mac アプリ / CLI / Web 管理画面）

  • クライアントごとに 1 つの WS 接続を使用します。
  • リクエスト（health、status、send、agent、system-presence）を送信します。
  • イベント（tick、agent、presence、shutdown）を購読します。

Node（macOS / iOS / Android / ヘッドレス）

  • role: node を使用して、同じ WS サーバーに接続します。
  • connect でデバイス ID を提供します。ペアリングはデバイスベース（ロールは node）であり、 承認情報はデバイスペアリングストアに保存されます。
  • canvas.*、camera.*、screen.record、location.get などのコマンドを公開します。

プロトコルの詳細：Gateway プロトコル

WebChat

  • チャット履歴の取得と送信に Gateway WS API を使用する静的 UI です。
  • リモート構成では、ほかのクライアントと同じ SSH/Tailscale トンネルを介して接続します。

接続ライフサイクル（単一クライアント）

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (成功)
    Note right of Gateway: または res エラー + 切断
    Note left of Client: payload=hello-ok<br>スナップショット: プレゼンス + ヘルス

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>確認応答 {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>（ストリーミング）
    Gateway-->>Client: res:agent<br>最終結果 {runId, status, summary}

ワイヤープロトコル（概要）

  • トランスポート：WebSocket。JSON ペイロードを含むテキストフレームを使用します。
  • 最初のフレームは connect でなければなりません。
  • ハンドシェイク後：
    • リクエスト：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • イベント：{type:"event", event, payload, seq?, stateVersion?}
  • hello-ok.features.methods / events は検出用メタデータであり、 呼び出し可能なすべてのヘルパールートを生成したダンプではありません。
  • 共有シークレット認証では、設定された Gateway 認証モードに応じて connect.params.auth.token または connect.params.auth.password を使用します。
  • Tailscale Serve （gateway.auth.allowTailscale: true）や local loopback 以外の gateway.auth.mode: "trusted-proxy" など、ID 情報を伴うモードでは、connect.params.auth.* の代わりに リクエストヘッダーによって認証を満たします。
  • プライベートイングレスの gateway.auth.mode: "none" は共有シークレット認証を 完全に無効化します。公開または信頼できないイングレスでは、このモードを無効にしてください。
  • 安全に再試行できるよう、副作用を伴うメソッド（send、agent）には 冪等性キーが必要です。サーバーは短時間有効な重複排除キャッシュを保持します。
  • Node は role: "node" に加え、caps/commands/permissions を connect に含める必要があります。

ペアリングとローカルの信頼

  • すべての WS クライアント（オペレーターと Node）は、connect にデバイス IDを含めます。
  • 新しいデバイス ID にはペアリングの承認が必要です。Gateway は以降の接続に使用するデバイストークンを発行します。
  • 同一ホストでの UX を円滑に保つため、local loopback への直接接続は自動承認できます。
  • OpenClaw には、信頼された共有シークレットヘルパーフロー向けに、 バックエンドまたはコンテナのローカルに限定された自己接続パスもあります。
  • 同一ホストの tailnet バインドを含む Tailnet および LAN 接続には、引き続き 明示的なペアリング承認が必要です。
  • すべての接続は connect.challenge nonce に署名する必要があります。署名ペイロード v3 は platform と deviceFamily にも結び付けられます。Gateway は再接続時にペアリング済みのメタデータを固定し、 メタデータを変更する場合は修復ペアリングを要求します。
  • ローカル以外からの接続には、引き続き明示的な承認が必要です。
  • Gateway 認証（gateway.auth.*）は、ローカルかリモートかを問わず、すべての接続に適用されます。

詳細：Gateway プロトコル、ペアリング、 セキュリティ。

プロトコルの型定義とコード生成

  • TypeBox スキーマがプロトコルを定義します。
  • JSON Schema はこれらのスキーマから生成されます。
  • Swift モデルは JSON Schema から生成されます。

リモートアクセス

  • 推奨：Tailscale または VPN。

  • 代替手段：SSH トンネル

    bash
    ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

  • トンネル経由でも、同じハンドシェイクと認証トークンが適用されます。

  • リモート構成では、WS に対して TLS と任意のピンニングを有効化できます。

運用の概要

  • 起動：openclaw gateway（フォアグラウンドで実行し、標準出力にログを出力）。
  • ヘルス：WS 経由の health（hello-ok にも含まれます）。
  • 監視：自動再起動には launchd/systemd を使用します。

不変条件

  • ホストごとに、厳密に 1 つの Gateway が単一の Baileys セッションを制御します。
  • ハンドシェイクは必須です。JSON 以外、または connect 以外のフレームが最初に送信された場合、即座に接続を閉じます。
  • イベントは再送されません。欠落が発生した場合、クライアントは情報を更新する必要があります。

関連項目

Was this useful?
On this page

On this page