Skip to content
OpenClaw Docs

Raspberry Pi

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.

Hardware compatibility

Section titled “Hardware compatibility”
Pi modelRAMWorks?Notes
Pi 54/8 GBBestFastest, recommended.
Pi 44 GBGoodSweet spot for most users.
Pi 42 GBOKAdd swap.
Pi 41 GBTightPossible with swap, minimal config.
Pi 3B+1 GBSlowWorks but sluggish.
Pi Zero 2 W512 MBNoNot 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.

Prerequisites

Section titled “Prerequisites”
  • Raspberry Pi 4 or 5 with 2 GB+ RAM (4 GB recommended)
  • MicroSD card (16 GB+) or USB SSD (better performance)
  • Official Pi power supply
  • Network connection (Ethernet or WiFi)
  • 64-bit Raspberry Pi OS (required — do not use 32-bit)
  • About 30 minutes

Setup

Section titled “Setup”

  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. 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.

  2. Connect via SSH

    Terminal window
    ssh user@gateway-host

  3. Update the system

    Terminal window
    sudo apt update && sudo apt upgrade -y
    sudo apt install -y git curl build-essential
    

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

  4. Install Node.js 24

    Terminal window
    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
    sudo apt install -y nodejs
    node --version

  5. Add swap (important for 2 GB or less)

    Terminal window
    sudo fallocate -l 2G /swapfile
    sudo chmod 600 /swapfile
    sudo mkswap /swapfile
    sudo swapon /swapfile
    echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
    

    # Reduce swappiness for low-RAM devices
    echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
    sudo sysctl -p

  6. Install OpenClaw

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

  7. Run onboarding

    Terminal window
    openclaw onboard --install-daemon

    Follow the wizard. API keys are recommended over OAuth for headless devices. Telegram is the easiest channel to start with.

  8. Verify

    Terminal window
    openclaw status
    systemctl --user status openclaw-gateway.service
    journalctl --user -u openclaw-gateway.service -f

  9. Access the Control UI

    On your computer, get a dashboard URL from the Pi:

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

    Then create an SSH tunnel in another terminal:

    Terminal window
    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.

Performance tips

Section titled “Performance tips”

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:

Terminal window
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

OPENCLAW_NO_RESPAWN=1 keeps routine Gateway restarts in-process, which avoids extra process handoffs and keeps PID tracking simple on small hosts.

Reduce memory usage — For headless setups, free GPU memory and disable unused services:

Terminal window
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:

Terminal window
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)".

Section titled “Recommended model setup”

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.

ARM binary notes

Section titled “ARM binary notes”

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.

Persistence and backups

Section titled “Persistence and backups”

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:

Terminal window
openclaw backup create

If you keep these on an SSD, both performance and longevity improve over the SD card.

Troubleshooting

Section titled “Troubleshooting”

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.

Next steps

Section titled “Next steps”
Section titled “Related”