OpenClaw Linux Setup Guide: Install on Ubuntu, Debian, Fedora & Raspberry Pi

Introduction

Linux is an excellent platform for running OpenClaw, especially for always-on servers and Raspberry Pi deployments. This guide covers installation on popular Linux distributions including Ubuntu, Debian, Fedora, and Raspberry Pi OS, plus ARM64 support and systemd service configuration.

For general installation instructions, see our complete installation guide.

System Requirements

Supported Distributions

Ubuntu 20.04+ (LTS recommended)
Debian 11+ (Bullseye or later)
Fedora 34+
Raspberry Pi OS (Debian-based)
Arch Linux (via AUR or manual install)
Other Debian/Ubuntu-based distributions

Hardware Requirements

RAM — 2GB+ recommended (1GB minimum for Raspberry Pi)
Storage — 500MB+ for installation, additional space for memory/data
CPU — x86_64 or ARM64 architecture
Network — Internet connection for API calls and updates

Software Prerequisites

Node.js 18+ — Can be auto-installed by the one-liner installer
curl — Usually pre-installed
git — Optional, for hackable install from source
systemd — For service management (most modern distributions)

Installation Methods

Method 1: One-Liner Install (Recommended)

The easiest way to install OpenClaw on Linux:

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

This script automatically:

Detects your Linux distribution
Installs Node.js if missing (via NodeSource or distribution package manager)
Installs OpenClaw globally via npm
Sets up necessary permissions
Verifies the installation

Note: You may be prompted for your password (sudo) to install Node.js or system packages.

Method 2: npm Install

If you already have Node.js installed:

npm i -g openclaw

Verify Node.js version first:

node --version

Should be v18.0.0 or higher.

Method 3: Distribution-Specific Packages

Ubuntu/Debian (via apt)

Some distributions may have OpenClaw packages available:

# Add repository (if available)
curl -fsSL https://openclaw.ai/repo/deb/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/openclaw.gpg
echo "deb [signed-by=/usr/share/keyrings/openclaw.gpg] https://openclaw.ai/repo/deb stable main" | sudo tee /etc/apt/sources.list.d/openclaw.list

# Install
sudo apt update
sudo apt install openclaw

Note: Official packages may not be available yet. Check docs.openclaw.ai for the latest installation methods.

Fedora (via dnf)

# Add repository (if available)
sudo dnf install openclaw

Arch Linux (via AUR)

yay -S openclaw
# or
paru -S openclaw

Method 4: Hackable Install (From Source)

For developers who want to modify the source:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run build

Then run:

npm run openclaw onboard

Or link globally:

sudo npm link --global

Installing Node.js

Ubuntu/Debian

Option 1: NodeSource Repository (Recommended)

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

Option 2: Distribution Packages

sudo apt update
sudo apt install nodejs npm

Note: Distribution packages may be outdated. NodeSource provides newer versions.

