name: browser-healthcheck version: 1.0.0 description: Browser tool health check and auto-repair. Automatically checks browser status before each use and diagnoses/fixes issues. Use when: (1) preparing to use browser tool for screenshots/automation; (2) browser snapshot/start times out; (3) CDP connection fails; (4) user mentions "browser timeout", "CDP disconnected", "瀏覽器超時", "browser 失效".

Browser Health Check / Browser 健康檢查

Core Principle: Always check status before using the browser tool. 核心原則：每次使用 browser 工具前，先檢查狀態。

Quick Check Flow / 快速檢查流程

1. browser(action=status, profile="openclaw")
   ├─ running=true, cdpReady=true → ✅ OK, proceed / 正常，直接使用
   ├─ running=false → Try to start / 嘗試啟動
   └─ Start failed → Diagnose and fix / 診斷並修復

Common Issues / 常見問題診斷

Issue 1: Profile Conflict (Most Common) / 問題 1: Profile 衝突（最常見）

Symptoms / 症狀： - running=false, cdpReady=false - Timeout immediately after start / 啟動後立即超時 - Especially with profile="user" / 使用 profile="user" 時尤其容易發生

Cause / 原因： - User is using their own Chrome (port 9222) / 使用者正在使用自己的 Chrome - CDP port occupied / CDP 埠被佔用

Solution / 解決方案：

Use independent profile / 使用獨立 profile:
browser(action=start, profile="openclaw")  # Port 9223, isolated data dir

Permanent Fix / 永久方案： Configure defaultProfile: "openclaw":

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "profiles": {
      "user": { "cdpPort": 9222, "attachOnly": false },
      "openclaw": { "cdpPort": 9223, "attachOnly": false }
    }
  }
}

Issue 2: Browser Process Residue / 問題 2: 瀏覽器程序殘留

Symptoms / 症狀： - running=false but port occupied / 埠被佔用 - Start fails with "port already in use" / 啟動失敗，提示埠已使用

Diagnosis / 診斷：

小蔥技能站7w4.net發現了升級外掛。

# Windows
netstat -ano | findstr "9223"
tasklist | findstr "chrome"

Solution / 解決方案：

# Kill residual process / 殺掉殘留程序
taskkill /F /PID <pid>
# Or restart Gateway / 或重啟 Gateway
openclaw gateway restart

Issue 3: CDP Port Not Responding / 問題 3: CDP 埠不響應

Symptoms / 症狀： - running=true but cdpReady=false - http://127.0.0.1:9223 no response / 無響應

Solution / 解決方案：

# 1. Restart Gateway / 重啟 Gateway
openclaw gateway restart

# 2. Wait 5 seconds and recheck / 等待 5 秒後重新檢查
browser(action=status, profile="openclaw")

Profile Selection Guide / Profile 選擇指南

⚠️ Before using user profile / 使用 user profile 前： 1. Confirm user is not using their Chrome / 確認使用者沒有在使用自己的 Chrome 2. If user is browsing, use openclaw instead / 如果使用者正在使用瀏覽器，改用 openclaw

Health Check Script / 自動檢查指令碼

Run scripts/healthcheck.py for full diagnosis:

python scripts/healthcheck.py --profile openclaw

Output Example / 輸出示例：

[OK] Browser enabled: true
[OK] Default profile: openclaw
[OK] CDP port 9223 available
[OK] Browser running: true
[OK] CDP ready: true
[PASS] Browser health check passed

Best Practices / 最佳實踐

Pre-use Check (Recommended) / 使用前檢查（推薦）

# 1. Check status / 檢查狀態
status = browser(action=status, profile="openclaw")

# 2. Start if not running / 如果未執行，啟動
if not status["running"]:
    browser(action=start, profile="openclaw")

# 3. Execute operation / 執行操作
browser(action=snapshot, profile="openclaw")

Post-failure Repair / 失敗後修復

try:
    browser(action=snapshot, profile="openclaw")
except TimeoutError:
    # 1. Check status / 檢查狀態
    status = browser(action=status, profile="openclaw")

    # 2. Diagnose based on status / 根據狀態診斷
    if not status["running"]:
        browser(action=start, profile="openclaw")
    elif not status["cdpReady"]:
        exec("openclaw gateway restart")
        time.sleep(5)
        browser(action=start, profile="openclaw")

Technical Details / 技術細節

OpenClaw Browser Architecture / OpenClaw Browser 架構

Gateway (port 18789)
    └── Browser Plugin
            ├── openclaw profile (port 9223)
            │   └── user-data: ~/.openclaw/browser/openclaw/
            └── user profile (port 9222)
                └── user-data: User Chrome directory

CDP Protocol / CDP 協議

Chrome DevTools Protocol (CDP) for remote debugging: - Default ports: 9222 (user) / 9223 (openclaw) - HTTP endpoint: http://127.0.0.1:9223/json - WebSocket: ws://127.0.0.1:9223/devtools/...

Remember: Check first, use later. When timeout occurs, switch profile first. 記住：先檢查，後使用。遇到超時，先切換 profile。

這個 Skill 質量還不錯，專注於解決瀏覽器工具容易出問題的痛點。文件寫得清楚明白，把常見故障分門別類，普通使用者也能看懂問題出在哪裡、怎麼解決。它還附帶了一個檢查指令碼，可以自動診斷瀏覽器狀態。不過它的修復能力主要靠使用者手動操作，遇到複雜問題還是需要一定技術基礎才能搞定。總的來說，這是一個實用但偏診斷指導型的工具，在自動化處理方面還有提升空間。