From 762fed1f90290a4bd4fb6fc5ca9ae27c87009cab Mon Sep 17 00:00:00 2001 From: chocobo9 Date: Tue, 24 Mar 2026 16:07:47 -0700 Subject: [PATCH] fix(daemon): add headless server hints to systemd unavailable error Add loginctl enable-linger and XDG_RUNTIME_DIR recovery hints to the generic (non-WSL) systemd unavailable error path, helping users on SSH/headless servers diagnose and fix the issue without a desktop session. Fixes #11805 Co-Authored-By: Claude Sonnet 4.6 --- src/daemon/systemd-hints.test.ts | 2 ++ src/daemon/systemd-hints.ts | 2 ++ 2 files changed, 4 insertions(+) diff --git a/src/daemon/systemd-hints.test.ts b/src/daemon/systemd-hints.test.ts index 9d7621bd798..529bd1409c5 100644 --- a/src/daemon/systemd-hints.test.ts +++ b/src/daemon/systemd-hints.test.ts @@ -28,6 +28,8 @@ describe("renderSystemdUnavailableHints", () => { it("renders generic Linux recovery hints outside WSL", () => { expect(renderSystemdUnavailableHints()).toEqual([ "systemd user services are unavailable; install/enable systemd or run the gateway under your supervisor.", + "On a headless server (SSH/no desktop session): run `loginctl enable-linger` to persist your systemd user session across logins.", + "Also ensure XDG_RUNTIME_DIR is set: `export XDG_RUNTIME_DIR=/run/user/$(id -u)`, then retry.", `If you're in a container, run the gateway in the foreground instead of \`${formatCliCommand("openclaw gateway")}\`.`, ]); }); diff --git a/src/daemon/systemd-hints.ts b/src/daemon/systemd-hints.ts index 49cd2a9016d..5709207503a 100644 --- a/src/daemon/systemd-hints.ts +++ b/src/daemon/systemd-hints.ts @@ -24,6 +24,8 @@ export function renderSystemdUnavailableHints(options: { wsl?: boolean } = {}): } return [ "systemd user services are unavailable; install/enable systemd or run the gateway under your supervisor.", + "On a headless server (SSH/no desktop session): run `loginctl enable-linger` to persist your systemd user session across logins.", + "Also ensure XDG_RUNTIME_DIR is set: `export XDG_RUNTIME_DIR=/run/user/$(id -u)`, then retry.", `If you're in a container, run the gateway in the foreground instead of \`${formatCliCommand("openclaw gateway")}\`.`, ]; }