OpenClaw Docker: Schritt-für-Schritt Anleitung zur Installation und Einrichtung

OpenClaw ist ein quelloffenes Framework von Phioranex, das KI-Agenten in isolierten Sandbox-Umgebungen ausführt. Ein eingebautes Gateway koordiniert HTTPS-Anfragen zwischen dem Host-System und den einzelnen Containern. Docker macht das Setup reproduzierbar: Keine manuell verwalteten Node-Abhängigkeiten, keine Versionskonflikte, saubere Trennung zwischen Entwicklungs- und Produktionsumgebung.

Dieser Leitfaden führt dich vollständig durch Installation, Gateway-Konfiguration, Sandbox-Setup und die häufigsten Fehlerfälle. Vorausgesetzt sind Docker-Grundkenntnisse; tiefer gehende Systemadministration ist nicht nötig.

Was ist OpenClaw und für wen ist Docker die richtige Wahl?

OpenClaw stellt eine Gateway-Schicht bereit, über die KI-Agenten mit externen Diensten kommunizieren. Das Gateway nimmt HTTPS-Anfragen entgegen, leitet sie an die zuständige Agent-Sandbox weiter und gibt Antworten zurück. Phioranex hat das System so gebaut, dass jede Sandbox vollständig isoliert läuft – ein Absturz in einem Container zieht andere nicht mit.

Docker ist der empfohlene Installationsweg, wenn du OpenClaw auf mehreren Maschinen identisch deployen willst. Das offizielle Image enthält alle Abhängigkeiten inklusive Node.js; auf dem Host muss nur Docker selbst laufen.

Wer direkt am Quellcode mitentwickeln möchte, kann OpenClaw auch nativ aus dem Repository starten. Für Produktions-Deployments und Teams ist der container-basierte Weg jedoch wartbarer und weniger fehleranfällig. Mehr zum Ökosystem rund um quelloffene KI-Assistenten findest du im OpenClaude-Leitfaden.

Voraussetzungen vor der Installation

Bevor du das Docker-Image ziehst, prüfe die folgende Checkliste. Fehlende Voraussetzungen führen später zu schwer diagnostizierbaren Fehlern.

• Docker Engine: Version 24.0 oder neuer, prüfbar mit docker --version.
• Docker Compose: Version 2.20+ als Plugin (in Docker Desktop integriert; auf Linux separat installieren).
• Freie Ports: Port 3000 für das Gateway und Port 8080 für die Sandbox-API dürfen auf dem Host nicht belegt sein.
• TLS-Zertifikat: Für Produktionsumgebungen brauchst du ein gültiges HTTPS-Zertifikat. Für lokale Tests genügt ein selbstsigniertes.
• RAM: Mindestens 2 GB für das Gateway, 512 MB pro zusätzlicher Sandbox-Instanz.
• Netzwerkzugang: Der Host muss Docker Hub (registry-1.docker.io) über Port 443 erreichen können.

Prüfe Docker-Version und Compose-Plugin in einem Schritt:

docker --version
docker compose version

Nutzt du noch ein älteres Binary-basiertes Docker Compose, ersetze docker compose in allen folgenden Befehlen durch docker-compose.

OpenClaw Docker Image installieren

Das offizielle Image liegt auf Docker Hub unter dem Namespace phioranex. Ziehe die aktuelle stabile Version:

docker pull phioranex/openclaw:latest

Für Produktionsumgebungen pinne ein konkretes Tag, damit Updates nicht unbeabsichtigt einspielen:

docker pull phioranex/openclaw:1.4.2

Kontrolliere, ob das Image korrekt in der lokalen Registry gelandet ist:

docker images | grep openclaw

Starte einen Schnelltest-Container, um das Image zu verifizieren:

docker run --rm phioranex/openclaw:latest openclaw --version

Die Ausgabe gibt Versionsnummer und Build-Timestamp aus. Erscheint stattdessen ein Fehler, leere den Docker-Cache und wiederhole den Pull:

