Deploy OpenClaw on Raspberry Pi 4 or 5

A low-power, always-on deployment for running OpenClaw agents at home. The Pi acts as a lightweight client that calls LLM APIs over the network -- it does not run models locally. Total hardware cost is under $100, and idle power draw is 3-5 watts.

Prerequisites

You also need a second computer (Mac, Windows, or Linux) to flash the SD card and SSH into the Pi.

Step 1: Flash and Boot Raspberry Pi OS

1. Download and install Raspberry Pi Imager on your computer.
2. Insert your microSD card.
3. Open Raspberry Pi Imager and select:
   • Device: Raspberry Pi 4 or Raspberry Pi 5
   • OS: Raspberry Pi OS Lite (64-bit) -- under "Raspberry Pi OS (other)"
   • Storage: Your microSD card
4. Click the gear icon (or "Edit Settings") before writing to pre-configure:

Hostname:        openclaw-pi
Enable SSH:      Use password authentication
Username:        openclaw
Password:        <choose a strong password>
WiFi SSID:       <your network name>
WiFi Password:   <your WiFi password>
WiFi Country:    <your country code, e.g. US>
Locale:          <your timezone, e.g. America/New_York>

5. Click Write and wait for the image to finish.
6. Insert the microSD into the Pi, connect Ethernet (if available), and power on.
7. Wait 60-90 seconds for the first boot to complete.

Find the Pi on your network:

# From your computer -- scan the local network
ping openclaw-pi.local

# If mDNS does not resolve, check your router's DHCP client list
# or scan with nmap:
nmap -sn 192.168.1.0/24

Step 2: Initial System Setup

SSH into the Pi from your computer:

ssh openclaw@openclaw-pi.local

Update the system and install essential packages:

sudo apt update && sudo apt full-upgrade -y
sudo apt install -y git curl wget build-essential

Set a Static IP Address

A static IP prevents the Pi's address from changing after a router reboot. Edit the dhcpcd configuration:

sudo nano /etc/dhcpcd.conf

Add the following at the bottom (adjust addresses for your network):

interface eth0
static ip_address=192.168.1.50/24
static routers=192.168.1.1
static domain_name_servers=192.168.1.1 8.8.8.8

For WiFi, replace eth0 with wlan0. Alternatively, set a DHCP reservation in your router's admin panel -- this is simpler and avoids editing system files.

Set Timezone

sudo timedatectl set-timezone America/New_York
# Verify:
timedatectl

Reboot to apply all changes:

sudo reboot

Step 3: Install Node.js 20 LTS

The default Node.js in Raspberry Pi OS repos is outdated. Use the NodeSource repository to get Node.js 20 LTS, which is the current Long Term Support release:

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

Verify the installation:

node --version
# Expected: v20.x.x

npm --version
# Expected: 10.x.x

Why not nvm? nvm compiles Node.js from source on ARM, which can take 30+ minutes on a Pi 4 and may fail on low-memory boards. The NodeSource binary packages are pre-built for arm64 and install in seconds.

Step 4: Install and Configure OpenClaw

Install OpenClaw globally:

sudo npm install -g openclaw

Verify it installed correctly:

openclaw --version

Configure API Keys

Create a dedicated directory for OpenClaw configuration:

mkdir -p ~/.openclaw

Create the environment file with your API keys:

nano ~/.openclaw/.env

Add your configuration:

# Required: Your LLM provider API key
ANTHROPIC_API_KEY=sk-ant-your-key-here
# Or if using OpenAI:
# OPENAI_API_KEY=sk-your-key-here

# Optional: Customize agent behavior
OPENCLAW_LOG_LEVEL=info
OPENCLAW_MAX_CONCURRENT_SKILLS=2

Lock down permissions on the env file:

chmod 600 ~/.openclaw/.env

Initialize Your Agent

cd ~/.openclaw
openclaw init

This creates a SOUL.md file and default skill configuration. Edit SOUL.md to define your agent's persona and behavior, or copy one of the templates from the OpenClaw Directory.

