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/versioncurl.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 :9222netsh interface portproxy show allcurl.exe http://127.0.0.1:9222/json/versioncurl.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/versioncurl 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.comopenclaw browser --browser-profile remote tabs

正常結果：

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

常見的誤導性錯誤

快速分類檢查清單

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 疑難排解