---
read_when:
    - macOS UI を使用せずに Node ペアリング承認を実装する
    - リモート Node を承認するための CLI フローの追加
    - Node管理によるGatewayプロトコルの拡張
summary: Node 機能の承認：デバイスのペアリング後に Node でコマンドが利用可能になる仕組み
title: Node のペアリング
x-i18n:
    generated_at: "2026-07-11T22:16:43Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 753b01681fa9be17df853b63210f54374d054a6dde37746a3b5fda69073af71d
    source_path: gateway/pairing.md
    workflow: 16
---

Node ペアリングには 2 つのレイヤーがあり、どちらも Gateway の SQLite 状態データベース内にあるペアリング済みデバイスレコードに保存されます。

- **デバイスのペアリング**（ロール `node`）は `connect` ハンドシェイクを制御します。以下の
  [信頼済み CIDR によるデバイスの自動承認](#trusted-cidr-device-auto-approval)
  および [チャンネルのペアリング](/ja-JP/channels/pairing) を参照してください。
- **Node 機能の承認**（`node.pair.*`）は、接続された Node が公開できる、宣言済みの
  機能やコマンドを制御します。Gateway が信頼できる唯一の情報源であり、UI（macOS アプリ、Control UI）は保留中のリクエストを承認または
  拒否するフロントエンドです。

以前の独立した Node ペアリングストア（Node ごとのトークンを含む `nodes/paired.json`。
2026 年 1 月に接続経路から廃止）は削除されました。Gateway は起動時に一度だけ、
残っている行をデバイスレコードへ統合し、従来のファイルを `.migrated` サフィックス付きで
アーカイブします。従来の TCP ブリッジ対応も削除されました。

## 機能の承認の仕組み

1. Node が Gateway WS に接続します（この手順はデバイスのペアリングによって制御されます）。
2. Gateway は、宣言された機能やコマンドの範囲を承認済みの範囲と比較します。新しい範囲または拡張された範囲がある場合、デバイスレコードに
   **保留中のリクエスト**を保存し、`node.pair.requested` を発行します。
3. リクエストを承認または拒否します（CLI または UI）。
4. 承認されるまで Node コマンドはフィルタリングされたままです。承認されると、通常のコマンドポリシーに従って、宣言された
   範囲が公開されます。

保留中のリクエストは、**Node が最後に再試行してから 5 分後**に自動的に期限切れになります。再接続を続けている Node では、試行ごとに新しいリクエスト（および承認プロンプト）を生成せず、
1 件の保留中リクエストが維持されます。

## 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` は、ペアリング済みまたは接続済みの Node と、その機能を表示します。

## API サーフェス（Gateway プロトコル）

イベント：

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

メソッド：

- `node.pair.list` - 保留中およびペアリング済みの Node を一覧表示します（`operator.pairing`）。
- `node.pair.approve` - 保留中のリクエストを承認します。
- `node.pair.reject` - 保留中のリクエストを拒否します。
- `node.pair.remove` - ペアリング済みの Node を削除します。ペアリング済みデバイスストアでデバイスの `node`
  ロールを取り消し、それに伴って承認済みの Node サーフェスを削除し、
  そのデバイスの Node ロールセッションを無効化して切断します。**複数ロール**の
  デバイス（たとえば `operator` も保持するデバイス）は行が保持され、`node`
  ロールのみを失います。Node 専用デバイスの行は削除されます。認可：
  `operator.pairing` は、operator ではない Node の行を削除できます。デバイストークンを使用する呼び出し元が、複数ロールのデバイスで
  **自身の** Node ロールを取り消すには、追加で
  `operator.admin` が必要です。
- `node.rename` - ペアリング済み Node の、operator に表示される表示名を変更します。

2026.7 で削除：`node.pair.request` および `node.pair.verify`。保留中の
リクエストは Node の接続時に Gateway 自身によって作成され、それらが使用していた
独立した Node ごとのトークンは存在しなくなりました。Node の認証には
デバイスのペアリングトークンが使用されます。

注：

- サーフェスが変更されていない再接続では、保留中のリクエストが再利用されます。リクエストを繰り返すと、
  operator が確認できるように、保存されている Node メタデータと、許可リストに含まれる最新の
  宣言済みコマンドのスナップショットが更新されます。
- operator のスコープレベルと承認時のチェックについては、
  [operator スコープ](/ja-JP/gateway/operator-scopes) にまとめられています。
- `node.pair.approve` は、保留中のリクエストで宣言されたコマンドを使用して、
  追加の承認スコープを適用します。
  - コマンドを含まないリクエスト：`operator.pairing`
  - 実行系ではないコマンドのリクエスト：`operator.pairing` + `operator.write`
  - `system.run` / `system.run.prepare` / `system.which` のリクエスト：
    `operator.pairing` + `operator.admin`

<Warning>
Node ペアリングの承認では、信頼する機能サーフェスが記録されます。Node ごとに稼働中の Node コマンドサーフェスを固定するものでは**ありません**。

- 稼働中の Node コマンドは、Node が接続時に宣言した内容を基にし、
  Gateway のグローバル Node コマンドポリシー（`gateway.nodes.allowCommands` および
  `denyCommands`）によってフィルタリングされます。
- Node ごとの `system.run` の許可ポリシーと確認ポリシーは、ペアリングレコードではなく、
  Node 上の `exec.approvals.node.*` に保存されます。

</Warning>

## Node コマンドの制御（2026.3.31 以降）

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

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

これは次のことを意味します。

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

## Node イベントの信頼境界（2026.3.31 以降）

<Warning>
**破壊的変更：** Node から開始された実行は、範囲が縮小された信頼済みサーフェス内に限定されるようになりました。
</Warning>

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

永続的な Node の存在状態の更新にも、同じ識別情報の境界が適用されます。
`node.presence.alive` イベントは、認証済みの Node デバイスセッションからのみ受け入れられ、
デバイスと Node の識別情報がすでにペアリングされている場合に限り、ペアリングメタデータを更新します。自己申告された `client.id` の値だけでは、
最終確認状態を書き込めません。

## SSH 検証済みデバイスの自動承認（デフォルト）

プライベートアドレスまたは CGNAT アドレスから初めて行われる `role: node` のデバイスペアリングは、
Gateway が **SSH 経由でマシンの所有を証明できる**場合に自動承認されます。Gateway はペアリング元ホストへ接続し直し（`BatchMode`、`StrictHostKeyChecking=yes`）、
そこで `openclaw node identity --json` を実行し、リモートの
デバイス ID と公開鍵が保留中のリクエストに完全に一致する場合にのみ承認します。安全性を担保するのは鍵の一致です。到達可能であるだけでは承認されないため、NAT を共有する他の利用者、
共有ホスト上の他のユーザー、LAN スプーフィングはいずれも通常の
プロンプトへフォールバックします。

デフォルトで有効です。動作するための要件：

- Gateway プロセスのユーザー（または `sshVerify.user`）が、Node ホストへ
  非対話形式で SSH 接続でき（鍵またはエージェント。Tailscale SSH も使用可能）、ホスト鍵が
  すでに信頼されていること。
- 非対話形式の `sh -lc` で、リモートの `PATH` から `openclaw` を解決できること。
- 接続元 IP が、直接接続された（プロキシ経由でもループバックでもない）プライベート、ULA、
  リンクローカル、または CGNAT アドレスであるか、設定されている場合は `sshVerify.cidrs` に一致すること。
- 信頼済み CIDR による承認と同じ最低適格条件を満たすこと。つまり、スコープのない新規 Node
  ペアリングのみが対象です。アップグレード、ブラウザ、Control UI、WebChat では常にプロンプトが表示されます。

プローブの実行中、Node クライアントには手動承認を待って停止する代わりに、
再試行を続けるよう通知されます（`wait_then_retry`）。プローブが
失敗すると、次回の試行では通常のプロンプトフローへフォールバックします。失敗した接続先には、
短いクールダウンが適用されます（鍵の不一致から 5 分間）。

承認されたデバイスには `approvedVia: "ssh-verified"` が記録され、最初に宣言された
機能サーフェスも同じ手順で承認されます。鍵の一致によって、その Node が所有するマシン上で operator のアカウントを使用して実行されていることがすでに証明されるためです。これは、手動の機能承認が表明する内容と
同じです。後から行われるサーフェスのアップグレードでは、引き続きプロンプトが表示されます。

強化または無効化するには：

```json5
{
  gateway: {
    nodes: {
      pairing: {
        // 完全に無効化：
        sshVerify: false,
        // ...またはプローブの範囲や設定を調整：
        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
      },
    },
  },
}
```

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

macOS アプリは、次の条件を満たす場合に Node 機能リクエストの
**サイレント承認**を試行できます。

- リクエストが `silent` としてマークされていること（デバイスのペアリングが非対話形式で承認された場合、Gateway は最初の機能
  サーフェスをサイレントとしてマークします）。
- アプリが、同じ
  ユーザーを使用して Gateway ホストへの SSH 接続を検証できること。

サイレント承認に失敗すると、通常の Approve/Reject プロンプトへフォールバックします。

## 信頼済み CIDR によるデバイスの自動承認

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

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

セキュリティ境界：

- `gateway.nodes.pairing.autoApproveCidrs` が未設定の場合は無効です。
- LAN 全体またはプライベートネットワーク全体を一律に自動承認するモードはありません。SSH 検証済みの
  自動承認（上記）には暗号学的なデバイス鍵の一致が必要であり、
  ネットワーク上の近接性だけに依存することはありません。
- リクエストされたスコープがない、新規の `role: node` デバイスペアリングリクエストのみが
  対象です。
- operator、ブラウザ、Control UI、WebChat のクライアントは引き続き手動です。
- ロール、スコープ、メタデータ、公開鍵のアップグレードは引き続き手動です。
- 同一ホストのループバックを使用する信頼済みプロキシヘッダー経路は対象外です。この
  経路はローカルの呼び出し元によってスプーフィングされる可能性があるためです。

## サイレントペアリングの置き換えクリーンアップ

非対話形式の承認では、その由来がペアリング済みデバイスの行に記録されます。
同一ホストのローカルポリシーによる承認は `silent`、信頼済み CIDR による Node の承認は
`trusted-cidr`、SSH 検証済み Node の承認は `ssh-verified` です。状態ディレクトリが一時的なクライアント（一時ホーム、
コンテナ、実行ごとのサンドボックス）は、実行ごとに新しいデバイス鍵ペアを生成し、
実行のたびにまったく新しいデバイスとしてサイレントに再ペアリングされます。クリーンアップしなければ、ペアリング済みリストには実行ごとに古い行が 1 件ずつ
増えていきます。

Gateway が **ローカル**デバイスのペアリングをサイレント承認すると、
同じクライアントクラスターに属し
（`clientId`、`clientMode`、表示名が一致）、現在接続されていない、
以前の `silent` 承認済みレコードを廃止します。ローカルクライアントは Gateway ホスト自体で実行されるため、
このクラスターキーが別のマシンと一致することはありません。廃止された行のトークンは直ちに失効します。
一致する従来の Node ペアリングエントリも削除され、`node.pair.resolved`
削除イベントがブロードキャストされます。

境界：

- 最新の承認が同一ホストのローカル承認（`silent`）であるレコードだけが、
  トリガーおよび対象として適格です。信頼済み CIDR および SSH 検証済みのペアリングは
  ホストをまたぎ、その表示メタデータはマシンの識別情報ではないため、
  自動的には削除されません。これらには Control UI のクリーンアップまたは
  `openclaw nodes remove` を使用してください。
- 所有者が承認したペアリング、および QR コードやセットアップコードによる（ブートストラップ）ペアリングは、
  自動的に削除されません。承認元の記録機能が存在する前に承認されたレコードは、
  同じデバイス ID が後からサイレントに再承認された場合でも保護されます。
- 現在接続中のデバイスはスキップされるため、個別の状態ディレクトリを使用する同時実行中のローカルセッションでは、
  接続中はトークンが維持されます。直近 1 分以内に承認されたレコードも
  スキップされるため、同時に行われるペアリングハンドシェイクが、接続登録前に
  互いを廃止することはありません。
- 対象クライアントは構造上ローカルであるため、次回の接続時に
  サイレントに再ペアリングされます。

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

すでにペアリング済みのデバイスが、機密性のないメタデータの変更だけを伴って再接続した場合
（表示名やクライアントプラットフォームのヒントなど）、OpenClaw はそれを
`metadata-upgrade` として扱います。サイレント自動承認の適用範囲は限定的です。ローカル認証情報または共有認証情報の所有をすでに証明している、信頼済みかつブラウザではないローカル再接続にのみ
適用されます。これには、OS バージョンのメタデータ変更後に同一ホストのネイティブアプリが再接続する場合も含まれます。ブラウザや Control UI のクライアント、およびリモートクライアントでは、
引き続き明示的な再承認フローが使用されます。スコープのアップグレード（読み取りから
書き込みまたは管理者への変更）と公開鍵の変更は、メタデータアップグレードの自動承認の
対象では**ありません**。これらは引き続き明示的な再承認リクエストとして扱われます。

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

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

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

## ローカル性と転送ヘッダー

Gateway のペアリングでは、生のソケットと上流プロキシからの証拠の両方が一致する場合にのみ、接続をループバックとして扱います。リクエストがループバック経由で到着しても、`Forwarded`、いずれかの `X-Forwarded-*`、または `X-Real-IP` ヘッダーによる証拠が含まれている場合、その転送ヘッダーの証拠によってループバックのローカル性という判定は無効になります。この場合、ペアリング経路ではリクエストを同一ホストからの接続として暗黙に扱わず、明示的な承認を必要とします。オペレーター認証における同等のルールについては、[信頼済みプロキシ認証](/ja-JP/gateway/trusted-proxy-auth)を参照してください。

## ストレージ（ローカル、非公開）

ペアリング状態は、Gateway の状態ディレクトリ（デフォルトは `~/.openclaw`）配下にある共有 SQLite 状態データベース内の、ペアリング済みデバイスレコードに保存されます。

- `~/.openclaw/state/openclaw.sqlite`（デバイス認証情報を持つペアリング済みデバイス、承認済み Node サーフェス、保留中のサーフェスリクエスト、保留中のデバイスペアリングリクエスト、およびブートストラップトークン）

`OPENCLAW_STATE_DIR` を上書きすると、データベースもそのディレクトリへ移動します。JSON ストアを使用していたリリースからアップグレードした Gateway は、起動時にそれらをインポートし、`devices/*.json.migrated` および `nodes/*.json.migrated` のアーカイブを残します。

セキュリティ上の注意:

- デバイストークンはシークレットです。状態データベースは機密情報として扱ってください。
- デバイストークンのローテーションには、`openclaw devices rotate` / `device.token.rotate` を使用します。

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

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

## 関連項目

- [チャンネルのペアリング](/ja-JP/channels/pairing)
- [Node CLI](/ja-JP/cli/nodes)
- [デバイス CLI](/ja-JP/cli/devices)