How to Install OpenClaw on Linux with Systemd and Auto-Start

OpenClaw logged over 416,000 npm downloads in a single 30-day window as of February 2026, making it one of the fastest-growing open-source AI projects ever released. Most of those installs land on Linux servers, VPSes, and cloud instances where the agent needs to run unattended around the clock.

The problem is that the default install ties the Gateway process to your login session. Run the onboard command over SSH, close the terminal, and the Gateway stops. On a desktop Linux machine with a persistent graphical session, you might never notice. On a headless server, it breaks the first time you disconnect.

The fix requires three things the quick-start docs don't emphasize: a systemd user service to manage the Gateway lifecycle, loginctl lingering so the service starts at boot without an active login session, and memory management tuning so the kernel protects the Gateway under pressure. This guide covers all three, plus SSH tunneling for remote dashboard access.

The five steps from start to finish:

1. Install Node 24 and OpenClaw
2. Run the onboard wizard with the daemon flag
3. Create a systemd user service
4. Enable loginctl lingering
5. Verify the Gateway survives a logout

OpenClaw runs on any Linux distribution with a modern kernel, but Ubuntu 22.04 LTS or 24.04 LTS gives the smoothest experience for server deployments. Debian 12+ and Fedora 40+ work equally well with minor package manager differences.

Hardware minimums:

• 1 vCPU and 1 GB RAM for a single-channel Gateway
• 2 vCPU and 2 GB RAM for stable multi-channel use
• 4 GB+ RAM recommended if you plan to run local models or heavy tool use

Software prerequisites:

• Node.js 24 (recommended) or Node.js 22.19+ (minimum supported)
• curl and git (the installer handles git if missing)
• A non-root user account with sudo access

Node 24 is the default runtime for OpenClaw installs, CI, and release workflows. Node 22 LTS still works, but upgrading to 24 avoids edge cases in newer OpenClaw releases. The official docs explicitly warn against using Bun for the Gateway due to unresolved WhatsApp and Telegram integration bugs.

If your server already has an older Node version, use a version manager like fnm or nvm to install Node 24 alongside it without conflicts:

curl -fsSL https://fnm.vercel.app/install | bash
fnm install 24
fnm use 24
node --version

On Ubuntu or Debian, the NodeSource repository is another option:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

OpenClaw offers two installation paths on Linux: the official installer script and a manual npm global install. Both end at the same place, but the installer handles Node detection and PATH setup automatically.

Option 1: Official installer (recommended)

curl -fsSL https://openclaw.ai/install.sh | bash

The script detects your OS, installs Node 24 if needed, pulls the latest OpenClaw release, and runs the onboarding wizard. When the wizard finishes, the Gateway is running and you can access a local dashboard URL shown in the terminal output.

Option 2: npm global install

If you manage your own Node environment, install directly:

npm install -g openclaw@latest
openclaw onboard --install-daemon

The daemon flag tells the onboarding process to configure a managed startup entry. On Linux, that means a systemd user service. The official install docs cover all available onboarding flags.

Verify the install:

openclaw --version
openclaw doctor
openclaw gateway status

The doctor command checks your Node version, verifies PATH configuration, and flags common issues like permission errors on the global npm prefix. If openclaw: command not found appears after installation, add npm's global bin directory to your shell startup file:

export PATH="$(npm prefix -g)/bin:$PATH"

Add that line to ~/.bashrc or ~/.zshrc so it persists across sessions.

The onboard command's daemon flag creates a systemd user service automatically, but understanding the unit file lets you customize it for production. The service file lives at ~/.config/systemd/user/openclaw-gateway.service. If you used a named profile during onboarding, the filename includes the profile name: openclaw-gateway-<profile>.service.

Here is the standard unit file structure:

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=%h/.local/bin/openclaw gateway
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

A few things worth noting about this configuration. The Restart=always directive means systemd restarts the Gateway if it crashes, exits cleanly, or gets killed by OOM. The RestartSec=5 adds a 5-second delay between restarts to prevent tight crash loops. The KillMode=control-group ensures all child processes (MCP servers, browser instances, shell sessions) get stopped when the service stops, not just the main Gateway process.

If the automated install already created the file, you can customize it in place:

mkdir -p ~/.config/systemd/user
systemctl --user edit openclaw-gateway.service

After any manual edits, reload and restart:

systemctl --user daemon-reload
systemctl --user enable --now openclaw-gateway.service
systemctl --user status openclaw-gateway.service

The enable --now flag both enables the service for future boots and starts it immediately. Check the status output for active (running) and confirm the Gateway responds by running openclaw gateway status.

