openclaw - 💡(How to fix) Fix Helper commands can silently resurrect stopped user-level openclaw-gateway units

Summary

OpenClaw helper commands can silently resurrect a previously stopped user-level openclaw-gateway systemd unit. On systems where the installer created ~/.config/systemd/user/openclaw-gateway.service and linger is enabled, commands like openclaw status, openclaw doctor, or openclaw configure can cause the user service to start listening again even after systemctl --user stop and disable.

Environment

• OpenClaw version: 2026.5.7
• Host OS: Ubuntu 24.04
• Install style: native install with user-level systemd unit

Reproduction

# Fresh install as a user
curl -fsSL https://openclaw.dev/install.sh | bash
systemctl --user is-enabled openclaw-gateway
loginctl show-user "$USER" --property=Linger

# Stop and disable the user unit
systemctl --user stop openclaw-gateway
systemctl --user disable openclaw-gateway
ss -tlnp | grep 18789   # port appears free

# Run a helper command
openclaw status

# Gateway is back
ss -tlnp | grep 18789

Expected

If an operator explicitly stops and disables the user-level gateway unit, helper commands should not silently re-enable or restart it.

Actual

The gateway process can reappear under the user's UID after helper invocations or other triggers, which makes the port unexpectedly busy again.

Why this matters

This is a painful operational failure mode during cutovers or handoffs. In our case it caused a multi-hour NUC migration/debug session because the wrong user-level gateway kept reclaiming the port and conflicting with the intended service.

Likely cause

The helper path appears to do something equivalent to:

systemctl --user is-active openclaw-gateway || systemctl --user start openclaw-gateway

That behavior ignores operator intent unless the unit is masked.

Suggested fix

• Do not auto-start the user gateway from helper commands by default.
• If auto-start is necessary, require an explicit flag such as --ensure-running.
• Respect masked units and document the difference between disable and mask in installer/uninstall guidance.

Notes

Primary AoAOS doc:

• docs/upstream-bugs/user-systemd-autoresurrect-on-helper-invocation.md