WSL2 + Windows + 遠端 Chrome CDP 疑難排解

本指南涵蓋常見的跨主機架構，其中：

  • OpenClaw Gateway 執行在 WSL2 內
  • Chrome 執行在 Windows 上
  • 瀏覽器控制必須跨越 WSL2/Windows 的邊界

本指南同時涵蓋 issue #39369 中的多層故障模式：多個獨立的問題可能同時出現，讓你誤判錯誤的層級。

先選擇正確的瀏覽器模式

你有兩種有效的模式：

選項一：原始遠端 CDP

使用遠端瀏覽器設定檔，從 WSL2 指向 Windows Chrome 的 CDP 端點。

適合以下情況：

  • 你只需要瀏覽器控制功能
  • 你願意將 Chrome 的遠端偵錯功能暴露給 WSL2
  • 你不需要 Chrome 擴充功能中繼

選項二：Chrome 擴充功能中繼

使用內建的 chrome 設定檔搭配 OpenClaw Chrome 擴充功能。

適合以下情況：

  • 你想透過工具列按鈕附掛到既有的 Windows Chrome 分頁
  • 你偏好擴充功能式的控制，而非原始的 --remote-debugging-port
  • 中繼本身必須能跨越 WSL2/Windows 的邊界

如果你跨命名空間使用擴充功能中繼，browser.relayBindHost 是 瀏覽器 和 Chrome 擴充功能 中介紹的重要設定。

正常運作的架構

參考架構：

  • WSL2 在 127.0.0.1:18789 上執行 Gateway
  • Windows 在一般瀏覽器中開啟控制 UI，位址為 http://127.0.0.1:18789/
  • Windows Chrome 在連接埠 9222 上暴露 CDP 端點
  • WSL2 可以連線到該 Windows CDP 端點
  • OpenClaw 的瀏覽器設定檔指向從 WSL2 可達的位址

為什麼這個設定容易搞混

多個故障可能交疊出現：

  • WSL2 無法連線到 Windows CDP 端點
  • 控制 UI 從非安全來源開啟
  • gateway.controlUi.allowedOrigins 與頁面來源不符
  • 缺少 token 或配對
  • 瀏覽器設定檔指向錯誤的位址
  • 擴充功能中繼仍為僅回環模式，但你實際需要跨命名空間存取

因此，修復了一層問題後，另一個不同的錯誤可能仍然存在。

控制 UI 的關鍵規則

從 Windows 開啟 UI 時，除非你有刻意設定 HTTPS，否則請使用 Windows 的 localhost。

使用：

http://127.0.0.1:18789/

不要預設使用區域網路 IP 開啟控制 UI。在區域網路或 tailnet 位址上使用明文 HTTP 可能會觸發與 CDP 本身無關的不安全來源 / 裝置驗證行為。請參閱 控制 UI。

逐層驗證

由上往下依序進行，不要跳過。

第一層：確認 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。

第二層：確認 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（如果沒有開啟的頁面，空陣列也是正常的）

如果失敗：

  • Windows 尚未將連接埠暴露給 WSL2
  • WSL2 端使用的位址不正確
  • 防火牆 / 連接埠轉發 / 本地代理還沒設定好

在動 OpenClaw 設定之前先修復這個。

第三層：設定正確的瀏覽器設定檔

若使用原始遠端 CDP，將 OpenClaw 指向從 WSL2 可達的位址：

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

注意事項：

  • 使用 WSL2 可達的位址，不是只能在 Windows 上用的那個
  • 外部管理的瀏覽器請保持 attachOnly: true
  • 在期望 OpenClaw 能成功之前，先用 curl 測試同一個 URL

第四層：如果你改用 Chrome 擴充功能中繼

如果瀏覽器所在的機器和 Gateway 被命名空間邊界隔開，中繼可能需要非回環的繫結位址。

範例：

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

只在必要時使用：

  • 預設行為更安全，因為中繼僅繫結回環位址
  • 0.0.0.0 擴大了暴露面
  • 請確保 Gateway 驗證、節點配對和周圍的網路環境保持私密

如果不需要擴充功能中繼，建議使用上面的原始遠端 CDP 設定檔。

第五層：單獨驗證控制 UI

從 Windows 開啟 UI：

http://127.0.0.1:18789/

然後確認：

  • 頁面來源與 gateway.controlUi.allowedOrigins 預期的一致
  • token 驗證或配對已正確設定
  • 你沒有把控制 UI 的驗證問題當成瀏覽器問題來除錯

相關頁面：

第六層：端對端驗證瀏覽器控制

從 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：你是否從 http://127.0.0.1:18789/ 開啟，而非區域網路 IP？
  5. 僅擴充功能中繼：你是否真的需要 browser.relayBindHost？如果需要，是否已明確設定？

實用結論

這個架構通常是可行的。困難之處在於瀏覽器傳輸、控制 UI 來源安全性、token / 配對，以及擴充功能中繼的網路拓撲各自可能獨立失敗，但從使用者的角度看起來很像。

如果不確定：

  • 先在 Windows 本機驗證 Chrome 端點
  • 再從 WSL2 驗證同一個端點
  • 然後才去除錯 OpenClaw 設定或控制 UI 驗證
下一頁
Overview
arrow_forward