Description

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

README (SKILL.md)

Browser Recover

Name: browser-recover
Author: wind0ws

Automated recovery for OpenClaw browser environment failures.

Quick Start

When a browser tool call fails, follow this workflow:

Detect: Check if error matches browser environment issues
Diagnose: Run scripts/check_state.sh to inspect current state
Recover: Run scripts/recover.sh to clean up
Retry: Execute the original browser operation ONCE
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:

Kills stale browser processes (chromium, chrome variants)
Clears port conflicts (9222, 18800, configured ports)
Removes lock files (SingletonLock, SingletonSocket, SingletonCookie)
Clears cache directories (Cache, Code Cache, GPUCache)
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:

Run check_state.sh to diagnose
Check OpenClaw logs: ~/.openclaw/logs/
Verify configuration: ~/.openclaw/config/openclaw.json
Review references/troubleshooting.md
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

Usage Guidance

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.

Capability Analysis

Type: OpenClaw Skill Name: browser-recover Version: 1.0.0 The browser-recover skill bundle provides diagnostic and recovery scripts (check_state.sh and recover.sh) designed to resolve common Chromium environment failures such as stale processes, port conflicts, and lock files. While the recovery script uses powerful commands like pkill and rm -rf, its actions are restricted to the OpenClaw environment (~/.openclaw/browser) and are accompanied by extensive safety documentation (safety.md) and troubleshooting guides. There is no evidence of data exfiltration, persistence mechanisms, or malicious intent.

Capability Assessment

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

Version History

v1.0.0

- Initial release of **browser-recover**: automated recovery for Chromium/Chrome environment failures in OpenClaw. - Detects and resolves common browser issues: startup failures, connection errors, port conflicts, stale processes, and page freezes. - Provides diagnostic (`check_state.sh`) and automated cleanup (`recover.sh`) scripts to recover broken browser states. - Supports safe, targeted cleanup: only affects OpenClaw-managed browser instances; avoids user browsers and unrelated data. - Implements retry and safety policies: limits recovery attempts, tracks session failures, and escalates persistent issues to human operators.

Metadata

Slug browser-recover

Version 1.0.0

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 1

Frequently Asked Questions

What is 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... It is an AI Agent Skill for Claude Code / OpenClaw, with 102 downloads so far.

How do I install browser-recover?

Run "/install browser-recover" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is browser-recover free?

Yes, browser-recover is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does browser-recover support?

browser-recover is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created browser-recover?

It is built and maintained by Threshold (@wind0ws); the current version is v1.0.0.

More Skills

browser-recover