openclaw - 💡(How to fix) Fix [Bug]: Linux systemd auto-update can shut down gateway and fail to restart from service cgroup [1 comments, 2 participants]

Bug type

Regression / reliability bug

Summary

On a Linux install managed by a user-level systemd service, OpenClaw gateway auto-update can terminate the running gateway, report the auto-update as failed, and leave the service offline until a manual update/restart is run outside the gateway service context.

This appears distinct from the previously reported macOS LaunchAgent restart issues: the observed service manager is Linux systemd --user.

Environment

• OS: Linux x64
• Node.js: 22.x
• Install method: global npm/pnpm-style install
• Gateway service: systemd --user unit, Restart=always, SuccessExitStatus=0 143
• OpenClaw: running version before incident was 2026.5.2; auto-update target logged as 2026.5.3-1; manual recovery installed 2026.5.4
• Update channel: stable
• update.auto.enabled: true

What happened

A stable auto-update became due and the running gateway attempted to apply it from inside the gateway service process.

Observed sanitized timeline:

00:14 UTC  auto-update still deferred; target version 2026.5.3-1
01:14 UTC  gateway receives SIGTERM
01:14 UTC  gateway logs: received SIGTERM; shutting down
01:14 UTC  shutdown completed cleanly
01:14 UTC  auto-update attempt failed: reason=non-zero-exit, target=2026.5.3-1

Later manual restart attempts start the old gateway again, but it repeats the same auto-update failure path and shuts down again.

Manual `openclaw update` run from an interactive shell later installs 2026.5.4 and restarts the gateway successfully.

Relevant sanitized log shape:

[gateway] signal SIGTERM received
[gateway] received SIGTERM; shutting down
[gateway/shutdown] shutdown started: gateway stopping
[gateway] auto-update attempt failed { channel: "stable", version: "2026.5.3-1", reason: "non-zero-exit" }
[gateway/shutdown] shutdown completed cleanly

The gateway restart log contained no auto-update restart-script entry for the failed in-service auto-update attempts. It only contained entries for a later manual openclaw update invocation, which succeeded:

openclaw restart attempt source=update target=openclaw-gateway.service
openclaw restart done source=update

Expected behavior

Auto-update should not be able to leave a systemd-managed gateway offline. At least one of these should happen:

1. The update/restart handoff survives the old gateway service being stopped.
2. The old gateway remains running if the update cannot safely restart it.
3. The service exits in a way that systemd retries/restarts it into a healthy state.
4. The failure is surfaced clearly and auto-update backs off without repeatedly killing the service on each manual start.

Actual behavior

The gateway stopped cleanly after SIGTERM, auto-update logged non-zero-exit, and the service stayed unavailable until manual intervention. Re-starting the old service repeated the failed auto-update shutdown path.

Suspected root cause

The Linux update restart helper currently generates a shell script that does roughly:

sleep 1
systemctl --user restart openclaw-gateway.service

and launches it with Node spawn(..., { detached: true }).unref().

Detaching the process from the Node parent may not be enough under systemd: the helper is still started from inside the gateway unit's cgroup. When it calls systemctl --user restart <same-unit>, systemd stops the unit and may kill the entire service control group, including the helper that was supposed to complete the restart/logging. That would explain:

• the gateway receiving SIGTERM,
• no successful in-service restart log entry,
• the update command returning non-zero from the gateway auto-update path,
• manual openclaw update from an interactive shell succeeding because it runs outside the gateway service cgroup.

Potential mitigations might include running the restart helper outside the gateway unit cgroup, e.g. via systemd-run --user --scope or a transient user unit, or otherwise avoiding systemctl restart of the current unit from a child process that remains in the unit cgroup.

Steps to reproduce

Exact reproduction was observed during a stable auto-update window rather than a synthetic test, but the likely reproduction shape is:

1. Install an older OpenClaw version on Linux with a user systemd gateway service.
2. Enable stable auto-update.
3. Let the gateway's internal auto-update check reach a due newer version.
4. Observe whether the in-service update path sends SIGTERM and leaves the gateway offline or in a repeated start/update/fail loop.

Impact

Complete gateway outage until manual intervention. Inbound channel messages are not processed while the gateway is offline.

Notes

This report intentionally omits hostnames, user IDs, tokens, chat IDs, full local paths, and unrelated deployment details.