> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

> Bonjour、Tailnet、SSH を使った検出入力と接続選択ポリシー、直接接続時のペアリング、各コンポーネントの責務を解説します。

# 検出と通信方式

OpenClaw において、ゲートウェイを見つけるための仕組みは、表面的には似ていますが、以下の 2 つの異なる課題を解決するためのものです:

1. **オペレーターによるリモート操作**: 別の場所で動作しているゲートウェイを、macOS のメニューバーアプリ等から制御する。
2. **ノードのペアリング**: iOS/Android（および将来のノード）がゲートウェイを見つけ、安全にペアリングを確立する。

設計上の目標は、ネットワーク上の検出や広告に関する機能をすべて **ノードゲートウェイ** (`openclaw gateway`) に集約し、各クライアント（Mac アプリや iOS 等）はそれを利用する側（コンシューマー）に徹することです。

## 用語の定義

* **ゲートウェイ (Gateway)**: 状態（セッション、ペアリング、ノードレジストリ）を保持し、各チャネルを稼働させる、単一の常駐プロセス。通常は 1 ホストにつき 1 プロセスですが、分離されたマルチゲートウェイ構成も可能です。
* **ゲートウェイ WS (コントロールプレーン)**: デフォルトで `127.0.0.1:18789` で動作する WebSocket エンドポイント。`gateway.bind` 設定により LAN や Tailnet にバインド可能です。
* **直接接続 (Direct WS)**: SSH を介さず、LAN や Tailnet を通じて直接アクセス可能なゲートウェイの WS エンドポイント。
* **SSH 経由 (SSH transport)**: `127.0.0.1:18789` を SSH ポートフォワードすることで実現する、リモート操作用のフォールバック（代替）経路。
* **レガシー TCP ブリッジ (非推奨/削除)**: 旧式のノード用通信路（詳細は [ブリッジプロトコル](/gateway/bridge-protocol) を参照）。現在は検出用の広告は行われません。

プロトコルの詳細:

* [ゲートウェイプロトコル](/gateway/protocol)
* [ブリッジプロトコル (レガシー)](/gateway/bridge-protocol)

## なぜ「直接接続」と「SSH」の両方を維持するのか

* **直接接続 (Direct WS)** は、同一ネットワーク内や Tailnet 内で最高のユーザー体験を提供します:
  * Bonjour による LAN 内での自動検出が可能。
  * ペアリングトークンや ACL（アクセス制御）をゲートウェイが直接管理。
  * シェルアクセスが不要なため、プロトコルの露出面を最小限に抑え、監査性を高めることが可能。
* **SSH** は、あらゆる環境で使える万能なフォールバックとして残り続けます:
  * SSH アクセスさえあれば、ネットワーク構成を問わずどこからでも動作。
  * マルチキャストや mDNS が通らない環境でも利用可能。
  * SSH 以外の追加のインバウンドポートを開放する必要がない。

## 検出のインプット (クライアントがゲートウェイの場所を知る方法)

### 1) Bonjour / mDNS (LAN 内限定)

Bonjour はベストエフォートの仕組みであり、ネットワークの境界を越えることはできません。同一 LAN 内での利便性のためにのみ使用されます。

仕組み:

* **ゲートウェイ** は、自身の WS エンドポイント情報を Bonjour 経由で広告します。
* クライアントはそれらをスキャンし、UI 上に「接続先の選択」リストを表示します。選択されたエンドポイント情報はクライアントに保存されます。

トラブルシューティングとビーコンの詳細は、[Bonjour](/gateway/bonjour) を参照してください。

#### サービスビーコンの仕様

* サービスタイプ:
  * `_openclaw-gw._tcp` (ゲートウェイ通信用ビーコン)
