「OpenClaw Pairing Required」エラーを openclaw doctor --fix で修正する（2026）

ブラウザを開いて OpenClaw インスタンスにアクセスすると、見慣れたチャットインターフェースの代わりに以下が表示されます：

Pairing Required
Enter the pairing code displayed in your terminal.

さらに悪いことに、Telegram ボットが突然応答しなくなり、ログに以下が表示されます：

WARN  device not paired — rejecting connection from device abc123

これは OpenClaw のデバイスペアリングシステムが設計通りに動作しています：認識されていない接続を拒否しています。幸いなことに、何が起きたかを理解すれば約30秒で修正できます。

なぜ OpenClaw にはデバイスペアリングがあるのか

OpenClaw はメール、カレンダー、ファイル、潜在的に機密性の高いデータにアクセスする個人アシスタントとして動作します。デバイスペアリングは、明示的に承認したデバイスのみがゲートウェイに接続できることを保証するセキュリティメカニズムです^[1]。

新しいデバイス（ブラウザ、Telegram クライアント、API 接続）が初めてゲートウェイに接続すると、「保留中」状態に置かれます。コマンドラインから承認するまで、デバイスはメッセージの送受信ができません。これにより、誰かがゲートウェイ URL を発見しても不正アクセスが防止されます。

「Pairing Required」が表示されるタイミングと理由

このエラーはいくつかのシナリオで表示されます。どれに該当するかを理解することが最速の修正方法を決めます。

シナリオ1：新しいブラウザまたはデバイス

最も明白なケースです。一度もペアリングされたことのないデバイスから接続しています — 新しいラップトップ、スマートフォン、または OpenClaw で使用していないブラウザ。

シナリオ2：ブラウザの Cookie やデータをクリアした

OpenClaw はデバイストークンをブラウザのローカルストレージに保存します。Cookie やサイトデータをクリアしたり、プライバシークリーナーを実行したり、シークレットモードを使用すると、デバイストークンが消えます。ゲートウェイはあなたを新しいデバイスとして認識します。

シナリオ3：OPENCLAW_GATEWAY_TOKEN なしのコンテナ再起動

最も一般的な原因で、最も見落としがちです。Docker デプロイメントでは、OPENCLAW_GATEWAY_TOKEN 環境変数が明示的に設定されていない限り、ゲートウェイはコンテナ再起動のたびに認証トークンを再生成します^[2]。トークンが変わると、以前にペアリングされたすべてのデバイスがゲートウェイにとって「不明」になります。古いトークンをまだ提示しているためです。

シナリオ4：アップデート後のゲートウェイトークン不一致

OpenClaw のアップデート後、内部トークンフォーマットが変更されることがあります。既存のデバイスペアリングが無効になる可能性があります。

シナリオ5：リバースプロキシによるヘッダーの除去

Nginx、Caddy、または別のリバースプロキシの背後で OpenClaw を実行している場合、設定ミスにより X-Device-Token ヘッダーが除去されることがあります。ゲートウェイはデバイスの資格情報を受け取らないため、すべてのリクエストを新しい未ペアリングデバイスとして扱います。

修正1：openclaw doctor --fix（推奨）

最速の解決方法です。openclaw doctor コマンドがペアリング問題を検出し、--fix フラグが自動的に解決します：

openclaw doctor --fix

出力例：

CHECK  device pairing status
FAIL   2 devices pending approval
FIX    approving all pending devices...
OK     2 devices approved

CHECK  gateway token consistency
FAIL   device token mismatch detected
FIX    regenerating tokens and re-pairing...
OK     tokens synchronized

--fix フラグは、保留中のデバイス承認とトークン不一致の両方を1パスで処理します。実行後、ブラウザを更新するか Telegram クライアントを再起動してください。

修正2：手動デバイス承認

デバイスを個別に承認したい場合（各接続を確認したい場合に推奨）：

# すべてのデバイスとステータスをリスト
openclaw devices list

出力：

