功能描述

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

使用说明 (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

安全使用建议

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.

功能分析

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.

能力评估

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

版本历史

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.

元数据

Slug browser-recover

版本 1.0.0

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 1

常见问题

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... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 102 次。

如何安装 browser-recover？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install browser-recover」即可一键安装，无需额外配置。

browser-recover 是免费的吗？

是的，browser-recover 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

browser-recover 支持哪些平台？

browser-recover 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 browser-recover？

由 Threshold（@wind0ws）开发并维护，当前版本 v1.0.0。

browser-recover