OpenClawゲートウェイ構築ガイド：WebSocket接続を5分で実装

複数のメッセージングプラットフォームを同期させ、安定した接続を維持するのは、開発者にとって常に頭の痛い問題です。APIの仕様変更やセッションの管理に追われるのではなく、もっとスマートに通信を統合できれば理想的ですよね。

そこで役立つのが、今回紹介する Gateway アーキテクチャです。複雑な通信フローを一つのハブに集約することで、開発の効率を大幅に高めることができます。

概要

単一の長寿命な Gateway が、すべてのメッセージングサーフェス（Baileys 経由の WhatsApp、grammY 経由の Telegram、Slack、Discord、Signal、iMessage、WebChat）を所有します。
コントロールプレーンのクライアント（macOS アプリ、CLI、Web UI、オートメーション）は、設定されたバインドホスト（デフォルトは 127.0.0.1:18789）上の WebSocket を介して Gateway に接続します。
Nodes（macOS/iOS/Android/headless）も WebSocket 経由で接続しますが、明示的な caps/commands とともに role: node を宣言します。
ホストごとに一つの Gateway が存在し、WhatsApp セッションを開く唯一の場所となります。
canvas host は、Gateway の HTTP サーバーによって以下のパスで提供されます。
- /__openclaw__/canvas/（エージェントが編集可能な HTML/CSS/JS）
- /__openclaw__/a2ui/（A2UI ホスト） Gateway と同じポート（デフォルト 18789）を使用します。

コンポーネントとフロー

Gateway (daemon)

プロバイダーとの接続を維持します。
型定義された WS API（リクエスト、レスポンス、サーバープッシュイベント）を公開します。
インバウンドフレームを JSON Schema に対して検証します。
agent, chat, presence, health, heartbeat, cron などのイベントを発行します。

クライアント (mac app / CLI / web admin)

クライアントごとに一つの WS 接続を持ちます。
リクエスト（health, status, send, agent, system-presence）を送信します。
イベント（tick, agent, presence, shutdown）をサブスクライブします。

Nodes (macOS / iOS / Android / headless)

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

プロトコルの詳細：

Gateway protocol

WebChat

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

接続ライフサイクル（シングルクライアント）

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: or res error + close
    Note left of Client: payload=hello-ok<br>snapshot: presence + health

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

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(streaming)
    Gateway-->>Client: res:agent<br>final {runId, status, summary}

通信プロトコル（概要）

トランスポート：WebSocket、JSON ペイロードを含むテキストフレーム。
最初のフレームは必ず connect である必要があります。
ハンドシェイク後：
- リクエスト：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
- イベント：{type:"event", event, payload, seq?, stateVersion?}
OPENCLAW_GATEWAY_TOKEN（または --token）が設定されている場合、connect.params.auth.token が一致しなければソケットは閉じられます。
べき等性キーは、副作用を伴うメソッド（send, agent）で安全に再試行するために必要です。サーバーは短期間の重複排除キャッシュを保持します。
Nodes は connect 時に role: "node" に加えて caps/commands/permissions を含める必要があります。

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

すべての WS クライアント（オペレーターおよびノード）は、connect 時にデバイス識別子を含めます。
新しいデバイス ID にはペアリングの承認が必要です。Gateway はその後の接続のためにデバイストークンを発行します。
ローカル接続（ループバックまたは Gateway ホスト自身の Tailscale アドレス）は、同一ホスト内でのユーザー体験をスムーズにするために自動承認される場合があります。
すべての接続は connect.challenge ノンスに署名する必要があります。
署名ペイロード v3 は platform と deviceFamily もバインドします。Gateway は再接続時にペアリングされたメタデータを固定し、メタデータが変更された場合はペアリングの修復を要求します。
非ローカル接続には、引き続き明示的な承認が必要です。
Gateway 認証（gateway.auth.*）は、ローカルかリモートかを問わず、すべての接続に適用されます。

詳細：Gateway protocol, Pairing, Security

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

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

リモートアクセス

推奨：Tailscale または VPN。

代替案：SSH トンネル

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

トンネル経由でも同じハンドシェイクと認証トークンが適用されます。
リモート設定の WS では、TLS とオプションのピン留めを有効にできます。

運用のスナップショット

起動：openclaw gateway（フォアグラウンド、stdout にログ出力）。
ヘルスチェック：WS 経由の health（hello-ok にも含まれます）。
管理：自動再起動のための launchd/systemd。

不変条件

ホストごとに、ただ一つの Gateway が単一の Baileys セッションを制御します。
ハンドシェイクは必須です。JSON 以外、または connect 以外の最初のフレームは強制的に切断されます。
イベントは再送されません。クライアントは欠落が発生した場合にリフレッシュする必要があります。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。