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:

1. Detect-only mode is the default — no processes are killed without INLINECODE1
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 INLINECODE3
No root required — runs as regular user

Usage

Detect only (safe, default)

CODEBLOCK0

Output example:
CODEBLOCK1

Detect and clean

CODEBLOCK2

Options

Option	Default	Description
INLINECODE4	off	Actually terminate zombie processes
INLINECODE5

Integration with Health Checks

Add to your health check script or heartbeat:

CODEBLOCK3

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

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) |

浏览器僵尸进程清理工具

检测并清理OpenClaw网关重启后遗留的孤立浏览器进程。

问题描述

OpenClaw的browser工具使用Playwright启动Chrome/Chromium/Firefox。当网关重启（更新、崩溃、手动重启）时，这些浏览器子进程会成为孤儿进程——它们的父PID变为1（init/systemd）。这些进程持续运行，消耗内存，并随时间累积。

安全设计

本工具默认安全：

1. 仅检测模式为默认设置——不使用--kill参数不会终止任何进程
三重验证：OpenClaw用户数据目录模式 + 孤儿PPID + 最小存活时间
仅处理当前用户进程——绝不触及其他用户
仅识别OpenClaw浏览器——通过命令行中的~/.openclaw/browser/标识
优雅关闭——先发送SIGTERM，宽限期过后才发送SIGKILL
审计日志——所有操作记录到/tmp/openclaw/zombie-browser-cleanup.log
无需root权限——以普通用户身份运行

使用方法

仅检测（安全，默认）

bash
bash /scripts/cleanup-zombie-browsers.sh

输出示例：

发现8个OpenClaw浏览器进程，其中5个为僵尸进程（总计1200MB）
僵尸进程: PID=66301 PPID=1 存活时间=3天2小时内存=388MB
僵尸进程: PID=152356 PPID=1 存活时间=2天4小时内存=168MB
...
使用 --kill 参数可终止这些僵尸进程

检测并清理

bash
bash /scripts/cleanup-zombie-browsers.sh --kill

选项说明

选项	默认值	描述
--kill	关闭	实际终止僵尸进程
--min-age N

集成健康检查

添加到您的健康检查脚本或心跳检测中：

bash

检测并报告（不终止）

bash /path/to/cleanup-zombie-browsers.sh

自动清理并保留安全余量（进程存活超过2小时）

bash /path/to/cleanup-zombie-browsers.sh --kill --min-age 7200

僵尸进程识别方法

满足以下所有条件的进程被归类为僵尸浏览器进程：

1. 浏览器进程——可执行文件名匹配chrome/chromium/brave/msedge/firefox
OpenClaw来源——命令行包含.openclaw/browser/（OpenClaw使用的用户数据目录）
孤儿进程——PPID为1（init）或systemd，表示父网关进程已不存在
存活足够久——进程存活时间超过--min-age阈值（防止终止正在初始化的浏览器）

只要任一条件不满足，该进程将被跳过。

平台支持

平台	状态	说明
Linux	完整支持	使用/proc文件系统进行精确检测
macOS

支持的浏览器

所有Playwright支持且使用OpenClaw用户数据目录的浏览器：

- Google Chrome / Chromium
Brave浏览器
Microsoft Edge
Firefox

退出码

代码	含义
0	未发现僵尸进程，或僵尸进程已清理（--kill模式）
1

检测到僵尸进程但未终止（检测模式） |

browser-zombie-cleaner僵尸浏览器清理