How to Deploy OpenClaw Headless on Raspberry Pi

Running OpenClaw on a Raspberry Pi gives you a dedicated, always-on AI agent for about $4 to published pricing in electricity. A Pi 5 draws roughly 6W under typical load, which is a fraction of what even the cheapest cloud VM costs monthly. The headless approach strips away the desktop environment, freeing about 600 MB of RAM for OpenClaw's orchestration work.

The Pi doesn't run LLMs locally. It acts as an orchestration layer that manages tool calls, channel integrations (Telegram, Discord, Slack), and workflow automation while delegating reasoning to cloud APIs like Anthropic, OpenAI, or Google. This separation means a $80 Pi 5 with 8 GB RAM handles the coordination work comfortably, and your AI budget goes toward API calls rather than hardware.

Most headless Pi guides stop at "install the software and SSH in." This guide goes further: systemd for process management, Docker for container isolation, UFW for firewall rules, and gateway token rotation for credential hygiene. If your agent has access to tools that can execute code, send messages, or modify files, these layers matter.

Start with the right hardware. A Raspberry Pi 5 with 8 GB RAM is the recommended baseline. The Pi 4 with 4 GB works but struggles with multiple concurrent tool calls. Avoid the 2 GB variant entirely.

SD cards create a bottleneck for OpenClaw's frequent small reads and writes to its SQLite database. The official Raspberry Pi M.2 HAT with a budget NVMe drive eliminates this problem and costs under $30.

Use the official 27W USB-C power supply. Third-party chargers frequently trigger under-voltage warnings when an SSD and active cooler draw power simultaneously. The official Pi 5 case with integrated fan costs about $10 and prevents thermal throttling during sustained agent workloads.

Flash Raspberry Pi OS Lite

Open the Raspberry

Pi Imager and select Raspberry Pi OS Lite (64-bit). You need the 64-bit version, as 32-bit is not supported. Before flashing, configure these settings in the Imager:

• Hostname: gateway-host (or your preferred name)
• Enable SSH with password authentication
• Set your username and password
• Configure WiFi credentials if not using Ethernet

Flash the image to your NVMe or SD card, insert it into the Pi, and power on. Give it a minute to boot, then connect:

ssh youruser@gateway-host

Once connected, update the system and install dependencies:

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

Optimize for Headless Use

Reduce GPU memory allocation since there's no display attached, and disable Bluetooth if you won't use it:

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

If you're running a 2 GB or 4 GB Pi, configure swap space. This is critical for avoiding out-of-memory kills:

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
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

OpenClaw requires Node.js 22 or later. Install it from the NodeSource repository:

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

Then install OpenClaw itself:

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

Run the onboarding wizard with the daemon flag to set up headless operation:

openclaw onboard --install-daemon

This registers the Gateway as a systemd service and prompts you for API keys. Use API key authentication rather than OAuth for headless devices, since there's no browser available for the OAuth redirect flow.

Verify the gateway is running:

openclaw gateway status

The Gateway listens on port 18789 by default. On a headless Pi, you won't access the dashboard directly. Instead, create an SSH tunnel from your laptop:

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

Then open http://localhost:18789 in your local browser to access the OpenClaw dashboard remotely.

Speed Up CLI Response Time

OpenClaw's Node.js CLI benefits from compile caching. Add these to your shell profile:

export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache
mkdir -p /var/tmp/openclaw-compile-cache
export OPENCLAW_NO_RESPAWN=1

This reduces cold-start latency for CLI commands, which adds up when the agent runs frequent tool calls.

Give your headless agent a workspace it can share

Fastio gives your Raspberry Pi agent 50 GB of free persistent storage with MCP access, semantic search, and ownership transfer. No credit card, no expiration. Built for openclaw raspberry headless workflows.

Sign Up Free

The onboarding wizard creates a basic systemd unit, but you should review and harden it. The service file lives at /etc/systemd/system/openclaw.service:

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi
ExecStart=/usr/local/bin/openclaw gateway start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Key settings here: Restart=always ensures the gateway comes back after crashes or OOM kills. RestartSec=5 adds a brief delay to avoid rapid restart loops. The After=network.target dependency makes sure networking is available before the gateway tries to reach cloud APIs.

Enable and start the service:

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

Check that it's running:

sudo systemctl status openclaw

To follow logs in real time:

journalctl -u openclaw -f

If the service fails repeatedly, check the last 100 log lines for specifics:

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

Handling WiFi Drops

Headless Pis on WiFi sometimes lose connectivity when the adapter enters power-saving mode. If you see intermittent API failures in the logs, disable WiFi power management:

sudo iwconfig wlan0 power off

For a permanent fix, add a NetworkManager dispatcher script or use Ethernet. An always-on agent needs an always-on connection.

Running OpenClaw directly on the host means the agent's tool executions share the same filesystem and network namespace as everything else on the Pi. Docker adds a layer of isolation that limits blast radius if a tool call goes wrong.

Install Docker on the Pi:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Create a docker-compose.yml with security-hardened settings:

services:
  openclaw:
    image: openclaw/gateway:latest
    restart: always
    ports:
      - "127.0.0.1:18789:18789"
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
    env_file:
      - .env.secrets

Three things to notice in this configuration:

Port binding to 127.0.0.1. The 127.0.0.1:18789:18789 binding means the gateway only listens on localhost, not on all interfaces. Without this, the default 0.0.0.0 binding exposes port 18789 to every device on your network with no authentication. You can verify this is working correctly with ss -tlnp | grep 18789, which should show only 127.0.0.1:18789.

Read-only filesystem. The read_only: true flag makes the container's filesystem immutable. Combined with tmpfs: /tmp for temporary scratch space, this prevents unauthorized modifications to the OpenClaw binary or configuration from within the container.

No privilege escalation. The no-new-privileges:true security option prevents processes inside the container from gaining additional privileges after startup. If a tool execution is compromised, it can't escalate to root.

Store your API keys and gateway token in .env.secrets with restrictive permissions:

chmod 600 .env.secrets

Start the container:

docker compose up -d

Docker isolation protects against container-level threats, but network-level hardening prevents unauthorized access to the Pi itself.

UFW Firewall Rules

Configure UFW to deny all incoming traffic by default, then allow only SSH:

sudo ufw default deny incoming
sudo ufw allow ssh
sudo ufw enable
sudo ufw status verbose

Since the gateway binds to 127.0.0.1, you don't need a UFW rule for port 18789. The SSH tunnel handles remote access, and the firewall blocks direct connections from other devices.

Gateway Token Security

The OpenClaw gateway token controls access to your agent. Generate a strong one with at least 32 random characters:

openssl rand -hex 32

Store this in your .env.secrets file, never in version control. Rotate gateway tokens monthly and API keys quarterly. A compromised token gives full control over your agent's tool execution.

VLAN Isolation For stronger isolation, put the Pi on its own VLAN. Configure your router to create a dedicated network segment for AI agent hardware, with firewall rules that restrict the Pi's access to the internet and any specific services it needs (like Home Assistant). Block all inbound internet connections to the Pi.

This is especially relevant if your agent has tools that interact with home automation, file systems, or external services. A compromised agent on an isolated VLAN can't pivot to other devices on your home network.

Run a Security Audit

OpenClaw includes a built-in security audit tool:

openclaw security audit

This checks your configuration for common issues like exposed ports, weak tokens, and overly permissive tool access. For automated remediation of straightforward issues:

openclaw security audit --fix

A headless Pi agent generates outputs: research files, processed data, reports, configuration backups. Storing everything locally on the Pi creates a single point of failure. The SD card or NVMe drive is the only copy, and Pi hardware isn't designed for archival storage.

You have several options for persistent storage. Local NAS or NFS mounts keep data on your network. S3-compatible object storage (MinIO, Backblaze B2) works for cold storage. For agent workflows where outputs need to be shared with humans or other agents, Fastio provides workspaces built for that handoff.

Fastio workspaces let an agent upload files, organize them into folders, and share them through purpose-built Send, Receive, and Exchange workflows. When Intelligence Mode is enabled, uploaded files are automatically indexed for semantic search and citation-backed chat, so a human reviewer can ask questions about the agent's output without downloading and reading every file.

The Fastio MCP server exposes workspace operations through Streamable HTTP, which means your OpenClaw agent can interact with Fastio workspaces through MCP tool calls. Upload research results, create shares for client delivery, or pull files from Google Drive and Dropbox into a workspace without local I/O through URL Import.

The free agent plan includes 50 GB of storage, 5,000 credits per month, and 5 workspaces with no credit card required and no expiration. For a headless Pi running a personal agent, that's enough storage to handle months of output before you need to think about cleanup.

When the agent's work is ready for human review, ownership transfer lets the agent hand off an entire organization, including workspaces, shares, and permissions, to a human account while retaining admin access for ongoing maintenance.