OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Hosting

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

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.

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

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

  • Connect via SSH

    bash
    ssh user@gateway-host

  • Update the system

    bash
    sudo apt update && sudo apt upgrade -ysudo apt install -y git curl build-essential # Set timezone (important for cron and reminders)sudo timedatectl set-timezone America/Chicago

  • Install Node.js 24

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

  • Add swap (important for 2 GB or less)

    bash
    sudo fallocate -l 2G /swapfilesudo chmod 600 /swapfilesudo mkswap /swapfilesudo swapon /swapfileecho '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab # Reduce swappiness for low-RAM devicesecho 'vm.swappiness=10' | sudo tee -a /etc/sysctl.confsudo sysctl -p

  • Install OpenClaw

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

  • Run onboarding

    bash
    openclaw onboard --install-daemon

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

  • Verify

    bash
    openclaw statussystemctl --user status openclaw-gateway.servicejournalctl --user -u openclaw-gateway.service -f

  • Access the Control UI

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

    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.

    • Performance tips

    Use a USB SSD -- SD cards are slow and wear out. A USB SSD dramatically improves performance and survives more write cycles; use it for OPENCLAW_STATE_DIR if you keep the OS on SD. See the Pi USB boot guide.

    Enable module compile cache -- Speeds up repeated CLI invocations on lower-power Pi hosts. OPENCLAW_NO_RESPAWN=1 keeps routine Gateway restarts in-process, avoiding extra process handoffs and keeping PID tracking simple on small hosts:

    bash
    grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secretexport NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cachemkdir -p /var/tmp/openclaw-compile-cacheexport OPENCLAW_NO_RESPAWN=1EOFsource ~/.bashrc

    Use /var/tmp, not /tmp -- some distros clear /tmp on boot, which drops the warmed cache.

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

    bash
    echo 'gpu_mem=16' | sudo tee -a /boot/config.txtsudo systemctl disable bluetooth

    systemd drop-in for stable restarts -- If this Pi is mostly running OpenClaw, add a service drop-in:

    bash
    systemctl --user edit openclaw-gateway.service
    ini
    [Service]Environment=OPENCLAW_NO_RESPAWN=1Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cacheRestart=alwaysRestartSec=2TimeoutStartSec=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 -- do not run local LLMs on a Pi, even small models are too slow to be useful:

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

    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 architecture with uname -m (should show aarch64), then check a missing binary's release page for linux-arm64 / aarch64 artifacts before falling back to building from source.

    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 and benefit from SSD over SD card for both performance and longevity. Take a portable snapshot with:

    bash
    openclaw backup create

    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

    Was this useful?
    On this page

    On this page