Option 3: nvm (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

Fedora

sudo dnf install nodejs npm

Or use NodeSource:

curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo dnf install -y nodejs

Raspberry Pi (ARM64/ARMv7)

Raspberry Pi OS (Debian-based)

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

For ARMv7 (32-bit), NodeSource may not have packages. Use distribution packages or build from source.

Alternative: Install via nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18

Post-Installation Setup

After installation, configure OpenClaw:

openclaw onboard

This interactive setup covers:

1. AI Model Configuration

Choose your AI provider:

Anthropic Claude:

Claude 3.5 Sonnet (recommended)
Claude 3 Opus
Claude 4

Get your API key from console.anthropic.com.

OpenAI GPT:

GPT-4o
GPT-4 Turbo
GPT-4.1

Get your API key from platform.openai.com.

Local Models:

Ollama (runs locally, no API key needed)
LM Studio
MiniMax

2. Linux Permissions

OpenClaw may need permissions:

File System — Read/write access to ~/.openclaw
Network — For API calls and chat bridges
System Commands — If using system control features

3. Firewall Configuration

Allow OpenClaw through firewall:

UFW (Ubuntu/Debian):

sudo ufw allow 3000/tcp

firewalld (Fedora/RHEL):

sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --reload

Running OpenClaw

Start the Server

openclaw

This starts the local server and connects all configured integrations.

Run in Background

Use nohup:

nohup openclaw > ~/.openclaw/logs/output.log 2>&1 &

Or use screen:

screen -S openclaw
openclaw
# Press Ctrl+A then D to detach

Or use tmux:

tmux new -s openclaw
openclaw
# Press Ctrl+B then D to detach

Run as systemd Service (Always-On)

Create a systemd service for automatic startup:

Create service file:

sudo nano /etc/systemd/system/openclaw.service

Add configuration:

[Unit]
Description=OpenClaw Personal AI Assistant
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/home/your-username
ExecStart=/usr/bin/openclaw
Restart=always
RestartSec=10
Environment="NODE_ENV=production"

[Install]
WantedBy=multi-user.target

Replace your-username with your actual username.

Reload systemd:
```
sudo systemctl daemon-reload
```
Enable service:
```
sudo systemctl enable openclaw
```
Start service:
```
sudo systemctl start openclaw
```
Check status:
```
sudo systemctl status openclaw
```
View logs:
```
sudo journalctl -u openclaw -f
```

Using pm2 (Process Manager)

Install pm2:

npm i -g pm2

Start OpenClaw:

pm2 start openclaw
pm2 save
pm2 startup

The pm2 startup command will generate a systemd service automatically.

Raspberry Pi Specific Setup

Performance Optimization

Raspberry Pi has limited resources. Optimize:

Use lighter AI models:
- Local models (Ollama) are more efficient
- Or use smaller cloud models
Limit concurrent operations:
- Configure OpenClaw to handle fewer simultaneous requests
Monitor resources:
```
htop
```

Always-On Setup

For Raspberry Pi running 24/7:

Use systemd service (see above)
Enable auto-login (if needed)

Configure power management:

sudo raspi-config
# Navigate to Advanced Options → Wait for Network at Boot

Cloudflare Tunnel (External Access)

Expose OpenClaw to the internet securely:

Install cloudflared:

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64 -o cloudflared
chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

Authenticate:
```
cloudflared tunnel login
```
Create tunnel:
```
cloudflared tunnel create openclaw
```

Configure: Create ~/.cloudflared/config.yml:

tunnel: <tunnel-id>
credentials-file: /home/pi/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: openclaw.yourdomain.com
    service: http://localhost:3000
  - service: http_status:404

Run tunnel:
```
cloudflared tunnel run openclaw
```
Add to systemd (for auto-start):
```
sudo cloudflared service install
```

ARM64 Support

OpenClaw works on ARM64 architecture:

Apple Silicon Macs (via Linux VM)
Raspberry Pi 4+ (64-bit)
AWS Graviton instances
Other ARM64 servers

Installation is identical to x86_64. The one-liner installer detects architecture automatically.

For ARMv7 (32-bit Raspberry Pi), some packages may not be available. Use distribution packages or build from source.

Troubleshooting

Permission Denied Errors

If you see permission errors:

sudo npm i -g openclaw

Or fix npm permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Command Not Found

If openclaw isn’t found:

Check npm global path:
```
npm config get prefix
```

Add to PATH:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Restart terminal

Port Already in Use

Change the port:

openclaw --port 3001

Or find and kill the process:

lsof -ti:3000 | xargs kill
# or
sudo netstat -tlnp | grep :3000
sudo kill <PID>

systemd Service Issues

If the service fails to start:

Check logs:
```
sudo journalctl -u openclaw -n 50
```
Verify user: Ensure the service runs as the correct user
Check permissions:
```
ls -la ~/.openclaw
```
Test manually:
```
openclaw
```

Raspberry Pi Specific Issues

Low memory:

# Increase swap
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Set CONF_SWAPSIZE=2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

Slow performance:

Use lighter AI models
Limit browser sessions
Reduce memory usage

Performance Tips

Resource Monitoring

Monitor CPU and memory:

htop
# or
top

Monitor disk usage:

df -h
du -sh ~/.openclaw

Optimization

Use local models for better performance on low-end hardware
Limit browser sessions to reduce memory usage
Configure log rotation to prevent disk fill-up
Use SSD instead of SD card (Raspberry Pi)

Updating OpenClaw

Update to the latest version:

npm update -g openclaw

Or re-run the installer:

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

Uninstalling

Remove OpenClaw:

npm uninstall -g openclaw

Remove configuration:

rm -rf ~/.openclaw

Stop and remove systemd service:

sudo systemctl stop openclaw
sudo systemctl disable openclaw
sudo rm /etc/systemd/system/openclaw.service
sudo systemctl daemon-reload

Next Steps

Now that OpenClaw is installed on Linux:

Set Up Always-On — Configure systemd service
Connect Chat Apps — WhatsApp, Telegram, Discord
Explore Skills — Skills Library
Read FAQ — Common Questions

Conclusion

Linux is an excellent platform for OpenClaw, especially for always-on deployments and Raspberry Pi projects. The one-liner installer handles most complexity, and systemd integration makes it easy to run as a service.

For more help, check our general installation guide or FAQ page. Happy automating on Linux!

Quick Answer