browser-healthcheck（浏览器健康检查）

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 / 诊断：

# 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。