Bridge Protocol (Legacy) の仕組みと移行

分散した Node を Gateway に接続しようとするとき、どのプロトコルを選ぶべきか迷うことがあります。特に、既存のシステムをメンテナンスしたり、古い実装を参考にしたりしていると、現在の標準とは異なる接続方式に遭遇することがあります。

結論からお伝えすると、新しく Node クライアントを構築する場合は、統一された Gateway WebSocket プロトコル を使用してください。Bridge プロトコルは レガシー なものとして扱われており、現在の OpenClaw ビルドには TCP Bridge リスナーは含まれていません。この記事では、歴史的なリファレンスとしてその仕様をまとめます。

必要なもの

このプロトコルを理解・検証するために必要な要素は以下の通りです。

• TCP および JSONL（1行ごとに1つの JSON オブジェクト）の知識
• 有効な Node トークン（ペアリング用）
• TLS 証明書（TLS を有効にする場合）
• Tailscale 環境（Tailnet 経由で接続する場合）

クイックスタート

Bridge プロトコルでの接続とペアリングは、以下の 4 ステップで進みます。

1. Hello 送信: クライアントが Node のメタデータとトークン（保持している場合）を含む hello フレームを送信します。
2. ペアリング確認: ペアリングされていない場合、Gateway は error (NOT_PAIRED または UNAUTHORIZED) を返します。
3. ペアリングリクエスト: クライアントが pair-request を送信します。
4. 承認と完了: Gateway 側で承認されると、pair-ok と hello-ok が送信されます。

hello-ok が返されると、serverName や canvasHostUrl などの情報が取得でき、通信が可能になります。

Transport の仕様

Bridge は TCP をベースにしており、データは JSONL 形式でやり取りされます。

• Port: レガシーなデフォルトポートは 18790 です。
• TLS: bridge.tls.enabled が true の場合、TLS が使用されます。
• Discovery: TLS 有効時、Bonjour の TXT レコードには bridgeTls=1 と bridgeTlsSha256 が含まれ、Node は証明書をピン留めできます。

なお、現在の設定スキーマからは bridge.* キーは削除されています。

フレームの種類

クライアントと Gateway の間では、以下のフレームがやり取りされます。

Client → Gateway

• req / res: チャット、セッション、設定、ヘルスチェックなどの RPC。
• event: 音声の書き起こしやエージェントのリクエストなど、Node からのシグナル。

Gateway → Client

• invoke / invoke-res: camera.* や sms.send といった Node へのコマンド。
• event: 購読しているセッションのチャット更新。
• ping / pong: 接続維持のためのキープアライブ。

Exec lifecycle events

Node は system.run のアクティビティを通知するために exec.finished や exec.denied イベントを発行できます。

ペイロードに含まれる主なフィールドは以下の通りです。

• sessionKey (必須): システムイベントを受け取るエージェントセッション。
• runId: 実行を識別する ID。
• command: 実行されたコマンド文字列。
• exitCode, success, output: 完了時の詳細情報。

Tailnet での利用

Bridge を Tailnet IP にバインドするには、~/.openclaw/openclaw.json で以下のように設定します。

{
  "bridge.bind": "tailnet"
}

この設定により、クライアントは MagicDNS 名や Tailnet IP を介して接続できるようになります。ただし、Bonjour はネットワークを跨げないため、必要に応じてホスト名を手動で指定してください。

トラブルシューティング

接続時に発生する代表的な問題と解決策です。

• NOT_PAIRED / UNAUTHORIZED エラー: クライアントがまだ Gateway に登録されていません。pair-request を送信し、Gateway 側で承認を待機してください。
• 接続できない: 現在の OpenClaw ビルドでは TCP Bridge リスナーは起動しません。最新のクライアントを使用している場合は、Gateway WebSocket プロトコルへの移行を検討してください。

最後に

Bridge プロトコルは後方互換性のためにドキュメント化されていますが、今後の開発では Gateway プロトコルの利用を強く推奨します。

セットアップに関する具体的な質問がある場合は、AI Setup Assistant を活用してください。

次のステップ

• Gateway protocol: 最新の推奨プロトコルについて学ぶ
• Node client development: Node の開発ガイドラインを確認する