* TXT キー (非機密情報):
  * `role=gateway`
  * `lanHost=<ホスト名>.local`
  * `sshPort=22` (または設定されたポート)
  * `gatewayPort=18789` (ゲートウェイの WS + HTTP)
  * `gatewayTls=1` (TLS 有効時のみ)
  * `gatewayTlsSha256=<sha256>` (TLS 有効かつフィンガープリント利用可能時のみ)
  * `canvasPort=<ポート番号>` (Canvas ホスト有効時のみ。現在は `gatewayPort` と同じ)
  * `cliPath=<パス>` (オプション。実行可能な `openclaw` エントリポイントの絶対パス)
  * `tailnetDns=<magicdns>` (Tailscale 利用時のオプション。自動検出されます)

セキュリティ上の注意:

* Bonjour/mDNS の TXT レコードは **未認証（署名なし）** です。クライアントは TXT の内容をあくまで「利便性のためのヒント」として扱う必要があります。
* ルーティング（ホスト/ポート）情報の決定には、TXT 内の `lanHost`, `tailnetDns`, `gatewayPort` よりも、**解決されたサービスエンドポイント** (SRV + A/AAAA) を優先すべきです。
* TLS ピン留めにおいて、広告された `gatewayTlsSha256` が、既に保存されているピン情報を上書きすることを決して許可してはいけません。
* iOS/Android ノードは、検出ベースの直接接続を **TLS 限定** として扱い、初回接続時のフィンガープリントを信頼する前にユーザーへ明示的な確認を求める必要があります。

無効化と上書き:

* `OPENCLAW_DISABLE_BONJOUR=1` で広告を無効化。
* `~/.openclaw/openclaw.json` 内の `gateway.bind` で待機モードを制御。
* `OPENCLAW_SSH_PORT` で、TXT レコードに含める SSH ポート番号を上書き（デフォルト 22）。
* `OPENCLAW_TAILNET_DNS` で、`tailnetDns` (MagicDNS) のヒントを公開。
* `OPENCLAW_CLI_PATH` で、公開される CLI パスを上書き。

### 2) Tailnet (ネットワークを跨ぐ接続)

拠点が異なる場合などでは Bonjour は機能しません。推奨される「直接接続」のターゲットは以下の通りです:

* Tailscale の MagicDNS 名（推奨）、または固定の Tailnet IP アドレス。

ゲートウェイが Tailscale 下で動作していることを検知した場合、クライアント（広域ビーコンを含む）へのヒント情報として `tailnetDns` を公開します。

### 3) 手動設定 / SSH ターゲット

直接の通信経路がない（または無効化されている）場合、クライアントはループバックのゲートウェイポートをポートフォワードすることで、いつでも SSH 経由で接続できます。

詳細は [リモートアクセス](/gateway/remote) を参照してください。

## 通信方式の選択ポリシー (クライアント側)

推奨されるクライアントの挙動:

1. ペアリング済みの直接接続エンドポイントが構成されており、到達可能な場合はそれを使用する。
2. そうでない場合、Bonjour が LAN 内でゲートウェイを見つけたなら、ワンタップで「このゲートウェイを使用する」という選択肢を提示し、承認されればそれを直接接続エンドポイントとして保存する。
3. そうでない場合、Tailnet の DNS/IP が構成されていれば直接接続を試みる。
4. いずれも不可な場合は、SSH 接続にフォールバックする。

## ペアリングと認証 (直接接続時)

ゲートウェイが、ノードやクライアントの参加許可に関する「真実のソース」となります。

* ペアリング要求の作成、承認、拒否はすべてゲートウェイ上で行われます（[ゲートウェイペアリング](/gateway/pairing) を参照）。
* ゲートウェイは以下を強制します:
  * 認証（トークン、キーペア）
  * スコープと ACL（ゲートウェイはすべてのメソッドを無条件に通すプロキシではありません）
  * レート制限

## コンポーネントごとの責務

* **ゲートウェイ**: 検出用のビーコンを広告し、ペアリングの判定を行い、WebSocket エンドポイントをホストします。
* **macOS アプリ**: 接続先のゲートウェイ選択を支援し、ペアリングのプロンプトを表示します。SSH はあくまでフォールバックとして使用します。
* **iOS/Android ノード**: Bonjour をスキャンして利便性を提供し、ペアリング済みのゲートウェイ WS に接続します。