Step 5: Run OpenClaw as a Systemd Service

A systemd service ensures OpenClaw starts automatically on boot and restarts if it crashes.

Create the service file:

sudo nano /etc/systemd/system/openclaw.service

Paste the following:

[Unit]
Description=OpenClaw AI Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw/.openclaw
ExecStart=/usr/bin/openclaw start
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
EnvironmentFile=/home/openclaw/.openclaw/.env

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/openclaw/.openclaw

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable openclaw.service
sudo systemctl start openclaw.service

Check that it is running:

sudo systemctl status openclaw.service

# View live logs:
journalctl -u openclaw.service -f

# View last 50 log lines:
journalctl -u openclaw.service -n 50

Step 6: Performance Optimization

The Pi has limited RAM and CPU. These optimizations free up resources for OpenClaw.

Reduce GPU Memory

Since you are running headless (no monitor), minimize the GPU memory allocation. Edit the boot config:

sudo nano /boot/firmware/config.txt

Add or modify this line:

gpu_mem=16

This frees up to 240 MB of RAM compared to the default 76 MB allocation.

Configure Swap

The default 200 MB swap is too small. Increase it to 1 GB:

sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile

Set the swap size:

CONF_SWAPSIZE=1024

Apply the change:

sudo dphys-swapfile setup
sudo dphys-swapfile swapon

Boot from USB SSD (Recommended)

MicroSD cards are slow and prone to wear. USB SSD boot gives 5-10x faster I/O and much better reliability for long-running services.

1. Flash Raspberry Pi OS to your USB SSD using Raspberry Pi Imager (same steps as the microSD).
2. On Pi 5: USB boot is enabled by default. Plug in the SSD and power on without an SD card.
3. On Pi 4: You may need to update the bootloader first. With the SD card still inserted, run:

sudo rpi-eeprom-update -a
sudo raspi-config
# Navigate to: Advanced Options > Boot Order > USB Boot
sudo reboot

4. Remove the SD card and boot from SSD.

Disable Unnecessary Services

# Disable Bluetooth if not needed
sudo systemctl disable bluetooth
sudo systemctl stop bluetooth

# Disable audio (not needed headless)
sudo systemctl disable alsa-restore

Step 7: Remote Access

SSH (Already Configured)

SSH is your primary access method. For key-based authentication (more secure than passwords):

# On your computer, copy your SSH key to the Pi:
ssh-copy-id openclaw@openclaw-pi.local

# Then disable password auth on the Pi:
sudo sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart sshd

Tailscale (Remote Access From Anywhere)

Tailscale creates a WireGuard VPN mesh so you can reach your Pi from anywhere without opening router ports:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Follow the printed URL to authenticate. After setup, you can SSH into your Pi from anywhere using its Tailscale IP (100.x.y.z) or MagicDNS hostname.

Optional: Pi-hole Companion

If you are already running Pi-hole on this device for DNS-level ad blocking, OpenClaw runs alongside it without conflict. Just make sure Pi-hole and OpenClaw are not both trying to use port 80. OpenClaw defaults to port 3000, so no changes are needed in most cases.

Power and Reliability

UPS HAT for Power Outage Protection

Sudden power loss can corrupt SD cards and leave OpenClaw in a bad state. A UPS HAT provides battery backup and clean shutdown:

• PiSugar 3 (~$40): 1200 mAh battery, software-triggered shutdown, RTC clock
• Geekworm X728 (~$35): Supports 18650 batteries, safe shutdown via GPIO
• Official Raspberry Pi Battery Pack: Use any USB-C power bank with pass-through charging as a basic UPS

Temperature Monitoring

The Pi throttles CPU speed when it overheats. Monitor the temperature:

# Check current CPU temperature
vcgencmd measure_temp
# Example output: temp=45.0'C

# Add to crontab for logging every 5 minutes:
(crontab -l 2>/dev/null; echo "*/5 * * * * /usr/bin/vcgencmd measure_temp >> /home/openclaw/temp.log") | crontab -

