openclaw/docs/platforms/raspberry-pi.md

summary, read_when, title

summary	read_when	title
OpenClaw on Raspberry Pi (budget self-hosted setup)	Setting up OpenClaw on a Raspberry Pi Running OpenClaw on ARM devices Building a cheap always-on personal AI	Raspberry Pi

OpenClaw on Raspberry Pi

Goal

Run a persistent, always-on OpenClaw Gateway on a Raspberry Pi for ~$35-80 one-time cost (no monthly fees).

Perfect for:

• 24/7 personal AI assistant
• Home automation hub
• Low-power, always-available Telegram/WhatsApp bot

Hardware Requirements

Pi Model	RAM	Works?	Notes
Pi 5	4GB/8GB	✅ Best	Fastest, recommended
Pi 4	4GB	✅ Good	Sweet spot for most users
Pi 4	2GB	✅ OK	Works, add swap
Pi 4	1GB	⚠️ Tight	Possible with swap, minimal config
Pi 3B+	1GB	⚠️ Slow	Works but sluggish
Pi Zero 2 W	512MB	❌	Not recommended

Minimum specs: 1GB RAM, 1 core, 500MB disk
Recommended: 2GB+ RAM, 64-bit OS, 16GB+ SD card (or USB SSD)

What You'll Need

• Raspberry Pi 4 or 5 (2GB+ recommended)
• MicroSD card (16GB+) or USB SSD (better performance)
• Power supply (official Pi PSU recommended)
• Network connection (Ethernet or WiFi)
• ~30 minutes

1) Flash the OS

Use Raspberry Pi OS Lite (64-bit) — no desktop needed for a headless server.

1. Download Raspberry Pi Imager
2. Choose OS: Raspberry Pi OS Lite (64-bit)
3. Click the gear icon (⚙️) to pre-configure:
   • Set hostname: gateway-host
   • Enable SSH
   • Set username/password
   • Configure WiFi (if not using Ethernet)
4. Flash to your SD card / USB drive
5. Insert and boot the Pi

2) Connect via SSH

ssh user@gateway-host
# or use the IP address
ssh user@192.168.x.x

3) System Setup

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

# Install essential packages
sudo apt install -y git curl build-essential

# Set timezone (important for cron/reminders)
sudo timedatectl set-timezone America/Chicago  # Change to your timezone

4) Install Node.js 22 (ARM64)

# Install Node.js via NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

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

5) Add Swap (Important for 2GB or less)

Swap prevents out-of-memory crashes:

# Create 2GB swap file
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# Optimize for low RAM (reduce swappiness)
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

6) Install OpenClaw

Option A: Standard Install (Recommended)

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

Option B: Hackable Install (For tinkering)

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

The hackable install gives you direct access to logs and code — useful for debugging ARM-specific issues.

7) Run Onboarding

openclaw onboard --install-daemon

Follow the wizard:

1. Gateway mode: Local
2. Auth: API keys recommended (OAuth can be finicky on headless Pi)
3. Channels: Telegram is easiest to start with
4. Daemon: Yes (systemd)

8) Verify Installation

# Check status
openclaw status

# Check service
sudo systemctl status openclaw

# View logs
journalctl -u openclaw -f

9) Access the OpenClaw Dashboard

Replace user@gateway-host with your Pi username and hostname or IP address.

On your computer, ask the Pi to print a fresh dashboard URL:

ssh user@gateway-host 'openclaw dashboard --no-open'

The command prints Dashboard URL:. Depending on how gateway.auth.token is configured, the URL may be a plain http://127.0.0.1:18789/ link or one that includes #token=....

In another terminal on your computer, create the SSH tunnel:

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

Then open the printed Dashboard URL in your local browser.

If the UI asks for auth, paste the token from gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN) into Control UI settings.

For always-on remote access, see Tailscale.

---

Performance Optimizations

Use a USB SSD (Huge Improvement)

SD cards are slow and wear out. A USB SSD dramatically improves performance:

# Check if booting from USB
lsblk

See Pi USB boot guide for setup.

Speed up CLI startup (module compile cache)

On lower-power Pi hosts, enable Node's module compile cache so repeated CLI runs are faster:

grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret
export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1
EOF
source ~/.bashrc

Notes:

• NODE_COMPILE_CACHE speeds up subsequent runs (status, health, --help).
• /var/tmp survives reboots better than /tmp.
• OPENCLAW_NO_RESPAWN=1 avoids extra startup cost from CLI self-respawn.
• First run warms the cache; later runs benefit most.

systemd startup tuning (optional)

If this Pi is mostly running OpenClaw, add a service drop-in to reduce restart jitter and keep startup env stable:

sudo systemctl edit openclaw

[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90

Then apply:

sudo systemctl daemon-reload
sudo systemctl restart openclaw

If possible, keep OpenClaw state/cache on SSD-backed storage to avoid SD-card random-I/O bottlenecks during cold starts.

How Restart= policies help automated recovery: systemd can automate service recovery.

Reduce Memory Usage

# Disable GPU memory allocation (headless)
echo 'gpu_mem=16' | sudo tee -a /boot/config.txt

# Disable Bluetooth if not needed
sudo systemctl disable bluetooth

Monitor Resources

# Check memory
free -h

# Check CPU temperature
vcgencmd measure_temp

# Live monitoring
htop

---

ARM-Specific Notes

Binary Compatibility

Most OpenClaw features work on ARM64, but some external binaries may need ARM builds:

Tool	ARM64 Status	Notes
Node.js	✅	Works great
WhatsApp (Baileys)	✅	Pure JS, no issues
Telegram	✅	Pure JS, no issues
gog (Gmail CLI)	⚠️	Check for ARM release
Chromium (browser)	✅	sudo apt install chromium-browser

If a skill fails, check if its binary has an ARM build. Many Go/Rust tools do; some don't.

32-bit vs 64-bit

Always use 64-bit OS. Node.js and many modern tools require it. Check with:

uname -m
# Should show: aarch64 (64-bit) not armv7l (32-bit)

---

Recommended Model Setup

Since the Pi is just the Gateway (models run in the cloud), use API-based models:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-20250514",
        "fallbacks": ["openai/gpt-4o-mini"]
      }
    }
  }
}

Don't try to run local LLMs on a Pi — even small models are too slow. Let Claude/GPT do the heavy lifting.

---

Auto-Start on Boot

The onboarding wizard sets this up, but to verify:

# Check service is enabled
sudo systemctl is-enabled openclaw

# Enable if not
sudo systemctl enable openclaw

# Start on boot
sudo systemctl start openclaw

---

Troubleshooting

Out of Memory (OOM)

# Check memory
free -h

# Add more swap (see Step 5)
# Or reduce services running on the Pi

Slow Performance

• Use USB SSD instead of SD card
• Disable unused services: sudo systemctl disable cups bluetooth avahi-daemon
• Check CPU throttling: vcgencmd get_throttled (should return 0x0)

Service Won't Start

# Check logs
journalctl -u openclaw --no-pager -n 100

# Common fix: rebuild
cd ~/openclaw  # if using hackable install
npm run build
sudo systemctl restart openclaw

ARM Binary Issues

If a skill fails with "exec format error":

1. Check if the binary has an ARM64 build
2. Try building from source
3. Or use a Docker container with ARM support

WiFi Drops

For headless Pis on WiFi:

# Disable WiFi power management
sudo iwconfig wlan0 power off

# Make permanent
echo 'wireless-power off' | sudo tee -a /etc/network/interfaces

---

Cost Comparison

Setup	One-Time Cost	Monthly Cost	Notes
Pi 4 (2GB)	~$45	$0	+ power (~$5/yr)
Pi 4 (4GB)	~$55	$0	Recommended
Pi 5 (4GB)	~$60	$0	Best performance
Pi 5 (8GB)	~$80	$0	Overkill but future-proof
DigitalOcean	$0	$6/mo	$72/year
Hetzner	$0	€3.79/mo	~$50/year

Break-even: A Pi pays for itself in ~6-12 months vs cloud VPS.

---

See Also

• Linux guide — general Linux setup
• DigitalOcean guide — cloud alternative
• Hetzner guide — Docker setup
• Tailscale — remote access
• Nodes — pair your laptop/phone with the Pi gateway