Self-Host OpenClaw on Raspberry Pi

A Raspberry Pi makes an excellent always-on host for OpenClaw. It draws minimal power, runs silently, and sits on your desk or in a closet providing a personal AI coding agent around the clock. Since OpenClaw offloads inference to cloud LLM providers, the Pi only needs to handle orchestration, file I/O, and the gateway server — tasks well within its capabilities.

This guide covers installing OpenClaw on a Raspberry Pi 4 (4GB+) or Pi 5 running Raspberry Pi OS 64-bit, tuning performance, setting up a systemd service for automatic startup, and configuring remote access.

Quick Path

For experienced Pi users:

1. Flash Raspberry Pi OS (64-bit) and boot with SSH enabled
2. Install OpenClaw: curl -fsSL https://openclaw.dev/install.sh | sh
3. Set your API key: export ANTHROPIC_API_KEY=sk-ant-... and run openclaw setup
4. Enable the systemd service: sudo systemctl enable --now openclaw-gateway
5. Access via http://pi-ip:18789 or set up Tailscale for remote access

Hardware Requirements

A 64-bit operating system is required. OpenClaw does not support 32-bit ARM.

System Preparation

Flash the OS

Download Raspberry Pi OS Lite (64-bit) and flash it to your SD card or USB drive using the Raspberry Pi Imager. In the imager's advanced settings:

• Enable SSH with password authentication or your public key
• Set your username and password
• Configure Wi-Fi if not using Ethernet
• Set the hostname (e.g., openclaw-pi)

Boot and Connect

Insert the storage, connect power, and wait 1-2 minutes for the Pi to boot. Then SSH in:

ssh your-username@openclaw-pi.local

Update the System

sudo apt update && sudo apt upgrade -y

Verify 64-bit Architecture

uname -m

This must output aarch64. If it shows armv7l, you are running a 32-bit OS and need to reflash with the 64-bit image.

Configure Swap

On 4GB models, add swap space to prevent out-of-memory issues during builds and heavy operations:

# Increase swap to 2GB
sudo dphys-swapfile swapoff
sudo sed -i 's/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=2048/' /etc/dphys-swapfile
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

# Verify
free -h

On 8GB models, the default swap is usually sufficient, but adding 1-2GB does not hurt.

Optimize for Headless Operation

If you are running the Pi without a monitor, reduce the GPU memory allocation to free RAM for OpenClaw:

echo "gpu_mem=16" | sudo tee -a /boot/firmware/config.txt
sudo reboot

Reconnect via SSH after the reboot.

Install OpenClaw

Using the Installer Script

The official installer detects your architecture and installs the appropriate binary:

curl -fsSL https://openclaw.dev/install.sh | sh

The script installs OpenClaw to ~/.local/bin/openclaw and adds it to your PATH. Verify the installation:

openclaw --version

Install Node.js (if needed)

If the installer reports that Node.js is missing or too old:

# Install Node.js 20 LTS via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify
node --version   # Should be v20.x or later
npm --version

Initial Configuration

Run the setup wizard:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"
openclaw setup

This creates the configuration directory at ~/.openclaw/ with:

• openclaw.json — runtime configuration
• agents/ — agent instruction files
• workspace/ — project and session data

Edit the configuration to set your preferred model and gateway options:

nano ~/.openclaw/openclaw.json

{
  "model": "claude-sonnet-4-20250514",
  "gateway": {
    "bind": "0.0.0.0",
    "port": 18789
  },
  "permissions": {
    "allow_network": true,
    "allow_file_write": true
  }
}

Generate and save a gateway token:

OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
echo "OPENCLAW_GATEWAY_TOKEN=$OPENCLAW_GATEWAY_TOKEN" >> ~/.openclaw/.env
echo "Your gateway token: $OPENCLAW_GATEWAY_TOKEN"

Save this token somewhere secure. You will need it to authenticate.

Set Up the systemd Service

Create a systemd unit file so OpenClaw starts automatically on boot and restarts on failure:

sudo tee /etc/systemd/system/openclaw-gateway.service > /dev/null << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=your-username
Group=your-username
WorkingDirectory=/home/your-username
EnvironmentFile=/home/your-username/.openclaw/.env
Environment=ANTHROPIC_API_KEY=sk-ant-your-key-here
Environment=XDG_CONFIG_HOME=/home/your-username/.openclaw
ExecStart=/home/your-username/.local/bin/openclaw gateway
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

Replace your-username with your actual username and set the correct API key.

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway

Check the status:

