Issue: openclaw gateway status fails on EC2/headless servers due to missing user-level systemd

Summary

On headless EC2 instances (and similar server environments), openclaw gateway status and openclaw gateway install fail with "Failed to connect to bus: No medium found" because user-level systemd (systemctl --user) is unavailable by default.

Environment

• OS: Amazon Linux 2023 (6.1.159-182.297.amzn2023.x86_64)
• OpenClaw: 2026.2.6-3
• Node.js: v22.22.0
• Architecture: x86_64 EC2 instance

Problem

Error Message

Gateway service check failed: Error: systemctl --user unavailable: Failed to connect to bus: No medium found

Runtime: unknown (Error: systemctl --user unavailable: Failed to connect to bus: No medium found)

systemd user services unavailable.
systemd user services are unavailable; install/enable systemd or run the gateway under your supervisor.

Root Cause

On EC2 and headless servers:

1. User-level systemd requires a D-Bus session bus
2. D-Bus session bus requires XDG_RUNTIME_DIR to be set
3. SSH sessions don't automatically set XDG_RUNTIME_DIR
4. loginctl enable-linger needs to be enabled for the user

Current Workaround

# 1. Enable linger for user persistence
sudo loginctl enable-linger $(whoami)

# 2. Set XDG_RUNTIME_DIR (add to ~/.bashrc)
export XDG_RUNTIME_DIR=/run/user/$(id -u)

# 3. Now openclaw gateway install works
openclaw gateway install --force

Suggested Improvements

Option A: Better Error Message + Documentation

• Detect the missing XDG_RUNTIME_DIR scenario
• Provide actionable fix instructions in the error message:

  systemctl --user unavailable: D-Bus session bus not found.
  
  On headless servers (EC2, etc.), run:
    sudo loginctl enable-linger $(whoami)
    export XDG_RUNTIME_DIR=/run/user/$(id -u)
  
  Then retry: openclaw gateway install
  

Option B: Support System-Level systemd Service

• Add --system flag to openclaw gateway install
• Install to /etc/systemd/system/openclaw.service instead of user-level
• Useful for servers where system-level services are preferred

Option C: Auto-detect and Set XDG_RUNTIME_DIR

• If XDG_RUNTIME_DIR is unset but /run/user/<uid> exists, set it automatically
• Would fix the issue transparently for most cases

Logs

{"0":"Gateway service check failed: Error: systemctl --user unavailable: Failed to connect to bus: No medium found","_meta":{"logLevelName":"ERROR"},"time":"2026-02-08T10:20:22.063Z"}
{"0":"systemd user services unavailable.","_meta":{"logLevelName":"ERROR"},"time":"2026-02-08T10:21:23.811Z"}

Related

This likely affects all headless Linux deployments:

• AWS EC2
• GCP Compute Engine
• Azure VMs
• Docker containers (already mentioned in current error message)
• Any server accessed via SSH without a desktop session