Docker für dein Gateway nutzen

Hast du schon mal Stunden damit verbracht, einen Fehler zu suchen, der nur auf deinem Rechner auftritt? Unterschiedliche Umgebungen sind anstrengend und kosten Zeit. Docker hilft dir dabei, diese Unterschiede zu eliminieren, damit dein Gateway überall gleich läuft.

Ich empfehle dir Docker, wenn du Konsistenz in deinem Team sicherstellen willst. Es ist der beste Weg, um “funktioniert bei mir”-Probleme direkt zu vermeiden.

Voraussetzungen

• Docker (installiert und konfiguriert)
• Ein Gateway-Setup

Schnellstart

Docker ist in diesem Projekt optional. Du musst es nicht zwingend verwenden, um das Gateway zu betreiben. Folge diesen Schritten, wenn du dich für den Container-Weg entscheidest:

1. Einsatzzweck prüfen: Nutze Docker nur, wenn du ein containerisiertes Gateway benötigst.
2. Flow validieren: Verwende Docker, um den spezifischen Docker flow innerhalb deiner Umgebung zu testen.

Fehlerbehebung

Hier sind die Lösungen für bekannte Hürden aus der Dokumentation:

• Docker flow schlägt fehl: Überprüfe, ob du Docker wirklich benötigst. Da es optional ist, kannst du das Gateway auch ohne Container-Umgebung validieren.
• Gateway nicht erreichbar: Stelle sicher, dass du Docker nur einsetzt, wenn du explizit ein containerisiertes Gateway für deine Infrastruktur willst.

Du hast Fragen zu deiner Konfiguration? Frag den AI Setup Assistant.

Nächste Schritte

• Gateway Konfiguration
• Deployment Guide
• API Referenz
• CLI Übersicht

Jeder Entwickler kennt das: Du möchtest ein neues Tool testen, aber dein System nicht mit unzähligen Abhängigkeiten belasten. Manchmal willst du eine Umgebung, die du nach dem Experimentieren einfach löschen kannst, ohne Spuren zu hinterlassen.

Hier erfährst du, ob Docker für dein Setup mit OpenClaw sinnvoll ist oder ob du besser beim lokalen Workflow bleibst.

Voraussetzungen

Bevor du startest, stelle sicher, dass dein System bereit ist:

• Docker Desktop (oder Docker Engine) + Docker Compose v2
• Ausreichend Speicherplatz auf der Festplatte für Images und Logs

Schnellstart

Die Entscheidung hängt davon ab, wie du arbeitest und was dein Ziel ist. Hier ist die Entscheidungshilfe:

• Ja, nutze Docker, wenn du eine isolierte Gateway-Umgebung suchst, die du nach Gebrauch einfach wegwerfen kannst. Es ist auch die beste Wahl, wenn du OpenClaw auf einem Host betreiben willst, ohne lokale Installationen vorzunehmen.
• Nein, wenn du auf deinem eigenen Rechner entwickelst und den schnellsten Dev-Loop suchst. In diesem Fall solltest du den normalen Install-Flow nutzen.

Sandboxing vs. Gateway

Ein wichtiger Punkt zum Thema Sandboxing: Das Sandboxing für Agents nutzt ebenfalls Docker. Das bedeutet aber nicht, dass das gesamte Gateway in Docker laufen muss. Du kannst ein lokales Gateway mit Docker-isolierten Agent-Tools kombinieren. Details dazu findest du unter Sandboxing.

Dieser Guide deckt zwei Szenarien ab:

1. Containerized Gateway: Das komplette OpenClaw läuft innerhalb von Docker.
2. Per-session Agent Sandbox: Ein lokales Gateway auf deinem Host nutzt Docker-isolierte Agent-Tools.

Fehlerbehebung

Falls Probleme auftreten, liegen diese meist an der Umgebung:

• Docker Version: Stelle sicher, dass du Docker Compose v2 verwendest. Ältere Versionen unterstützen die Konfiguration eventuell nicht korrekt.
• Speicherplatz: Docker Images und Logs können viel Platz einnehmen. Wenn Container nicht starten, prüfe, ob noch genug Disk Space verfügbar ist.

