docs/install/raspberry-pi.md
Run a persistent, always-on OpenClaw Gateway on a Raspberry Pi. Since the Pi is just the gateway (models run in the cloud via API), even a modest Pi handles the workload well — typical hardware cost is $35–80 one-time, no monthly fees.
| Pi model | RAM | Works? | Notes |
|---|---|---|---|
| Pi 5 | 4/8 GB | Best | Fastest, recommended. |
| Pi 4 | 4 GB | Good | Sweet spot for most users. |
| Pi 4 | 2 GB | OK | Add swap. |
| Pi 4 | 1 GB | Tight | Possible with swap, minimal config. |
| Pi 3B+ | 1 GB | Slow | Works but sluggish. |
| Pi Zero 2 W | 512 MB | No | Not recommended. |
Minimum: 1 GB RAM, 1 core, 500 MB free disk, 64-bit OS. Recommended: 2 GB+ RAM, 16 GB+ SD card (or USB SSD), Ethernet.
1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/).
2. Choose OS: **Raspberry Pi OS Lite (64-bit)**.
3. In the settings dialog, pre-configure:
- Hostname: `gateway-host`
- Enable SSH
- Set username and password
- Configure WiFi (if not using Ethernet)
4. Flash to your SD card or USB drive, insert it, and boot the Pi.
# Set timezone (important for cron and reminders)
sudo timedatectl set-timezone America/Chicago
```
# Reduce swappiness for low-RAM devices
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```
Follow the wizard. API keys are recommended over OAuth for headless devices. Telegram is the easiest channel to start with.
```bash
ssh user@gateway-host 'openclaw dashboard --no-open'
```
Then create an SSH tunnel in another terminal:
```bash
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
```
Open the printed URL in your local browser. For always-on remote access, see [Tailscale integration](/gateway/tailscale).
Use a USB SSD -- SD cards are slow and wear out. A USB SSD dramatically improves performance. See the Pi USB boot guide.
Enable module compile cache -- Speeds up repeated CLI invocations on lower-power Pi hosts:
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
Reduce memory usage -- For headless setups, free GPU memory and disable unused services:
echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
sudo systemctl disable bluetooth
systemd drop-in for stable restarts -- If this Pi is mostly running OpenClaw, add a service drop-in:
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 systemctl --user daemon-reload && systemctl --user restart openclaw-gateway.service. On a headless Pi, also enable lingering once so the user service survives logout: sudo loginctl enable-linger "$(whoami)".
Since the Pi only runs the gateway, use cloud-hosted API models:
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-6",
"fallbacks": ["openai/gpt-5.4-mini"]
}
}
}
}
Do not run local LLMs on a Pi — even small models are too slow to be useful. Let Claude or GPT do the model work.
Most OpenClaw features work on ARM64 without changes (Node.js, Telegram, WhatsApp/Baileys, Chromium). The binaries that occasionally lack ARM builds are typically optional Go/Rust CLI tools shipped by skills. Verify a missing binary's release page for linux-arm64 / aarch64 artifacts before falling back to building from source.
OpenClaw state lives under:
~/.openclaw/ — openclaw.json, per-agent auth-profiles.json, channel/provider state, sessions.~/.openclaw/workspace/ — agent workspace (SOUL.md, memory, artifacts).These survive reboots. Take a portable snapshot with:
openclaw backup create
If you keep these on an SSD, both performance and longevity improve over the SD card.
Out of memory -- Verify swap is active with free -h. Disable unused services (sudo systemctl disable cups bluetooth avahi-daemon). Use API-based models only.
Slow performance -- Use a USB SSD instead of an SD card. Check for CPU throttling with vcgencmd get_throttled (should return 0x0).
Service will not start -- Check logs with journalctl --user -u openclaw-gateway.service --no-pager -n 100 and run openclaw doctor --non-interactive. If this is a headless Pi, also verify lingering is enabled: sudo loginctl enable-linger "$(whoami)".
ARM binary issues -- If a skill fails with "exec format error", check whether the binary has an ARM64 build. Verify architecture with uname -m (should show aarch64).
WiFi drops -- Disable WiFi power management: sudo iwconfig wlan0 power off.