forked from Selig/openclaw-skill
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.
147 lines
7.7 KiB
Markdown
147 lines
7.7 KiB
Markdown
# 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 操控瀏覽器時**固定走 `chrome` profile**，因此必須在 `browser.profiles` 中覆寫 `chrome` 的 `cdpUrl` 指向 Playwright CDP（port 18801），否則會走 extension relay 模式而報錯。
|
||
>
|
||
> **踩坑 2**：v2026.3.7 內建 `openclaw` profile（port 18800），Gateway 會嘗試用 detectedPath（`/usr/bin/chromium-browser`，snap 版）啟動瀏覽器。snap Chromium 會剝掉 CDP 參數導致永遠啟動失敗，agent tool call 15 秒後 timeout。**修復**：在 `browser.profiles` 覆寫 `openclaw` profile，讓它也指向 Playwright CDP（port 18801）。
|
||
|
||
### 9.4 常用指令
|
||
|
||
```bash
|
||
# 狀態查看
|
||
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 安裝步驟（從零開始）
|
||
|
||
```bash
|
||
# 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` |
|