ID          STATUS     TYPE       LAST SEEN
abc123      pending    browser    2026-02-24 10:30
def456      approved   telegram   2026-02-24 09:15
ghi789      pending    browser    2026-02-24 10:32

特定のデバイスを承認：

# デバイス ID で承認
openclaw devices approve abc123

# すべての保留中デバイスを一括承認
openclaw devices approve --all

Telegram ペアリングには、ペアリングコードフローが必要な場合があります：

# ボットから Telegram ペアリングコードを取得
# その後承認
openclaw pairing approve telegram <CODE>

修正3：OPENCLAW_GATEWAY_TOKEN を設定する（再発防止）

Docker で実行していてコンテナ再起動後にエラーが繰り返す場合、これが恒久的な修正です：

# 安定したトークンを生成
openssl rand -hex 32

Docker run コマンドまたは docker-compose ファイルに設定：

# docker-compose.yml
services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your_generated_token_here
    volumes:
      - openclaw_data:/data

または docker run で：

docker run -d \
  -e OPENCLAW_GATEWAY_TOKEN=your_generated_token_here \
  -v openclaw_data:/data \
  openclaw-stack

この変数を設定すると、ゲートウェイは再起動を跨いで同じトークンを使用し、デバイスペアリングが維持されます^[3]。

修正4：リバースプロキシ設定の確認

OPENCLAW_GATEWAY_TOKEN を設定してもデバイスが再ペアリングを必要とし続ける場合、リバースプロキシがデバイストークンヘッダーを除去している可能性があります。

Caddy の場合：

yourdomain.com {
    reverse_proxy localhost:3001 {
        # WebSocket アップグレードの動作を確認
        header_up X-Real-IP {remote_host}
    }
}

Caddy はデフォルトですべてのヘッダーを通すので、これが原因であることはまれです。ただし、WebSocket アップグレードが機能していることを確認してください。ゲートウェイは永続接続に WebSocket を使用します。

Nginx の場合：

location / {
    proxy_pass http://localhost:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    # 重要：カスタムヘッダーを除去しない
    proxy_pass_request_headers on;
}

また、OpenClaw で gateway.trustedProxies が設定されていることを確認：

openclaw config set gateway.trustedProxies '["127.0.0.1"]'
openclaw restart

予防策：再発を防ぐ

当面のエラーを解決したら、再発を防ぐために以下の手順を実施してください：

1. Docker では常に OPENCLAW_GATEWAY_TOKEN を設定する

これはいくら強調しても足りません。コンテナ化されたデプロイメントで繰り返しペアリング問題が発生する最も一般的な原因です。

2. OpenClaw ドメインのサイトデータクリアを避ける

ブラウザクリーニングツールを使用している場合、OpenClaw ドメインを除外リストに追加してください。ローカルストレージに保存されたデバイストークンはペアリングの維持に不可欠です。

3. 専用のブラウザプロファイルを使用する

OpenClaw 専用のブラウザプロファイルの作成を検討してください。これにより、通常のブラウジングクリーンアップルーティンからデータが分離されます。

4. openclaw doctor で監視する

定期的に openclaw doctor を実行（または cron ジョブを設定）して、問題が発生する前に検出してください：

# 毎日のヘルスチェック用に crontab に追加
0 8 * * * openclaw doctor >> /var/log/openclaw-health.log 2>&1

マネージドホスティングならこの問題を完全に回避

デバイスペアリングシステムは、インターネットに公開される可能性のあるセルフホストインスタンスを保護するために存在します。ClawTank を通じたマネージドホスティングでは、ゲートウェイトークン、リバースプロキシヘッダー、デバイス管理がすべて自動的に処理されます。ペアリングインフラは存在しますが、初期ペアリングはワンクリックセットアッププロセス中に完了します。「pairing required」画面が表示されることはありません。

クイックリファレンス

参考文献

1. OpenClaw Security Model -- Device Pairing
2. OpenClaw Docker Environment Variables
3. OpenClaw Gateway Token Persistence