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

> ゲートウェイ主導でノード参加を管理する考え方、承認フロー、CLI 操作、API、保存場所、自動承認の挙動を解説します。

# ゲートウェイ主導のペアリング

ゲートウェイ主導のペアリングでは、どのノード（デバイス）の参加を許可するかについて、**ゲートウェイ** が「真実のソース」となります。macOS アプリや将来の他のクライアントなどの UI は、保留中の要求を承認または拒否するためのフロントエンドとして機能します。

**重要:** WebSocket（WS）ノードは、`connect` ハンドシェイク時に **デバイスペアリング** (role: `node`) を使用します。`node.pair.*` は独立したペアリング用ストアであり、WS の接続確立そのものをゲート（制限）するものではありません。このフローは、明示的に `node.pair.*` メソッドを呼び出すクライアントのみが使用します。

## コンセプト

* **保留中の要求 (Pending request)**: 参加を求めているノード。管理者の承認が必要です。
* **ペアリング済みノード (Paired node)**: 承認され、認証トークンが発行されたノード。
* **通信路（トランスポート）**: ゲートウェイの WebSocket エンドポイントは要求を転送しますが、参加の可否を独自に判断することはありません（レガシーな TCP ブリッジのサポートは削除されました）。

## ペアリングの流れ

1. ノードがゲートウェイの WebSocket に接続し、ペアリングを要求します。
2. ゲートウェイは **保留中の要求** を保存し、`node.pair.requested` イベントを発行します。
3. 管理者が要求を承認または拒否します（CLI または UI を使用）。
4. 承認されると、ゲートウェイは **新しいトークン** を発行します（再ペアリング時にはトークンが更新されます）。
5. ノードはそのトークンを使用して再接続し、「ペアリング済み」の状態になります。

保留中の要求は **5 分間** 経過すると自動的に期限切れになります。

## CLI での操作 (ヘッドレス環境向け)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node <id|名前|ip> --name "リビングの iPad"
```

`nodes status` を実行すると、ペアリング済み・接続済みのノードとその機能（Capabilities）を確認できます。

## API リファレンス (ゲートウェイプロトコル)

イベント:

* `node.pair.requested` — 新しい保留中の要求が作成されたときに発行されます。
* `node.pair.resolved` — 要求が承認、拒否、または期限切れになったときに発行されます。

メソッド:

* `node.pair.request` — 保留中の要求を作成、または既存のものを再利用します。
* `node.pair.list` — 保留中およびペアリング済みのノードを一覧表示します。
* `node.pair.approve` — 保留中の要求を承認します（トークンを発行します）。
* `node.pair.reject` — 保留中の要求を拒否します。
* `node.pair.verify` — `{ nodeId, token }` の妥当性を検証します。

補足事項:

* `node.pair.request` はノードごとにべき等（idempotent）です。同じ内容で繰り返し呼び出しても、同じ保留中の要求が返されます。
* 承認時には **必ず** 新しいトークンが生成されます。`node.pair.request` メソッドの返り値にトークンが含まれることはありません。
* 要求には、自動承認フローへのヒントとして `silent: true` を含めることができます。

## 自動承認 (macOS アプリ)

macOS アプリは、以下の条件を満たす場合に **サイレント承認**（確認プロンプトなしの承認）を試みることができます:

* 要求に `silent: true` が設定されている。
* アプリが、同じユーザーを使用してゲートウェイホストへの SSH 接続を確認できる。

サイレント承認に失敗した場合は、通常の「承認/拒否」プロンプトへフォールバックします。

## データの保存場所 (ローカル、非公開)

ペアリングの状態は、ゲートウェイの状態ディレクトリ（デフォルト `~/.openclaw`）配下に保存されます:

* `~/.openclaw/nodes/paired.json`
* `~/.openclaw/nodes/pending.json`

`OPENCLAW_STATE_DIR` 環境変数でディレクトリを変更した場合、`nodes/` フォルダも同様に移動します。

セキュリティ上の注意:

* トークンはシークレット情報です。`paired.json` は機密性の高いファイルとして扱ってください。
* トークンを更新するには、再承認を受けるか、既存のノードエントリを削除する必要があります。

## 通信路（トランスポート）の挙動

* 通信レイヤーは **ステートレス** です。参加資格に関する情報は保持しません。
* ゲートウェイがオフラインの場合、またはペアリング機能が無効化されている場合は、ノードはペアリングできません。
* ゲートウェイがリモートモードで動作している場合でも、ペアリング処理は接続先のリモートゲートウェイのストアに対して行われます。