docker system prune -f
docker pull phioranex/openclaw:latest

Containerisiertes Gateway einrichten mit Docker Compose

Docker Compose startet Gateway und Sandbox als zusammenhängenden Stack. Lege im Projektverzeichnis eine Datei docker-compose.yml an und kopiere den folgenden Block direkt:

services:
  gateway:
    image: phioranex/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - OPENCLAW_HOST=0.0.0.0
      - OPENCLAW_PORT=3000
      - OPENCLAW_TLS_CERT=/certs/server.crt
      - OPENCLAW_TLS_KEY=/certs/server.key
    volumes:
      - ./certs:/certs:ro
      - ./config:/app/config:ro
    networks:
      - openclaw-net

  sandbox:
    image: phioranex/openclaw:latest
    container_name: openclaw-sandbox
    restart: unless-stopped
    command: sandbox
    environment:
      - GATEWAY_URL=https://gateway:3000
      - SANDBOX_PORT=8080
    ports:
      - "8080:8080"
    depends_on:
      - gateway
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

Starte den kompletten Stack im Hintergrund:

docker compose up -d

Prüfe, ob beide Container den Status Up zeigen:

docker compose ps

Gateway-Logs streamst du mit:

docker compose logs -f gateway

Das Gateway lauscht jetzt auf Port 3000 und akzeptiert HTTPS-Verbindungen. Die Sandbox kommuniziert intern über das openclaw-net-Netzwerk mit dem Gateway; Port 8080 nach außen öffnen ist nur für direkte API-Tests nötig.

Die folgende Tabelle zeigt die wichtigsten Umgebungsvariablen im Überblick:

Agent Sandbox konfigurieren und starten

Die Sandbox-Konfiguration liegt im Container unter /app/config/sandbox.json. Mounte eine eigene Datei über das Volume im Compose-File:

./config/sandbox.json:/app/config/sandbox.json:ro

Eine funktionale Minimalkonfiguration für den ersten Start:

{
  "agents": [
    {
      "id": "agent-01",
      "model": "claude-3-5-sonnet",
      "maxTokens": 4096,
      "tools": ["web_search", "code_execution"]
    }
  ],
  "rateLimits": {
    "requestsPerMinute": 60,
    "tokensPerDay": 1000000
  }
}

Nach jeder Konfigurationsänderung reicht ein Neustart der Sandbox – das Gateway bleibt dabei oben:

docker compose restart sandbox

Eigene Node-Plugins bindest du ein, indem du ein angepasstes Dockerfile auf dem Basis-Image aufbaust:

FROM phioranex/openclaw:latest
WORKDIR /app
COPY plugins/package.json ./plugins/
RUN cd plugins && npm install --production

So bleibt das Basis-Image unberührt, und du kannst jederzeit auf neue Releases aktualisieren. Drei parallele Sandbox-Instanzen startest du mit:

docker compose up -d --scale sandbox=3

Das Gateway verteilt Anfragen automatisch auf alle laufenden Sandbox-Container. Für komplexere Automatisierungen lässt sich OpenClaw gut in bestehende Workflow-Automation-Pipelines integrieren.

Häufige Fehler und deren Lösungen

Connection refused auf Port 3000

Das Gateway hat noch nicht gestartet oder der TLS-Pfad stimmt nicht. Prüfe, ob die Zertifikatsdateien vorhanden und lesbar sind:

ls -la ./certs/

