How to Run OpenClaw on Raspberry Pi: Complete Setup Guide

Mar 11, 2026

Cowrie

Dev @ Bswen

I tried running OpenClaw on my Raspberry Pi 4. It took three attempts before I got it working. The main problem? Node.js version compatibility on ARM architecture.

Here’s what I learned and how to avoid my mistakes.

The Challenge

OpenClaw runs on Node.js. Simple enough. But on Raspberry Pi, I hit several walls:

• Node.js 18 had module compatibility issues
• npm permission errors blocked global installation
• Memory constraints on my 4GB model caused crashes
• “Illegal instruction” errors from wrong ARM binary

After three failed attempts and hours of troubleshooting, I finally got a stable setup running 24/7. This guide shows you the working path.

Hardware Requirements

I tested on two Raspberry Pi models:

Model	RAM	Result
Pi 4 (8GB)	8GB	Works great, runs 5 agents
Pi 4 (4GB)	4GB	Works with memory optimization

The 8GB model is worth the extra cost if you’re serious about this. With 4GB, I had to enable swap and limit concurrent operations.

Minimum setup:

• Raspberry Pi 4 (4GB minimum, 8GB recommended)
• 16GB+ microSD card (Class 10) or USB SSD
• Official 5V/3A power supply
• Raspberry Pi OS Lite (64-bit) or Ubuntu Server ARM64

Step 1: Install Node.js 22

My first mistake was using Node.js 18. It installed fine, but OpenClaw threw errors about missing modules.

Use Node.js 22 LTS. Here’s the working method:

install-nodejs.sh

# Update system
sudo apt update && sudo apt upgrade -y

# Install build dependencies
sudo apt install -y build-essential curl python3

# Add Node.js 22 repository (auto-detects ARM architecture)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -

# Install Node.js
sudo apt install -y nodejs

# Verify installation
node --version  # Should show v22.x.x
npm --version

The NodeSource repository auto-detects your ARM version. This saved me from the “Illegal instruction” error I got with manually downloaded binaries.

Fixing npm Permission Errors

My second attempt failed with npm permission errors. The fix:

fix-npm-permissions.sh

# Create npm global directory
mkdir ~/.npm-global

# Configure npm to use user directory
npm config set prefix '~/.npm-global'

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Don’t use sudo npm install. That was my mistake. It creates permission problems later.

Step 2: Create Dedicated User

Running OpenClaw as my regular user felt risky. If something went wrong, an attacker would have access to all my files.

I created a dedicated user:

create-user.sh

# Create openclaw user
sudo adduser --disabled-password --gecos "" openclaw

# Add to sudo group (for service management)
sudo usermod -aG sudo openclaw

# Configure passwordless sudo for systemd
echo "openclaw ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/openclaw
sudo chmod 440 /etc/sudoers.d/openclaw

This isolates OpenClaw from your personal files. A compromised agent can only access what’s in the openclaw user’s home directory.

Step 3: Install OpenClaw

Switch to the openclaw user and install:

install-openclaw.sh

# Switch to openclaw user
sudo su - openclaw

# Configure npm prefix
npm config set prefix ~/.npm-global

# Install OpenClaw globally
npm install -g openclaw@latest

# Add to PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
openclaw --version

Run Initial Configuration

onboard.sh

# Run onboarding wizard
openclaw onboard

This generates your gateway token, configures authentication, and creates the initial agent. Configuration files go to ~/.openclaw/openclaw.json.

Step 4: Set Up Systemd Service

For 24/7 operation, I needed OpenClaw to start automatically and restart on failure.

create-service.sh

sudo tee /etc/systemd/system/openclaw-gateway.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw Gateway (Always-On AI Assistant)
After=network-online.target
Wants=network-online.target

[Service]
User=openclaw
WorkingDirectory=/home/openclaw
Environment=PATH=/usr/bin:/bin:/home/openclaw/.npm-global/bin
ExecStart=/home/openclaw/.npm-global/bin/openclaw gateway --bind loopback --port 18789 --verbose
Restart=always
RestartSec=5

# Security hardening
NoNewPrivileges=false
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF

Enable and start:

enable-service.sh

# Reload systemd
sudo systemctl daemon-reload

# Enable service (start on boot)
sudo systemctl enable openclaw-gateway.service

# Start service
sudo systemctl start openclaw-gateway.service

# Check status
sudo systemctl status openclaw-gateway.service

Check logs:

view-logs.sh

sudo journalctl -u openclaw-gateway.service -f

Step 5: Configure Model (Local or Cloud)

OpenClaw needs a model backend. I tested two approaches.

Option A: Local Model with Ollama

For privacy, I ran models locally:

install-ollama.sh

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull lightweight model (good for Pi 4)
ollama pull ministral-3:3b

Recommended models for Raspberry Pi:

Model	Size	Notes
ministral-3:3b	3B	Best balance, fast
llama3.2:3b	3B	Larger context window
qwen2.5:3b	3B	Good for tool use

On my 4GB Pi, the 3B models run fine. Larger models caused memory issues.

Option B: Cloud Models

For better reasoning quality, I configured cloud APIs:

configure-cloud.sh

# Configure Anthropic Claude
openclaw models configure anthropic --api-key YOUR_KEY

# Set default model
openclaw models aliases set default claude-sonnet-4.5