Thermal thresholds:

• Below 60 C: Normal operation
• 60-80 C: Warm but safe. Consider adding a heatsink.
• Above 80 C: Throttling begins. Install an active fan or the official Pi 5 Active Cooler ($5).

Heatsink and Fan Recommendations

• Pi 4: A basic aluminum heatsink set ($5-8) is sufficient for headless workloads. Add a small 30mm fan if you see temperatures above 70 C regularly.
• Pi 5: The official Raspberry Pi Active Cooler ($5) is strongly recommended. The Pi 5 runs hotter than the Pi 4 under load.

Limitations

Be aware of what a Raspberry Pi can and cannot do in this context:

• The Pi is an API client, not a model host. OpenClaw calls LLM APIs (Anthropic, OpenAI, etc.) over the network. The Pi does not run language models locally. You need an active internet connection and a valid API key.
• RAM is the primary constraint. A 4 GB Pi can run OpenClaw with 2-3 concurrent skills comfortably. An 8 GB Pi handles more headroom for complex workflows. If you exceed memory, the OOM killer will terminate the process.
• CPU-heavy skills will be slow. Tasks like image processing or large file manipulation will take longer on the Pi's ARM cores than on a desktop CPU. API-calling skills (which is most of what OpenClaw does) are not affected because the bottleneck is network latency, not local compute.
• SD card wear. Frequent writes (heavy logging, large temp files) degrade microSD cards over time. Use a USB SSD for long-term deployments, and keep log levels at info or warn rather than debug.
• Stick to 2-3 concurrent skills on a 4 GB board. Monitor memory usage with htop and reduce concurrency if swap usage climbs above 200 MB.

Cost Breakdown

Optional upgrades:

Ongoing costs are limited to your LLM API usage and electricity (~$3-5/year at typical residential rates for a Pi running 24/7).

Troubleshooting

Node.js Installation Fails

Symptom: dpkg: error processing package nodejs or architecture mismatch errors.

Cause: You are running 32-bit Raspberry Pi OS. NodeSource only provides arm64 (64-bit) binaries for recent Node.js versions.

Fix: Reflash with Raspberry Pi OS Lite 64-bit. Verify your architecture:

uname -m
# Must show: aarch64
# If it shows armv7l, you are on 32-bit

Out of Memory Errors / Process Killed

Symptom: OpenClaw exits unexpectedly. journalctl shows oom-kill entries.

Fix:

1. Reduce concurrent skills in your config: OPENCLAW_MAX_CONCURRENT_SKILLS=1
2. Increase swap to 2 GB (see Step 6)
3. Close other running services
4. Check memory usage: free -h
5. Upgrade to an 8 GB Pi if the problem persists

SD Card Corruption / Read-Only Filesystem

Symptom: Errors like Read-only file system or boot failures after a power outage.

Fix:

1. Power off the Pi and remove the SD card.
2. On your computer, run fsck on the SD card partition:

# On Linux/Mac (adjust device path):
sudo fsck -y /dev/sdX2

3. If the card is beyond repair, reflash from a backup image.
4. Prevention: Use a UPS HAT or USB SSD to avoid this entirely.

OpenClaw Service Fails to Start

Symptom: systemctl status openclaw shows failed.

Fix: Check the logs for the specific error:

journalctl -u openclaw.service -n 100 --no-pager

Common causes:

• Missing or invalid API key in ~/.openclaw/.env
• Wrong WorkingDirectory path in the service file
• Node.js not found (check that /usr/bin/openclaw exists: which openclaw)
• Permission issues (the service runs as user openclaw, not root)

High CPU Temperature / Throttling

Symptom: Sluggish performance. vcgencmd get_throttled returns a non-zero value.

Fix:

1. Check temperature: vcgencmd measure_temp
2. Install a heatsink and fan (see Power and Reliability section)
3. Ensure the Pi has adequate ventilation and is not enclosed in a sealed case
4. Reduce workload or add a 30-second delay between skill executions