Run OpenClaw Gateway on Raspberry Pi: Self-Hosting Guide

Run an OpenClaw Gateway around the clock on a Raspberry Pi. Because the Pi only acts as the gateway, with models executing in the cloud through APIs, even a low-end Pi manages the load without trouble. Typical hardware costs run $35-80 once, with no recurring subscription.

Hardware compatibility

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

• A Raspberry Pi 4 or 5 carrying at least 2 GB of RAM (4 GB is preferred)
• A MicroSD card of 16 GB or larger, or a USB SSD for improved speed
• The official Pi power adapter
• Connectivity through Ethernet or WiFi
• A 64-bit Raspberry Pi OS installation (mandatory, skip 32-bit versions)
• Roughly half an hour of your time

Setup

Flash the OS

Go with Raspberry Pi OS Lite (64-bit) since a headless server has no need for a desktop environment.

1. Grab Raspberry Pi Imager.
2. Pick Raspberry Pi OS Lite (64-bit) as the operating system.
3. Inside the settings screen, set up these options ahead of time:
   • Hostname: gateway-host
   • Turn on SSH
   • Provide a username and password
   • Set up WiFi unless you are wired in
4. Write the image to your SD card or USB drive, plug it in, and power on the Pi.

Connect via SSH

ssh user@gateway-host

Update the system

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

Install Node.js 26

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

Add swap (important for 2 GB or less)

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

Install OpenClaw

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

Run onboarding

openclaw onboard --install-daemon

Work through the wizard. For headless devices, API keys are the better choice compared to OAuth. Starting with Telegram gives you the simplest channel to test.

Verify

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

Access the Control UI

From your own machine, pull a dashboard URL off the Pi:

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

After that, open a second terminal and set up an SSH tunnel:

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

Load the printed URL in your local browser. For access that stays available remotely at all times, check the Tailscale integration.

Performance tips

Prefer a USB SSD -- SD cards are slow and prone to wear. A USB SSD boosts speed noticeably and handles far more write cycles; point OPENCLAW_STATE_DIR at it if the OS remains on SD. Refer to the Pi USB boot guide.

Turn on the module compile cache -- This cuts down the time for repeated CLI calls on less powerful Pi hardware. OPENCLAW_NO_RESPAWN=1 keeps routine Gateway restarts inside the same process, cutting out extra process handoffs and making PID tracking simpler on small systems:

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

Pick /var/tmp over /tmp -- certain distros wipe /tmp at boot, which erases the warmed cache.

Lower memory consumption -- For headless setups, release GPU memory and shut off services you do not need:

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

systemd drop-in for dependable restarts -- When OpenClaw is the main job of this Pi, 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 run systemctl --user daemon-reload && systemctl --user restart openclaw-gateway.service. On a headless Pi, also switch on lingering so the user service stays alive after logout: sudo loginctl enable-linger "$(whoami)".

Recommended model setup

Given that the Pi handles only the gateway, stick with cloud-hosted API models. Running local LLMs on a Pi is not viable, even small ones are far too slow to be practical:

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

ARM binary notes

The majority of OpenClaw features run on ARM64 without any changes (Node.js, Telegram, WhatsApp/Baileys, Chromium). The binaries that sometimes lack ARM builds tend to be optional Go/Rust CLI tools shipped by skills. Confirm the architecture with uname -m (it should report aarch64), then look at a missing binary's release page for linux-arm64 / aarch64 artifacts before you resort to compiling from source.

Persistence and backups

OpenClaw keeps its state in these locations:

• ~/.openclaw/ -- openclaw.json, per-agent auth-profiles.json, channel/provider state, sessions.
• ~/.openclaw/workspace/ -- the agent workspace (SOUL.md, memory, artifacts).

Both survive reboots, and an SSD beats an SD card here for speed and lifespan. Capture a portable snapshot with:

openclaw backup create
openclaw backup restore <archive.tar.gz> --target <fresh-directory>

Restoring checks and unpacks the data into a fresh staging directory; activation is a separate step done offline. See Restore a full archive for the rollback warnings and the activation sequence.

Troubleshooting

Out of memory -- Confirm swap is active with free -h. Stop services you are not using (sudo systemctl disable cups bluetooth avahi-daemon). Stick to API-based models only.

Slow performance -- Swap the SD card for a USB SSD. Watch for CPU throttling using vcgencmd get_throttled (it should come back as 0x0).

Service will not start -- Inspect the logs with journalctl --user -u openclaw-gateway.service --no-pager -n 100 and execute openclaw doctor --non-interactive. On a headless Pi, also make sure lingering is on: sudo loginctl enable-linger "$(whoami)".

ARM binary issues -- When a skill returns "exec format error", confirm that an ARM64 build of the binary exists. Check the architecture using uname -m, which should output aarch64.

WiFi drops -- Turn off WiFi power management with sudo iwconfig wlan0 power off.

Next steps

• Channels -- link Telegram, WhatsApp, Discord, and other services
• Gateway configuration -- every configuration option
• Updating -- maintain OpenClaw at the latest version

Related

• Install overview
• Linux server
• Platforms