---
read_when:
    - macOS UIなしでノードペアリング承認を実装する
    - リモートノードを承認するための CLI フローの追加
    - ノード管理による Gateway プロトコルの拡張
summary: Gateway が所有する iOS およびその他のリモートノード向けノードペアリング（オプション B）
title: Gateway が所有するペアリング
x-i18n:
    generated_at: "2026-06-27T11:32:36Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: aefddafaef419fc59b04ee17dae8ef21685b4f514f4286530bf07362663a8996
    source_path: gateway/pairing.md
    workflow: 16
---

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

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

## 概念

- **保留中のリクエスト**: ノードが参加を要求した状態。承認が必要です。
- **ペアリング済みノード**: 発行済み認証トークンを持つ、承認済みのノード。
- **トランスポート**: Gateway WS エンドポイントはリクエストを転送しますが、メンバーシップは判断しません。（レガシー TCP ブリッジサポートは削除されました。）

## ペアリングの仕組み

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 remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
```

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

## API サーフェス（gateway protocol）

イベント:

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

メソッド:

- `node.pair.request` - 保留中のリクエストを作成または再利用します。
- `node.pair.list` - 保留中 + ペアリング済みノードを一覧表示します（`operator.pairing`）。
- `node.pair.approve` - 保留中のリクエストを承認します（トークンを発行）。
- `node.pair.reject` - 保留中のリクエストを拒否します。
- `node.pair.remove` - ペアリング済みノードを削除します。デバイスに基づくペアリングでは、これによりデバイスの `node` ロールが取り消されます。つまり、`devices/paired.json` を変更し、そのデバイスの node-role セッションを無効化/切断します。**混在ロール** のデバイス（例: `operator` も保持している）は行を維持し、`node` ロールだけを失います。node のみのデバイス行は削除されます。また、一致するレガシーの gateway 所有ノードペアリングエントリも削除します。Authz: `operator.pairing` は非 operator ノード行を削除できます。デバイストークン呼び出し元が混在ロールデバイス上の **自身の** node ロールを取り消す場合は、追加で `operator.admin` が必要です。
- `node.pair.verify` - `{ nodeId, token }` を検証します。

注記:

- `node.pair.request` はノードごとに冪等です。繰り返し呼び出すと同じ保留中のリクエストが返されます。
- 同じ保留中ノードへの繰り返しリクエストでは、保存されたノードメタデータと、operator の可視性のための最新の許可リスト済み宣言コマンドスナップショットも更新されます。
- 承認では **常に** 新しいトークンが生成されます。`node.pair.request` からトークンが返されることはありません。
- Operator スコープレベルと承認時チェックは [Operator スコープ](/ja-JP/gateway/operator-scopes) に要約されています。
- リクエストには、自動承認フローのヒントとして `silent: true` を含めることができます。
- `node.pair.approve` は、保留中リクエストの宣言コマンドを使用して、追加の承認スコープを強制します:
  - コマンドなしリクエスト: `operator.pairing`
  - 非 exec コマンドリクエスト: `operator.pairing` + `operator.write`
  - `system.run` / `system.run.prepare` / `system.which` リクエスト:
    `operator.pairing` + `operator.admin`

<Warning>
ノードペアリングは、信頼と ID のフローに加えてトークン発行を行うものです。ノードごとのライブノードコマンドサーフェスを固定するものでは **ありません**。

- ライブノードコマンドは、gateway のグローバルノードコマンドポリシー（`gateway.nodes.allowCommands` と `denyCommands`）が適用された後に、ノードが接続時に宣言する内容から取得されます。
- ノードごとの `system.run` の許可および確認ポリシーは、ペアリングレコードではなく、ノード上の `exec.approvals.node.*` に存在します。

</Warning>

## ノードコマンドゲート（2026.3.31+）

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

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

これは次を意味します:

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

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

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

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

永続的なノードプレゼンス更新も同じ ID 境界に従います。`node.presence.alive` イベントは、認証済みノードデバイスセッションからのみ受け付けられ、デバイス/ノード ID がすでにペアリング済みの場合にのみペアリングメタデータを更新します。自己宣言された `client.id` 値だけでは、last-seen 状態を書き込むのに十分ではありません。

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

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

- リクエストが `silent` とマークされている、かつ
- アプリが同じユーザーを使用して Gateway ホストへの SSH 接続を検証できる。

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

## 信頼済み CIDR デバイス自動承認

`role: node` の WS デバイスペアリングは、デフォルトでは手動のままです。Gateway がすでにネットワークパスを信頼しているプライベートノードネットワークでは、operator は明示的な CIDR または正確な IP を指定してオプトインできます:

```json5
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
```

セキュリティ境界:

- `gateway.nodes.pairing.autoApproveCidrs` が未設定の場合は無効です。
- 包括的な LAN またはプライベートネットワーク自動承認モードは存在しません。
- 要求スコープのない新規の `role: node` デバイスペアリングのみが対象です。
- Operator、ブラウザー、Control UI、WebChat クライアントは手動のままです。
- ロール、スコープ、メタデータ、公開鍵のアップグレードは手動のままです。
- 同一ホストのループバック信頼済みプロキシヘッダーパスは、そのパスがローカル呼び出し元によって偽装される可能性があるため対象外です。

## メタデータアップグレードの自動承認

すでにペアリング済みのデバイスが、機微でないメタデータ変更のみ（例: 表示名やクライアントプラットフォームのヒント）で再接続した場合、OpenClaw はそれを `metadata-upgrade` として扱います。サイレント自動承認は限定的です。OS バージョンメタデータ変更後の同一ホストネイティブアプリの再接続を含め、ローカルまたは共有資格情報の所持をすでに証明している、信頼済みの非ブラウザーローカル再接続にのみ適用されます。ブラウザー/Control UI クライアントとリモートクライアントは、引き続き明示的な再承認フローを使用します。スコープアップグレード（read から write/admin）と公開鍵の変更は、メタデータアップグレード自動承認の対象 **ではありません**。これらは明示的な再承認リクエストのままです。

## QR ペアリングヘルパー

`/pair qr` は、モバイルクライアントとブラウザークライアントが直接スキャンできるように、ペアリングペイロードを構造化メディアとしてレンダリングします。

デバイスを削除すると、そのデバイス ID に対する古い保留中ペアリングリクエストも一掃されるため、取り消し後に `nodes pending` が孤立した行を表示することはありません。

## ローカリティと転送ヘッダー

Gateway ペアリングは、生のソケットと上流プロキシの証拠の両方が一致する場合にのみ、接続をループバックとして扱います。リクエストがループバックで到着しても、`Forwarded`、任意の `X-Forwarded-*`、または `X-Real-IP` ヘッダーの証拠を含む場合、その転送ヘッダーの証拠によりループバックローカリティの主張は失格になります。その場合、ペアリングパスは、リクエストを同一ホスト接続としてサイレントに扱うのではなく、明示的な承認を要求します。operator 認証における同等のルールについては、[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth) を参照してください。

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

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

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

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

セキュリティ注記:

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

## トランスポート動作

- トランスポートは **ステートレス** です。メンバーシップを保存しません。
- Gateway がオフライン、またはペアリングが無効な場合、ノードはペアリングできません。
- Gateway がリモートモードの場合でも、ペアリングはリモート Gateway のストアに対して行われます。

## 関連

- [チャネルペアリング](/ja-JP/channels/pairing)
- [ノード](/ja-JP/nodes)
- [Devices CLI](/ja-JP/cli/devices)