$cd ../troubleshooting/
Ubuntu Server Install Fails: systemctl --user & Homebrew
// Two separate issues commonly hit on Ubuntu 24.04 server fresh installs: (1) Homebrew not present on Linux → skill install fails, (2) systemctl --user unavailable when running as root.
install.log
🔍 Errors You'll See
Install failed: github — brew not installed — Homebrew is not installed.
Install failed: summarize — brew not installed — Homebrew is not installed.
Error: systemctl is-enabled unavailable: Command failed: systemctl --user is-enabled openclaw-gateway.service
fix_1.sh
✅ Fix 1 — Homebrew Skills Failing (github, summarize)
Then re-run openclaw setup
# Option A: Install Homebrew on Linux /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Manual fallback for github + summarize skills
# Option B: Install missing skill deps manually pip3 install gitpython pip3 install sumy
fix_2.sh
✅ Fix 2 — systemctl --user Unavailable (running as root)
Recommended: run as dedicated service user
# Create a non-root user for openclaw useradd -m -s /bin/bash openclaw su - openclaw # Then install openclaw as this user curl -fsSL https://get.openclaw.com | sh
fix_3.sh
✅ Fix 3 — Enable lingering for systemctl --user
Required if you must run as your own user on a headless server
# Enable user linger (allows systemd --user without login session) loginctl enable-linger $USER # Verify loginctl show-user $USER | grep Linger
ℹ Note on Running as Root
OpenClaw officially recommends running as a non-root user with a dedicated service account. Running as root bypasses the user systemd session, causing --user flag to fail.
📌 Community Report github.com/openclaw/openclaw/discussions/33612
❓ FAQ
Q1. Why does systemctl --user fail as root?
systemctl --user requires a per-user systemd session with a valid XDG_RUNTIME_DIR (typically /run/user/UID). When logged in as root directly, there's no user session — only the system session. The --user flag only works when there's an active login session for that user. The cleanest fix is to create a dedicated non-root user and run OpenClaw from that account.
Q2. Should I run OpenClaw as root?
No. Running as root is a significant security risk. If the AI agent is ever prompted to execute a command (even indirectly via a crafted message), running as root means those commands have full system access. Create a dedicated non-root service user: 'useradd -m -s /bin/bash openclaw && su - openclaw'. Then install and run OpenClaw from that account. The process can still bind to ports above 1024 without root.
Q3. Can I use Docker instead of systemctl?
Yes, and Docker is actually the recommended deployment method for Ubuntu servers. It completely avoids both the systemctl --user issue and the Homebrew dependency issue. Docker manages the process lifecycle, restarts on crash, and isolates the environment. Use 'docker compose up -d' with a restart policy of 'unless-stopped' to get behavior equivalent to a systemd service.
Q4. Why is Homebrew missing on Ubuntu Server?
Homebrew is primarily a macOS package manager. While it technically works on Linux (it installs to /home/linuxbrew/.linuxbrew), Ubuntu Server minimal installations don't include it, and many Ubuntu guides don't mention it. Some OpenClaw skills use Homebrew to install their dependencies. The alternative is to install skill dependencies manually via apt or pip3, or use Docker which bundles all dependencies.
Q5. What is loginctl enable-linger and when do I need it?
By default, a user's systemd session (and all --user services) are destroyed when that user logs out. On a headless server, this means your OpenClaw process dies when you close your SSH session. 'loginctl enable-linger <username>' tells systemd to keep that user's session alive even when they're not logged in — similar to setting a service account. Run it once and it persists across reboots.
Q6. After creating a new user, the OpenClaw binary isn't in PATH. How do I fix this?
When you install OpenClaw as one user and then switch to another (via su - openclaw), the new user's PATH doesn't include the original install location. If OpenClaw was installed globally (/usr/local/bin or /usr/bin), it should be accessible to all users. If installed in your original user's home directory (~/.local/bin), add that path to the openclaw user's profile: 'echo export PATH=$PATH:/home/youroriginaluser/.local/bin >> ~/.bashrc && source ~/.bashrc'. Or reinstall OpenClaw while logged in as the openclaw user.