Die Dateien brauchen mindestens Leserechte für den Docker-Prozess (chmod 644 ./certs/*.crt, chmod 600 ./certs/*.key).

Sandbox verbindet sich nicht mit Gateway

Die Variable GATEWAY_URL muss den Container-Namen gateway verwenden, nicht localhost. Container im selben Docker-Netzwerk kommunizieren ausschließlich über Service-Namen.

Image lässt sich nicht pullen

Docker Hub setzt Rate-Limits für anonyme Pulls. Logge dich mit deinem Account ein:

docker login

Alternativ konfigurierst du einen internen Registry-Mirror in der Docker-Daemon-Konfiguration.

Out of Memory beim Starten mehrerer Sandboxen

Setze explizite Memory-Limits im Compose-File, damit keine Sandbox den Host vollständig belegt:

deploy:
  resources:
    limits:
      memory: 1g
    reservations:
      memory: 512m

Node-Module fehlen zur Laufzeit

Wenn du Plugins ohne eigenes Dockerfile einbindest, musst du npm install als Teil des Entrypoints ausführen:

entrypoint: ["sh", "-c", "npm install --prefix /app/plugins && openclaw sandbox"]

Lizenz

Phioranex veröffentlicht OpenClaw unter der MIT-Lizenz. Du kannst das Projekt kostenlos nutzen, modifizieren und in kommerzielle Produkte integrieren, solange der Copyright-Hinweis in allen Kopien erhalten bleibt. Das vollständige Lizenzdokument liegt im Repository unter LICENSE.

Für Teams, die OpenClaw in produktionskritischer Infrastruktur betreiben, empfiehlt Phioranex, die Release-Notes aktiv zu verfolgen und Security-Patches innerhalb von 48 Stunden einzuspielen. Das Image-Tag latest aktualisiert sich bei jedem docker pull automatisch auf den neuesten Stable-Build.

Wenn du OpenClaw als Teil einer KI-Agentur-Infrastruktur einsetzt, kann ein AI-Consulting-Gespräch helfen, den richtigen Deployment-Ansatz für deine Anforderungen zu finden.

FAQ

Brauche ich ein Docker-Hub-Konto, um OpenClaw zu installieren?

Für den initialen Pull reicht ein anonymes Konto. Docker Hub limitiert anonyme Pulls jedoch auf 100 Anfragen pro 6 Stunden pro IP. Für Teams oder CI/CD-Pipelines ist ein kostenloses Docker-Hub-Konto empfehlenswert, das das Limit auf 200 Pulls pro 6 Stunden anhebt.

Kann ich OpenClaw ohne Docker Compose betreiben?

Ja. Du kannst Gateway und Sandbox als einzelne Container mit docker run starten. Für produktive Setups ist Docker Compose jedoch klarer, weil Service-Abhängigkeiten, Netzwerke und Volumes deklarativ beschrieben sind.

Wie aktualisiere ich OpenClaw auf eine neue Version?

Ziehe das neue Image, dann starte den Stack neu:

docker compose pull
docker compose up -d

Docker Compose ersetzt dabei nur Container, deren Image sich verändert hat. Konfigurationsdateien in gemounteten Volumes bleiben unberührt.

Unterstützt OpenClaw ARM-Architekturen wie Apple Silicon?

Phioranex veröffentlicht Multi-Platform-Images für linux/amd64 und linux/arm64. Auf Apple-Silicon-Macs mit Docker Desktop läuft das Image nativ ohne Emulation. Auf ARM-basierten Cloud-Instanzen (z. B. AWS Graviton) funktioniert das gleiche Image-Tag ohne Anpassung.

Wie sichere ich das Gateway für den Produktionseinsatz ab?

Nutze ausschließlich HTTPS mit einem von einer CA signierten Zertifikat, schränke den Zugriff auf Port 3000 über Firewall-Regeln auf bekannte IP-Bereiche ein und setze NODE_ENV=production, damit das Gateway detaillierte Fehlermeldungen nicht nach außen gibt. Für zusätzliche Absicherung bietet sich ein Reverse Proxy wie nginx mit Rate-Limiting vor dem OpenClaw-Gateway an.

Lässt sich OpenClaw in bestehende CI/CD-Pipelines integrieren?

Ja. Da das Setup vollständig über Umgebungsvariablen und gemountete Konfigurationsdateien steuerbar ist, lässt sich OpenClaw in GitHub Actions, GitLab CI oder Jenkins-Pipelines einbinden. Das Image lässt sich auch in eine private Container-Registry spiegeln, um Pipeline-Abhängigkeiten von Docker Hub zu vermeiden.

—