Fix: Onboarding Wizard Does Not Install Systemd Service on Ubuntu

The OpenClaw onboarding wizard's isSystemdUserServiceAvailable function checks for an active D-Bus session to register the systemd user service. On Ubuntu 22.04 servers accessed via SSH or in headless environments, the required environment variables are not set — so the wizard silently fails and the gateway service is never installed. This guide walks through the manual fix.

Step 1: Enable Linger for Your User

By default, systemd user services only run while a user has an active login session. On servers, this means services stop when you disconnect via SSH. loginctl enable-linger tells systemd to keep the user slice alive even without an active session:

loginctl enable-linger $USER

# Verify linger is enabled
loginctl show-user $USER | grep Linger

Step 2: Start a Fresh Login Session

Disconnect from SSH and reconnect. A fresh login session will have the D-Bus socket and XDG_RUNTIME_DIR properly initialized by PAM/systemd-logind:

# After reconnecting, verify env vars are set
echo $DBUS_SESSION_BUS_ADDRESS
echo $XDG_RUNTIME_DIR

# Should output something like:
# unix:path=/run/user/1000/bus
# /run/user/1000

Step 3: Manually Install the Systemd User Service

With a properly initialized session, install and start the OpenClaw gateway as a systemd user service:

# Enable the service to start on boot
systemctl --user enable openclaw-gateway

# Start it now
systemctl --user start openclaw-gateway

# Check status
systemctl --user status openclaw-gateway

If openclaw-gateway.service is not found, the onboarding wizard may not have created the service file. Create it manually:

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/openclaw-gateway.service << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/openclaw gateway start
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now openclaw-gateway

Step 4: Verify the Service is Running

systemctl --user status openclaw-gateway

# Check gateway responds
curl -s http://localhost:18789/health

Step 5: Confirm Auto-Start on Reboot

# After rebooting the server, check (without logging in interactively):
ssh user@server "systemctl --user status openclaw-gateway"