Gateway-owned pairing の仕組みと導入ガイド

新しいデバイスやノードをネットワークに追加する際、どの接続を許可し、どれを拒否するかを管理するのは意外と面倒な作業です。セキュリティを担保しつつ、開発者が直感的に操作できる認証フローを構築するのは、多くのプロジェクトで共通の課題となります。

OpenClaw では、Gateway が「信頼できる唯一の情報源（Source of Truth）」として機能する Gateway-owned pairing を推奨しています。UI はあくまでリクエストを承認・却下するためのフロントエンドに過ぎず、すべての権限管理は Gateway 側で行われます。

必要なもの

OpenClaw Gateway
CLI ツール (openclaw)
WS node (role node)

クイックスタート

Gateway-owned pairing を 5 分でセットアップする最小の手順は以下の通りです。

ノードの接続: ノードから Gateway WS へ接続し、ペアリングをリクエストします。
リクエストの確認: CLI で保留中のリクエストを確認します。
Terminal window
```
openclaw nodes pending
```
リクエストの承認: 特定の requestId を指定して承認します。
Terminal window
```
openclaw nodes approve <requestId>
```
ステータスの確認: ノードが正しくペアリングされたか確認します。
Terminal window
```
openclaw nodes status
```

承認されると Gateway から新しいトークンが発行されます。ノードはそのトークンを使用して再接続することで、正式に「ペアリング済み」の状態となります。

主なコンセプト

Gateway-owned pairing を理解するための 4 つの要素を紹介します。

Pending request: 参加をリクエストし、承認を待っているノードの状態です。
Paired node: 承認され、認証トークンが発行されたノードです。
Transport: Gateway WS エンドポイントはリクエストを転送しますが、メンバーシップの決定は行いません。
Storage: ペアリング状態は Gateway のディレクトリ（デフォルトは ~/.openclaw）に保存されます。

CLI によるワークフロー

ヘッドレス環境でも操作しやすい CLI コマンドが用意されています。

# 保留中のリクエスト一覧を表示
openclaw nodes pending

# リクエストの承認と却下
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>

# 接続済みノードのステータスと機能を確認
openclaw nodes status

# ノードに分かりやすい名前を付ける
openclaw nodes rename --node &lt;id|name|ip&gt; --name "Living Room iPad"

API surface (gateway protocol)

API を介してペアリングを制御する場合、以下のイベントとメソッドを使用します。

Events

node.pair.requested: 新しい保留リクエストが作成された時に通知されます。
node.pair.resolved: リクエストが承認、却下、または期限切れになった時に通知されます。

Methods

node.pair.request: 保留中のリクエストを作成、または再利用します。
node.pair.list: 保留中およびペアリング済みのノードを一覧表示します。
node.pair.approve: リクエストを承認し、新しいトークンを発行します。
node.pair.reject: リクエストを却下します。

注意点として、承認時には常に新しいトークンが生成されます。node.pair.request からトークンが返されることはありません。

トラブルシューティング

よくある問題と解決策です。

リクエストが見つからない: 保留中のリクエストは 5 分間で自動的に期限切れになります。期限が切れた場合は、ノードから再度リクエストを送信してください。
ペアリングができない: Gateway がオフラインの場合や、ペアリング機能が無効化されている場合、ノードはペアリングを完了できません。
トークンの紛失: セキュリティのため、トークンは再発行（再承認）するか、paired.json のエントリを削除してやり直す必要があります。
保存場所の変更: OPENCLAW_STATE_DIR 環境変数を設定している場合、ペアリング情報は nodes/ フォルダと共にそのディレクトリへ移動します。

セットアップに関する不明点は AI Setup Assistant でいつでも質問してください。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。