knownasnaffy Browser Zombie Cleaner
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:
- Detect-only mode is the default — no processes are killed without
--kill - Triple verification before killing: OpenClaw user-data-dir pattern + orphaned PPID + minimum age
- Only current user's processes — never touches other users
- Only OpenClaw browsers — identified by
~/.openclaw/browser/in the command line - Graceful shutdown — SIGTERM first, SIGKILL only after grace period
- Audit log — every action is logged to
/tmp/openclaw/zombie-browser-cleanup.log - 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:
- Browser process — executable name matches chrome/chromium/brave/msedge/firefox
- OpenClaw origin — command line contains
.openclaw/browser/(the user-data-dir used by OpenClaw) - Orphaned — PPID is 1 (init) or systemd, meaning the parent Gateway process is gone
- Old enough — process age exceeds
--min-agethreshold (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) |