Deploying OpenClaw on a Raspberry Pi

Table of Contents

What is OpenClaw?

OpenClaw is an open-source personal AI assistant that you can run on your own hardware. The basic idea is straightforward: you give an LLM — Claude, GPT, or whatever you prefer — access to a real computer. It gets a shell, a file system, a browser, and connections to the messaging platforms you already use, and it acts as a persistent, always-on assistant you can talk to from anywhere.

The project was created by Peter Steinberger (@steipete), a developer well known in the Apple and iOS community. It was released in January 2026 and gained traction very quickly, reaching over 221,000 GitHub stars within weeks. It is written in TypeScript and runs on Node.js v22 or newer.

The project is fully open source and available at github.com/openclaw/openclaw.

By the way, 📚🚀 I invite you to dive into my sci-fi epic, GÖD’S GATE! Alongside an action-packed storyline, I’ve woven in some cool computer science elements, detailing the cyber offense capabilities of a powerful AI. Whether you’re a sci-fi fan or a computer scientist, this one’s for you. 👾👾

How it works

At the centre of OpenClaw is a component called the Gateway. It’s a WebSocket-based control plane that runs on your device and ties everything together: sessions, messaging channels, tools, scheduled tasks, webhooks, and a web-based Control UI.

WhatsApp / Telegram / Slack / Discord / Signal / iMessage / Teams / WebChat
                              |
                              v
                  ┌───────────────────────┐
                  │       Gateway         │
                  │   (control plane)     │
                  │  ws://127.0.0.1:18789 │
                  └───────────┬───────────┘
                              |
              ┌───────────────┼───────────────┐
              |               |               |
         Pi agent (RPC)    CLI tools     macOS/iOS/Android
                                            nodes

The Gateway connects to an LLM provides and routes messages between your channels and the AI agent. The actual inference happens in the cloud, so the device running the Gateway doesn’t need much compute power — it just orchestrates everything.

Key components

  • Gateway — The brain. Manages sessions, channels, tools, events, cron jobs, webhooks, and hosts the Control UI dashboard.
  • Agent — The AI runtime. Runs in RPC mode, handling tool calls and streaming responses from the LLM provider.
  • Channels — A multi-channel inbox. OpenClaw connects to WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage (via BlueBubbles), Microsoft Teams, Matrix, and a built-in WebChat.
  • Skills — A plugin system. The agent can discover, install, and even write its own skills. Skills are defined as markdown files in your workspace, and there’s a community registry called ClawHub.
  • Nodes — Device-local capabilities like camera access, screen recording, location, and system notifications.
  • Browser control — A managed Chromium instance that the agent controls through the Chrome DevTools Protocol.

What can it actually do?

Based on what people have reported using it for:

  • Managing calendars, email, reminders, and documents
  • Writing and deploying code — websites, APIs, CLI tools — from a chat message
  • Running shell commands, installing software, opening browsers
  • Controlling smart home devices through Home Assistant
  • Drafting emails, unsubscribing from mailing lists, handling insurance correspondence
  • Running cron jobs, background monitoring, and proactive check-ins (“heartbeats”)
  • Writing its own new skills and hot-reloading them
  • Voice interaction using ElevenLabs for text-to-speech and Whisper for speech-to-text
  • Coordinating multiple agent instances across sessions
  • Interfacing with hardware — cameras, sensors, NeoPixels — especially on a Raspberry Pi

Timeline

  • January 2026 — Initial release. Goes viral almost immediately.
  • Late January / Early February 2026 — Community forms on Discord. ClawHub skill registry launches. Rapid development cycle with stable, beta, and dev release channels.
  • February 2026 — Adafruit publishes a Raspberry Pi 5 deployment guide. Community members build Pi Zero implementations. GitHub stars surpass 221k. VirusTotal partnership announced for skill security scanning. Companion apps available for macOS, iOS, and Android.

Running it on my Raspberry Pi

This is the part I actually wanted to write about. The Raspberry Pi 5 with 8GB of RAM is the recommended configuration. Since the heavy computation is offloaded to cloud LLM providers, the Pi only needs to run the Gateway — which is well within the Pi 5’s reach.

What you need

  • Raspberry Pi 5 (8GB) with a power supply and Raspberry Pi OS 64-bit
  • An Anthropic API key or a Claude Pro/Max subscription
  • Docker and Docker Compose v2 installed on the Pi
  • A messaging channel to talk to it through (Telegram is the quickest to set up)

Optional hardware

The Adafruit guide covers some interesting hardware additions if you want to go beyond a headless box:

  • PiTFT 2.8" display (320×240) — A small resistive touchscreen HAT that plugs directly onto the Pi’s GPIO header. At 320×240 pixels it’s not for watching video, but it’s ideal for a status dashboard showing the agent’s current state, active sessions, or recent messages — no external monitor required.
  • BME680 sensor — A compact I²C sensor from Bosch that measures temperature, humidity, barometric pressure, and volatile organic compounds (VOC) in one package. With this attached, the agent can answer questions like “what’s the air quality in the room right now?” or trigger automations when conditions change.
  • USB camera — Gives the agent eyes. OpenClaw can capture still frames or short clips on demand and pass them to a vision-capable LLM. Useful for monitoring a physical space, reading a label, or checking whether a plant needs watering.
  • NeoPixels — Individually addressable RGB LEDs (Adafruit’s brand for WS2812B-compatible strips and rings). They’re wired to a GPIO pin and controlled in software, so the agent can use them as a visual notification system — flash green when a task completes, pulse red on an error, and so on.
  • eSpeak / Whisper — eSpeak is a lightweight text-to-speech engine that runs entirely on-device and lets the agent read its replies aloud through a speaker. Whisper (OpenAI’s speech recognition model) goes the other direction: it transcribes your voice input so you can talk to the agent without typing. Together they turn the Pi into a voice-first assistant.

My deployment approach

I containerised OpenClaw with Docker so the Pi never has to compile anything itself. The image is built on my Mac with docker buildx for multi-architecture support (ARM64 for the Pi, AMD64 for everything else), pushed to DockerHub, and pulled on the Pi.

The build is a standard two-stage Dockerfile: a node:22-bookworm builder that clones openclaw/openclaw, runs pnpm install / pnpm build, and builds the UI; and a node:22-bookworm-slim runtime stage that copies over dist, node_modules, ui, skills, extensions, and packages and starts the Gateway on port 8084.

The push step is a one-liner:

docker buildx build \
  --platform linux/arm64,linux/amd64 \
  -t docker.io/gonzalomg0/openclaw:latest \
  --push .

On the Pi, everything is orchestrated by docker compose. Two services share the same image — openclaw-gateway runs as the long-lived daemon, and openclaw-cli is a one-shot entrypoint for onboarding, adding channels, and running ad-hoc commands. Both mount ~/.openclaw and ~/.openclaw/workspace from the host so configuration and state survive container restarts and image updates.

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    environment:
      HOME: /home/node
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-8084}:8084"
      - "${OPENCLAW_BRIDGE_PORT:-8085}:8085"
    init: true
    restart: unless-stopped

Bringing it up the first time looks like this:

mkdir -p ~/.openclaw/workspace
docker compose pull openclaw-gateway
docker compose run --rm openclaw-cli onboard --no-install-daemon
docker compose up -d openclaw-gateway

Then the Control UI is reachable at http://<PI_IP>:8084/.

The Pi sits behind a Cloudflare tunnel, so I don’t expose SSH to the open internet. Copying files and shelling in goes through the tunnel host with ssh -J / scp -J.

Adding channels is a one-liner against the CLI service:

# Telegram — paste the BotFather token
docker compose run --rm openclaw-cli channels add --channel telegram --token "<BOT_TOKEN>"

# WhatsApp — QR-code pairing flow
docker compose run --rm openclaw-cli channels login

The full setup and configuration files are in this repository: github.com/gonzalo-munillag/openclaw_instance.

Enabling Claude “extra usage”

If you’re on a Claude Pro or Max subscription rather than paying per-token via the API, OpenClaw can authenticate against your subscription instead of an API key. That’s significantly cheaper for an always-on assistant that may chat with you dozens of times a day.

Out of the box your subscription gives you the standard plan quota. Once you’ve burned through it on a given window, the Gateway will start hitting rate limits and the agent will go quiet at the worst possible moment. The fix is to enable extra usage on the subscription — Anthropic’s pay-as-you-go top-up that kicks in when the included quota is exhausted, so the assistant degrades to “still works, costs a little extra” instead of “fails until the window resets.”

You enable it from the Claude dashboard under Settings → Billing → Usage, where there’s a toggle for extra usage with a configurable spending cap. With that turned on, the Pi-hosted Gateway never has a hard ceiling during normal use, and you still get a billing alert before anything runaway happens. For a personal assistant that schedules cron jobs and heartbeats, that single toggle is the difference between “works most of the time” and “actually reliable.”

A note on security

This is worth saying clearly: running an LLM-powered agent with shell access on a device carries real risk. Inbound messages from chat channels are untrusted input, and prompt injection is a genuine concern. The agent can run arbitrary commands and access anything available to its user account. The OpenClaw documentation has a security guide that is worth reading carefully before exposing this to any external channels — and putting the Pi behind something like a Cloudflare tunnel rather than port-forwarding from your router is a good baseline.

Resources

Glossary

WebSocket — A persistent, full-duplex communication channel over a single TCP connection. Unlike plain HTTP, where the client always initiates a request and the server replies once, a WebSocket connection stays open so either side can send data at any time. OpenClaw’s Gateway uses it so the agent can push a message to you the moment it finishes a task, without you having to poll.

Webhook — An HTTP callback: you register a URL with an external service (say, GitHub or a payment provider), and that service sends a POST request to your URL whenever a relevant event happens. The Gateway can expose webhook endpoints so external systems can trigger agent actions directly — “when a new GitHub issue is opened, summarise it and post it to Telegram.”

RPC (Remote Procedure Call) — A pattern where one process calls a function that executes in a different process (or on a different machine) as if it were a local call. OpenClaw’s Agent runs in RPC mode: the Gateway sends it a “run this tool call” instruction and waits for the result, abstracting away the fact that the Agent might be running in a separate container or on a different device.

One-shot entrypoint — A container configuration where the container is meant to run a single command to completion and then exit, rather than stay alive as a daemon. The openclaw-cli service in the compose file works this way: you invoke it with docker compose run --rm openclaw-cli <command>, it does its job (onboarding, adding a channel, etc.), and the container is removed. No persistent process, no port bindings.

Control plane — The part of a system responsible for configuration, coordination, and routing — as opposed to the data plane, which carries the actual payload. The Gateway is OpenClaw’s control plane: it decides which channel a message came from, which agent session should handle it, which tools are available, and where the reply should go.

Claude DevTools Protocol (CDP) — A debugging and automation protocol built into Chromium-based browsers. It lets external programs inspect the DOM, intercept network requests, take screenshots, click elements, and execute JavaScript — all over a local WebSocket. OpenClaw uses it to give the agent full control of a managed browser instance without needing a UI of its own.

Docker Buildx — A Docker CLI plugin that extends the standard docker build command with support for multi-platform builds (e.g. building an ARM64 image on an x86 Mac) and more advanced caching and output options. The --platform linux/arm64,linux/amd64 flag tells it to produce a single manifest that works on both the Raspberry Pi and standard Intel/AMD machines.

Cloudflare Tunnel — A service that creates an outbound-only connection from your device to Cloudflare’s edge network, then lets Cloudflare route inbound traffic to it. Because the connection is initiated outward, you never need to open ports on your router or expose your home IP. SSH over a Cloudflare tunnel (ssh pi-ssh.gonzalo-mg.com) looks like a normal SSH connection to the client but never touches the Pi’s public IP directly.

HAT (Hardware Attached on Top) — A standard form-factor add-on board for the Raspberry Pi that connects via the 40-pin GPIO header. A compliant HAT includes an EEPROM chip that lets the Pi auto-configure the board on boot.

I²C (Inter-Integrated Circuit) — A two-wire serial communication protocol (clock + data) used to connect low-speed peripherals like sensors to a microcontroller or single-board computer. The BME680 uses I²C, so it only needs four wires to the Pi: power, ground, clock (SCL), and data (SDA).

GPIO (General-Purpose Input/Output) — The row of programmable pins on a Raspberry Pi that can be used to read signals from sensors or send signals to actuators (LEDs, motors, relays). NeoPixels and many other peripherals are controlled through GPIO.

WS2812B — The LED driver IC inside most NeoPixel products. Each chip controls one RGB LED and passes the data signal along a chain, so you can address hundreds of LEDs using a single GPIO pin and a timed serial protocol.

VOC (Volatile Organic Compound) — Organic chemicals that easily evaporate at room temperature. Many common household products (paints, cleaning agents, adhesives) emit VOCs. High VOC levels indoors are often correlated with reduced air quality, which is why the BME680 includes a VOC index alongside temperature and humidity.

pnpm — A fast, disk-efficient Node.js package manager. Unlike npm, it stores packages once in a central content-addressable store and hard-links them into each project’s node_modules, saving both disk space and install time. OpenClaw uses it as its package manager.

ARM64 / AArch64 — The 64-bit instruction set architecture used by Raspberry Pi 4 and 5 chips (and Apple Silicon Macs). Most cloud servers and desktop computers run x86-64 (AMD64) instead, which is why a multi-platform Docker build is needed to produce an image that runs on both.

GÖD'S GATE — Buy on Amazon