Recovery after a hard Gateway stop
On POSIX systems, OpenClaw checks for registered orphaned Codex app-server processes before spawning each fresh stdio child. Gateway startup also runs a best-effort background sweep; the before-spawn check remains authoritative. OpenClaw records the parent and child process identities in the current state directory’s SQLite plugin store before sending Codexinitialize, so a child cannot start a native turn before
its registration is durable.
Cleanup only targets a registered child whose original OpenClaw parent is no
longer running. It checks process IDs, start times, and process groups before
terminating the orphan and its discoverable descendants. When recorded, a
fingerprint of the child command line must also match the live process before
signaling; the durable registration stores only that digest, never the raw
arguments. Another live
OpenClaw instance, processes registered under another state directory, and externally
managed WebSocket or Unix-socket app-servers are left alone. These portable
process checks do not provide an atomic operating-system ownership guarantee
or discover descendants that independently reparented before inspection.
Linux reads process identities directly from /proc, including the boot ID
and process start ticks, so Alpine/BusyBox installations do not need procps.
Startup identity and command inspection share a 10-second deadline. During Linux
startup, an empty command line waits within that deadline while the same live
process identity remains valid. Registration still
requires a usable command fingerprint; unreadable or changed identities fail.
macOS uses its native ps with a fixed locale and timezone. Registration checks
inspect only the observer and the relevant parent and child processes; an
unrelated unreadable process does not block those checks. Destructive cleanup
still requires full process-tree inspection and fresh identity checks before
signaling.
If a required process cannot be inspected or bounded cleanup cannot confirm that
the registered orphan is gone, the new stdio connection fails instead of spawning
another child. Follow the reported reason: a deadline failure calls for checking
host load and Gateway logs, while an access-denied failure calls for checking
/proc access on Linux or ps permissions on macOS. Other inspection failures
require checking that the process-inspection facility is available and returning
usable data. Do not broaden permissions to address a timeout. If cleanup cannot
stop a verified orphan, inspect and stop that process before retrying. If the
cleanup budget expires, retry to finish the remaining registrations.
This recovery requires a spawn-time registration. It does not discover
unregistered children left by an older OpenClaw version or scan command names
to infer ownership. Windows has no equivalent orphan registration or
recovery.