I use a hybrid approach: local models for routine tasks, cloud models for complex reasoning. This keeps API costs down.

Step 6: Memory Optimization (4GB Model)

On my 4GB Pi, I hit memory constraints. Here’s what helped:

Enable Swap

enable-swap.sh

# Check current swap
free -h

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

Monitor Memory Usage

monitor-memory.sh

# Watch memory
htop

# Or simpler view
watch -n 5 free -h

Limit Node.js Memory

limit-node-memory.sh

# Add to systemd service or .bashrc
export NODE_OPTIONS="--max-old-space-size=3072"  # 3GB limit

Step 7: Remote Access Setup

With OpenClaw bound to localhost, I needed a way to access it remotely.

Option A: SSH Tunnel (Simple)

ssh-tunnel.sh

# On your local machine
ssh -N -L 18789:127.0.0.1:18789 openclaw@YOUR_PI_IP

# Access at http://localhost:18789

Option B: Tailscale (Recommended)

install-tailscale.sh

# Install Tailscale on Raspberry Pi
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# Now accessible from any device on your tailnet

Tailscale is more convenient than SSH tunnels. No port forwarding, no exposed services.

Step 8: Security Hardening

An AI agent with file system access is a security risk. I applied these hardening measures:

Run Security Audit

security-audit.sh

# Basic audit
openclaw security audit

# Deep audit with network checks
openclaw security audit --deep

# Auto-fix common issues
openclaw security audit --fix

Restrict Tool Access

Edit ~/.openclaw/openclaw.json:

openclaw.json

{
  "gateway": {
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "YOUR_SECURE_TOKEN"
    }
  },
  "tools": {
    "profile": "messaging",
    "deny": ["group:automation", "group:runtime", "group:fs"],
    "exec": {
      "security": "deny",
      "ask": "always"
    }
  }
}

This restricts dangerous operations. File system and command execution require explicit approval.

Step 9: Install Skills

Skills extend OpenClaw’s capabilities. From the Reddit success case, these work well on Pi:

install-skills.sh

# Core skills
openclaw skills install clawhub
openclaw skills install notion
openclaw skills install gog

# For local speech recognition
openclaw skills install whisper

# For code assistance
openclaw skills install nano-banana

Monitoring and Maintenance

Health Check Script

monitor-openclaw.sh

#!/bin/bash

echo "=== OpenClaw System Monitor ==="
echo ""

echo "Memory Usage:"
free -h
echo ""

echo "CPU Temperature:"
vcgencmd measure_temp
echo ""

echo "OpenClaw Service Status:"
sudo systemctl status openclaw-gateway.service --no-pager | head -n 15
echo ""

echo "Recent Logs:"
sudo journalctl -u openclaw-gateway.service -n 10 --no-pager

Backup Configuration

backup.sh

# Backup OpenClaw setup
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw

Update OpenClaw

update.sh

# Stop service
sudo systemctl stop openclaw-gateway.service

# Update
npm update -g openclaw@latest

# Restart
sudo systemctl start openclaw-gateway.service

# Verify
openclaw --version

Troubleshooting Common Issues

”Illegal instruction” Error

This means wrong Node.js binary for your ARM version. Use NodeSource repository which auto-detects architecture.

npm Permission Errors

Don’t use sudo npm install. Configure npm to use your home directory:

fix-permissions.sh

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Out of Memory

On 4GB model, enable swap and use smaller models:

memory-fix.sh

# Enable swap
sudo dphys-swapfile swapoff
# Edit /etc/dphys-swapfile, set CONF_SWAPSIZE=2048
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

# Use smaller model
ollama pull ministral-3:3b

Service Won’t Start

Check logs:

debug-service.sh

sudo journalctl -u openclaw-gateway.service -n 50

# Common issue: wrong path in ExecStart
ls -la /home/openclaw/.npm-global/bin/openclaw

Performance Tips

Use SSD Instead of microSD

microSD cards are slow. I switched to a USB 3.0 SSD and saw significant improvement:

ssd-setup.sh

# Mount SSD
sudo mkdir -p /mnt/ssd/openclaw
sudo chown openclaw:openclaw /mnt/ssd/openclaw

# Move OpenClaw data
export OPENCLAW_STATE_DIR=/mnt/ssd/openclaw

CPU Governor

Set to performance mode for consistent speed:

cpu-performance.sh

echo "performance" | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

What I Learned

Running OpenClaw on Raspberry Pi is possible but requires patience. The key challenges:

1. Node.js compatibility: Use version 22, not 18
2. Memory: 8GB model is worth the extra cost
3. Permissions: Never use sudo npm
4. Security: Bind to localhost, use VPN for remote access
5. Models: 3B parameter models work well on Pi 4

After three weeks of running this setup, I have 5 agents running continuously with local memory. No cloud infrastructure costs. Complete data privacy. The setup took effort, but the result is worth it.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

• 👨‍💻 OpenClaw Documentation
• 👨‍💻 OpenClaw GitHub
• 👨‍💻 Node.js ARM Downloads
• 👨‍💻 Raspberry Pi Documentation
• 👨‍💻 Reddit: Running OpenClaw on Raspberry Pi

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags:

• ai-coding
• performance
• ai
• ai-agents
• security

How to Reduce API Costs When Using AI Agents: A Practical Guide

Build an AI Agent Memory System with Daily Consolidation