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、自動化）は、設定されたバインドホスト（デフォルトは 127.0.0.1:18789）上の WebSocket を介して Gateway に接続します。

  • Node（macOS/iOS/Android/ヘッドレス）も WebSocket を介して接続しますが、明示的な機能／コマンドとともに 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 (ok)
    Note right of Gateway: または res error + close
    Note left of Client: payload=hello-ok<br>スナップショット: presence + health

    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}

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

  • トランスポート：JSON ペイロードを含むテキストフレームを使用する WebSocket。
  • 最初のフレームは必ず 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 は、connect に role: "node" と機能／コマンド／権限を含める必要があります。

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

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

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

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

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

リモートアクセス

  • 推奨：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 を使用します。

不変条件

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

関連項目

Was this useful?
On this page

On this page