Für alles Weitere hilft dir der AI Setup Assistant.

Nächste Schritte

• Sandboxing – Erfahre mehr über die Isolierung von Agent-Tools.

Kennst du das? Du möchtest ein neues Tool lokal ausprobieren, aber die Installation von Abhängigkeiten und das Verwalten von Node.js-Versionen führt zu Konflikten auf deinem Rechner. Oft enden solche Versuche in einer Fehlersuche, warum eine Library auf deinem OS anders reagiert als dokumentiert.

Mit Docker Compose umgehst du dieses Problem. Du isolierst das Gateway in einem Container, hältst dein Host-System sauber und stellst sicher, dass die Umgebung exakt den Anforderungen entspricht. In dieser Anleitung zeige ich dir, wie du das Gateway schnell startest und für den produktiven Einsatz anpasst.

Voraussetzungen

• Docker und Docker Compose auf deinem System installiert
• Ein geklontes Repository (Befehle werden vom Repo Root ausgeführt)
• Für macOS/Windows: Docker Desktop mit freigegebenen Pfaden für Mounts

Schnellstart

Der schnellste Weg führt über das mitgelieferte Setup-Skript. Führe diesen Befehl im Root-Verzeichnis deines Repos aus:

./docker-setup.sh

Das Skript erledigt folgende Aufgaben für dich:

• Es baut das Gateway Image.
• Es startet den Onboarding Wizard.
• Es zeigt dir Hinweise für das Provider-Setup.
• Es startet das Gateway via Docker Compose.
• Es generiert einen Gateway Token und schreibt ihn in die .env.

Du kannst das Verhalten über optionale Umgebungsvariablen steuern:

• OPENCLAW_DOCKER_APT_PACKAGES: Installiert zusätzliche apt-Pakete während des Builds.
• OPENCLAW_EXTRA_MOUNTS: Fügt zusätzliche Host Bind Mounts hinzu.
• OPENCLAW_HOME_VOLUME: Persistiert /home/node in einem Named Volume.

Sobald das Skript fertig ist:

1. Öffne http://127.0.0.1:18789/ in deinem Browser.
2. Kopiere den Token in die Control UI (Settings → token).
3. Falls du die URL erneut benötigst, nutze: docker compose run --rm openclaw-cli dashboard --no-open.

Das Setup schreibt die Konfiguration und den Workspace auf deinen Host unter ~/.openclaw/ und ~/.openclaw/workspace.

Shell Helpers (optional)

Für die tägliche Arbeit mit Docker kannst du ClawDock installieren:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

Füge den Helper zu deiner Shell-Konfiguration hinzu (Beispiel für zsh):

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Danach stehen dir Befehle wie clawdock-start, clawdock-stop und clawdock-dashboard zur Verfügung. Eine Übersicht aller Befehle liefert clawdock-help. Weitere Details findest du im ClawDock Helper README.

Manual Flow (Compose)

Falls du die Schritte lieber manuell ausführst, nutze diese Befehlskette:

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

Wichtig: Führe docker compose immer vom Repo Root aus. Wenn du OPENCLAW_EXTRA_MOUNTS oder OPENCLAW_HOME_VOLUME aktiviert hast, generiert das Setup eine docker-compose.extra.yml. Diese musst du bei manuellen Aufrufen einbinden:

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

Control UI Token + Pairing

Erhältst du Fehlermeldungen wie “unauthorized” oder “disconnected (1008): pairing required”? Dann musst du einen neuen Dashboard-Link abrufen und das Gerät bestätigen:

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

Weitere Informationen findest du unter Dashboard und Devices.

Zusätzliche Mounts und Persistenz

Extra Mounts

Um weitere Verzeichnisse vom Host in den Container zu spiegeln, setze OPENCLAW_EXTRA_MOUNTS vor dem Ausführen von docker-setup.sh. Die Liste wird kommagetrennt angegeben.

Beispiel:

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Home-Verzeichnis persistieren

Standardmäßig gehen Daten in /home/node verloren, wenn der Container neu erstellt wird. Mit OPENCLAW_HOME_VOLUME nutzt du ein Named Volume für die Persistenz:

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

