Browser Recover

Automated recovery for OpenClaw browser environment failures.

Quick Start

When a browser tool call fails, follow this workflow:

1. 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

Recovery Scripts

check_state.sh

Usage:
CODEBLOCK0

Output:

• - Browser process count and PIDs
• Port usage status (9222, 18800, custom ports)
• Lock file locations
• Recommendation (clean or no action needed)

recover.sh

Usage:
CODEBLOCK1

Actions:

1. 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:

• - Reads ~/.openclaw/config/openclaw.json for browser settings
• Falls back to defaults if config not found
• See references/configuration.md for details

Retry Policy

Session-level tracking:

• - Maximum 2 recovery attempts per session
• Track failures to prevent infinite loops
• Stop after 2nd failure and escalate to human

Implementation:
CODEBLOCK2

When to stop:

• - 2nd recovery in same session fails
• Error is not browser-environment related
• System-level issues detected (permissions, resources)
• User explicitly requests manual intervention

Safety Constraints

DO:

• - Only clean OpenClaw-managed browser instances
• Verify process ownership before killing
• Check profile path matches INLINECODE12
• Log all actions to stderr for OpenClaw to capture

DON'T:

• - Kill user's personal browser processes
• Delete user profile directories (~/.config/chrome, etc.)
• Use kill -9 without verification
• Restart entire system
• Clean up other agents' browser instances without isolation

See references/safety.md for detailed guidelines.

Troubleshooting

If recovery fails or behaves unexpectedly:

1. 1. Run check_state.sh to diagnose
2. Check OpenClaw logs: INLINECODE16
3. Verify configuration: INLINECODE17
4. Review references/troubleshooting.md
5. If unsure, escalate to human operator

Configuration

Scripts automatically read OpenClaw config for:

• - Browser debug port (browser.debugPort)
• Profile directory (browser.userDataDir)

See references/configuration.md for:

• - Custom port configuration
• Multiple instance setup
• Platform-specific notes
• Environment variables

Example Workflow

CODEBLOCK3

Notes

• - All scripts log to stderr for OpenClaw to capture automatically
• No separate log files are created
• Scripts read OpenClaw config for browser settings
• Recovery is idempotent (safe to run multiple times)
• Maximum 2 recovery attempts per session to prevent loops