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 / 症状：
Solution / 解决方案：
# 1. Restart Gateway / 重启 Gateway
openclaw gateway restart
# 2. Wait 5 seconds and recheck / 等待 5 秒后重新检查
browser(action=status, profile="openclaw")
Profile Selection Guide / Profile 选择指南
| Profile | Port / 端口 | Data Directory / 数据目录 | Use Case / 适用场景 |
|---|
openclaw | 9223 | ~/.openclaw/browser/openclaw/user-data | Default choice / 默认选择, isolated, no conflict |
user | 9222 | User Chrome data dir / 用户 Chrome 目录 | Need user's logged-in accounts (YouTube etc.) |
⚠️ Before using user profile / 使用 user profile 前：
- Confirm user is not using their Chrome / 确认用户没有在使用自己的 Chrome
- 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。
