openclaw - 💡(How to fix) Fix [Bug]: Stale plugin-runtime-deps lock survives container restart and is never reclaimed (PID collision in containers) [1 comments, 2 participants]

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

Summary

When OpenClaw runs in a container with persistent storage for ~/.openclaw/plugin-runtime-deps/, a lock left behind by a prior gateway process is incorrectly treated as live by the next gateway, because lock ownership is identified by PID alone. In a container's PID namespace the new gateway frequently lands on the same PID as the previous one (typically 7), so the liveness check trivially succeeds and the new gateway waits the full 300s timeout per plugin before giving up. All plugins that need bundled runtime deps fail to initialise.

Environment

• OpenClaw version: 2026.4.26
• Deployment: Docker container (Coolify-managed), Debian trixie / Node 24, ARM64
• Persistent volume mounted at /home/node/.openclaw

Evidence of the PID collision

From a stuck container:

$ docker exec <c> cat .openclaw-runtime-mirror.lock/owner.json
{"pid":7,...,"startedAt":"2026-04-30T07:37:..."}

$ docker exec <c> ps -o pid,etime,cmd -p 7
  PID     ELAPSED CMD
    7    00:09:14 openclaw-gateway

The recorded startedAt is from the previous container; the live pid 7 is the new gateway, started 9 minutes ago. PID alone cannot distinguish them.

Workaround

Delete the lock directory before starting the gateway:

rm -rf ~/.openclaw/plugin-runtime-deps/openclaw-<version>-<hash>/.openclaw-runtime-mirror.lock

An entrypoint script can do this conditionally — the lock should never legitimately exist at startup, since it is only held during an active deps install.

Suggested fix

Record more discriminating identity in owner.json and validate all of it before treating the lock as live. Any one of the following would make the bug unreachable; combining a couple gives belt and braces:

• Process start time (/proc/<pid>/stat field 22, or ps -o lstart). Cheap, namespace-agnostic, and uniquely identifies a process across PID reuse.
• Boot ID (/proc/sys/kernel/random/boot_id). Different across container restarts and host reboots.
• Container ID / hostname (/etc/hostname is the short container ID by default). Trivially differs between container instances.
• A self-test write: have the lock holder periodically touch a heartbeat file; treat the lock as stale if the heartbeat is older than N seconds.

The owner check should require the recorded and observed values to match, not just kill(pid, 0).

Additional notes

• Persistent storage of plugin-runtime-deps is desirable — it avoids a 25-minute reinstall on every container restart for plugins like lossless-claw. The fix should preserve that benefit.
• The error message already prints ownerAge (the wall-clock age of the lock). It might be worth surfacing that more prominently, or warning when ownerAge greatly exceeds typical install duration, so operators notice staleness sooner.

Steps to reproduce

1. Run OpenClaw in a container with ~/.openclaw on a persistent volume.
2. While the gateway is starting (specifically while bundled runtime deps are being installed by any plugin), stop the container ungracefully — docker kill, OOM, host reboot, or docker compose down mid-startup. The lock directory is not removed on exit.
3. Start a new container against the same volume.

Expected behavior

The new gateway detects that the lock owner is from a previous run and reclaims the lock, then proceeds normally.

Actual behavior

The new gateway reads owner.json, finds pid=7, asks the kernel whether pid 7 is alive, and gets true — because the new gateway process is itself pid 7 in its own namespace. Each plugin needing bundled deps then waits the full 300s lock timeout and fails validation:

[gateway] [plugins] failed to install bundled runtime deps: Error: Timed out waiting
for bundled runtime deps lock at .../.openclaw-runtime-mirror.lock
(waited=300068ms, ownerFile=ok, pid=7 alive=true, ownerAge=326616ms, ...)

Plugins serialise on the lock, so the failures are spaced 300s apart. In our case browser, discord, memory-core, slack, and telegram all failed; the gateway came up with only lossless-claw (which had genuinely held the lock during the previous run's install).

OpenClaw version

2026.4.26

Operating system

Debian GNU/Linux 13 (trixie)

Install method

npm install -g [email protected]

Model

N/A

Provider / routing chain

N/A

Additional provider/model setup details

No response

Logs, screenshots, and evidence

Impact and severity

No response

Additional information

No response