Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
7.7 KiB
7.7 KiB
9. Browser Control 瀏覽器控制
9.1 架構總覽
Telegram Agent 發出瀏覽器指令
│
▼
┌──────────────────────────────────────────────┐
│ OpenClaw Gateway (port 18789) │
│ browser.request → 轉發給 Node Host │
└──────────────┬───────────────────────────────┘
│ WebSocket
┌──────────────▼───────────────────────────────┐
│ OpenClaw Node Host │
│ systemd user: openclaw-node.service │
│ browser relay：接收 Gateway 指令 │
│ caps: browser, system │
└──────────────┬───────────────────────────────┘
│ CDP (Chrome DevTools Protocol)
┌──────────────▼───────────────────────────────┐
│ Playwright Chromium (port 18801) │
│ systemd user: playwright-chrome.service │
│ binary: ~/.cache/ms-playwright/chromium-1208 │
│ user-data: ~/.openclaw/browser/playwright-data│
│ DISPLAY=:99 (Xvfb) │
└───────────────────────────────────────────────┘
9.2 服務組成
| 服務 | systemd unit | 功能 | 環境要求 |
|---|---|---|---|
| Node Host | openclaw-node.service |
Gateway <-> Chrome relay | DISPLAY=:99 |
| Playwright Chrome | playwright-chrome.service |
Chromium 實例，CDP port 18801 | DISPLAY=:99 |
9.3 Browser Profile
| Profile 名稱 | Driver | Port | 用途 | 狀態 |
|---|---|---|---|---|
cdp-direct |
openclaw (CDP) | 18801 | 預設（CLI 使用），直連 Playwright Chromium | 使用中 |
chrome |
openclaw (CDP) | 18801 | 覆寫為 CDP，Agent 透過 Node Host 操控時固定走此 profile | 使用中 |
openclaw |
openclaw (CDP) | 18801 | 覆寫為 CDP（原為 Gateway 內建 port 18800，會嘗試啟動 snap Chromium 而失敗） | 使用中 |
設定位置：~/.openclaw/openclaw.json → browser.defaultProfile: "cdp-direct"
踩坑 1：
defaultProfile只影響 CLI 指令。Agent 透過 Node Host 操控瀏覽器時固定走chromeprofile，因此必須在browser.profiles中覆寫chrome的cdpUrl指向 Playwright CDP（port 18801），否則會走 extension relay 模式而報錯。踩坑 2：v2026.3.7 內建
openclawprofile（port 18800），Gateway 會嘗試用 detectedPath（/usr/bin/chromium-browser，snap 版）啟動瀏覽器。snap Chromium 會剝掉 CDP 參數導致永遠啟動失敗，agent tool call 15 秒後 timeout。修復：在browser.profiles覆寫openclawprofile，讓它也指向 Playwright CDP（port 18801）。
9.4 常用指令
# 狀態查看
openclaw browser status # 查看預設 profile 狀態
openclaw browser profiles # 列出所有 profile
openclaw nodes status # Node Host 連線狀態
# 分頁操作
openclaw browser tabs # 列出分頁
openclaw browser open <url> # 開新分頁
openclaw browser navigate <url> # 當前分頁導航
openclaw browser focus <tab-id> # 切換分頁
openclaw browser close <tab-id> # 關閉分頁
# 截圖與快照
openclaw browser screenshot # 截圖
openclaw browser screenshot --full-page # 完整頁面截圖
openclaw browser snapshot # AI 可讀的頁面快照（預設 ai 格式）
openclaw browser snapshot --format aria # Accessibility tree 格式
# 互動操作
openclaw browser click <ref> # 點擊元素
openclaw browser type <ref> "text" # 輸入文字
openclaw browser press Enter # 按鍵
openclaw browser hover <ref> # 滑鼠 hover
openclaw browser fill --fields '[...]' # 表單填寫
# 其他
openclaw browser pdf # 存成 PDF
openclaw browser console --level error # 查看 console 錯誤
openclaw browser evaluate --fn '...' # 執行 JavaScript
9.5 安裝步驟（從零開始）
# 1. 確保 Xvfb 在運行（DISPLAY=:99）
pgrep -la Xvfb
# 2. 安裝 Playwright 瀏覽器（如未安裝）
npx playwright install chromium
# 3. 安裝 OpenClaw Node service
openclaw node install
# 手動加入 DISPLAY=:99 到 service 檔案
# ~/.config/systemd/user/openclaw-node.service → Environment=DISPLAY=:99
# 4. 確保 gateway.env 也有 DISPLAY=:99
echo 'DISPLAY=:99' >> ~/.config/openclaw/gateway.env
# 5. 啟動 Node service 並配對
systemctl --user daemon-reload
systemctl --user enable --now openclaw-node.service
# 等待 Node 連上 Gateway 後出現 pending device
openclaw devices list # 查看 pending request
openclaw devices approve <id> # 核准配對
# 6. 建立 Playwright Chrome service
# 見 ~/.config/systemd/user/playwright-chrome.service
systemctl --user enable --now playwright-chrome.service
# 7. 建立 cdp-direct browser profile
openclaw browser create-profile --name cdp-direct --cdp-url http://127.0.0.1:18801 --driver openclaw
# 8. 設為預設 profile，並覆寫 chrome + openclaw profile
# 在 openclaw.json 的 browser 區塊：
# "defaultProfile": "cdp-direct"
# "profiles": {
# "cdp-direct": { "cdpUrl": "http://127.0.0.1:18801", "color": "#00AAFF" },
# "chrome": { "cdpUrl": "http://127.0.0.1:18801", "color": "#00AA00" },
# "openclaw": { "cdpUrl": "http://127.0.0.1:18801", "color": "#FF4500" }
# }
# chrome profile 必須覆寫，Agent 透過 Node Host 固定走此 profile
# openclaw profile 必須覆寫，否則 Gateway 嘗試用 snap Chromium 啟動而 timeout
# 9. 重啟 Gateway
systemctl --user restart openclaw-gateway
# 10. 驗證
openclaw browser status
openclaw browser navigate https://example.com
openclaw browser screenshot
9.6 已知問題
| 問題 | 原因 | 修復 |
|---|---|---|
Snap Chromium 不支援 --load-extension / --remote-debugging-port |
snap 沙箱會剝掉安全相關旗標 | 改用 Playwright Chromium（非 snap，直接二進位） |
Node service pairing required |
首次連線需經 Gateway 核准 | openclaw devices approve <id> |
| Browser start timeout | Node/Gateway 缺少 DISPLAY 環境變數 |
在 service 和 gateway.env 加 DISPLAY=:99；Gateway service 本身也需要 Environment=DISPLAY=:99 |
openclaw browser start --browser-profile chrome 需要點擴充套件 |
chrome profile 使用 extension relay 模式 |
改用 cdp-direct profile（CDP 直連，不需擴充套件） |
| Port 18800 被 Gateway 佔用 | openclaw profile 預設使用 18800 |
自訂 port 使用 18801 |
| Agent 操控瀏覽器仍報 extension relay 錯誤 | defaultProfile 只影響 CLI，Agent 透過 Node Host 固定走 chrome profile |
在 openclaw.json 的 browser.profiles 覆寫 chrome 的 cdpUrl 指向 Playwright CDP port 18801 |
| Agent browser tool timeout（v2026.3.7，2026-03-11） | 內建 openclaw profile 嘗試用 snap Chromium 啟動（detectedPath: /usr/bin/chromium-browser），snap 會剝掉 --remote-debugging-port 導致 CDP 永遠無法建立 |
在 browser.profiles 覆寫 openclaw profile 的 cdpUrl 指向 Playwright CDP port 18801；同時確認 Gateway service 有 Environment=DISPLAY=:99 |