解決 WSL2 與 Windows 間的 OpenClaw Chrome CDP 連線問題

相信很多在 Windows 上開發的朋友都遇過這種情況：你想在 WSL2 裡面跑服務，但又想控制 Windows 端的 Chrome。這聽起來很簡單，但一旦涉及跨系統的網路通訊，各種連線錯誤、權限問題就會接踵而至，讓你搞不清楚到底是防火牆擋住了，還是設定寫錯了。

這份指南會帶你解決 OpenClaw Gateway 跑在 WSL2，而 Chrome 跑在 Windows 這種「跨主機」環境下的常見問題，特別是當多個獨立的小問題同時發生，導致你很難判斷到底是哪一層出錯的時候。

先選擇正確的 Browser 模式

你有兩種可行的模式可以選擇：

選項 1：純遠端 CDP (Raw remote CDP)

使用遠端 Browser Profile，讓 WSL2 直接指向 Windows Chrome 的 CDP 端點。

當你符合以下情況時選擇這個：

• 你只需要控制瀏覽器
• 你不介意將 Chrome 的遠端偵錯（Remote Debugging）暴露給 WSL2
• 你不需要使用 Chrome extension relay

選項 2：Chrome extension relay

使用內建的 chrome Profile 搭配 OpenClaw Chrome extension。

當你符合以下情況時選擇這個：

• 你想透過工具列按鈕直接連接到現有的 Windows Chrome 分頁
• 你想透過 Extension 控制，而不是原始的 --remote-debugging-port
• Relay 本身必須能跨越 WSL2/Windows 邊界被存取

如果你跨命名空間（Namespaces）使用 Extension Relay，browser.relayBindHost 是最重要的設定，這在 Browser 和 Chrome extension 文件中都有提到。

運作架構

參考架構如下：

• WSL2 執行 Gateway，位址在 127.0.0.1:18789
• Windows 使用一般瀏覽器開啟 Control UI，網址為 http://127.0.0.1:18789/
• Windows Chrome 在 port 9222 開放 CDP 端點
• WSL2 可以連線到該 Windows CDP 端點
• OpenClaw 的 Browser Profile 指向 WSL2 可以存取的那個位址

為什麼這個設定很讓人困惑

因為好幾個失敗點可能會重疊在一起：

• WSL2 無法連線到 Windows 的 CDP 端點
• Control UI 是從非安全來源（Non-secure origin）開啟的
• gateway.controlUi.allowedOrigins 與頁面來源不符
• 缺少 Token 或配對（Pairing）
• Browser Profile 指向了錯誤的位址
• 當你其實需要跨命名空間存取時，Extension Relay 卻還設定在 loopback-only

正因如此，就算你修好了一層，可能還是會看到另一個錯誤。

Control UI 的關鍵規則

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

請使用： http://127.0.0.1:18789/

不要預設使用區域網路（LAN）的 IP 來開啟 Control UI。在區域網路或 Tailnet 位址上使用純 HTTP 可能會觸發與 CDP 無關的「不安全來源/裝置認證」行為。詳情請參考 Control UI。

分層驗證

請由上而下執行，不要跳過任何步驟。

第一層：確認 Chrome 在 Windows 上有提供 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 還沒把 port 暴露給 WSL2
• 對 WSL2 來說，這個位址是錯的
• 防火牆、Port Forwarding 或本地 Proxy 設定有誤
• 網路路由配置不正確

在動 OpenClaw 設定之前，請先修好這部分。

第三層：設定正確的 Browser Profile

如果是使用純遠端 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 extension relay

如果瀏覽器所在的機器與 Gateway 被命名空間邊界隔開，Relay 可能需要一個非 loopback 的綁定位址。

範例：

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

僅在必要時使用：

• 預設行為比較安全，因為 Relay 會保持在 loopback-only
• 0.0.0.0 會擴大暴露風險
• 請確保 Gateway 認證、Node 配對以及周邊網路是私有的

如果你不需要 Extension Relay，建議優先使用上面的純遠端 CDP Profile。

第五層：單獨驗證 Control UI 層

從 Windows 開啟 UI：

http://127.0.0.1:18789/

然後確認：

• 頁面來源（Origin）符合 gateway.controlUi.allowedOrigins 的預期
• Token 認證或配對已正確設定
• 你不是在把 Control UI 的認證問題當成 Browser 問題來除錯

參考頁面：

• Control UI

第六層：驗證端到端（End-to-End）瀏覽器控制

從 WSL2 執行：

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

如果是使用 Extension Relay：

openclaw browser tabs --browser-profile chrome

正確的結果：

• 分頁在 Windows Chrome 中開啟
• openclaw browser tabs 回傳目標分頁
• 後續動作（snapshot, screenshot, navigate）在同一個 Profile 下都能運作

常見的誤導性錯誤

把每個訊息當作特定層級的線索：

• control-ui-insecure-auth
  • UI 來源或安全上下文（Secure-context）問題，不是 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
  • 選擇了 Extension Relay Profile，但還沒有連接任何分頁

快速排錯清單

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. Control UI：你開啟的是 http://127.0.0.1:18789/ 而不是區域網路 IP 嗎？
5. 僅限 Extension Relay：你真的需要 browser.relayBindHost 嗎？如果是，有明確設定它嗎？

實務總結

這種設定通常是可行的。最難的地方在於瀏覽器傳輸、Control UI 來源安全性、Token/配對以及 Extension Relay 拓撲，這些都有可能獨立出錯，但在使用者看來卻長得很像。

當你感到困惑時：

• 先在 Windows 本地驗證 Chrome 端點
• 接著從 WSL2 驗證同一個端點
• 最後才去偵錯 OpenClaw 設定或 Control UI 認證

如果你在設定過程中遇到其他問題，可以試試我們的 AI Setup Assistant 來獲取即時協助。

下一步

• 設定 Browser Profiles
• 安裝 Chrome Extension
• Control UI 安全性設定