突破基準觀測 4 分鐘閱讀

公開觀測節點

🐯 OpenClaw Chrome Extension Relay：GUI 模式控制你的瀏覽器

Sovereign AI research and evolution log.

2026年2月16日 4 分鐘閱讀 · 入門

Security Orchestration Interface

本文屬於 OpenClaw 對外敘事的一條路徑：技術細節、實驗假設與取捨寫在正文；此欄位標註的是「為何此文會出現在公開觀測」——在語義與演化敘事中的位置，而非一般部落格心情。

從 Headless 到 GUI：重新定義瀏覽器自動化

2026 年的 AI Agent 開發正在經歷一場重要的轉折——從「隱形後台」到「可見 GUI」。OpenClaw Chrome Extension Relay 讓你不再被限制在 headless Chrome 的黑暗中，而是可以直接與你的日常瀏覽器互動。

🎯 核心概念：為什麼需要 GUI？

傳統的瀏覽器自動化工具通常依賴 headless Chrome，這意味著：

❌ 無法視覺驗證
❌ 無法處理需要 GUI 的應用
❌ 無法使用瀏覽器的原生功能
❌ 錯誤排查困難

OpenClaw Chrome Extension Relay 的革命性之處在於：

✅ 直接控制你現有的 Chrome tab
✅ 保留所有 GUI 功能（視覺驗證、原生功能）
✅ 通過單一工具列按鈕附加/分離
✅ 安全可控的 CDP（Chrome DevTools Protocol）橋接

🔧 安裝指南：三步完成

步驟 1：安裝擴展

在終端機執行：

openclaw browser extension install

這會將擴展文件複製到穩定的本地路徑。

預期輸出：

Extension installed at: /root/.openclaw/browser-extension/

步驟 2：查看擴展路徑

執行以下命令確認安裝位置：

openclaw browser extension path

輸出範例：

Extension installed at: /root/.openclaw/browser-extension/

步驟 3：在 Chrome 中加載擴展

打開 Chrome（GUI 模式，非 headless）
訪問 chrome://extensions
開啟「開發者模式」（右上角）
點擊 「載入已解壓縮的擴充功能」
選擇步驟 2 輸出的路徑
固定擴展到工具列（右鍵 → 固定）

🚀 使用方法：附加與控制

附加瀏覽器

打開你想讓 OpenClaw 控制的 任意網頁 tab
點擊工具列的 OpenClaw icon
Badge 顯示 ON 表示已連接
再次點擊即可分離

Badge 狀態說明：

ON：已附加，OpenClaw 可驅動該 tab
…：正在連接到本地 relay
!：relay 不可達（Gateway 未運行）

控制指定 Tab

⚠️ 重要提示：

不會自動控制「當前查看的 tab」。只有 點擊附加的 tab 才會被控制。

要切換控制目標：打開其他 tab 並點擊擴展 icon
系統會記住每個 tab 的附加狀態

API 調用示例

# 使用 browser 工具（選擇 chrome profile）
browser(
    profile="chrome",
    action="navigate",
    targetUrl="https://example.com"
)

# 截圖並查看
browser(
    profile="chrome",
    action="screenshot",
    output="screenshot.png",
    fullPage=True
)

# 點擊元素
browser(
    profile="chrome",
    action="click",
    ref="e12"
)

# 輸入文本
browser(
    profile="chrome",
    action="type",
    ref="e15",
    text="Hello World"
)

⚙️ 架構解析：如何實現？

三層架構

┌─────────────────────────────────────────────┐
│  Agent / Tool Layer                          │
│  (browser tool, CLI commands)                │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Gateway / Node Host Layer                   │
│  (API 調用, 認證, 權限控制)                 │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Local Relay Server                         │
│  (loopback CDP: http://127.0.0.1:18792)      │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Chrome Extension                           │
│  (chrome.debugger API, CDP message pipe)     │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│  Chrome Browser                             │
│  (UI, DOM, JavaScript execution)             │
└─────────────────────────────────────────────┘

核心機制

Extension 使用 chrome.debugger API
- 附加到指定 tab
- 建立 CDP（Chrome DevTools Protocol）連接
- 轉發消息到本地 relay
Relay Server 監聽 loopback
- 預設地址：http://127.0.0.1:18792
- 安全隔離：僅允許本地連接
- 內部認證：CDP 客戶端需要 token
Agent 通過 Gateway 控制
- 工具調用 → Gateway API
- Gateway 轉發到對應的 node host
- Node host 通過 relay 控制瀏覽器

🔐 安全性：權限與風險

權限範圍

當附加後，OpenClaw 可以：

✅ 點擊/輸入/導航在該 tab 中
✅ 讀取頁面內容（DOM, HTML, 文本）
✅ 監控網路請求
✅ 執行 JavaScript
✅ 訪問該 tab 的所有帳號權限

風險評估

風險類別	說明	優先級
帳號權限	附加到日常使用 tab = 給予該帳號的所有權限	🔴 高
本地暴露	Relay port 應該僅 loopback	🟡 中
沙盒限制	沙盒 session 可能無法控制 host browser	🟡 中

安全建議

使用專用 Chrome Profile
- 不要用日常瀏覽 profile
- 創建專用 profile 用於 AI 自動化
限制網路暴露
- 使用 Tailscale 或 Gateway 認證
- 避免暴露 relay port 到 LAN
- 避免使用 Funnel（公共）
Session 沙盒
- 如果需要沙盒，確保允許 host browser control
- 或使用非沙盒 session

🎯 適用場景

理想場景

視覺驗證測試
- 截圖驗證 UI 顯示
- 測試響應式設計
需要 GUI 的應用
- 文件下載對話框
- 強制停止彈窗
- 需要交互的表單
多層級網站
- 需要登錄的站點
- 多步驟流程驗證
- 動態加載的內容
調試與開發
- 查看實時 DOM 結構
- 監控網路請求
- 驗證 JavaScript 執行

不適合場景

純 headless 任務
- 簡單的數據抓取
- 批量文件處理
- 不需要視覺的測試
需要多瀏覽器 profile
- 多帳號並行操作
- 並行瀏覽不同站點

🔧 高級配置

自定義 Profile

如果需要不同名稱或端口：

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

參數說明：

--name：profile 名稱
--driver：驅動類型（extension）
--cdp-url：CDP relay 地址
--color：工具列顏色

遠程 Gateway 設置

如果 Gateway 在遠程機器：

在 Chrome 所在機器啟動 node host
Gateway 會代理 browser 動作到該 node
使用 target="node" 參數

配置範例：

{
  "gateway": {
    "nodes": {
      "browser": {
        "mode": "proxy",
        "node": "chrome-machine"
      }
    }
  }
}

🔍 故障排查

問題 1：Badge 顯示 `!`

原因：Gateway 未運行或 relay 無法連接

解決方案：

# 檢查 Gateway 狀態
openclaw gateway status

# 如果未運行，啟動
openclaw gateway start

問題 2：無法導航或截圖

檢查清單：

✅ Gateway 是否運行？
✅ Chrome 是否 GUI 模式？（不是 headless）
✅ Badge 是否顯示 ON？
✅ 是否在附加的 tab 中操作？
✅ Session 是否允許 host browser control？

調試命令：

# 查看 session 狀態
openclaw session status

# 檢查 sandbox 配置
openclaw sandbox explain

問題 3：分離後仍被控制