Browser Zombie Cleaner

Detect and clean up zombie browser processes left by OpenClaw's browser tool. When the OpenClaw Gateway restarts, Playwright-launched browser processes get o...

Security Scan

The skill's code and instructions match its stated purpose (detect and optionally terminate orphaned OpenClaw-launched browser processes) and do not request unrelated credentials or installs; it defaults to detect-only and includes several safety checks.

Purpose & Capability

Name/description match the implementation: the script scans processes (via /proc and ps), filters by current user and a user-data-dir pattern (.openclaw/browser/) and optionally kills matched orphans. It does not ask for cloud credentials, global system access, or unrelated binaries.

Instruction Scope

The SKILL.md and script stay within the declared purpose. The script reads /proc and invokes normal system utilities, and only kills when --kill is passed. Two cautionary notes: (1) it inspects full command lines, which can include sensitive arguments — these are written to the log by default; (2) platform-specific parsing (macOS ps parsing) can be brittle and could misclassify processes in edge cases. The presence of a configurable pattern and min-age mitigates accidental kills but requires the operator to verify settings.

Install Mechanism

Instruction-only skill with a bundled shell script; no install spec, no external downloads, and no packages are installed. Lowest-risk distribution model.

Credentials

No credentials or privileged environment variables are required. The script supports an optional OPENCLAW_ZOMBIE_LOG env var and allows custom pattern/log path via CLI; these are reasonable and proportionate for the task.

Persistence & Privilege

always is false and the skill does not request permanent/forced inclusion or modify other skills or system-wide settings. It runs as the invoking user and explicitly avoids touching other users' processes.

Assessment

This skill appears to do what it says, but follow safe steps before using its kill functionality: (1) run the default detect-only mode and review the output to confirm detected PIDs are indeed orphaned OpenClaw browser processes; (2) inspect the log file (default /tmp/openclaw/zombie-browser-cleanup.log) and consider setting --log to a secure path so command lines (which may contain sensitive args) aren't left in a world-readable temp file; (3) tune --pattern and --min-age to your environment to avoid false positives; (4) avoid running as root — the script is designed to run as the regular user; (5) on macOS test the parsing thoroughly because ps output parsing can be brittle. If you need extra assurance, run with --json and validate programmatically before enabling automatic --kill runs.

Detect and clean up orphaned browser processes left behind when OpenClaw Gateway restarts.

The Problem

OpenClaw's browser tool uses Playwright to launch Chrome/Chromium/Firefox. When the Gateway restarts (update, crash, manual restart), these browser child processes become orphans — their parent PID changes to 1 (init/systemd). They keep running, consuming memory, and accumulate over days.

Safety Design

This tool is safe by default:

1. Detect-only mode is the default — no processes are killed without --kill
2. Triple verification before killing: OpenClaw user-data-dir pattern + orphaned PPID + minimum age
3. Only current user's processes — never touches other users
4. Only OpenClaw browsers — identified by ~/.openclaw/browser/ in the command line
5. Graceful shutdown — SIGTERM first, SIGKILL only after grace period
6. Audit log — every action is logged to /tmp/openclaw/zombie-browser-cleanup.log
7. No root required — runs as regular user

Usage

Detect only (safe, default)

bash <skill_dir>/scripts/cleanup-zombie-browsers.sh

Output example:

Found 8 OpenClaw browser processes, 5 are zombies (1200MB total)
  ZOMBIE: PID=66301 PPID=1 age=3d 2h mem=388MB
  ZOMBIE: PID=152356 PPID=1 age=2d 4h mem=168MB
  ...
Run with --kill to terminate these zombie processes

Detect and clean

bash <skill_dir>/scripts/cleanup-zombie-browsers.sh --kill

Options

Option	Default	Description
--kill	off	Actually terminate zombie processes
--min-age N	3600 (1h)	Only target processes older than N seconds
--grace N	10	Seconds between SIGTERM and SIGKILL
--json	off	Output as JSON (for programmatic use)
--log PATH	/tmp/openclaw/zombie-browser-cleanup.log	Log file location
--pattern STR	.openclaw/browser/	Pattern to identify OpenClaw browsers

Integration with Health Checks

Add to your health check script or heartbeat:

# Detect and report (no kill)
bash /path/to/cleanup-zombie-browsers.sh

# Auto-clean with safety margin (processes must be >2 hours old)
bash /path/to/cleanup-zombie-browsers.sh --kill --min-age 7200

How It Identifies Zombies

A process is classified as a zombie browser if ALL of these are true:

1. Browser process — executable name matches chrome/chromium/brave/msedge/firefox
2. OpenClaw origin — command line contains .openclaw/browser/ (the user-data-dir used by OpenClaw)
3. Orphaned — PPID is 1 (init) or systemd, meaning the parent Gateway process is gone
4. Old enough — process age exceeds --min-age threshold (prevents killing browsers that are actively initializing)

If ANY condition is not met, the process is skipped.

Platform Support

Platform	Status	Notes
Linux	Full	Uses /proc filesystem for precise detection
macOS	Full	Uses ps with etime parsing
Windows	Not yet	Planned (PowerShell-based)

Supported Browsers

All Playwright-supported browsers with OpenClaw user-data-dir:

• Google Chrome / Chromium
• Brave Browser
• Microsoft Edge
• Firefox

Exit Codes

Code	Meaning
0	No zombies found, or zombies cleaned (--kill mode)
1	Zombies detected but not killed (detect mode)