Gateway Fails on Headless Linux — No User systemd

You SSH into your server, run openclaw gateway install or openclaw gateway status, and get: "systemctl --user unavailable: Failed to connect to bus: No medium found." The gateway binary itself works fine — it's only the service management commands that break.

What the Error Looks Like

The key pattern: any openclaw gateway subcommand that tries to interact with systemd fails. But running the gateway binary directly (openclaw gateway start in the foreground) works fine. This confirms the issue is with systemd user sessions, not OpenClaw itself.

Why This Happens

Diagnose Your Setup

Run these checks to understand what's missing:

# 1. Is XDG_RUNTIME_DIR set?
echo "XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR"

# 2. Does the runtime directory exist?
ls -la /run/user/$(id -u)/ 2>&1

# 3. Is linger enabled for your user?
loginctl show-user $(whoami) 2>/dev/null | grep Linger

Fix A: Enable User Linger (Recommended)

This enables user-level systemd for your account, even when no interactive session is active.

sudo loginctl enable-linger $(whoami)

echo 'export XDG_RUNTIME_DIR=/run/user/$(id -u)' >> ~/.bashrc
source ~/.bashrc

openclaw gateway install --force
openclaw gateway status

Fix B: System-Level Service

If you prefer not to mess with user-level systemd, run OpenClaw as a system service instead. This is common in production deployments where the gateway should start at boot regardless of user logins.

sudo tee /etc/systemd/system/openclaw-gateway.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ubuntu
Group=ubuntu
WorkingDirectory=/home/ubuntu
ExecStart=/usr/local/bin/openclaw gateway start
Restart=on-failure
RestartSec=5
Environment=HOME=/home/ubuntu
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway
sudo systemctl status openclaw-gateway

Fix C: Manual Process Management

If you don't want to use systemd at all, run the gateway in a detached screen/tmux session or use a process manager like PM2.

tmux new-session -d -s openclaw 'openclaw gateway start'
# Reattach later: tmux attach -t openclaw

npm install -g pm2
pm2 start "openclaw gateway start" --name openclaw-gateway
pm2 save
pm2 startup  # generates the boot script

Verify It Works

Still Stuck?

If linger is enabled and XDG_RUNTIME_DIR is set but it still fails, check if systemd-logind is actually running:

# Is logind running?
systemctl status systemd-logind

# Is the user session registered?
loginctl list-sessions

# Check the bus socket directly
ls -la /run/user/$(id -u)/bus

On some minimal cloud images (Alpine, Busybox-based), systemd is not installed at all. In that case, skip to Fix B (system-level service) or Fix C (manual management).