docs/platforms/raspberry-pi.md
Run a persistent, always-on OpenClaw Gateway on a Raspberry Pi for ~$35-80 one-time cost (no monthly fees).
Perfect for:
| 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)
Use Raspberry Pi OS Lite (64-bit) — no desktop needed for a headless server.
gateway-hostssh user@gateway-host
# or use the IP address
ssh [email protected]
# 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
# Install Node.js via NodeSource
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
# Verify
node --version # Should show v24.x.x
npm --version
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
curl -fsSL https://openclaw.ai/install.sh | bash
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.
openclaw onboard --install-daemon
Follow the wizard:
# Check status
openclaw status
# Check service (standard install = systemd user unit)
systemctl --user status openclaw-gateway.service
# View logs
journalctl --user -u openclaw-gateway.service -f
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 shared-secret auth, paste the configured token or password
into Control UI settings. For token auth, use gateway.auth.token (or
OPENCLAW_GATEWAY_TOKEN).
For always-on remote access, see Tailscale.
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.
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.If this Pi is mostly running OpenClaw, add a service drop-in to reduce restart jitter and keep startup env stable:
systemctl --user edit openclaw-gateway.service
[Service]
Environment=OPENCLAW_NO_RESPAWN=1
Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
Restart=always
RestartSec=2
TimeoutStartSec=90
Then apply:
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.service
If possible, keep OpenClaw state/cache on SSD-backed storage to avoid SD-card random-I/O bottlenecks during cold starts.
If this is a headless Pi, enable lingering once so the user service survives logout:
sudo loginctl enable-linger "$(whoami)"
How Restart= policies help automated recovery:
systemd can automate service recovery.
# Disable GPU memory allocation (headless)
echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
# Disable Bluetooth if not needed
sudo systemctl disable bluetooth
# Check memory
free -h
# Check CPU temperature
vcgencmd measure_temp
# Live monitoring
htop
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.
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)
Since the Pi is just the Gateway (models run in the cloud), use API-based models:
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-6",
"fallbacks": ["openai/gpt-5.4-mini"]
}
}
}
}
Don't try to run local LLMs on a Pi — even small models are too slow. Let Claude/GPT do the heavy lifting.
Onboarding sets this up, but to verify:
# Check service is enabled
systemctl --user is-enabled openclaw-gateway.service
# Enable if not
systemctl --user enable openclaw-gateway.service
# Start on boot
systemctl --user start openclaw-gateway.service
# Check memory
free -h
# Add more swap (see Step 5)
# Or reduce services running on the Pi
sudo systemctl disable cups bluetooth avahi-daemonvcgencmd get_throttled (should return 0x0)# Check logs
journalctl --user -u openclaw-gateway.service --no-pager -n 100
# Common fix: rebuild
cd ~/openclaw # if using hackable install
npm run build
systemctl --user restart openclaw-gateway.service
If a skill fails with "exec format error":
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
| 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.