> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # WSL2 + Windows + 遠端 Chrome CDP 疑難排解 在常見的主機分離設定中，OpenClaw 閘道在 WSL2 內執行，Chrome 在 Windows 上執行，而瀏覽器控制必須跨越 WSL2/Windows 邊界。數個 彼此獨立的問題可能同時浮現（請參閱 [問題 #39369](https://github.com/openclaw/openclaw/issues/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： ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} http://127.0.0.1:18789/ ``` 不要預設使用 LAN IP。LAN 或 tailnet 位址上的純 HTTP 可能會觸發與 CDP 本身無關的不安全來源／裝置驗證行為。請參閱 [控制介面](/zh-TW/web/control-ui)。 ## 分層驗證 請由上而下處理，不要跳過前面的步驟。修正其中一層後， 更下層的其他錯誤仍可能顯示。 ### 第 1 層：確認 Chrome 正在 Windows 上提供 CDP ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} chrome.exe --remote-debugging-port=9222 --user-data-dir="$env:LOCALAPPDATA\OpenClaw\ChromeCDP" ``` Chrome 136 及後續版本會忽略針對預設 Chrome 資料目錄所設定的 遠端偵錯命令列開關。請使用如上所示的獨立非預設資料目錄。 請參閱 Chrome 的 [遠端偵錯安全性變更](https://developer.chrome.com/blog/remote-debugging-port)。 這不會讓一般已登入的 Chrome 設定檔可受遠端控制。 先從 Windows 驗證 Chrome 本身： ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 版本推斷： ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 "`。 * 如果 `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 位址： ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}} 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` 中使用的確切位址： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 連線的位址： ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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` 的預期 * 權杖驗證或配對已正確設定 * 你沒有將控制介面驗證問題誤當成瀏覽器問題進行偵錯 實用頁面：[控制介面](/zh-TW/web/control-ui)。 ### 第 5 層：驗證端對端瀏覽器控制 從 WSL2 執行： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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..cdpUrl` 是否使用該確切的 WSL2 可連線位址？ 4. 控制介面：你是否開啟 `http://127.0.0.1:18789/`，而不是 LAN IP？ 5. 你是否嘗試跨 WSL2 和 Windows 使用 `existing-session`， 而不是原始遠端 CDP？ 請先在 Windows 本機驗證 Chrome 端點，再從 WSL2 驗證相同端點， 最後才偵錯 OpenClaw 設定或控制介面驗證。 ## 相關內容 * [瀏覽器](/zh-TW/tools/browser) * [瀏覽器登入](/zh-TW/tools/browser-login) * [瀏覽器 Linux 疑難排解](/zh-TW/tools/browser-linux-troubleshooting)