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

在常見的主機分離設定中，OpenClaw 閘道在 WSL2 內執行，Chrome 在 Windows 上執行，而瀏覽器控制必須跨越 WSL2/Windows 邊界。數個 彼此獨立的問題可能同時浮現（請參閱 問題 #39369）：CDP 傳輸、控制介面來源安全性，以及權杖／配對都可能各自失敗， 同時產生外觀相似的錯誤。請依序逐層處理 下列項目，不要猜測是哪一項故障。

​

先選擇正確的瀏覽器模式

​

選項 1：從 WSL2 到 Windows 的原始遠端 CDP

使用遠端瀏覽器設定檔，從 WSL2 指向 Windows Chrome CDP 端點。當閘道留在 WSL2 內、Chrome 在 Windows 上執行，且瀏覽器控制需要跨越 WSL2/Windows 邊界時，請選擇此模式。

​

選項 2：主機本機 Chrome MCP

僅當閘道與 Chrome 在同一部主機上執行、你想使用本機已登入的瀏覽器狀態、 不需要跨主機瀏覽器傳輸，而且不需要 responsebody、 PDF 匯出、下載攔截或批次動作時，才使用 existing-session 驅動程式 （user 設定檔）（Chrome MCP 設定檔不支援這些功能）。

若是 WSL2 閘道 + Windows Chrome，請使用原始遠端 CDP。Chrome MCP 是主機本機功能，並非 WSL2 到 Windows 的橋接器。

​

運作架構

• WSL2 在 127.0.0.1:18789 上執行閘道
• Windows 在一般瀏覽器中透過 http://127.0.0.1:18789/ 開啟控制介面
• Windows Chrome 在連接埠 9222 公開 CDP 端點
• WSL2 可以連線至該 Windows CDP 端點
• OpenClaw 將瀏覽器設定檔指向可從 WSL2 連線的位址

​

控制介面的關鍵規則

從 Windows 開啟介面時，除非你有刻意設定 HTTPS，否則請使用 Windows localhost：

http://127.0.0.1:18789/

不要預設使用 LAN IP。LAN 或 tailnet 位址上的純 HTTP 可能會觸發與 CDP 本身無關的不安全來源／裝置驗證行為。請參閱 控制介面。

​

分層驗證

請由上而下處理，不要跳過前面的步驟。修正其中一層後， 更下層的其他錯誤仍可能顯示。

​

第 1 層：確認 Chrome 正在 Windows 上提供 CDP

chrome.exe --remote-debugging-port=9222 --user-data-dir="$env:LOCALAPPDATA\OpenClaw\ChromeCDP"

Chrome 136 及後續版本會忽略針對預設 Chrome 資料目錄所設定的 遠端偵錯命令列開關。請使用如上所示的獨立非預設資料目錄。 請參閱 Chrome 的 遠端偵錯安全性變更。 這不會讓一般已登入的 Chrome 設定檔可受遠端控制。

先從 Windows 驗證 Chrome 本身：

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

如果此步驟失敗，請診斷下方的 Windows 接聽程式。此時問題尚不在 OpenClaw。

​

變更 portproxy 前，先診斷 IPv4 與 IPv6

Chromium 會先嘗試將遠端偵錯繫結至 127.0.0.1，只有在 IPv4 繫結失敗時才改用 [::1]。在 127.0.0.1:9222 上接聽的持續性 v4tov4 規則，可能會在 Chrome 啟動前占用該端點。Chrome 接著會 改用 [::1]:9222，而舊規則會將 IPv4 流量轉送回 自己的接聽程式，並傳回空白回覆。

請從 Windows 檢查實際的接聽程式與 Proxy 規則，而不要根據 Chrome 版本推斷：

netstat -ano | findstr :9222
netsh interface portproxy show all
curl.exe http://127.0.0.1:9222/json/version
curl.exe http://[::1]:9222/json/version

針對 netstat 中的每個 PID 使用 tasklist /fi "PID eq <PID>"。

• 如果 chrome.exe 在 127.0.0.1 上有回應，請移除任何同時 在 127.0.0.1:9222 上接聽的 portproxy 規則。只將 WSL2 可連線的 Windows 網路介面卡位址轉送至 127.0.0.1。