sudo systemctl status openclaw-gateway

View logs:

journalctl -u openclaw-gateway -f

Performance Tips

Use a USB SSD Instead of an SD Card

SD cards are slow for random I/O and wear out faster under heavy write loads. A USB 3.0 SSD dramatically improves performance:

1. Flash Raspberry Pi OS to the SSD using the Pi Imager
2. Connect the SSD to a USB 3.0 port (blue)
3. Update the boot order to prefer USB: sudo raspi-config and navigate to Advanced Options, then Boot Order

Increase I/O Scheduler Priority

For the OpenClaw service, set an I/O scheduling class:

# Add to the [Service] section of the systemd unit
IOSchedulingClass=best-effort
IOSchedulingPriority=0

Monitor Resource Usage

Keep an eye on memory and CPU:

# Real-time monitoring
htop

# Check memory including swap
free -h

# Check disk usage
df -h

If the Pi is swapping heavily during normal operation, consider upgrading to an 8GB model.

ARM Compatibility Notes

OpenClaw runs natively on ARM64 (aarch64). Most Node.js packages include prebuilt ARM64 binaries. In rare cases, a native module may need to compile from source during installation, which is slower on the Pi but only happens once. If a build fails due to missing development headers:

sudo apt install -y build-essential python3

Network and Remote Access

Local Network Access

From any device on the same network, access the gateway at:

http://openclaw-pi.local:18789

or using the Pi's IP address:

# Find the Pi's IP
hostname -I

Remote Access with Tailscale

For secure access from anywhere without opening ports on your router, install Tailscale:

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

After authentication, your Pi joins your tailnet. Access OpenClaw from any device on your tailnet at:

http://openclaw-pi:18789

Tailscale handles encryption, NAT traversal, and authentication. No port forwarding or dynamic DNS required.

Remote Access with SSH Tunnel

If you prefer not to install Tailscale, use an SSH tunnel from your local machine:

ssh -L 18789:localhost:18789 your-username@your-pi-public-ip

This requires your Pi to be reachable over SSH (via port forwarding on your router or a reverse tunnel service).

Security Best Practices

• Change the default password. If you did not set a custom password during OS setup, change it immediately: passwd
• Use SSH key authentication. Disable password-based SSH login after setting up keys:

# On the Pi
sudo sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart sshd

• Keep the gateway on the local network. Do not port-forward 18789 through your router. Use Tailscale or an SSH tunnel instead.
• Enable automatic security updates:

sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades

• Protect the API key. Store it in the .env file with restrictive permissions: chmod 600 ~/.openclaw/.env
• Use a strong gateway token. The openssl rand -hex 32 command generates a 256-bit token that is effectively unguessable.

Troubleshooting

OpenClaw fails to install

Verify you are running a 64-bit OS (uname -m should output aarch64). If you recently flashed the OS, run sudo apt update && sudo apt upgrade -y before installing.

Service fails to start

Check the journal for errors:

journalctl -u openclaw-gateway -n 50 --no-pager

Common causes:

• Wrong path to the openclaw binary in the ExecStart line
• Missing or incorrect API key in the environment
• Port 18789 already in use by another service

Out of memory errors

Check current memory usage:

free -h

If swap is exhausted, increase the swap size or close other services running on the Pi. On 4GB models, avoid running other memory-intensive applications alongside OpenClaw.

Slow response times

The Pi is not the bottleneck for most operations — the LLM provider's response time dominates. If local operations (file reads, git commands) feel slow:

• Switch from SD card to USB SSD
• Check that swap is not being used heavily (indicates memory pressure)
• Reduce the number of concurrent agent sessions

Network connectivity issues

If the gateway is unreachable from other devices:

# Check the service is running
sudo systemctl status openclaw-gateway

# Check the port is listening
ss -tlnp | grep 18789

# Check firewall rules (if ufw is enabled)
sudo ufw status
sudo ufw allow 18789/tcp   # Only for local network access

SD card corruption

SD cards can corrupt under heavy writes or improper shutdowns. Symptoms include read-only filesystem errors or boot failures. Mitigations:

• Use a USB SSD as your primary boot device
• Always shut down cleanly: sudo shutdown -h now
• Keep regular backups of your ~/.openclaw/ directory

Updating OpenClaw

Run the installer again to update to the latest version:

curl -fsSL https://openclaw.dev/install.sh | sh

Then restart the service:

sudo systemctl restart openclaw-gateway

Your configuration, agent instructions, and workspace data in ~/.openclaw/ are preserved across updates.