Issue 1: Gateway shows "disabled" despite running

Symptom: openclaw status or openclaw gateway status shows disabled, but the service is actually running.

Root cause: The gateway process spawns systemctl --user is-enabled without XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS in its environment. Without these, systemd user bus is unreachable → "Failed to connect to bus: No medium found".

⚠️ Common wrong fix: Adding these vars to ~/.bashrc or shell environment does NOT help — the gateway daemon doesn't inherit your shell env.

Correct fix: Add the vars directly to the systemd unit file:

RUNTIME_DIR="/run/user/$(id -u)"
UNIT=~/.config/systemd/user/openclaw-gateway.service
# Append env vars after [Service] line (idempotent check first)
grep -q "XDG_RUNTIME_DIR" "$UNIT" || python3 - "$UNIT" "$RUNTIME_DIR" <<'EOF'
import sys, re
unit, runtime = sys.argv[1], sys.argv[2]
content = open(unit).read()
insert = f"\nEnvironment=XDG_RUNTIME_DIR={runtime}\nEnvironment=DBUS_SESSION_BUS_ADDRESS=unix:path={runtime}/bus"
content = re.sub(r'(\[Service\])', r'\1' + insert, content, count=1)
open(unit, 'w').write(content)
print("Unit file updated.")
EOF
# Reload and restart safely
systemctl --user daemon-reload
nohup bash -c 'sleep 2 && systemctl --user restart openclaw-gateway' > /tmp/gw-restart.log 2>&1 &
sleep 3 && openclaw gateway status

Expected result: Service: systemd (enabled)

Issue 2: Safe gateway restart

Problem: openclaw gateway restart and systemctl --user restart openclaw-gateway send SIGTERM to the gateway, which also kills the shell that ran the command.

Always use this pattern:

nohup bash -c 'sleep 2 && systemctl --user restart openclaw-gateway' > /tmp/gw-restart.log 2>&1 &

sleep 2 + & detaches the restart from the current process tree before the gateway shuts down.

Issue 3: openclaw gateway status shows "disabled" in SSH session

This is a separate issue from Issue 1 — the gateway itself works fine, but your shell session lacks XDG_RUNTIME_DIR.

Affected: sudo su (without -), non-login shells, cron, sudo openclaw.

Fix: Add to ~/.bashrc and /etc/profile.d/openclaw-env.sh:

export XDG_RUNTIME_DIR=/run/user/$(id -u)
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u)/bus

Shell escalation cheatsheet:

Issue 4: Service not persisting after reboot

OpenClaw runs as a user-scope systemd service (~/.config/systemd/user/), not system-scope. Without linger, user services stop when the last session closes.

loginctl enable-linger $(whoami)   # persist after logout
systemctl --user enable openclaw-gateway  # auto-start on boot

See references/diagnosis.md for a full diagnostic checklist.