Gateway Service Installation Failure: Missing systemd Service File

Issue Type

• Bug Report
• Feature Request
• Documentation Issue

Description

The OpenClaw Gateway service fails to install with a systemd error indicating the service unit file does not exist. This affects users attempting to run the gateway as a systemd user service.

Error Message

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

Root Cause Analysis

Problem Summary

The openclaw gateway install command attempts to create and enable a systemd user service, but fails because:

1. The systemd service unit file is not being created properly during installation
2. The systemctl --user command requires a properly configured user session with:
   • XDG_RUNTIME_DIR environment variable set
   • systemd user session available (DBUS session bus)
   • systemd linger enabled for the user (for headless/server environments)

Environment-Specific Issues

This problem commonly occurs in:

• SSH sessions without proper systemd user session setup
• Containers or minimal Linux installations
• Systems where loginctl enable-linger has not been configured
• Environments where XDG_RUNTIME_DIR is not set

Steps to Reproduce

1. Install openclaw: npm install -g openclaw
2. Run gateway installation: openclaw gateway install
3. Observe the systemd service file error

Expected Behavior

The gateway service should either:

1. Successfully install and start as a systemd user service, OR
2. Gracefully fall back to an alternative runtime mode (e.g., background process)

Actual Behavior

Installation fails with systemd error, leaving the gateway in an unusable state.

Environment

Comparison of Fix Scripts

Two fix scripts have been developed to address this issue:

Script 1: /root/temp/fix-gateway.sh (Comprehensive Diagnostic Tool)

Purpose: Full diagnostic and interactive repair tool

Features:

• Comprehensive system checks (systemctl, systemd, XDG_RUNTIME_DIR, linger)
• Diagnoses systemd user session availability
• Checks gateway service file, process, and port status
• Provides interactive repair options:
  1. Fix via systemd service
  2. Reinstall via openclaw CLI
  3. Manual start without systemd
• Generates detailed diagnosis report

Best For: Troubleshooting complex systemd-related issues

Limitations:

• Requires user interaction for repair selection
• More complex, may be overkill for simple cases

Script 2: /root/fix-openclaw-gateway.sh (Simple Fallback Solution)

Purpose: Quick fix by running gateway as background process

Features:

• Checks if openclaw is installed
• Starts gateway as a background process (no systemd)
• Verifies gateway is listening on port 18789
• Provides log file location and management commands
• Non-interactive, runs automatically

Best For: Quick deployment in environments where systemd is not available or desired

Limitations:

• Does not fix the underlying systemd issue
• Gateway runs as background process (not a proper service)
• May not survive system reboot without additional configuration

Proposed Solutions

Solution 1: Improve Gateway Installation Fallback (Recommended)

Modify the openclaw gateway install command to:

1. Detect if systemd user session is available
2. If systemd is unavailable, automatically fall back to background process mode
3. Provide clear feedback about which mode was used

Pros:

• Seamless user experience
• Works in all environments
• No manual intervention required

Cons:

• Requires changes to openclaw core

Solution 2: Document Prerequisites

Add documentation for running openclaw gateway install:

# Prerequisites for systemd user service
export XDG_RUNTIME_DIR="/run/user/$(id -u)"
mkdir -p "$XDG_RUNTIME_DIR"
loginctl enable-linger $USER

Pros:

• No code changes required
• Users can prepare their environment

Cons:

• Poor user experience
• Easy to miss during installation

Solution 3: Provide Official Fix Script

Include an official openclaw gateway fix command that:

• Detects the installation mode
• Applies appropriate fixes
• Offers fallback to background process

Pros:

• Official support channel
• Can be updated independently

Cons:

• Requires development effort

Temporary Workaround

Use either of the provided fix scripts:

Option A: Comprehensive diagnostic (interactive)

chmod +x fix-gateway.sh
./fix-gateway.sh

Option B: Quick background start (non-interactive)

chmod +x fix-openclaw-gateway.sh
./fix-openclaw-gateway.sh

Option C: Manual background start

nohup openclaw gateway > /tmp/openclaw-gateway.log 2>&1 &

Files Affected

• $HOME/.config/systemd/user/openclaw-gateway.service (may not exist)
• /tmp/openclaw-gateway.log (when running in background mode)

Additional Context

This issue highlights a broader challenge with systemd user services in non-desktop Linux environments. Many server/container environments do not have full systemd user session support, making systemd user services unreliable as a default deployment method.

Checklist

• I have searched for existing issues
• I have included the environment information
• I have provided steps to reproduce
• I have proposed potential solutions
• I have compared available fix scripts

Report Date: 2026-03-25
Reporter: Automated Diagnosis Tool
Related Files:

• /root/temp/fix-gateway.sh (Comprehensive diagnostic script)
• /root/fix-openclaw-gateway.sh (Simple fallback script)