Power-User Konfiguration

Das Standard-Image ist auf Sicherheit optimiert und nutzt den User node (UID 1000). Das bedeutet: Keine Root-Rechte, kein Homebrew und kein vorinstalliertes Chromium.

Für volle Funktionalität empfehle ich dieses Vorgehen:

1. System-Pakete einbacken: Nutze OPENCLAW_DOCKER_APT_PACKAGES="git curl jq".
2. Playwright Browser installieren:

   docker compose run --rm openclaw-cli \
     node /app/node_modules/playwright-core/cli.js install chromium

3. Playwright Downloads persistieren: Setze PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright in der docker-compose.yml und sorge dafür, dass /home/node via Volume gemountet ist.

Fehlerbehebung

Permissions + EACCES

Wenn Permission-Fehler bei /home/node/.openclaw auftreten, liegt das meist an falschen Berechtigungen auf dem Host. Der Container nutzt UID 1000. Lösung (Linux):

sudo chown -R 1000:1000 /pfad/zu/openclaw-config /pfad/zu/openclaw-workspace

OpenAI Codex OAuth

Im headless Docker-Betrieb kann der OAuth-Callback fehlschlagen, da er versucht, http://127.0.0.1:1455/auth/callback im Browser zu öffnen. Kopiere in diesem Fall die komplette URL der Fehlerseite und füge sie manuell im Wizard ein, um die Authentifizierung abzuschließen.

Channel Setup

Konfiguriere deine Channels über den CLI-Container:

WhatsApp (QR):

docker compose run --rm openclaw-cli channels login

Telegram:

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord:

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Health Check & Tests

Prüfe den Status deines Gateways:

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

Für automatisierte Tests stehen folgende Skripte bereit:

• E2E Smoke Test: scripts/e2e/onboard-docker.sh
• QR Import Test: pnpm test:docker:qr

Hast du Fragen zum Setup oder brauchst Hilfe bei einer spezifischen Fehlermeldung? Nutze den AI Setup Assistant.

Nächste Schritte

• Hetzner (Docker VPS)
• WhatsApp Integration
• Telegram Integration
• Discord Integration

Du kennst das: Du lässt einen Agenten auf deinem Code arbeiten und plötzlich fragst du dich, ob er gerade dein halbes Home-Verzeichnis löscht oder ungefragt Pakete installiert. Die Angst vor unkontrolliertem Code-Zugriff ist real, besonders wenn man mit externen Tools arbeitet, die Dateien verändern oder Shell-Befehle ausführen.

Anstatt den Agenten direkt auf deinem Host-System wüten zu lassen, ist eine isolierte Umgebung der sicherste Weg. So behältst du die Kontrolle und verhinderst, dass ein Fehler im Agenten-Script dein gesamtes System instabil macht.

Voraussetzungen

Bevor du startest, stelle sicher, dass du folgende Voraussetzungen erfüllst:

• Docker ist auf deinem Host-System installiert und einsatzbereit.
• Das OpenClaw Gateway ist konfiguriert.
• Du hast Zugriff auf die Scripte im scripts/ Ordner deines Repositories.
• Ein lokaler Pfad für Sandboxes (standardmäßig ~/.openclaw/sandboxes).

Schnellstart

In weniger als 5 Minuten hast du deine erste Sandbox am Laufen. Folge diesen Schritten:

1. Sandbox Image bauen: Führe das Setup-Script aus, um das Standard-Image (openclaw-sandbox:bookworm-slim) zu erstellen:

   scripts/sandbox-setup.sh

2. Konfiguration anpassen: Öffne deine Konfigurationsdatei und aktiviere die Sandbox für non-main Sessions:

   {
     agents: {
       defaults: {
         sandbox: {
           mode: "non-main",
           scope: "agent",
           workspaceAccess: "rw"
         }
       }
     }
   }

3. Gateway neu starten: Sobald die Konfiguration aktiv ist, werden Tools automatisch in einem Docker-Container ausgeführt.

Funktionsweise der Sandbox

