Chrome 擴充功能（瀏覽器中繼）

OpenClaw Chrome 擴充功能讓代理可以控制你既有的 Chrome 分頁（你平常使用的 Chrome 視窗），而不需要啟動另一個 openclaw 受管理的 Chrome 設定檔。

附掛 / 解除附掛只需透過 Chrome 工具列上的一個按鈕即可完成。

如果你想要的是 Chrome 官方的 DevTools MCP 附掛流程，而非 OpenClaw 擴充功能中繼，請改用 existing-session 瀏覽器設定檔。請參閱 瀏覽器。Chrome 自身的設定文件請參閱 Chrome for Developers: Use Chrome DevTools MCP with your browser session 和 Chrome DevTools MCP README。

概念說明

由三個部分組成：

  • 瀏覽器控制服務（Gateway 或節點）：代理 / 工具呼叫的 API（透過 Gateway）
  • 本地中繼伺服器（回環 CDP）：在控制服務和擴充功能之間橋接（預設 http://127.0.0.1:18792）
  • Chrome MV3 擴充功能：使用 chrome.debugger 附掛到活躍的分頁，並將 CDP 訊息傳送到中繼

OpenClaw 接著透過一般的 browser 工具介面控制附掛的分頁（選擇正確的設定檔即可）。

安裝 / 載入（未封裝模式）

  1. 將擴充功能安裝到穩定的本地路徑：
openclaw browser extension install
  1. 印出已安裝的擴充功能目錄路徑：
openclaw browser extension path
  1. Chrome → chrome://extensions
  • 啟用「開發人員模式」
  • 「載入未封裝項目」→ 選擇上面印出的目錄
  1. 釘選擴充功能。

更新（無需建置步驟）

擴充功能隨 OpenClaw 發佈版本（npm 套件）一起提供，是靜態檔案，沒有獨立的「建置」步驟。

升級 OpenClaw 後：

  • 重新執行 openclaw browser extension install，將檔案更新到你的 OpenClaw 狀態目錄。
  • Chrome → chrome://extensions → 點擊擴充功能上的「重新載入」。

使用方式（設定一次 Gateway token）

OpenClaw 附帶一個名為 chrome 的內建瀏覽器設定檔，指向預設連接埠的擴充功能中繼。

首次附掛前，開啟擴充功能選項頁面設定：

  • Port（預設 18792）
  • Gateway token（必須與 gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 一致）

使用方式：

  • CLI：openclaw browser --browser-profile chrome tabs
  • 代理工具：browser 搭配 profile="chrome"

如果想用不同的名稱或中繼連接埠，可建立自訂設定檔：

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

自訂 Gateway 連接埠

如果你使用自訂的 Gateway 連接埠，擴充功能中繼連接埠會自動衍生：

擴充功能中繼連接埠 = Gateway 連接埠 + 3

範例：如果 gateway.port: 19001，那麼：

  • 擴充功能中繼連接埠：19004（gateway + 3）

請在擴充功能選項頁面中設定衍生的中繼連接埠。

附掛 / 解除附掛（工具列按鈕）

  • 開啟你希望 OpenClaw 控制的分頁。
  • 點擊擴充功能圖示。
    • 徽章顯示 ON 表示已附掛。
  • 再次點擊即可解除附掛。

控制的是哪個分頁？

  • 它不會自動控制「你正在看的分頁」。
  • 它只控制你透過點擊工具列按鈕明確附掛的分頁。
  • 要切換：開啟另一個分頁，然後在那裡點擊擴充功能圖示。

徽章 + 常見錯誤

  • ON：已附掛；OpenClaw 可以驅動該分頁。
  • …：正在連線到本地中繼。
  • !：中繼無法連線 / 驗證失敗（最常見原因：中繼伺服器未啟動，或 Gateway token 缺少 / 錯誤）。

看到 ! 時：

  • 確認 Gateway 在本地執行（預設設定），或如果 Gateway 在其他地方執行，請在這台機器上執行節點主機。
  • 開啟擴充功能選項頁面；它會驗證中繼可達性和 Gateway token 驗證。

遠端 Gateway（使用節點主機）

本地 Gateway（與 Chrome 同一台機器）—— 通常不需要額外步驟

如果 Gateway 與 Chrome 在同一台機器上執行，它會在回環位址啟動瀏覽器控制服務並自動啟動中繼伺服器。擴充功能連線到本地中繼；CLI / 工具呼叫走 Gateway。

遠端 Gateway（Gateway 在其他地方執行）—— 執行節點主機

如果 Gateway 在另一台機器上，請在執行 Chrome 的機器上啟動節點主機。Gateway 會將瀏覽器操作代理到該節點；擴充功能 + 中繼保持在瀏覽器機器本地。

如果連線了多個節點，可透過 gateway.nodes.browser.node 指定或設定 gateway.nodes.browser.mode。

沙箱（工具容器）

如果代理工作階段已沙箱化（agents.defaults.sandbox.mode != "off"），browser 工具可能會受限：

  • 預設情況下，沙箱化工作階段通常指向沙箱瀏覽器（target="sandbox"），而非你的主機 Chrome。
  • Chrome 擴充功能中繼接管需要控制主機端瀏覽器控制服務。

選項：

  • 最簡單：在非沙箱化的工作階段 / 代理中使用擴充功能。
  • 或允許沙箱化工作階段進行主機端瀏覽器控制：
{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}

然後確保工具未被工具策略拒絕，並（如有需要）在呼叫 browser 時使用 target="host"。

除錯：openclaw sandbox explain

遠端存取建議

  • Gateway 和節點主機請保持在同一個 tailnet 上；避免將中繼連接埠暴露到區域網路或公開網路。
  • 有意識地配對節點；不需要遠端控制時停用瀏覽器代理路由（gateway.nodes.browser.mode="off"）。
  • 中繼預設僅繫結回環，除非有實際的跨命名空間需求。若為 WSL2 或類似的跨主機架構，將 browser.relayBindHost 設為明確的繫結位址如 0.0.0.0，並透過 Gateway 驗證、節點配對和私有網路限制存取。

「extension path」的運作方式

openclaw browser extension path 印出的是已安裝的擴充功能檔案所在的磁碟目錄。

CLI 刻意不會印出 node_modules 路徑。務必先執行 openclaw browser extension install，將擴充功能複製到你的 OpenClaw 狀態目錄下的穩定位置。

如果你移動或刪除該安裝目錄，Chrome 會將擴充功能標記為損壞，直到你從有效路徑重新載入。

安全性影響（請務必閱讀）

這個功能強大但有風險。把它想成是讓模型「控制你的瀏覽器」。

  • 擴充功能使用 Chrome 的 debugger API（chrome.debugger）。附掛後，模型可以：
    • 在該分頁中點擊 / 輸入 / 導航
    • 讀取頁面內容
    • 存取該分頁已登入工作階段所能存取的一切
  • 這不像專屬的 openclaw 受管理設定檔那樣隔離。
    • 如果你附掛到日常使用的設定檔 / 分頁，就等於授予了對該帳號狀態的存取權。

建議：

  • 建議使用專屬的 Chrome 設定檔（與個人瀏覽分開）來使用擴充功能中繼。
  • Gateway 和節點主機請保持僅限 tailnet；依賴 Gateway 驗證 + 節點配對。
  • 避免透過 LAN（0.0.0.0）和 Funnel（公開）暴露中繼連接埠。
  • 中繼會阻擋非擴充功能來源，並要求 /cdp 和 /extension 的 Gateway token 驗證。

相關文件：

arrow_back
上一頁
Browser Login
下一頁
Browser Linux Troubleshooting
arrow_forward