For shared servers where multiple users each need their own Gateway, each user creates their own user service. For a single system-wide daemon, use a system service under /etc/systemd/system/ instead. The official docs recommend user services as the default and system services for always-on shared servers.

Give your OpenClaw agents persistent file storage

generous storage workspace with built-in RAG search, MCP server access, and ownership transfer. No credit card, no trial expiration.

Start 14-Day Trial

A systemd user service only runs while the user has an active login session. On a desktop machine with auto-login, that's effectively always. On a headless server accessed over SSH, the service manager shuts down when you disconnect, taking the Gateway with it.

The fix is loginctl enable-linger, which tells systemd to start the user's service manager at boot and keep it running regardless of login state:

sudo loginctl enable-linger $USER

Verify it took effect:

loginctl show-user $USER | grep Linger

You should see Linger=yes. From this point forward, your OpenClaw Gateway starts at boot and survives SSH disconnects.

Testing the full cycle:

1. Enable lingering as shown above
2. Start the service: systemctl --user enable --now openclaw-gateway.service
3. Disconnect from SSH
4. Reconnect and check: systemctl --user status openclaw-gateway.service

The service should still show active (running) with an uptime that spans your disconnection.

Accessing the dashboard remotely:

The Gateway binds to 127.0.0.1 by default, which is the right security posture. Never expose the Gateway port directly to the internet. Instead, use an SSH tunnel from your local machine to forward the Gateway's listening port:

ssh -N -L <local-port>:127.0.0.1:<gateway-port> youruser@your-server-ip

Replace <gateway-port> with the port shown in your service configuration or openclaw gateway status output, and <local-port> with the same number to keep things simple. Then open the forwarded URL in your local browser. The -N flag tells SSH not to open a shell, keeping the tunnel clean. You can add -f to background the tunnel process.

The first time you access the dashboard, OpenClaw presents a tokenized URL that drops you directly into the authenticated session. Copy the full URL from your server's terminal output rather than manually entering the authentication token.

Once your Gateway is running persistently, your agents need somewhere to store and share their output. Fastio provides 50 GB of free workspace storage with built-in Intelligence Mode for semantic search across agent-produced files. Agents connect via the Fastio MCP server and can hand off entire workspaces to human collaborators when a project wraps up.

The Linux kernel's OOM killer terminates processes when physical memory runs out. OpenClaw handles this proactively: the Gateway sets oom_score_adj to 1000 on all child processes by default. That value tells the kernel to kill child processes (MCP stdio servers, browser instances, PTY shells) before touching the Gateway itself.

This is a good default. Losing a child process is recoverable. Losing the Gateway means restarting everything and re-establishing all connected sessions.

The adjustment works through a /bin/sh wrapper that writes to /proc/<pid>/oom_score_adj. No elevated privileges are required because processes can increase their own children's OOM score. You can verify the setting on any running child:

cat /proc/$(pgrep -f "openclaw")/oom_score_adj

Disabling OOM score adjustment:

If you manage OOM behavior through cgroups, container limits, or a custom policy, disable OpenClaw's adjustment with an environment variable:

OPENCLAW_CHILD_OOM_SCORE_ADJ=0

The variable also accepts false, no, or off. Add it to your systemd service file under [Service]:

[Service]
Environment=OPENCLAW_CHILD_OOM_SCORE_ADJ=0

Setting memory limits in systemd:

For tighter control, add a hard memory ceiling to the service:

[Service]
MemoryMax=2G
MemoryHigh=1800M

MemoryMax is a hard limit that triggers an OOM kill when exceeded. MemoryHigh is a soft limit that causes the kernel to throttle memory allocation, giving the process a chance to free resources before hitting the wall. For a Gateway with moderate tool use, 2 GB is a reasonable ceiling. Scale up if you run local models or heavy browser automation.

Diagnosing memory issues:

If the Gateway or its children keep getting killed, check the system journal:

journalctl --user -u openclaw-gateway.service --since "1 hour ago"

Look for oom-kill entries or Killed process messages. If child processes are the victims, the Gateway recovers automatically. If the Gateway itself dies, consider increasing MemoryMax or adding physical RAM.

For persistent storage that doesn't depend on local disk, agents running on constrained VPSes can offload files to Fastio workspaces. The free tier includes generous storage and monthly credits during the trial with no credit card required, enough for most single-agent deployments. Files are automatically indexed for RAG search when Intelligence Mode is enabled, so your agent can query its own output history without maintaining a local vector database.