• 如果 chrome.exe 僅在 [::1] 上有回應，請使用 v4tov6 將 WSL2 可連線的接聽程式指向 ::1， 而不要轉送至未使用的 IPv4 位址：

  netsh interface portproxy add v4tov6 listenaddress=WINDOWS_HOST_OR_IP listenport=9222 connectaddress=::1 connectport=9222
  

請將接聽程式繫結至 WSL2 所需的網路介面卡位址。不要在 0.0.0.0、LAN 位址或 tailnet 位址上公開 CDP 連接埠：CDP 會授予瀏覽器工作階段的控制權。

​

第 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（若未開啟任何頁面，空陣列也沒問題）

如果此步驟失敗，表示 Windows 尚未將連接埠公開給 WSL2、 WSL2 端使用的位址錯誤，或缺少防火牆／連接埠轉送／Proxy 設定。 請先修正此問題，再修改 OpenClaw 設定。

​

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

將 OpenClaw 指向可從 WSL2 連線的位址：

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

注意事項：

• 使用 WSL2 可連線的位址，而不是僅能在 Windows 上使用的位址
• 對於由外部管理的瀏覽器，請保留 attachOnly: true
• cdpUrl 可以是 http://、https://、ws:// 或 wss://
• 若要讓 OpenClaw 探索 /json/version，請使用 HTTP(S)
• 只有當瀏覽器供應商提供直接的 DevTools 通訊端 URL 時，才使用 WS(S)
• 在預期 OpenClaw 成功前，先使用 curl 測試相同的 URL

​

第 4 層：單獨驗證控制介面層

從 Windows 開啟 http://127.0.0.1:18789/，然後確認：

• 頁面來源符合 gateway.controlUi.allowedOrigins 的預期
• 權杖驗證或配對已正確設定
• 你沒有將控制介面驗證問題誤當成瀏覽器問題進行偵錯

實用頁面：控制介面。

​

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

從 WSL2 執行：

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

正常結果：

• 分頁會在 Windows Chrome 中開啟
• browser tabs 傳回目標
• 後續動作（snapshot、screenshot、navigate）可透過相同的 設定檔運作

​

常見的誤導性錯誤

訊息	含義
control-ui-insecure-auth	介面來源／安全內容問題，不是 CDP 傳輸問題
token_missing	驗證設定問題
pairing required	裝置核准問題
Remote CDP for profile "remote" is not reachable	WSL2 無法連線至設定的 cdpUrl
透過 portproxy 收到空白 CDP 回覆／other side closed	Windows 接聽程式不相符或發生自我迴圈；請檢查兩種回送位址家族及 netsh interface portproxy show all
Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable	HTTP 端點已有回應，但無法開啟 DevTools WebSocket
遠端工作階段結束後仍保留舊的可視區域／深色模式／地區設定／離線覆寫	執行 openclaw browser --browser-profile remote stop 以關閉工作階段並釋放快取的 Playwright/CDP 連線，無須重新啟動閘道或外部瀏覽器
CDP 連線能力測試逾時	通常仍是 CDP 連線能力問題，或遠端端點速度緩慢／無法連線
Playwright page enumeration timed out after 3000ms	遠端 CDP 已連線，但其持續性分頁讀取停滯
No Chrome tabs found for profile="user"	選取了本機 Chrome MCP 設定檔，但沒有可用的主機本機分頁

​

快速分類檢查清單

1. Windows：127.0.0.1 或 [::1] 中，哪一個在 /json/version 上有回應， 而且該接聽程式是否屬於 chrome.exe？
2. WSL2：curl http://WINDOWS_HOST_OR_IP:9222/json/version 是否可用？
3. OpenClaw 設定：browser.profiles.<name>.cdpUrl 是否使用該確切的 WSL2 可連線位址？
4. 控制介面：你是否開啟 http://127.0.0.1:18789/，而不是 LAN IP？
5. 你是否嘗試跨 WSL2 和 Windows 使用 existing-session， 而不是原始遠端 CDP？

請先在 Windows 本機驗證 Chrome 端點，再從 WSL2 驗證相同端點， 最後才偵錯 OpenClaw 設定或控制介面驗證。

​

相關內容

• 瀏覽器
• 瀏覽器登入
• 瀏覽器 Linux 疑難排解