Configuration

ペアリング

「ペアリング」は、OpenClaw における明示的なアクセス承認手順です。次の 2 つの場面で使用されます。

DM ペアリング（ボットとの会話を許可する相手）
Node ペアリング（Gateway ネットワークへの参加を許可するデバイス／Node）

セキュリティの背景情報：セキュリティ

1) DM ペアリング（受信チャットへのアクセス）

チャンネルの DM ポリシーが pairing に設定されている場合、不明な送信者には短いコードが提示され、承認されるまでそのメッセージは処理されません。

デフォルトの DM ポリシーについては、セキュリティを参照してください。

dmPolicy: "open" が公開アクセスになるのは、有効な DM 許可リストに "*" が含まれている場合のみです。公開設定のセットアップと検証には、このワイルドカードが必要です。既存の状態に具体的な allowFrom エントリを持つ open が含まれている場合、ランタイムが許可するのは引き続きそれらの送信者のみであり、ペアリングストアで承認しても open のアクセス範囲は広がりません。

ペアリングコード：

8 文字、大文字、紛らわしい文字（0O1I）は不使用。
1 時間後に期限切れ。ボットがペアリングメッセージを送信するのは、新しいリクエストが作成されたときだけです（送信者ごとにおよそ 1 時間に 1 回）。
保留中の DM ペアリングリクエストは、チャンネルアカウントごとに 3 件までです。いずれかが期限切れになるか承認されるまで、それ以降のリクエストは無視されます。

Control UI から承認する

Settings → Channels → DM access requests を開きます。このキューには、DM ポリシーが pairing である設定済みのすべてのチャンネルアカウントから、保留中のリクエストがまとめて表示されます。チャンネルまたはアカウントで絞り込み、送信者 ID とメタデータを確認してから、 Approve を選択します。

承認によって付与されるのは、ダイレクトメッセージへのアクセスのみです。グループへのアクセスは付与されません。対応している場合、承認ダイアログには次の明示的なオプションも表示されます。

Notify the requester after approval
Also make this sender the first command owner。コマンド所有者が存在せず、Control UI セッションに operator.admin がある場合にのみ表示されます

保留中のリクエストを承認せずに削除するには、Dismiss を選択します。却下しても永続的にブロックされるわけではなく、送信者は後で再びアクセスをリクエストできます。

CLI から承認する

bash

openclaw pairing list telegramopenclaw pairing approve telegram &lt;CODE&gt;

同じチャンネルでリクエスト元に通知するには、--notify を追加します。複数アカウント対応チャンネルでは --account <id> を指定します。

Control UI の明示的なチェックボックスとは異なり、CLI はコマンド所有者が設定されていない場合、 telegram:123456789 のようなエントリを使用して commands.ownerAllowFrom を自動的に初期設定します。これにより、初回セットアップ時に、特権コマンドと実行承認プロンプトを扱う明示的な所有者が設定されます。所有者が存在した後は、以降のペアリング承認では DM アクセスのみが付与され、所有者が追加されることはありません。

対応チャンネル（ペアリングを宣言するインストール済みのチャンネル Plugin。openclaw-weixin などの外部 Plugin で追加可能）：discord、feishu、googlechat、imessage、irc、line、matrix、mattermost、msteams、nextcloud-talk、nostr、signal、slack、sms、synology-chat、telegram、twitch、whatsapp、zalo、zalouser。

再利用可能な送信者グループ

同じ信頼済み送信者の集合を複数のメッセージチャンネル、または DM とグループの両方の許可リストに適用する場合は、トップレベルの accessGroups を使用します。

静的グループでは type: "message.senders" を使用し、チャンネルの許可リストから accessGroup:<name> で参照します。

json5

{  accessGroups: {    operators: {      type: "message.senders",      members: {        discord: ["discord:123456789012345678"],        telegram: ["987654321"],        whatsapp: ["+15551234567"],      },    },  },  channels: {    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },  },}

アクセスグループの詳細については、アクセスグループを参照してください。

状態の保存場所

共有 SQLite 状態データベース ~/.openclaw/state/openclaw.sqlite に保存されます。

channel_pairing_requests 内の保留中リクエスト
channel_pairing_allow_entries 内の承認済み送信者

アカウントのスコープ動作：

各リクエストと承認済み送信者は、チャンネルとアカウントをキーとして管理されます
ランタイムは正規の SQLite 行のみを読み取り、レガシーファイルをマージしません

旧バージョンの Gateway は、~/.openclaw/credentials/ の下に <channel>-pairing.json と <channel>-<accountId>-allowFrom.json を書き込んでいました。起動時の移行と openclaw doctor --fix は、これらのファイルを SQLite にインポートし、インポートが成功すると各ソースを削除します。これらの行はアシスタントへのアクセスを制御するため、 SQLite データベースは機密情報として扱ってください。

2) Node デバイスのペアリング（iOS／Android／macOS／ヘッドレス Node）

Node は role: node を持つデバイスとして Gateway に接続します。Gateway は、承認が必要なデバイスペアリングリクエストを作成します。

Control UI からペアリングする（推奨）

operator.admin アクセスを持つ、接続済みの Control UI セッションを使用します。

Control UI を開き、Settings → Devices に移動します。
Devices ページで Pair mobile device をクリックします。
Full access (recommended) のままにするか、管理用 Gateway コントロールを除外するには Limited access を選択します。
Create setup code をクリックします。
スマートフォンで OpenClaw アプリを開き、Settings → Gateway に移動します。
QR コードをスキャンするかセットアップコードを貼り付けて、接続します。

