Describe the bug

On Linux systems, openclaw gateway install fails with the error:

Gateway service install failed: systemctl enable failed: Failed to enable unit: Unit file openclaw-gateway.service does not exist.

The root cause is that the systemd user session is not available when XDG_RUNTIME_DIR is not set, which is common in:

• SSH sessions without proper PAM configuration
• Container environments
• Minimal Linux installations

Steps to Reproduce

1. On a fresh Linux installation or SSH session
2. Ensure XDG_RUNTIME_DIR is not set: unset XDG_RUNTIME_DIR
3. Run: openclaw gateway install
4. Observe the failure

Expected Behavior

The installer should either:

1. Automatically set up the required environment (XDG_RUNTIME_DIR, enable linger)
2. Provide clear error messages with remediation steps

Actual Behavior

The installer fails with a cryptic error about the unit file not existing, when the real issue is the systemd user session being unavailable.

Root Cause Analysis

After debugging, I found:

1. Missing XDG_RUNTIME_DIR: Without this, systemd cannot connect to the user session bus
2. Linger not enabled: User services may not persist after logout
3. No automatic remediation: The installer does not attempt to fix these common issues

Solution

Immediate Fix (for users)

export XDG_RUNTIME_DIR=/run/user/$(id -u)
mkdir -p "$XDG_RUNTIME_DIR"
loginctl enable-linger $(whoami)
openclaw gateway install --force

Recommended Code Changes

1. Add pre-installation checks - Check XDG_RUNTIME_DIR and enable linger automatically
2. Improve error messages - Provide clear remediation steps

Environment

• OS: Linux (Ubuntu 22.04)
• OpenClaw Version: 2026.3.23
• Node.js: v24.14.1
• systemd: systemd 249+

Additional Context

I have created a comprehensive diagnostic script that handles these cases and can auto-fix the issues. Happy to help test any fixes.