Browser Health Check / Browser 健康检查
Core Principle: Always check status before using the browser tool.
核心原则：每次使用 browser 工具前，先检查状态。
Quick Check Flow / 快速检查流程
CODEBLOCK0
Common Issues / 常见问题诊断
Issue 1: Profile Conflict (Most Common) / 问题 1: Profile 冲突（最常见）
Symptoms / 症状：
- - INLINECODE0
- 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 / 解决方案：
CODEBLOCK1
Permanent Fix / 永久方案：
Configure defaultProfile: "openclaw":
CODEBLOCK2
Issue 2: Browser Process Residue / 问题 2: 浏览器进程残留
Symptoms / 症状：
- -
running=false but port occupied / 端口被占用 - Start fails with "port already in use" / 启动失败，提示端口已使用
Diagnosis / 诊断：
CODEBLOCK3
Solution / 解决方案：
CODEBLOCK4
Issue 3: CDP Port Not Responding / 问题 3: CDP 端口不响应
Symptoms / 症状：
- -
running=true but INLINECODE6 - http://127.0.0.1:9223 no response / 无响应
Solution / 解决方案：
CODEBLOCK5
Profile Selection Guide / Profile 选择指南
| Profile | Port / 端口 | Data Directory / 数据目录 | Use Case / 适用场景 |
|---|
| INLINECODE7 | 9223 | INLINECODE8 | Default choice / 默认选择, isolated, no conflict |
| INLINECODE9 |
9222 | User Chrome data dir / 用户 Chrome 目录 | Need user's logged-in accounts (YouTube etc.) |
⚠️ Before using user profile / 使用 user profile 前：
- 1. Confirm user is not using their Chrome / 确认用户没有在使用自己的 Chrome
- If user is browsing, use
openclaw instead / 如果用户正在使用浏览器，改用 INLINECODE13
Health Check Script / 自动检查脚本
Run scripts/healthcheck.py for full diagnosis:
CODEBLOCK6
Output Example / 输出示例：
CODEBLOCK7
Best Practices / 最佳实践
Pre-use Check (Recommended) / 使用前检查（推荐）
CODEBLOCK8
Post-failure Repair / 失败后修复
CODEBLOCK9
Technical Details / 技术细节
OpenClaw Browser Architecture / OpenClaw Browser 架构
CODEBLOCK10
CDP Protocol / CDP 协议
Chrome DevTools Protocol (CDP) for remote debugging:
- - Default ports: 9222 (user) / 9223 (openclaw)
- HTTP endpoint: INLINECODE15
- WebSocket: INLINECODE16
Remember: Check first, use later. When timeout occurs, switch profile first.
记住：先检查，后使用。遇到超时，先切换 profile。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:
json
{
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 / 诊断：
bash
Windows
netstat -ano | findstr 9223
tasklist | findstr chrome
Solution / 解决方案：
bash
Kill residual process / 杀掉残留进程
taskkill /F /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 / 解决方案：
bash
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 users logged-in accounts (YouTube etc.) |
⚠️ Before using user profile / 使用 user profile 前：
- 1. 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:
bash
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) / 使用前检查（推荐）
python
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 / 失败后修复
python
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。
