OpenClaw Docker-Einrichtung - Detailliert

Docker ist der empfohlene Weg, um OpenClaw zu betreiben. Es bietet Isolation, vereinfacht die Abhngigkeitsverwaltung und macht das Aktualisieren oder Zurcksetzen von Versionen einfach. Dieser Guide deckt alles ab, vom automatisierten Setup-Skript ber manuelle Installation bis Security-Hardening.

Voraussetzungen

Bevor du beginnst, stelle sicher, dass dein System diese Anforderungen erfllt:

• Docker Desktop (oder Docker Engine) und Docker Compose v2
• Betriebssystem: Ubuntu Server wird fr VPS-Installationen empfohlen. Fr Windows bietet WSL2 eine stabilere Erfahrung.
• Speicher: Mindestens 2GB RAM fr den Image-Build-Prozess. Ohne dies kann der pnpm install-Schritt wegen out-of-memory-Fehlern fehlschlagen.
• Festplattenplatz: Ausreichend fr Docker-Images, Logs und deinen Workspace.
• Git: Zum Klonen des OpenClaw-Repositories.
• SSH: Fr VPS-Installationen, nutze SSH mit Schlsseln fr eine sichere Verbindung.

Automatisches Setup (Empfohlen)

Der schnellste Weg, OpenClaw mit Docker zum Laufen zu bringen, ist das offizielle docker-setup.sh-Skript:

Schritt 1: Repository klonen

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Schritt 2: Setup-Skript ausfhren

./docker-setup.sh

Dieses Skript fhrt folgende Aktionen durch:

• Erstellt das Docker-Image lokal (oder zieht ein vorgefertigtes Image, wenn OPENCLAW_IMAGE gesetzt ist)
• Startet einen interaktiven Onboarding-Assistenten in einem Container
• Fragt nach deinen Provider-API-Schlsseln
• Generiert ein Gateway-Token und speichert es in einer .env-Datei
• Erstellt bentigte Volume-Verzeichnisse (~/.openclaw fr Konfiguration und ~/openclaw/workspace fr Dateien)
• Startet das OpenClaw-Gateway ber Docker Compose

Onboarding-Entscheidungen

Whrend des Onboarding-Prozesses triffst du mehrere wichtige Entscheidungen:

• Onboarding-Modus: Whle 'manual'
• Was einrichten: Whle 'Local gateway (this machine)'
• Modell-Anbieter: Whle deinen gewnschten KI-Anbieter (OpenAI, Anthropic, Google). Bei OpenAI Codex mit ChatGPT OAuth musst du möglicherweise eine Redirect-URL aus dem Browser zurck in den Assistenten kopieren.

Beheben von Speicherproblemen

Wenn der Build auf einem VPS mit wenig Speicher fehlschlgt, erstelle zuerst eine Swap-Datei:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Zugang zur Weboberflche

Sobald das Setup-Skript abgeschlossen ist, sollte das OpenClaw-Gateway laufen. Die Web-Control-UI ist erreichbar unter:

http://127.0.0.1:18789/

Du musst das generierte Gateway-Token in die Einstellungen einfgen, um auf die Oberflche zuzugreifen.

Den CLI-Container nutzen

OpenClaw bietet einen separaten CLI-Container (openclaw-cli) fr administrative Befehle. Fhre Befehle ber docker compose vom Repository-Root aus:

# Gateway-Status prfen
docker compose run --rm openclaw-cli status

# Messaging-Kanle konfigurieren
docker compose run --rm openclaw-cli channels add telegram

Manuelle Docker-Installation

Wenn du jeden Schritt manuell statt mit dem docker-setup.sh-Skript ausfhren mchtest:

Schritt 1: Docker-Image erstellen

docker build -t openclaw:local -f Dockerfile .

Schritt 2: Onboarding ausfhren und Gateway starten

Fhre das Onboarding und die Konfigurationsschreibungen direkt ber den openclaw-gateway-Container aus, bevor du den vollstndigen Docker Compose Stack hochfhrst.

Schritt 3: Docker Compose starten

docker compose up -d

Hufiges Troubleshooting

Installation hngt oder Unauthorized-Dashboard

Wenn die Installation nach dem Onboarding einzufrieren scheint oder das Dashboard einen Unauthorized-Fehler anzeigt:

• Stelle sicher, dass Docker Desktop luft
• Wenn es hngt, drcke Ctrl C im Terminal
• Manuell ausfhren: docker compose up -d openclaw-gateway
• Warte ein paar Minuten und aktualisiere den Browser
• Fr den hngenden Zustand, navigiere zu ~/.openclaw/pending.json und ndre "silent": false zu "silent": true

Gateway-Service startet nicht

Wenn das Gateway nicht startet oder du "connection refused" siehst:

• Prfe Docker Desktop, um zu besttigen, dass der Container luft
• berprfe Logs: docker logs openclaw --tail 50
• Prfe auf Port-Konflikte: sudo lsof -i :3000

Konfigurationsprobleme

Wenn OpenClaw wegen fehlender Umgebungsvariablen oder korrupter Config nicht startet:

• Prfe bentigte Env-Vars: docker exec openclaw env | grep -E "API_KEY|DATABASE|PORT"
• Validiere Config-Syntax: docker exec openclaw cat /app/config.yml | python3 -c "import sys,yaml; yaml.safe_load(sys.stdin)"
• Stelle sicher, dass du ein beschreibbares Host-Verzeichnis fr /app/data einbindest
• Verifiziere UID/GID des eingebundenen Verzeichnisses stimmt mit dem Container-User berein

Bot verbunden aber reagiert nicht

Wenn das Dashboard zeigt, dass der Bot verbunden ist, aber Nachrichten keine Antwort erhalten:

• Prfe, ob Nachrichten empfangen werden: docker logs openclaw --tail 100 | grep -i "incoming\|received\|message"
• Verifiziere KI-API-Konnektivitt und prfe auf abgelaufene oder rate-limited API-Keys
• Starte: docker exec openclaw openclaw doctor --fix
• Neustart: docker compose -p openclaw restart

Security-Hardening fr ffentliche Installationen

Das Standard-Docker-Setup ist fr Testen und Entwicklung gedacht. Fr VPS- oder ffentliche Installationen ist Security-Hardening entscheidend:

• An localhost binden: Konfiguriere die Weboberflche, um an 127.0.0.1:18789 statt 0.0.0.0 zu binden
• Reverse Proxy nutzen: Richte Nginx mit Authentifizierung und HTTPS fr externen Zugriff ein
• .env-Berechtigungen einschrnken: chmod 600 .env
• Secrets nie committen: Fge .env zu .gitignore hinzu

Docker-Sandboxing (Optional)

Fr strkere Isolation, besonders beim Ausfhren von Agenten, die Code ausfhren, consider Docker Sandboxes. Dies fhrt OpenClaw in isolierten Micro-VMs mit einem konfigurierbaren Netzwerk-Proxy aus.

Mit Docker Sandboxes knnen Agenten keine beliebigen Internet-Hosts verbinden, und API-Keys knnen sicher injiziert werden ohne Exposition.