公式の OpenClaw iOS／Android アプリは、セットアップコードのメタデータが一致すると自動的に承認されます。Pending approval にリクエストが表示された場合（たとえば、非公式クライアントやメタデータの不一致）、承認する前にロールとスコープを確認してください。

現在の Control UI セッションに管理者アクセスがない場合、ボタンは無効になります。その場合は、Gateway ホストから以下の CLI 承認フローを使用してください。

Telegram 経由でペアリングする

device-pair Plugin を使用している場合、初回のデバイスペアリングを Telegram だけで完了できます。

Telegram でボットに /pair とメッセージを送ります
ボットは 2 件のメッセージを返信します。1 件は手順のメッセージ、もう 1 件は独立したセットアップコードのメッセージです（Telegram で簡単にコピー＆ペーストできます）。
スマートフォンで OpenClaw iOS アプリを開き、Settings → Gateway に移動します。
QR コード（/pair qr）をスキャンするかセットアップコードを貼り付けて、接続します。
公式モバイルアプリは自動的に接続されます。/pair pending にリクエストが表示された場合は、承認する前にロールとスコープを確認してください。

セットアップコードは、次の内容を含む base64 エンコード済み JSON ペイロードです。

url：Gateway WebSocket URL（ws://... または wss://...）
urls：利用可能な場合に、モバイルアプリが順番に試行できる LAN／Tailnet ルート
bootstrapToken：初回ペアリングハンドシェイク用の 1 回限りのブートストラップトークン。Gateway は 10 分後に期限切れにします

ペアリングが完了したら、/pair cleanup を実行して未使用のセットアップコードを無効化します。

このブートストラップトークンには、組み込みのペアリング用ブートストラッププロファイルが含まれています。

安全な wss:// セットアップ（または同一ホストのループバック）では、デフォルトで node に加えて、完全なネイティブモバイル operator アクセスが付与されます
引き渡された node トークンは scopes: [] のままです
デフォルトで引き渡される operator トークンには、operator.admin、 operator.approvals、operator.read、operator.talk.secrets、および operator.write が含まれます
Control UI の Limited access と openclaw qr --limited では、他のオペレータースコープを維持しながら operator.admin が除外されます
平文 LAN ws:// セットアップでは、同じ制限付きプロファイルが自動的に使用されます。完全なアクセスを得るには、wss:// または Tailscale Serve を設定し、新しいコードを生成してください
以降のトークンのローテーション／取り消しは、デバイスで承認されたロール契約と、呼び出し元セッションのオペレータースコープの両方によって引き続き制限されます

セットアップコードが有効な間は、パスワードと同様に扱ってください。

iOS／Android の Settings → Gateway ページには、Full または Limited アクセスが表示されます。制限付きのスマートフォンをアップグレードするには、まず安全な wss:// または Tailscale Serve ルートを設定し、完全アクセス用の新しいセットアップコードを生成して、その設定ページでスキャンまたは貼り付けてから再接続します。

Tailscale、公開環境、またはその他のリモートモバイルペアリングには、Tailscale Serve／Funnel または別の wss:// Gateway URL を使用します。平文 ws:// セットアップコードが許可されるのは、 local loopback、プライベート LAN アドレス、.local Bonjour ホスト、および Android エミュレーターホストのみです。local loopback 以外の平文ルートには制限付きアクセスが付与されます。Tailnet CGNAT アドレス、.ts.net 名、および公開ホストについては、QR／セットアップコードが発行される前に引き続きフェイルクローズします。

gateway.bind=lan セットアップ URL の場合、OpenClaw は、アクティブな Gateway の local loopback ポートをプロキシする永続的な Tailscale Serve HTTPS ルートを検出し、LAN ルートとともに通知します。セットアップコマンドがこのフォールバックを追加するのは lan の場合のみです。custom と tailnet は、明示的に通知されたルートを維持します。 iOS アプリは通知されたルートを順番にプローブし、最初に到達できたエンドポイントを保存します。

Node デバイスを承認する

bash

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

ペアリング専用スコープで開かれたペアリング済みデバイスセッションによる明示的な承認が拒否された場合、CLI は同じリクエストを operator.admin で再試行します。これにより、既存の管理者権限を持つペアリング済みデバイスは、ペアリングストアを手動で編集せずに、新しい Control UI／ブラウザーのペアリングを復旧できます。 Gateway は再試行された接続も引き続き検証し、operator.admin で認証できないトークンはブロックされたままです。

同じデバイスが異なる認証情報（たとえば異なるロール／スコープ／公開鍵）で再試行すると、以前の保留中リクエストは置き換えられ、新しい requestId が作成されます。

信頼済み CIDR による Node の自動承認（任意）

デバイスのペアリングは、デフォルトでは手動のままです。厳密に管理された Node ネットワークでは、 CIDR または正確な IP を明示して、初回の Node 自動承認を有効にできます。

json5

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

これは、要求されたスコープがない新規の role: node ペアリングリクエストにのみ適用されます。オペレーター、ブラウザー、Control UI、および WebChat クライアントには、引き続き手動での承認が必要です。ロール、スコープ、メタデータ、および公開鍵の変更にも、引き続き手動での承認が必要です。

Node ペアリング状態の保存場所