Linux is OpenClaw’s natural habitat. No PATH mysteries. No long-filename bugs. No “works on Linux but not Windows” frustrations. Just solid, predictable Unix tools doing what they do.
But Linux isn’t monolithic. Ubuntu uses apt. Fedora uses dnf. Arch uses pacman. This guide covers Ubuntu/Debian, Fedora/RHEL/CentOS, and Arch/Manjaro. By the end, you’ll have OpenClaw running, starting on boot, with proper permissions.
What You Need Before Starting
- ●Root or sudo access (for installing packages)
- ●Basic terminal comfort (copy-paste is fine)
- ●Internet connection
- ●10-20 minutes of actual time
Assumptions: a fresh-ish system, you’re okay with systemd, and you want OpenClaw running 24/7 surviving reboots.
Ubuntu / Debian Installation
Ubuntu and its derivatives (Linux Mint, Pop!_OS, elementary OS) and Debian use the apt package manager.
Step 1: Update System Packages
sudo apt update && sudo apt upgrade -y
Step 2: Install Prerequisites
sudo apt install -y curl git build-essential
curl downloads files, git clones OpenClaw, build-essential brings the compiler tools needed for native npm modules.
Step 3: Install Node.js (The Right Way)
Option A: System Node (via NodeSource — Recommended)
# Add NodeSource repository (Node.js 20.x LTS) curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - # Install Node.js sudo apt install -y nodejs # Verify node --version npm --version
Pros: managed by apt, system-wide, no shell config. Cons: harder to switch versions, all users share the same one.
Option B: NVM (Node Version Manager)
# Install NVM curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" nvm install 20 nvm use 20 nvm alias default 20
For OpenClaw as a service, System Node is simpler. For development, NVM is better.
Step 4-6: Clone, Configure, Test
mkdir -p ~/openclaw cd ~/openclaw git clone https://github.com/openclaw/openclaw.git . npm install cp .env.example .env nano .env
Minimal configuration:
# AI Model (pick one) OPENAI_API_KEY=sk-proj-your-key-here ANTHROPIC_API_KEY=sk-ant-your-key-here AGENT_NAME=LinuxAgent PORT=3000
Run npm start. You should see the web interface running at http://localhost:3000. Test a prompt — if it responds, it works. Press Ctrl+C to stop.
Step 7: Create Systemd Service (Survive Reboots)
sudo nano /etc/systemd/system/openclaw.service
[Unit] Description=OpenClaw AI Agent After=network-online.target Wants=network-online.target [Service] Type=simple User=yourusername WorkingDirectory=/home/yourusername/openclaw Environment="PATH=/usr/bin:/usr/local/bin" ExecStart=/usr/bin/npm start Restart=on-failure RestartSec=10 StandardOutput=journal StandardError=journal [Install] WantedBy=multi-user.target
Replace yourusername with your actual username. If using NVM, set PATH to your NVM node bin directory and use the absolute path to npm.
sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw sudo systemctl status openclaw
Tail logs with sudo journalctl -u openclaw -f.
Fedora / RHEL / CentOS Installation
Fedora and RHEL-based distros (Rocky, AlmaLinux, CentOS Stream) use dnf (or yum on older systems).
sudo dnf update -y sudo dnf install -y curl git gcc-c++ make # System Node via NodeSource curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash - sudo dnf install -y nodejs
Steps 4-7 (clone, configure, test, systemd) are identical to Ubuntu. The only real difference is SELinux.
If OpenClaw won’t start, check SELinux
sestatus sudo setenforce 0 # temporarily disable sudo systemctl restart openclaw sudo setenforce 1 # re-enable sudo setsebool -P httpd_can_network_connect 1
Arch / Manjaro Installation
Arch and derivatives (Manjaro, EndeavourOS) use pacman.
sudo pacman -Syu --noconfirm sudo pacman -S --noconfirm curl git base-devel # System Node from official repos sudo pacman -S --noconfirm nodejs npm
Arch repos ship the latest Node.js (current, not LTS). For LTS, use NVM. Steps 4-7 are identical to Ubuntu.
NVM vs System Node: The Eternal Debate
System Node
- ●Pros: package-manager-managed, system-wide, systemd ‘just works’, production-ready
- ●Cons: only one version at a time, requires sudo to update
NVM
- ●Pros: multiple versions, no sudo, isolated from system
- ●Cons: user-specific, systemd needs custom paths, slightly more setup
Production server: System Node. Dev machine: NVM. If unsure: System Node.
Permissions You’ll Regret Skipping
Linux permissions are powerful but unforgiving. Skip these and you’ll debug mysterious errors for hours.
File Ownership
OpenClaw should run as a regular user, not root. If you cloned as root:
sudo chown -R yourusername:yourusername ~/openclaw ls -la ~/openclaw
npm Global Packages Without sudo
mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm install -g pm2
Port Binding (Ports < 1024)
Ports below 1024 require root. OpenClaw defaults to port 3000 (safe). If you want port 80, use a reverse proxy (recommended) or grant the binding capability:
sudo setcap 'cap_net_bind_service=+ep' $(which node)
Firewall Configuration
Ubuntu (ufw)
sudo ufw allow 3000/tcp sudo ufw allow 'Nginx Full' sudo ufw enable sudo ufw status
Fedora/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=3000/tcp sudo firewall-cmd --reload
Arch (iptables/firewalld)
Arch doesn’t enable a firewall by default. If you’ve enabled one, use the same firewalld commands as Fedora, or iptables rules with iptables -A INPUT -p tcp --dport 3000 -j ACCEPT.
Systemd Unit File Deep Dive
- ●After=network-online.target — wait for network before starting
- ●Type=simple — Node runs in foreground, no fork
- ●User= — run as this user, not root
- ●Environment=”PATH=…” — critical for finding npm/node
- ●Restart=on-failure + RestartSec=10 — auto-restart 10s after crash
- ●StandardOutput=journal — view with journalctl
- ●WantedBy=multi-user.target — start at normal boot
Advanced Options
[Service] MemoryMax=1G MemoryHigh=800M CPUQuota=50% StartLimitBurst=5 StartLimitIntervalSec=60
Monitoring and Logs
sudo systemctl status openclaw sudo systemctl is-active openclaw sudo systemctl is-enabled openclaw sudo journalctl -u openclaw -n 50 sudo journalctl -u openclaw -f sudo journalctl -u openclaw -b sudo journalctl -u openclaw --since "1 hour ago" ps aux | grep node htop
Updating OpenClaw
cd ~/openclaw sudo systemctl stop openclaw git pull origin main npm install sudo systemctl start openclaw sudo systemctl status openclaw
If you also need to update Node.js via NVM, install the new version, switch with nvm use, set the new default, then update the systemd unit’s PATH to the new node bin directory and run daemon-reload + restart.
Troubleshooting Common Linux Issues
“npm: command not found” after installing Node
PATH not updated in current shell. Logout and login, or source ~/.bashrc.
“EACCES: permission denied”
Trying to write to directories you don’t own. Fix npm global directory or run sudo chown -R $USER:$USER ~/openclaw.
“Cannot find module” after npm install
cd ~/openclaw rm -rf node_modules package-lock.json npm install
Systemd service fails to start
- ●Run sudo systemctl status openclaw to see the error
- ●View full logs with sudo journalctl -u openclaw -n 100
- ●Test manually: cd ~/openclaw && npm start — if that works, it’s a systemd config issue
- ●Ensure all paths are absolute, User= matches file ownership, WorkingDirectory= exists
OpenClaw runs but uses 100% CPU
Likely an infinite loop or runaway skill. Check logs, limit CPU via systemd CPUQuota, or disable the problematic skill.
Distro-Specific Quirks
Ubuntu/Debian
- ●Don’t install Node via snap — use NodeSource
- ●AppArmor can restrict file access (rarely an issue for user-installed apps)
Fedora/RHEL
- ●SELinux will block network access unless configured
- ●Firewalld is more complex than ufw but more powerful
Arch
- ●Rolling release — Node.js updates frequently, test after system updates
- ●AUR packages are community-maintained — use with caution
- ●Minimal base — expect to install more dependencies than Ubuntu
The PaioClaw Alternative (Yes, Even on Linux)
Initial install: 25-60 minutes including permission debugging. Ongoing maintenance: ~25 min/month for updates and Node bumps. PaioClaw on Linux ships a pre-built binary, an included systemd service, auto-updates, and professional support — starts free, $4/month for paid plans.
DIY when: you’re already comfortable with Linux, want full control, are developing OpenClaw skills, or have specific distro requirements. Use PaioClaw when: you just want OpenClaw working without maintaining systemd, your time is worth more than $4/month, or you need guaranteed uptime.
The Bottom Line
OpenClaw on Linux is the smoothest install path of any platform — predictable tools, clean package managers, and systemd handling lifecycle for you. Pick the right Node strategy for your use case, set ownership and firewall rules correctly, and the rest is mostly copy-paste. When something breaks, journalctl tells you exactly why.