PaioClaw

    Get Started →

    ← Back to Blog

    On this page

    How to Install OpenClaw on Linux (Ubuntu, Debian, Fedora, Arch)

    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)

    # 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.

    Join Our Community

    Connect with other PaioClaw users, share tips, and stay up to date.

    Discord
    𝕏 (Twitter)