Gateway アーキテクチャ
WebSocket Gateway のアーキテクチャ、コンポーネント、クライアントフロー。
Last updated: 2026-01-22
Overview
- 長期間稼働する ゲートウェイ がすべてのメッセージングインターフェースを所有（WhatsApp
Baileys, GrammY Telegram, Slack, Discord, Signal, iMessage, WebChat).
- コントロールプレーンクライアント（macOSアプリ、CLI、Web UI、自動化）は
設定バインドホスト上のゲートウェイに WebSocket 経由で接続（デフォルト
''127.0.0.1:18789''）。
- ノード（macOS/iOS/Android/ヘッドレス）も WebSocket 経由で接続しますが、
明示的な大文字/コマンド宣言 ''role: node'' を使用します。
- ホストごとに1つのゲートウェイ。これがWhatsAppセッションが開かれる唯一の場所です。
コンポーネントとフロー
#
ゲートウェイ（デーモン）
- プロバイダー接続を維持します。
- 型指定されたWS API（リクエスト、レスポンス、サーバー送信イベント）を公開します。
- JSONスキーマに対してインバウンドフレームを検証します。
- ''agent''、''chat''、''presence''、''health''、''heartbeat''、''cron'' などのイベントを発行します。
#
クライアント（macアプリ/CLI/Web管理）
- クライアントごとに1つのWS接続。
- リクエストを送信（''health''、''status''、''send''、''agent''、''system-presence''）。
- イベントを購読（''tick''、''agent''、''presence''、''shutdown''）。
#
ノード（macOS / iOS / Android / ヘッドレス）
- ''role: node'' を使用して ''同じWSサーバー'' に接続します。
- ''connect'' でデバイスIDを提供。ペアリングは ''デバイスベース''（ロール ''node''）で、
承認はデバイスペアリングストアに存在します。
- ''canvas.*''、''camera.*''、''screen.record''、''location.get'' などのコマンドを公開します。
プロトコル詳細：
- ''ゲートウェイプロトコル''
#
Webチャット
- Gateway WS APIを使用したチャット履歴と送信の静的UI。
- リモートセットアップでは、他のクライアントと同じSSH/Tailscaleトンネル経由で
接続します。
接続ライフサイクル（単一クライアント）
Client Gateway
| |
|| (or res error + close)
| (payload=hello-ok carries snapshot: presence + health)
| |
|< event:presence -----| (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''）は安全な再試行のためにべき等キーが必要です。
サーバーは短命の重複排除キャッシュを保持します。
ペアリング + ローカル信頼
- すべてのWSクライアント（オペレーター + ノード）は ''connect'' で ''デバイスID'' を含みます。
- 新しいデバイスIDはペアリング承認が必要。ゲートウェイは デバイストークン を発行します。
後続の接続用。
- ローカル 接続（ループバックまたはゲートウェイホスト自身のtailnetアドレス）は
同じホストUXをスムーズに保つために自動承認できます。
- ''非ローカル'' 接続は ''connect.challenge'' ナンスに署名し、
明示的な承認が必要です。
- ゲートウェイ認証（''gateway.auth.*''）は ''すべて'' の接続（ローカルまたは
リモート）に適用されます。詳細：''ゲートウェイプロトコル''、''ペアリング''、''セキュリティ''。
プロトコルタイプとコード生成
- TypeBoxスキーマがプロトコルを定義します。
- JSONスキーマはこれらのスキーマから生成されます。
- SwiftモデルはJSONスキーマから生成されます。
リモートアクセス
- 推奨：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。
Invariants
- ホストごとに1つのゲートウェイのみが1つのBaileysセッションを制御します。
- ハンドシェイクは必須。非JSONまたは非接続の最初のフレームは強制終了です。
- イベントは再再生されません。クライアントはギャップを追いつく必要があります。