browser-recover
by @wind0ws
Recover the local Chromium/Chrome environment when browser tool calls fail. Use when encountering (1) Browser startup failures, (2) CDP connection errors (Ta...
clawhub install browser-recoverπ About This Skill
name: browser-recover description: Recover the local Chromium/Chrome environment when browser tool calls fail. Use when encountering (1) Browser startup failures, (2) CDP connection errors (Target closed, ECONNREFUSED, timeout), (3) Stale browser processes blocking new instances, (4) Port conflicts on 9222/18800, (5) Browser page freezes causing subsequent tool calls to fail. Automatically kills stale processes, clears lock files, releases ports, and retries the original browser task once.
Browser Recover
Automated recovery for OpenClaw browser environment failures.
Quick Start
When a browser tool call fails, follow this workflow:
1. Detect: Check if error matches browser environment issues
2. Diagnose: Run scripts/check_state.sh to inspect current state
3. Recover: Run scripts/recover.sh to clean up
4. Retry: Execute the original browser operation ONCE
5. Report: If still fails, output error summary and STOP
Error Pattern Matching
| Error Pattern | Likely Cause | Recovery Action |
|---------------|--------------|-----------------|
| Target closed | Stale CDP connection | recover.sh --kill-processes |
| ECONNREFUSED on port 9222/18800 | Port conflict | recover.sh --clear-ports |
| timeout during browser.start | Lock file conflict | recover.sh --clear-locks |
| Multiple chromium processes | Zombie processes | recover.sh --full |
| Profile in use | Stale lock files | recover.sh --clear-locks |
Recovery Scripts
check_state.sh
Diagnose browser environment without making changes.Usage:
bash scripts/check_state.sh
Output:
recover.sh
Clean up stale browser resources.Usage:
# Full recovery (default)
bash scripts/recover.shSpecific actions
bash scripts/recover.sh --kill-processes
bash scripts/recover.sh --clear-ports
bash scripts/recover.sh --clear-locksExplicit full recovery
bash scripts/recover.sh --full
Actions: 1. Kills stale browser processes (chromium, chrome variants) 2. Clears port conflicts (9222, 18800, configured ports) 3. Removes lock files (SingletonLock, SingletonSocket, SingletonCookie) 4. Clears cache directories (Cache, Code Cache, GPUCache) 5. Waits 2 seconds for resources to release
Configuration:
~/.openclaw/config/openclaw.json for browser settingsRetry Policy
Session-level tracking:
Implementation:
Attempt 1: browser fails β diagnose β recover β retry β success β
Attempt 2: browser fails β diagnose β recover β retry β fails β STOP
When to stop:
Safety Constraints
DO:
~/.openclaw/browserDON'T:
~/.config/chrome, etc.)kill -9 without verificationSee references/safety.md for detailed guidelines.
Troubleshooting
If recovery fails or behaves unexpectedly:
1. Run check_state.sh to diagnose
2. Check OpenClaw logs: ~/.openclaw/logs/
3. Verify configuration: ~/.openclaw/config/openclaw.json
4. Review references/troubleshooting.md
5. If unsure, escalate to human operator
Configuration
Scripts automatically read OpenClaw config for:
browser.debugPort)browser.userDataDir)See references/configuration.md for:
Example Workflow
User: "Open https://example.com"
Assistant: [calls browser tool]
Error: "ECONNREFUSED on port 9222"Assistant: Detected port conflict. Running recovery...
[runs check_state.sh]
[runs recover.sh --clear-ports]
[waits 2 seconds]
[retries browser tool]
Success: Browser opened https://example.com
Notes
π‘ Examples
When a browser tool call fails, follow this workflow:
1. Detect: Check if error matches browser environment issues
2. Diagnose: Run scripts/check_state.sh to inspect current state
3. Recover: Run scripts/recover.sh to clean up
4. Retry: Execute the original browser operation ONCE
5. Report: If still fails, output error summary and STOP
βοΈ Configuration
Scripts automatically read OpenClaw config for:
browser.debugPort)browser.userDataDir)See references/configuration.md for: