OpenClaw Docker Setup op Raspberry Pi - Complete Gids 2025

U bent waarschijnlijk tegen dezelfde Raspberry Pi-muur aangelopen als ik: containers die niet opstarten na een herstart, mysterieuze ARM-imageproblemen, en een "gateway" die u per ongeluk aan het internet heeft blootgesteld. Deze handleiding zet OpenClaw (voorheen Clawdbot/MoltBot) op met Docker Compose op Raspberry Pi, zodat het herstarts overleeft, netjes upgradet, en standaard privé blijft.

Vereisten (houd het saai en correct)

• Raspberry Pi OS 64-bit (Bookworm aanbevolen), SSH-toegang, en sudo
• Raspberry Pi 4/5 met minimaal 4 GB RAM (8 GB loopt soepeler), SSD sterk aanbevolen voor 24/7
• Docker Engine + Docker Compose plugin (installeren we hieronder)
• Eén AI-providersleutel: OPENAI_API_KEY of ANTHROPIC_API_KEY
• Een plan voor privétoegang: alleen LAN, VPN, of tunnel (stel de gateway niet bloot)

Stap 1: Bereid de Raspberry Pi voor op always-on Docker

bashCopy
sudo apt update
sudo apt -y full-upgrade
sudo reboot

Uit mijn ervaring voorkomt dit veel van de "willekeurige" containerfalen: oude kernels, verkeerd geconfigureerde cgroups, verouderde libraries, die hele rotzooi. Raspberry Pi OS-updates bevatten ook netwerk- en bestandssysteemfixes die veel uitmaken op always-on apparaten.

Na de herstart, bevestig dat u op 64-bit userspace draait:

bashCopy
uname -m
getconf LONG_BIT

Als uname -m aarch64 toont en LONG_BIT 64 is, bent u klaar. Zo niet, schakel dan over naar Raspberry Pi OS 64-bit voordat u verdergaat. Multi-arch images en geheugengedrag zijn gewoon beter (en u bespaart uzelf later tijd).

Optioneel maar de moeite waard: verminder SD-kaartpijn

bashCopy
sudo apt -y install smartmontools
lsblk

OpenClaw 24/7 draaien schrijft state en logs. SSD's gaan hier veel beter mee om dan SD-kaarten. Als u een SD moet gebruiken, houd logs klein en roteer ze (doen we later via Docker logging-opties).

Stap 2: Installeer Docker en Docker Compose op Raspberry Pi OS

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

Het get.docker.com-script installeert een Docker-build die meestal goed werkt met Raspberry Pi OS. Uw gebruiker toevoegen aan de docker-groep betekent dat u niet overal sudo hoeft te gebruiken, wat ook helpt vreemde permissie-verrassingen op bind mounts te voorkomen.

Installeer de Compose plugin en basis tooling:

bashCopy
sudo apt -y install docker-compose-plugin git jq
docker --version
docker compose version

Als docker compose version een versie print, heeft u de moderne Compose plugin (wat u wilt, niet de oude docker-compose Python binary).

Stap 3: Maak een schone OpenClaw-werkdirectory

bashCopy
mkdir -p ~/openclaw
cd ~/openclaw

Niets bijzonders hier. Alles in één map houden maakt upgrades en backups pijnloos. Het doel is een reproduceerbare stack: Compose-bestand, .env, en een persistente data-directory.

Stap 4: Schrijf een Docker Compose-bestand dat Pi-veilig en upgrade-vriendelijk is

Maak docker-compose.yml:

yamlCopy
services:
  openclaw:
    image: openclawai/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    
    # Standaard alleen LAN-toegang. Verander alleen als u een VPN/tunnel/reverse proxy heeft.
    ports:
      - "127.0.0.1:18789:18789"
    
    env_file:
      - .env
    
    volumes:
      - ./data:/var/lib/openclaw
      - ./logs:/var/log/openclaw
    
    # Voorkomt dat containerlogs uw SD/SSD opvreten over tijd
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    
    # Helpt op kleine apparaten: voorkomt dat weglopend geheugen de Pi doodt
    mem_limit: 1500m

Deze Compose-setup doet drie dingen die, naar mijn ervaring, de meest voorkomende Raspberry Pi-falen voorkomen.

18789 binden aan 127.0.0.1 houdt de gateway privé (sla dit niet over). Het blootstellen aan uw WAN is de snelste manier om misbruikt te worden, en de 2026 beveiligingsupdates zijn om een reden gebeurd. De bind mounts ./data en ./logs zorgen dat state container-rebuilds en image-updates overleeft. En logrotatie voorkomt langzame opslagdood door een miljoen kleine schrijfacties.

Wat als de image-naam anders is in uw documentatie?

Sommige handleidingen verwijzen naar oudere Clawdbot/MoltBot image-namen. Als de pull faalt, check de officiële Docker deployment doc en update de image:-regel dienovereenkomstig: Docker Deployment Guide - Clawdbot AI. Vergelijk ook met de Compose-aanpak die hier beschreven staat: Running OpenClaw in Docker.

Stap 5: Voeg uw env bestand toe met tokens en AI-sleutels

Maak .env:

bashCopy
cd ~/openclaw
nano .env

Plak en bewerk:

bashCopy
## OpenClaw gateway-instellingen
OPENCLAW_GATEWAY_PORT=18789

# Genereer een sterke token. Hergebruik geen wachtwoorden.
OPENCLAW_GATEWAY_TOKEN=[PLAK_LANGE_WILLEKEURIGE_TOKEN]

# Kies één provider (of beide als ondersteund door uw build)
OPENAI_API_KEY=[UW_OPENAI_SLEUTEL]
ANTHROPIC_API_KEY=[UW_ANTHROPIC_SLEUTEL]

# Optioneel: houd de bot voorspelbaar op een klein apparaat
OPENCLAW_MAX_CONCURRENCY=2
OPENCLAW_LOG_LEVEL=info

Tokens en API-sleutels horen in .env omdat het secrets uit uw Compose-bestand houdt en upgrades veiliger maakt. Dan wanneer u een backup maakt van docker-compose.yml, kunt u .env weglaten (of in een wachtwoordmanager stoppen).

Genereer een sterke token:

bashCopy
openssl rand -hex 32

Plak die output in OPENCLAW_GATEWAY_TOKEN. Eerlijk gezegd, een lange willekeurige token is belangrijker dan mensen verwachten omdat gateways geraakt worden door geautomatiseerde scanners zelfs op thuisnetwerken (ja, echt).

Stap 6: Start OpenClaw met Docker Compose

bashCopy
cd ~/openclaw
docker compose pull
docker compose up -d
docker compose ps

pull forceert een schone image-download voor ARM. up -d start het op de achtergrond. ps toont of de container gezond is of vast zit in herstarten.

Check logs onmiddellijk:

bashCopy
docker logs -n 200 openclaw

Als OpenClaw een onboarding wizard vereist, tonen de logs meestal de eerste URL om te openen, pairing codes, of ontbrekende omgevingsvariabelen. Los dat op voordat u verdergaat, omdat "het draait maar doet niets" bijna altijd onboarding- of token-gerelateerd is.

Stap 7: Benader de gateway veilig (standaard alleen LAN)

Vanaf de Raspberry Pi zelf:

bashCopy
curl -sS http://127.0.0.1:18789/ | head

Vanaf een andere machine op uw LAN heeft u twee veilige opties.

Optie A: SSH port forward (snelst, geen netwerkwijzigingen):

bashCopy
ssh -L 18789:127.0.0.1:18789 pi@[RASPBERRY_PI_IP]

Open dan dit lokaal:

bashCopy
http://127.0.0.1:18789

Optie B: bind alleen aan LAN IP (nog steeds privé, maar bereikbaar op LAN). Verander Compose ports: naar:

yamlCopy
ports:
  - "[RASPBERRY_PI_LAN_IP]:18789:18789"

SSH forwarding is meestal het minst foutgevoelig omdat het de service nooit blootstelt aan het hele subnet. LAN bind is prima als het netwerk vertrouwd en gesegmenteerd is (en u weet wat er nog meer op dat netwerk staat).

Stap 8: Maak upgrades voorspelbaar (en omkeerbaar)

Upgrade flow:

bashCopy
cd ~/openclaw
docker compose pull
docker compose up -d
docker image prune -f

Dit pullt het laatste image, maakt de container opnieuw, en verwijdert oude images om schijfruimte te besparen. Omdat state in ./data staat, wissen upgrades uw config of geschiedenis niet.

Voor een omkeerbare upgrade, pin een versietag in plaats van latest:

yamlCopy
image: openclawai/openclaw:2026.1.3

Pinnen is saai, wat precies is waarom het werkt. Op een Raspberry Pi die 24/7 draait, zijn verrassingswijzigingen een topveroorzaker van downtime.

Stap 9: Voeg basis host hardening toe die echt uitmaakt

Installeer en schakel een firewall in:

bashCopy
sudo apt -y install ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw enable
sudo ufw status verbose

Dit blokkeert inbound verkeer behalve SSH. Omdat OpenClaw gebonden is aan localhost in Compose, bent u al in redelijke vorm, maar een firewall helpt nog steeds als iemand later port bindings aanpast (toekomstige-u telt mee).

Voeg Fail2ban toe voor SSH brute-force lawaai:

bashCopy
sudo apt -y install fail2ban
sudo systemctl enable --now fail2ban
sudo fail2ban-client status

Deze twee stappen dekken het meest voorkomende thuis-Pi compromispad: blootgestelde SSH met zwakke credentials. Voor Docker beveiligingshouding en guardrails gelden dezelfde principes als in onze Claude Code 2026 Best Practices: Guardrails & Tests handleiding: beperk eerst toegangspaden, voeg dan automatisering toe.

Stap 10: Skills en extensies zonder uw Pi in een ruimteverwarmer te veranderen

Begin met een gecureerde lijst zodat u niet blind willekeurige packages installeert:

• VoltAgent/awesome-openclaw-skills

De praktische beperking op Raspberry Pi is niet "kan het draaien" maar "kan het draaien terwijl het responsief blijft." Skills die webpagina's scrapen, headless browsers draaien, of veel subprocessen spawnen zullen het apparaat uithongeren.

En hier is het ding: een goed patroon is OpenClaw op de Pi houden, maar zware tools offloaden naar een andere machine via SSH of HTTP. Denk aan de Pi als de always-on coördinator, niet de compute node.

Uw setup testen

Voer deze tests in volgorde uit. Ze vangen de echte falen: slechte mounts, slechte tokens, en kapotte netwerken.

Test 1: Container health en restarts

bashCopy
docker compose ps
docker inspect -f '{{.State.Status}} {{.State.Restarting}}' openclaw

Als het herstart, check logs en fix config eerst. Restart loops komen meestal van ontbrekende vereiste env vars of een permissie-mismatch op ./data.

Test 2: Persistentie over container-recreatie

bashCopy
cd ~/openclaw
docker compose down
docker compose up -d
ls -la ./data

Als ./data gevuld blijft, heeft u echte persistentie. Als het leeg is of onverwacht root-owned, fix permissies. Een veelvoorkomende fix:

bashCopy
sudo chown -R $USER:$USER ~/openclaw/data ~/openclaw/logs

Test 3: Port exposure is privé

bashCopy
ss -lntp | grep 18789 || true

Als u 0.0.0.0:18789 ziet, heeft u het blootgesteld. Zet het terug naar 127.0.0.1:18789 tenzij u een VPN of strikte reverse proxy auth heeft.

Test 4: AI provider key wordt gelezen

bashCopy
docker exec -it openclaw /bin/sh -lc 'env | egrep "OPENAI_API_KEY|ANTHROPIC_API_KEY|OPENCLAW_" | sed "s/=.*/=REDACTED/"'

Als sleutels ontbreken, wordt het .env-bestand niet geladen of heeft het formatproblemen. De meest voorkomende fout is spaties rond = of het kopiëren van smart quotes uit een notitie-app (ben daar geweest).

Problemen oplossen die echt gebeuren op Raspberry Pi

"no matching manifest for linux/arm/v7"

bashCopy
uname -m
docker pull openclawai/openclaw:latest

Als de Pi 32-bit is (armv7l), ondersteunen veel images het niet. Ga naar Raspberry Pi OS 64-bit. Als u al op 64-bit bent maar nog steeds faalt, is het image mogelijk niet multi-arch. Bevestig in de officiële Docker doc: Docker Deployment Guide - Clawdbot AI.

Container start, dan stopt onmiddellijk

bashCopy
docker logs -n 300 openclaw
docker inspect openclaw --format '{{json.State}}' | jq

Exit-on-start is meestal een van deze: ontbrekende gateway token, ontbrekende provider key, of een vereiste directory niet schrijfbaar. Fix .env eerst, verifieer dan ./data permissies.

"bind: address already in use" op poort 18789

bashCopy
sudo ss -lntp | grep 18789
docker compose down

Een ander proces gebruikt die poort al, of een vorige container draait nog. Stop de oude container. Als u poorten moet wijzigen, wijzig zowel de host port mapping als client URLs.

Pi wordt traag of niet-responsief na het inschakelen van verschillende skills

bashCopy
docker stats --no-stream
vcgencmd measure_temp

Wanneer RAM-druk toeslaat, gaat Linux swappen en voelt alles kapot. Verminder concurrency in .env, behoud mem_limit, en verwijder zware skills. Als u browser automation nodig heeft, draai het op een aparte box en roep het aan vanaf de Pi.

Gateway beveiligingszorgen na het lezen over 2026 incidenten

Lees de incident-gerichte guidance: OpenClaw Complete Guide 2026. De praktische conclusie is simpel: privé bind standaard, sterke token altijd, en vermijd "no auth" modes als u ze ziet in oude tutorials.

Docker-first op Pi: waarom teams standaardiseren op dit patroon

Docker Compose is populair hier omdat het herhaalbare deployments geeft met een kleine operationele oppervlakte. Dat is belangrijk op edge devices waar "fix it live" pijnlijk is (en meestal gebeurt op het slechtste moment).

Hier is hoe de trade-offs vergelijken voor Raspberry Pi deployments:

Big-company container patronen mappen verrassend goed naar een Pi. Netflix rapporteerde een 50% reductie in deployment-gerelateerde incidenten na het verplaatsen van services naar immutable container images met gestandaardiseerde pipelines (Netflix TechBlog referenties over meerdere posts). Stripe heeft beschreven hoe sterke isolatiegrenzen en herhaalbare deploys "works on my machine" drift in productiesystemen verminderen. Shopify heeft meerdere case studies gepubliceerd die tonen dat consistente build en release artifacts rollback tijd tijdens incidenten verminderen.

Dat zijn big-company voorbeelden, maar dezelfde mechanica geldt op een Raspberry Pi: minder snowflake dependencies, duidelijkere rollback, en state buiten de container gehouden.

Deployment Checklist

Begin hier (uw eerste stap)

Maak ~/openclaw/docker-compose.yml met 127.0.0.1:18789:18789 en een persistente ./data mount.

Quick wins (onmiddellijke impact)

• Genereer en stel OPENCLAW_GATEWAY_TOKEN in met openssl rand -hex 32, herstart dan met docker compose up -d.
• Bevestig dat u de gateway niet heeft blootgesteld: voer ss -lntp | grep 18789 uit en verifieer dat het bindt aan 127.0.0.1.

Deep dive (voor degenen die meer willen)

• Pin de image tag (voorbeeld 2026.1.3) en documenteer uw upgrade command sequence in een RUNBOOK.md.
• Voeg UFW + Fail2ban toe, test dan remote toegang via SSH port forwarding in plaats van poorten openen.

Nuttige Resources

• Running OpenClaw in Docker - Compose walkthrough met volumes en onboarding notities.
• Docker Deployment Guide - Clawdbot AI - Officiële Docker en Compose deployment referentie.
• OpenClaw Complete Guide 2026 - Beveiligingswijzigingen en operationele notities van 2026 releases.
• OpenClaw Complete Guide (Formerly Moltbot/ClawdBot) - Rebrand context, setup flow, en ecosysteem notities.
• VoltAgent/awesome-openclaw-skills - Gecureerde skills directory voor veiligere extensie discovery.

Slotgedachten

Een Raspberry Pi kan OpenClaw betrouwbaar draaien, maar alleen als de gateway privé blijft, state op persistente opslag leeft, en upgrades behandeld worden als een herhaalbaar proces. Docker Compose is de simpelste manier om die eigenschappen te krijgen zonder uw Pi in een fragiele snowflake te veranderen.

Zodra de basis stack stabiel is, voeg skills langzaam toe en offload zwaar werk naar andere machines in plaats van alles op de Pi te forceren. Laten we eerlijk zijn: een Pi die alles probeert te doen eindigt met niets goed doen.