Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix Gateway Service Installation Failure: Missing systemd Service File [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#54429•Fetched 2026-04-08 01:27:40
View on GitHub
Comments
0
Participants
1
Timeline
1
Reactions
0
Author
4362228343622283
Participants
4362228343622283
Timeline (top)
cross-referenced ×1

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

Root Cause Analysis

Fix Action

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 &

PR fix notes

PR #57524: daemon(systemd): fix sudo install unit path and ownership

Description (problem / solution / changelog)

Summary

Linux: reject sudo openclaw gateway install at the CLI entry point

Problem

openclaw gateway install installs a user systemd service — it writes to ~/.config/systemd/user/ and manages it via systemctl --user. Neither operation requires root. However, the code previously tried to accommodate sudo invocations by adding workarounds in three places:

  1. resolveSystemdInstallUnitPath() — ran getent passwd $SUDO_USER to find the real user's home directory instead of /root.
  2. writeSystemdUnit() — ran chown after writing the unit file to give ownership back to the original user.
  3. execSystemctlUser() — preferred --machine user@ to bypass the missing D-Bus session that exists when running as root.

The only step that genuinely needs root is loginctl enable-linger, and that is already handled separately in the wizard/onboard flow.

Fix

Instead of patching around sudo, reject it cleanly at the CLI entry point:

  • Added failIfSudoInstall() in src/cli/daemon-cli/shared.ts (symmetric with the existing failIfNixDaemonInstallMode guard). It exits early with a clear error message and hints — including the exact sudo loginctl enable-linger <user> command the user should run separately.
  • Called the guard in runDaemonInstall() in src/cli/daemon-cli/install.ts right after the Nix-mode check.
  • Deleted resolveSystemdInstallUnitPath() from src/daemon/systemd.ts entirely, and replaced the await resolveSystemdInstallUnitPath(env) call in writeSystemdUnit() with the plain synchronous resolveSystemdUnitPath(env).
  • Deleted the trailing chown block from writeSystemdUnit().
  • Note: execSystemctlUser()'s --machine user@ fallback is intentionally kept — it is still useful for stop/restart, SSH sessions without a D-Bus socket, and WSL2 environments.

Tests

  • Removed two tests that exercised the now-deleted getent/chown paths.
  • Added a replacement test that asserts getent and chown are never invoked during a normal install.
  • Added four unit tests for failIfSudoInstall covering: blocked on Linux with uid 0 + SUDO_USER, allowed when not root, allowed when SUDO_USER is unset (direct root login), and no-op on non-Linux platforms.

Changed files

  • src/cli/daemon-cli/install.ts (modified, +34/-1)
  • src/cli/daemon-cli/shared.test.ts (modified, +96/-1)
  • src/cli/daemon-cli/shared.ts (modified, +20/-0)
  • tsdown.config.ts (modified, +1/-0)

Code Example

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

---

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

---

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

---

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

---

nohup openclaw gateway > /tmp/openclaw-gateway.log 2>&1 &
RAW_BUFFERClick to expand / collapse

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

ComponentVersion/Status
openclawLatest
systemdVaries
OSLinux (Ubuntu/Debian-based)
Session TypeSSH/Console

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)

extent analysis

Fix Plan

To resolve the OpenClaw Gateway service installation failure due to a missing systemd service file, follow these steps:

  • Option 1: Improve Gateway Installation Fallback

    1. Modify the openclaw gateway install command to 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.

    Example code snippet:

    # Check if systemd user session is available
if [ -z "$XDG_RUNTIME_DIR" ]; then
  # Fall back to background process mode
  nohup openclaw gateway > /tmp/openclaw-gateway.log 2>&1 &
  echo "Gateway started in background process mode"
else
  # Proceed with systemd user service installation
  systemctl --user enable openclaw-gateway
  echo "Gateway installed as systemd user service"
fi

  • Option 2: Document Prerequisites

    1. Add documentation for running openclaw gateway install.
    2. Include prerequisites for running the command, such as setting XDG_RUNTIME_DIR and enabling linger.

    Example documentation snippet:

    ### Prerequisites
Before running `openclaw gateway install`, ensure you have:
* Set `XDG_RUNTIME_DIR` environment variable: `export XDG_RUNTIME_DIR="/run/user/$(id -u)"`
* Created the `XDG_RUNTIME_DIR` directory: `mkdir -p "$XDG_RUNTIME_DIR"`
* Enabled linger for your user: `loginctl enable-linger $USER`

  • Option 3: Provide Official Fix Script

    1. Create an official openclaw gateway fix command.
    2. Detect the installation mode and apply appropriate fixes.
    3. Offer fallback to background process mode if necessary.

    Example code snippet:

    # Detect installation mode
if [ -f "$HOME/.config/systemd/user/openclaw-gateway.service" ]; then
  # Apply fixes for systemd user service mode
  systemctl --user restart openclaw-gateway
else
  # Fall back to background process mode
  nohup openclaw gateway > /tmp/openclaw-gateway.log 2>&1 &
fi

Verification

To verify the fix, check the status of the OpenClaw Gateway service:

  • If using systemd user service mode: systemctl --user status openclaw-gateway
  • If using background process mode: ps aux | grep openclaw

Extra Tips

  • Ensure that the XDG_RUNTIME_DIR environment variable is set and the corresponding directory is created before running the openclaw gateway install command.
  • If using a non-desktop Linux environment,

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#installation#prompt formatting#chain error#conversation history#environment variable

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING