OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Node ペアリング

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

  • デバイスペアリング（ロール node）は、connect ハンドシェイクを制御します。以下の 信頼済み CIDR によるデバイスの自動承認 および チャネルペアリングを参照してください。
  • 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 pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw 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 はオペレーター以外の Node 行を削除できます。複数ロールデバイスで 自身の Node ロールを取り消すデバイストークン呼び出し元には、追加で operator.admin が必要です。
  • node.rename - ペアリング済み Node の、オペレーター向け表示名を変更します。

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

注：

  • サーフェスが変更されていない再接続では、保留中のリクエストが再利用されます。リクエストが繰り返されると、 保存済みの Node メタデータと、オペレーターが確認できる最新の許可リスト登録済み 宣言コマンドのスナップショットが更新されます。
  • オペレーターのスコープレベルと承認時のチェックについては、 オペレータースコープにまとめられています。
  • node.pair.approve は保留中のリクエストで宣言されたコマンドを使用し、 追加の承認スコープを適用します。
    • コマンドなしのリクエスト：operator.pairing
    • 通常のコマンドリクエスト：operator.pairing + operator.write
    • system.run、system.run.prepare、 system.which、browser.proxy、fs.listDir、または system.execApprovals.get/set を含む管理上機密性の高いリクエスト：operator.pairing + operator.admin

Node コマンドのゲート制御（2026.3.31 以降）

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

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

  • 以前はコマンドの公開にデバイスペアリングだけを利用していた Node も、 今後は Node ペアリングを完了する必要があります。
  • ペアリングの承認前にキューへ入れられたコマンドは、保留されず破棄されます。

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

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

永続的な Node プレゼンスの更新も同じ ID 境界に従います。 node.presence.alive イベントは、認証済み Node デバイス セッションからのみ受け付けられ、デバイス／Node の ID がすでに ペアリング済みの場合にのみペアリングメタデータを更新します。自己申告された 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 も使用可能）、ホスト鍵が すでに信頼されていること。
  • openclaw が、非対話的な sh -lc のためにリモート PATH 上で解決されること。
  • 接続元 IP が、直接接続された（プロキシ経由でもループバックでもない）プライベート、ULA、 リンクローカル、または CGNAT アドレスであるか、設定時に sshVerify.cidrs と一致すること。
  • 信頼済み CIDR の承認と同じ適格性の下限：スコープのない新規 Node ペアリングのみ。アップグレード、ブラウザー、Control UI、WebChat では常にプロンプトが表示されます。

プローブの実行中、Node クライアントには、手動承認のために一時停止するのではなく、 再試行を続けるよう通知されます（wait_then_retry）。プローブが 失敗した場合、次回の試行は通常のプロンプトフローにフォールバックします。失敗したターゲットには、 短いクールダウンが適用されます（鍵の不一致後 5 分間）。

承認済みデバイスには approvedVia: "ssh-verified" が記録され、最初に宣言された ケイパビリティサーフェスも同じ手順で承認されます。鍵の一致により、その Node が オペレーターの所有するマシン上でオペレーターのアカウントとして実行されていることがすでに証明されます。これは 手動でのケイパビリティ承認が表明する内容と同じです。それ以降のサーフェスのアップグレードでは、引き続き プロンプトが表示されます。

強化または無効化：

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 ネットワークでは、オペレーターは明示的な CIDR または正確な IP を指定して オプトインできます。

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

セキュリティ境界：

  • gateway.nodes.pairing.autoApproveCidrs が未設定の場合は無効になります。
  • LAN 全体またはプライベートネットワーク全体を自動承認するモードはありません。SSH 検証済みの 自動承認（上記）では暗号学的なデバイス鍵の一致が必要であり、 ネットワーク上の近接性だけに依存することはありません。
  • 要求されたスコープがない、新規の role: node デバイスペアリングリクエストのみが 対象になります。
  • オペレーター、ブラウザー、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 検証済みのペアリングは、表示メタデータがマシン ID ではない ホスト間で行われるため、自動的に削除されることはありません。それらには 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 ヘッダーの証拠が含まれている場合、 その転送ヘッダーの証拠によってループバックのローカリティという主張は無効になります。ペアリング経路では、 リクエストを同一ホストからの接続としてサイレントに扱う代わりに、明示的な承認が必要です。 オペレーター認証における同等のルールについては、 信頼済みプロキシ認証を参照してください。

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

ペアリング状態は、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 のストアに対してペアリングが行われます。

関連項目

Was this useful?
On this page

On this page