Wenn agents.defaults.sandbox aktiviert ist, laufen alle Tools in einem Docker-Container, sofern es sich nicht um die Haupt-Session handelt. Das Gateway bleibt auf deinem Host, aber die Tool-Ausführung ist isoliert.

Hier sind die wichtigsten Details:

• Scope: Standardmäßig gilt scope: "agent". Das bedeutet ein Container und ein Workspace pro Agent. Mit scope: "session" erhältst du eine Isolation pro Session.
• Workspace: Jeder Scope hat einen eigenen Ordner, der im Container unter /workspace gemountet wird.
• Inbound Media: Eingehende Mediendateien werden nach media/inbound/* im aktiven Sandbox-Workspace kopiert, damit Tools sie lesen können (erfordert workspaceAccess: "rw").
• Tool-Policy: Eine Allow/Deny-Liste steuert den Zugriff. Wichtig: Deny gewinnt immer.

Warnung: Der Modus scope: "shared" deaktiviert die Isolation zwischen Sessions. Alle Sessions teilen sich dann einen Container und einen Workspace.

Profile für mehrere Agenten

Wenn du Multi-Agent-Routing nutzt, kann jeder Agent eigene Sandbox- und Tool-Einstellungen definieren. Das ist ideal, um verschiedene Zugriffsebenen in einem Gateway zu mischen:

• Voller Zugriff für deinen persönlichen Agenten.
• Read-only Tools und Read-only Workspace für einen Agenten, den du mit der Familie teilst.
• Keine Filesystem- oder Shell-Tools für öffentliche Agenten.

Die Einstellungen findest du unter agents.list[].sandbox und agents.list[].tools. Mehr Details dazu gibt es unter Multi-Agent Sandbox & Tools.

Standardverhalten und Security

Das Standard-Image ist openclaw-sandbox:bookworm-slim. Hier sind die wichtigsten Sicherheits-Defaults:

• Netzwerk: none (kein Internetzugriff, außer du aktivierst ihn explizit).
• Workspace-Zugriff: workspaceAccess: "none" nutzt standardmäßig ~/.openclaw/sandboxes.
• Auto-Prune: Container werden entfernt, wenn sie länger als 24 Stunden idle sind oder ein Alter von 7 Tagen überschreiten.
• Erlaubte Tools: exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status.
• Gesperrte Tools: browser, canvas, nodes, cron, discord, gateway.

Fortgeschrittene Konfiguration

Hier ist ein Beispiel für eine vollständige Konfiguration inklusive Hardening-Optionen:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec", "process", "read", "write", "edit",
          "sessions_list", "sessions_history", "sessions_send",
          "sessions_spawn", "session_status"
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

Browser in der Sandbox

Um das browser Tool innerhalb der Sandbox zu nutzen, musst du ein spezielles Image bauen:

scripts/sandbox-browser-setup.sh

Dies erstellt openclaw-sandbox-browser:bookworm-slim. Der Container nutzt Chromium mit CDP und optional noVNC für eine visuelle Kontrolle. Aktiviere ihn so:

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

Fehlerbehebung

Probleme mit setupCommand

Wenn du Pakete via setupCommand installierst, beachte zwei Dinge:

1. Das Standard-Netzwerk ist auf "none" gesetzt. Du musst Egress erlauben, um Pakete zu laden.
2. readOnlyRoot: true verhindert Installationen. Setze es auf false oder nutze passende Mounts.
3. Der user muss Root-Rechte haben (z.B. user: "0:0"), um apt-get zu nutzen.

OpenClaw erstellt Container automatisch neu, wenn sich der setupCommand ändert, es sei denn, der Container wurde in den letzten 5 Minuten aktiv genutzt. In diesem Fall siehst du eine Warnung im Log mit dem Befehl openclaw sandbox recreate ..., um den Vorgang manuell zu erzwingen.

Tool-Zugriff verweigert

Wenn ein Tool nicht funktioniert, prüfe die Allow/Deny-Listen. Denke daran: Wenn allow nicht leer ist, sind nur die dort gelisteten Tools verfügbar. Wenn du den Browser in der Sandbox nutzt, musst du browser explizit zu allow hinzufügen und aus deny entfernen.

Sicherheitshinweis

Die Isolation schützt primär die Tool-Ausführung (exec/read/write). Host-Tools wie Kamera oder Canvas sind standardmäßig blockiert. Wenn du browser in der Sandbox erlaubst, kann dies die Isolation schwächen, da Browser-Prozesse oft komplexere Anforderungen an die Umgebung stellen.

---

Noch Fragen zur Einrichtung? Frag den AI Setup Assistant.

Nächste Schritte

• Deep Dive: Sandboxing
• Multi-Agent Sandbox & Tools Examples

---
title: "Troubleshooting OpenClaw: So löst du Sandbox-Probleme"
description: "Wenn deine OpenClaw-Umgebung nicht wie erwartet läuft, findest du hier Lösungen für häufige Probleme mit Docker, Berechtigungen und Pfaden."
---

Es gibt kaum etwas Frustrierenderes, als wenn die lokale Entwicklungsumgebung streikt. Du hast alles konfiguriert, aber die Sandbox verhält sich nicht so, wie du es erwartest. Meistens sind es Kleinigkeiten in der Konfiguration oder beim Setup der Container, die den Workflow aufhalten.

Solche Hürden bei der Einrichtung von isolierten Umgebungen sind völlig normal. Wichtig ist nur, dass du schnell die richtige Lösung findest, damit du dich wieder auf das Wesentliche konzentrieren kannst.

## Voraussetzungen

- Zugriff auf das OpenClaw Repository
- Installiertes Docker auf deinem System
- Die Konfigurationsdatei für deine Agents

## Schnellstart

Wenn es schnell gehen muss, sind dies die wichtigsten Schritte, um die häufigsten Fehler zu beheben:

1.  Baue das Basis-Image mit dem bereitgestellten Shell-Script.
2.  Prüfe, ob deine UID/GID in der Konfiguration mit deinem Workspace übereinstimmt.
3.  Stelle sicher, dass deine Umgebungsvariablen für Tools korrekt gesetzt sind.
4.  Lass OpenClaw die Container-Erstellung automatisch verwalten.

## Fehlerbehebung

Hier sind die Lösungen für spezifische Probleme, die bei der Arbeit mit der OpenClaw Sandbox auftreten können:

### Image fehlt (Image missing)
Falls das Docker-Image nicht gefunden wird, musst du es manuell bauen. Nutze dafür das Script [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh). Alternativ kannst du das gewünschte Image direkt über den Parameter `agents.defaults.sandbox.docker.image` in deiner Konfiguration festlegen.

### Container läuft nicht (Container not running)
Wundere dich nicht, wenn du keinen aktiven Container siehst. Die Sandbox-Container werden bei Bedarf automatisch pro Session erstellt. Es ist also kein Fehler, wenn der Container im Leerlauf nicht existiert.

### Berechtigungsfehler in der Sandbox (Permission errors)
Wenn du Probleme mit Dateiberechtigungen innerhalb der Sandbox hast, solltest du `docker.user` auf eine UID:GID setzen, die den Berechtigungen deines gemounteten Workspaces entspricht. Eine andere Lösung ist, den Befehl `chown` auf den Workspace-Ordner anzuwenden, um die Besitzverhältnisse anzupassen.

### Eigene Tools werden nicht gefunden (Custom tools not found)
OpenClaw führt Befehle über `sh -lc` (Login Shell) aus. Das führt dazu, dass `/etc/profile` neu geladen wird, was deinen PATH zurücksetzen kann. Um das zu beheben, hast du zwei Möglichkeiten:
- Setze `docker.env.PATH`, um deine eigenen Tool-Pfade voranzustellen (Beispiel: `/custom/bin:/usr/local/share/npm-global/bin`).
- Füge ein eigenes Script unter `/etc/profile.d/` in deinem Dockerfile hinzu.

Hast du weitere Fragen zum Setup? Nutze den [AI Setup Assistant](/docs/).

## Nächste Schritte

- [Sandbox Configuration Guide](/docs/)
- [Docker Integration Details](/docs/)