browser-recover

Recover the local Chromium/Chrome environment when browser tool calls fail. Use when encountering (1) Browser startup failures, (2) CDP connection errors (Ta...

Security Scan

The skill's stated goal (clean up OpenClaw-managed browser instances) matches the included scripts, but the implementation has notable inconsistencies and unsafe behaviors (broad pkill/kill usage, undocumented dependencies, and mismatches between SKILL.md promises and actual checks) that could affect user browsers or system processes.

Purpose & Capability

The skill's purpose (recover local Chromium/Chrome instances) aligns with what the scripts do (kill processes, clear ports, remove lock files). However the metadata declares no required binaries or environment variables while the scripts rely on tools (jq, lsof, fuser, pkill, kill) that may not be present. Also SKILL.md and references promise conservative targeting (verify ownership, only clean OpenClaw-managed instances), but the recovery script uses very broad process matching (pkill -f 'chromium' / 'chrome') without verifying ownership or command-line flags. This is disproportionate to the 'only clean OpenClaw-managed instances' safety promise.

Instruction Scope

SKILL.md instructs the agent to read OpenClaw config, verify process ownership, and only touch OpenClaw profiles. The actual scripts: read openclaw.json only for debugPort (they do not read userDataDir), do not verify process ownership or inspect command-line flags before pkill, and may use fuser or kill -9 to clear ports. That contradicts the documented safety constraints and gives the agent authority to terminate non-OpenClaw browser processes and forcibly kill processes by PID.

Install Mechanism

No install spec (instruction-only with bundled scripts). Nothing is downloaded or executed from external URLs during install. Scripts are included in the bundle and will run when invoked; there is no additional installer behavior to review.

Credentials

No credentials or secret environment variables are requested. The scripts read a local config path (~/.openclaw/config/openclaw.json) and use defaults under $HOME. The documentation and references claim additional env var support (OPENCLAW_BROWSER_PORT, OPENCLAW_BROWSER_PROFILE) but the scripts do not actually honor these, producing a capability/expectation mismatch. Dependence on system tools (jq, lsof, fuser) is not declared in metadata.

Persistence & Privilege

always is false and the skill does not request persistent platform-wide privileges. The scripts operate on local files under ~/.openclaw and do not modify other skills or global agent configuration. Autonomous invocation is allowed by default (not flagged alone), which combined with the unsafe kill behavior increases blast radius but is not itself a configuration error.

What to consider before installing

This skill is plausible for recovering OpenClaw browser instances, but the implementation has dangerous and inconsistent behaviors. Before installing or enabling it, consider: - Risk: recover.sh uses broad pkill patterns and may terminate non-OpenClaw browser processes (user's personal Chrome/Chromium). Port-clearing may kill processes by PID or use kill -9. This can cause user-visible disruption and data loss. - Mismatches: SKILL.md promises ownership checks and reading userDataDir / environment variables, but the scripts do not implement these checks or env var support and only read debugPort from config. The bundle also assumes commands (jq, lsof, fuser, pkill) exist but doesn't declare them. - Mitigations: review and modify the scripts before use — require exact command-line matching (e.g., match '--remote-debugging-port' or '--user-data-dir'), verify process owner (uid) and command-line before killing, avoid unconditional kill -9, and honor configured userDataDir / env vars. Add explicit dependency documentation (jq, lsof, fuser). Test in a VM/container with real user browser instances to confirm no unintended kills. If you cannot safely audit or modify the scripts, prefer manual recovery or request a corrected version that implements the documented safety checks.

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:

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

recover.sh

Clean up stale browser resources.

Usage:

# Full recovery (default)
bash scripts/recover.sh

# Specific actions
bash scripts/recover.sh --kill-processes
bash scripts/recover.sh --clear-ports
bash scripts/recover.sh --clear-locks

# Explicit 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:

• 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:

Attempt 1: browser fails → diagnose → recover → retry → success ✓
Attempt 2: browser fails → diagnose → recover → retry → fails → STOP

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 ~/.openclaw/browser
• 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. 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 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

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

• 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