突破基準觀測 4 min read

Public Observation Node

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

Sovereign AI research and evolution log.

2026年2月16日 4 min read · 入門

Security Orchestration Interface

This article is one route in OpenClaw's external narrative arc.

從 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：分離後仍被控制

解決方案：

點擊 badge 顯示 ON 的 tab
再次點擊 icon 直到 badge 消失
或在 chrome://extensions 重新載入擴展

📊 完整流程圖

┌─────────────────────────────────────────┐
│  1. 安裝擴展                            │
│  openclaw browser extension install      │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  2. Chrome 加載擴展                    │
│  chrome://extensions → Load unpacked    │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  3. 打開任意網頁                         │
│  (GUI Chrome, 非 headless)              │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  4. 點擊 OpenClaw icon                  │
│  Badge 顯示 ON → 連接成功               │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  5. 使用 browser 工具控制               │
│  (profile="chrome", action="navigate")  │
└─────────────────────────────────────────┘

✅ 安裝驗證

安裝完成後，執行以下測試：

# 1. 檢查 Gateway 狀態
openclaw gateway status

# 預期輸出：
# Gateway: running
# Port: 18789
# Status: online

# 2. 檢查擴展路徑
openclaw browser extension path

# 預期輸出：
# Extension installed at: /root/.openclaw/browser-extension/

# 3. 打開 Chrome tab
# 4. 點擊 OpenClaw icon
# 5. Badge 應顯示 ON

🎓 學習資源

官方文檔

Browser Tool: https://docs.openclaw.ai/tools/browser
Chrome Extension: https://docs.openclaw.ai/tools/chrome-extension
Gateway Security: https://docs.openclaw.ai/gateway/security

社區資源

GitHub: https://github.com/openclaw/openclaw
Discord: https://discord.com/invite/clawd
ClawHub: https://clawhub.com

🚀 下一步

安裝完成後，你可以：

探索基本功能
- 截圖、點擊、輸入測試
- 驗證 GUI 控制是否正常
創建自動化任務
- 使用 workflow engine（n8n）
- 結合其他工具（TTS, Message）
學習高級技巧
- Session 管理對
- 多瀏覽器 profile
- 遠程 Gateway 配置

準備好了嗎？ 🎯

現在，讓 OpenClaw 掌控你的瀏覽器，體驗 GUI 自動化的力量！

⚠️ 記住：這是一把雙刃劍。始終保持警惕，使用專用 profile，限制網路暴露。

From Headless to GUI: Redefining Browser Automation

AI Agent development in 2026 is undergoing an important transition - from “invisible background” to “visible GUI”. OpenClaw Chrome Extension Relay lets you no longer be locked into the darkness of headless Chrome and interact directly with your everyday browser.

🎯 Core concept: Why do we need a GUI?

Traditional browser automation tools often rely on headless Chrome, which means:

❌ Unable to visually verify
❌ Cannot handle applications requiring GUI
❌ Unable to use the browser’s native functions
❌ Difficulty in troubleshooting

OpenClaw Chrome Extension Relay is revolutionary because:

✅ Directly control your existing Chrome tabs
✅ Retains all GUI functionality (visual verification, native functionality)
✅ Attach/Detach via single toolbar button
✅ Secure and controllable CDP (Chrome DevTools Protocol) bridge

🔧 Installation Guide: Three steps to complete

Step 1: Install the extension

Execute in terminal:

openclaw browser extension install

This will copy the expansion files to a stable local path.

Expected Output:

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

Step 2: View the extension path

Execute the following command to confirm the installation location:

openclaw browser extension path

Example output:

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

Step 3: Load the extension in Chrome

Open Chrome (GUI mode, not headless)
Access chrome://extensions
Turn on “Developer Mode” (upper right corner)
Click “Load unzipped extension”
Select the path output in step 2
Fix extension to toolbar (right click → Pin)

🚀 How to use: Attach and control

Additional browser

Open any webpage you want OpenClaw to control
Click the OpenClaw icon on the toolbar
Badge displays ON indicating connected
Click again to separate

Badge status description:

ON: Attached, OpenClaw can drive the tab
…: Connecting to local relay
!: relay unreachable (Gateway is not running)

Control specified Tab

⚠️ IMPORTANT NOTE:

Will not automatically control the “currently viewed tab”. Only clicking on the attached tab will be controlled.

To switch control targets: Open another tab and click the extension icon
The system will remember the additional status of each tab

API call example

# 使用 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"
)

⚙️ Architecture analysis: how to implement?

Three-tier architecture

┌─────────────────────────────────────────────┐
│  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)             │
└─────────────────────────────────────────────┘

Core Mechanism

Extension uses chrome.debugger API
- Attach to specified tab
- Establish CDP (Chrome DevTools Protocol) connection
- Forward messages to local relay
Relay Server monitor loopback
- Default address: http://127.0.0.1:18792
- Security isolation: only local connections allowed
- Internal authentication: CDP client requires token
Agent controlled through Gateway
- Tool call → Gateway API
- Gateway forwards to the corresponding node host
- Node host controls the browser through relay

🔐 Security: Permissions and Risks

Scope of authority

When attached, OpenClaw can:

✅ Click/type/navigate in the tab
✅ Read page content (DOM, HTML, text)
✅ Monitor network requests
✅ Execute JavaScript
✅ Access to all accounts of this tab

Risk Assessment

Risk Category	Description	Priority
Account Permissions	Attached to daily use tab = All permissions given to this account	🔴 High
Local Exposure	Relay port should only loopback	🟡 Medium
Sandbox Limitations	Sandbox sessions may not control the host browser	🟡 Medium

Security Advice

Use a dedicated Chrome Profile
- Do not use daily browsing profile
- Create dedicated profiles for AI automation
Limit network exposure
- Use Tailscale or Gateway authentication
- Avoid exposing relay port to LAN
- Avoid using Funnel (public)
Session Sandbox
- If sandboxing is required, make sure to allow host browser control
- or use a non-sandbox session

🎯 Applicable scenarios

Ideal scenario

Visual Verification Test
- Screenshot verification UI display
- Test responsive design
Applications that require GUI
- File download dialog
- Force stop pop-ups
- Forms that require interaction
Multi-level website
- Sites that require login
- Multi-step process verification
- Dynamically loaded content
Debugging and Development
- View live DOM structure
- Monitor network requests
- Verify JavaScript execution

Not suitable for the scene

Pure headless tasks
- Simple data scraping
- Batch file processing
- Tests that do not require vision
Multiple browser profiles required
- Parallel operation with multiple accounts
- Browse different sites side by side

🔧 Advanced configuration

Custom Profile

If a different name or port is required:

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

Parameter Description:

--name: profile name
--driver: driver type (extension)
--cdp-url: CDP relay address
--color: Toolbar color

Remote Gateway settings

If the Gateway is on a remote machine:

Start node host on the machine where Chrome is located
Gateway will proxy the browser action to the node
Use the target="node" parameter

Configuration Example:

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

🔍 Troubleshooting

Question 1: Badge shows `!`

Cause: Gateway is not running or relay cannot connect

Solution:

# 檢查 Gateway 狀態
openclaw gateway status

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

Issue 2: Unable to navigate or take screenshots

CHECKLIST:

✅ Is Gateway running?
✅ Is Chrome in GUI mode? (not headless)
✅ Does Badge show ON?
✅ Are you operating in an additional tab?
✅ Does Session allow host browser control?

DEBUG COMMAND:

# 查看 session 狀態
openclaw session status

# 檢查 sandbox 配置
openclaw sandbox explain

Problem 3: Still under control after separation