WSL2 + Windows + リモート Chrome CDP トラブルシューティング

このガイドは、以下の一般的な分割ホスト構成を対象としています:

  • OpenClaw Gateway が WSL2 内で動作
  • Chrome が Windows 上で動作
  • ブラウザ制御が WSL2/Windows の境界を越える必要がある

また、Issue #39369 で報告されたレイヤード障害パターンも扱います。複数の独立した問題が同時に発生すると、誤ったレイヤーが最初に壊れているように見えることがあります。

まず正しいブラウザモードを選択する

有効なパターンは 2 つあります:

オプション 1: 生のリモート CDP

WSL2 から Windows Chrome の CDP エンドポイントを指すリモートブラウザプロファイルを使用します。

以下の場合に選択:

  • ブラウザ制御のみが必要
  • Chrome のリモートデバッグを WSL2 に公開することに問題がない
  • Chrome エクステンションリレーが不要

オプション 2: Chrome エクステンションリレー

組み込みの chrome プロファイルと OpenClaw Chrome エクステンションを使用します。

以下の場合に選択:

  • ツールバーボタンで既存の Windows Chrome タブにアタッチしたい
  • --remote-debugging-port ではなくエクステンションベースの制御を使いたい
  • リレー自体が WSL2/Windows の境界を越えてアクセス可能である必要がある

名前空間を越えてエクステンションリレーを使用する場合、ブラウザ と Chrome エクステンション で紹介されている browser.relayBindHost が重要な設定です。

動作するアーキテクチャ

参照構成:

  • WSL2 が 127.0.0.1:18789 で Gateway を実行
  • Windows が通常のブラウザで http://127.0.0.1:18789/ のコントロール UI を表示
  • Windows Chrome がポート 9222 で CDP エンドポイントを公開
  • WSL2 がその Windows CDP エンドポイントに到達可能
  • OpenClaw が WSL2 から到達可能なアドレスを指すブラウザプロファイルを設定

この構成が混乱しやすい理由

複数の障害が重なる可能性があります:

  • WSL2 が Windows CDP エンドポイントに到達できない
  • コントロール UI が非セキュアなオリジンから開かれている
  • gateway.controlUi.allowedOrigins がページのオリジンと一致しない
  • トークンまたはペアリングが欠落している
  • ブラウザプロファイルが誤ったアドレスを指している
  • エクステンションリレーがループバック専用のまま、実際にはクロスネームスペースアクセスが必要

そのため、1 つのレイヤーを修正しても別のエラーが残っていることがあります。

コントロール UI の重要なルール

Windows から UI を開く場合は、意図的な HTTPS 構成がない限り Windows の localhost を使用してください。

使用すべき URL:

http://127.0.0.1:18789/

コントロール UI にはデフォルトで LAN IP を使わないでください。LAN やテイルネットアドレスでの平文 HTTP は、CDP とは無関係な insecure-origin/device-auth 動作を引き起こす可能性があります。コントロール UI を参照してください。

レイヤーごとに検証する

上から順に進めてください。先にスキップしないでください。

レイヤー 1: Windows で Chrome が CDP を提供していることを確認

Windows でリモートデバッグを有効にして Chrome を起動:

chrome.exe --remote-debugging-port=9222

まず Windows 側で Chrome 自体を確認:

curl http://127.0.0.1:9222/json/version
curl http://127.0.0.1:9222/json/list

Windows 側で失敗する場合、OpenClaw はまだ問題ではありません。

レイヤー 2: WSL2 から Windows エンドポイントに到達できることを確認

WSL2 から、cdpUrl で使用予定のアドレスをテスト:

curl http://WINDOWS_HOST_OR_IP:9222/json/version
curl http://WINDOWS_HOST_OR_IP:9222/json/list

成功時の結果:

  • /json/version が Browser / Protocol-Version メタデータを含む JSON を返す
  • /json/list が JSON を返す（ページが開かれていなければ空配列でも OK）

失敗する場合:

  • Windows がまだ WSL2 にポートを公開していない
  • WSL2 側のアドレスが間違っている
  • ファイアウォール / ポート転送 / ローカルプロキシがまだ設定されていない

