---
read_when:
    - macOS UIなしでノードペアリング承認を実装する場合
    - リモートノード承認用のCLIフローを追加する場合
    - ノード管理でgatewayプロトコルを拡張する場合
summary: iOSおよびその他のリモートノード向けのGateway所有ノードペアリング（Option B）
title: Gateway所有ペアリング
x-i18n:
    generated_at: "2026-04-05T12:44:45Z"
    model: gpt-5.4
    provider: openai
    source_hash: 8f90818c84daeb190f27df7413e23362372806f2c4250e4954295fbf6df70233
    source_path: gateway/pairing.md
    workflow: 15
---

# Gateway所有ペアリング（Option B）

Gateway所有ペアリングでは、どのノードの参加を許可するかについて、**Gateway** が信頼できる唯一の情報源です。UI（macOSアプリ、将来のクライアント）は、保留中リクエストを承認または拒否するためのフロントエンドにすぎません。

**重要:** WSノードは、`connect` 時に**デバイスペアリング**（role `node`）を使用します。
`node.pair.*` は別のペアリングストアであり、WSハンドシェイクを制御しません。
このフローを使うのは、明示的に `node.pair.*` を呼び出すクライアントだけです。

## 概念

- **保留中リクエスト**: ノードが参加を要求した状態。承認が必要です。
- **ペアリング済みノード**: 承認され、認証トークンが発行されたノード。
- **トランスポート**: Gateway WSエンドポイントはリクエストを転送しますが、参加可否は決定しません。（レガシーTCP bridgeサポートは削除されました。）

## ペアリングの仕組み

1. ノードがGateway WSに接続し、ペアリングを要求します。
2. Gatewayが**保留中リクエスト**を保存し、`node.pair.requested` を発行します。
3. リクエストを承認または拒否します（CLIまたはUI）。
4. 承認時、Gatewayは**新しいトークン**を発行します（再ペアリング時にはトークンがローテーションされます）。
5. ノードはそのトークンを使って再接続し、「ペアリング済み」になります。

保留中リクエストは**5分**後に自動的に期限切れになります。

## CLIワークフロー（ヘッドレス対応）

```bash
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
```

`nodes status` は、ペアリング済み/接続済みノードとそのcapabilitiesを表示します。

## APIインターフェース（gatewayプロトコル）

イベント:

- `node.pair.requested` — 新しい保留中リクエストが作成されたときに発行されます。
- `node.pair.resolved` — リクエストが承認/拒否/期限切れになったときに発行されます。

メソッド:

- `node.pair.request` — 保留中リクエストを作成または再利用します。
- `node.pair.list` — 保留中 + ペアリング済みノードを一覧表示します（`operator.pairing`）。
- `node.pair.approve` — 保留中リクエストを承認します（トークンを発行）。
- `node.pair.reject` — 保留中リクエストを拒否します。
- `node.pair.verify` — `{ nodeId, token }` を検証します。

注:

- `node.pair.request` はノードごとに冪等です。繰り返し呼び出しても同じ保留中リクエストが返されます。
- 同じ保留中ノードに対する繰り返しリクエストでは、保存済みノードメタデータと、オペレーター可視化用の最新のallowlist済み宣言コマンドスナップショットも更新されます。
- 承認では**常に**新しいトークンが生成されます。`node.pair.request` からトークンが返されることはありません。
- リクエストには、自動承認フローのヒントとして `silent: true` を含めることができます。
- `node.pair.approve` は、保留中リクエストの宣言済みコマンドを使って追加承認スコープを適用します:
  - コマンドなしリクエスト: `operator.pairing`
  - `exec` 以外のコマンドリクエスト: `operator.pairing` + `operator.write`
  - `system.run` / `system.run.prepare` / `system.which` リクエスト:
    `operator.pairing` + `operator.admin`

重要:

- ノードペアリングは、信頼/IDフローとトークン発行です。
- これは、ノードごとのライブなノードコマンドインターフェースを固定するものでは**ありません**。
- ライブなノードコマンドは、Gatewayのグローバルなノードコマンドポリシー（`gateway.nodes.allowCommands` /
  `denyCommands`）適用後に、ノードが接続時に宣言した内容から決まります。
- ノードごとの `system.run` のallow/askポリシーは、ペアリングレコードではなく、ノード上の
  `exec.approvals.node.*` にあります。

## ノードコマンドのゲーティング（2026.3.31以降）

<Warning>
**破壊的変更:** `2026.3.31` 以降、ノードペアリングが承認されるまでノードコマンドは無効になります。デバイスペアリングだけでは、宣言されたノードコマンドを公開するのに不十分になりました。
</Warning>

ノードが初めて接続すると、ペアリングが自動的に要求されます。ペアリングリクエストが承認されるまで、そのノードからの保留中ノードコマンドはすべてフィルタリングされ、実行されません。ペアリング承認によって信頼が確立されると、ノードが宣言したコマンドは通常のコマンドポリシーに従って利用可能になります。

これは次を意味します:

- 以前はデバイスペアリングのみでコマンドを公開していたノードも、今後はノードペアリングを完了する必要があります。
- ペアリング承認前にキューに入れられたコマンドは延期されず、破棄されます。

## ノードイベントの信頼境界（2026.3.31以降）

<Warning>
**破壊的変更:** ノード起点の実行は、より制限された信頼済みインターフェースにとどまるようになりました。
</Warning>

ノード起点の要約と関連するセッションイベントは、意図された信頼済みインターフェースに制限されます。以前はより広いホストまたはセッションのツールアクセスに依存していた通知駆動またはノード起点のフローは、調整が必要になる場合があります。このハードニングにより、ノードイベントが、そのノードの信頼境界を超えてホストレベルのツールアクセスへ昇格することを防ぎます。

## 自動承認（macOSアプリ）

macOSアプリは、次の場合に**サイレント承認**を試行できます:

- リクエストが `silent` とマークされており、
- アプリが同じユーザーを使ったgateway hostへのSSH接続を確認できる場合。

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

## ストレージ（ローカル、プライベート）

ペアリング状態はGatewayのstate directory配下に保存されます（デフォルトは `~/.openclaw`）:

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

`OPENCLAW_STATE_DIR` を上書きすると、`nodes/` フォルダーもそれに合わせて移動します。

セキュリティ上の注意:

- トークンはシークレットです。`paired.json` は機密として扱ってください。
- トークンのローテーションには再承認（またはノードエントリーの削除）が必要です。

## トランスポートの動作

- トランスポートは**ステートレス**であり、参加情報を保存しません。
- Gatewayがオフライン、またはペアリングが無効な場合、ノードはペアリングできません。
- Gatewayがremote modeでも、ペアリングは引き続きリモートGatewayのストアに対して行われます。