OpenClaw の設定を変更する前にこの問題を解決してください。

レイヤー 3: 正しいブラウザプロファイルを設定

生のリモート CDP の場合、WSL2 から到達可能なアドレスを OpenClaw に指定:

{
  browser: {
    enabled: true,
    defaultProfile: "remote",
    profiles: {
      remote: {
        cdpUrl: "http://WINDOWS_HOST_OR_IP:9222",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

注意点:

  • Windows でのみ動作するアドレスではなく、WSL2 から到達可能なアドレスを使用
  • 外部管理ブラウザには attachOnly: true を維持
  • OpenClaw での成功を期待する前に、同じ URL で curl テストを実施

レイヤー 4: Chrome エクステンションリレーを使用する場合

ブラウザマシンと Gateway が名前空間の境界で分離されている場合、リレーに非ループバックのバインドアドレスが必要になる場合があります。

例:

{
  browser: {
    enabled: true,
    defaultProfile: "chrome",
    relayBindHost: "0.0.0.0",
  },
}

必要な場合にのみ使用してください:

  • デフォルト動作はリレーがループバック専用なので安全
  • 0.0.0.0 は公開範囲を拡大する
  • Gateway 認証、ノードペアリング、周辺ネットワークをプライベートに保つ

エクステンションリレーが不要な場合は、上記の生のリモート CDP プロファイルを推奨します。

レイヤー 5: コントロール UI レイヤーを個別に検証

Windows から UI を開く:

http://127.0.0.1:18789/

確認事項:

  • ページのオリジンが gateway.controlUi.allowedOrigins の期待と一致している
  • トークン認証またはペアリングが正しく設定されている
  • コントロール UI の認証問題をブラウザの問題としてデバッグしていない

関連ページ:

レイヤー 6: エンドツーエンドのブラウザ制御を検証

WSL2 から:

openclaw browser open https://example.com --browser-profile remote
openclaw browser tabs --browser-profile remote

エクステンションリレーの場合:

openclaw browser tabs --browser-profile chrome

成功時の結果:

  • Windows Chrome でタブが開く
  • openclaw browser tabs がターゲットを返す
  • 以降のアクション（snapshot、screenshot、navigate）が同じプロファイルで動作する

よくある誤解を招くエラー

各メッセージをレイヤー固有の手がかりとして扱ってください:

  • control-ui-insecure-auth
    • UI のオリジン / セキュアコンテキストの問題であり、CDP トランスポートの問題ではない
  • token_missing
    • 認証設定の問題
  • pairing required
    • デバイス承認の問題
  • Remote CDP for profile "remote" is not reachable
    • WSL2 が設定された cdpUrl に到達できない
  • gateway timeout after 1500ms
    • 多くの場合 CDP の到達性の問題、または低速/到達不能なリモートエンドポイント
  • Chrome extension relay is running, but no tab is connected
    • エクステンションリレープロファイルが選択されているが、アタッチされたタブがまだない

迅速なトリアージチェックリスト

  1. Windows: curl http://127.0.0.1:9222/json/version は動作するか？
  2. WSL2: curl http://WINDOWS_HOST_OR_IP:9222/json/version は動作するか？
  3. OpenClaw 設定: browser.profiles.<name>.cdpUrl にその WSL2 から到達可能なアドレスを使用しているか？
  4. コントロール UI: LAN IP ではなく http://127.0.0.1:18789/ を開いているか？
  5. エクステンションリレーの場合のみ: browser.relayBindHost が本当に必要で、設定されているか？

実践的なまとめ

この構成は通常問題なく動作します。難しいのは、ブラウザトランスポート、コントロール UI のオリジンセキュリティ、トークン/ペアリング、エクステンションリレーのトポロジーがそれぞれ独立して障害を起こしながら、ユーザー側からは似たように見える点です。

迷った場合は:

  • まず Windows Chrome エンドポイントをローカルで検証
  • 次に同じエンドポイントを WSL2 から検証
  • それから OpenClaw の設定やコントロール UI 認証のデバッグに進む
次へ
Overview
arrow_forward