Docker

Docker is optioneel. Gebruik het alleen als je een gecontaineriseerde Gateway wilt of de Docker-flow wilt valideren.

Is Docker geschikt voor mij?

• Ja: je wilt een geïsoleerde, wegwerpbare Gateway-omgeving of OpenClaw uitvoeren op een host zonder lokale installaties.
• Nee: je draait op je eigen machine en wilt gewoon de snelste ontwikkelloop. Gebruik in plaats daarvan de normale installatiestroom.
• Opmerking over sandboxing: de standaard sandbox-backend gebruikt Docker wanneer sandboxing is ingeschakeld, maar sandboxing staat standaard uit en vereist niet dat de volledige Gateway in Docker draait. SSH- en OpenShell-sandbox-backends zijn ook beschikbaar. Zie Sandboxing.

Vereisten

• Docker Desktop (of Docker Engine) + Docker Compose v2
• Minimaal 2 GB RAM voor het bouwen van de image (pnpm install kan op hosts met 1 GB door OOM worden gestopt met exit 137)
• Genoeg schijfruimte voor images en logs
• Als je op een VPS/openbare host draait, bekijk dan Beveiligingsverharding voor netwerkblootstelling, vooral het Docker DOCKER-USER-firewallbeleid.

Gecontaineriseerde Gateway

./scripts/docker/setup.sh

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh

export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.sh

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

docker compose run --rm openclaw-cli dashboard --no-open

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Handmatige flow

Als je liever elke stap zelf uitvoert in plaats van het setupscript te gebruiken:

docker build -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'docker compose up -d openclaw-gateway

Omgevingsvariabelen

Het setupscript accepteert deze optionele omgevingsvariabelen:

De officiële Docker-image bevat geen Homebrew. Tijdens onboarding verbergt OpenClaw installers voor skill-afhankelijkheden die alleen via brew beschikbaar zijn wanneer het in een Linux- container zonder brew draait; die afhankelijkheden moeten door een custom image worden geleverd of handmatig worden geïnstalleerd. Gebruik voor afhankelijkheden die beschikbaar zijn als Debian-pakketten OPENCLAW_IMAGE_APT_PACKAGES tijdens het bouwen van de image. De legacy naam OPENCLAW_DOCKER_APT_PACKAGES wordt nog steeds geaccepteerd. Gebruik voor Python-afhankelijkheden OPENCLAW_IMAGE_PIP_PACKAGES. Dit voert python3 -m pip install --break-system-packages uit tijdens het bouwen van de image, dus pin pakketversies en gebruik alleen pakketindexen die je vertrouwt. Bron-builds zetten OPENCLAW_DOCKER_BUILD_NODE_OPTIONS standaard op --max-old-space-size=8192 en laten OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB unset zodat de tsdown-wrapper containergeheugenlimieten kan respecteren. Ze zetten ook standaard OPENCLAW_DOCKER_BUILD_SKIP_DTS=1, omdat runtime-images declaration- bestanden na build opschonen. Als Docker ResourceExhausted, cannot allocate memory meldt of tijdens tsdown afbreekt, verhoog dan de geheugenlimiet van de Docker-builder of probeer opnieuw met kleinere expliciete heaps, bijvoorbeeld OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

Maintainers kunnen gebundelde Plugin-bron testen tegen een packaged image door één Plugin-bronmap over het packaged bronpad te mounten, bijvoorbeeld OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Die gemounte bronmap overschrijft de overeenkomende gecompileerde /app/dist/extensions/synology-chat-bundle voor dezelfde Plugin-id.

Observeerbaarheid

OpenTelemetry-export is uitgaand vanuit de Gateway-container naar je OTLP- collector. Hiervoor is geen gepubliceerde Docker-poort nodig. Als je de image lokaal bouwt en de gebundelde OpenTelemetry-exporter binnen de image beschikbaar wilt hebben, neem dan de runtime-afhankelijkheden op:

export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.sh

Installeer de officiële @openclaw/diagnostics-otel Plugin vanuit ClawHub in packaged Docker-installaties voordat je export inschakelt. Custom source-built images kunnen nog steeds de lokale Plugin-bron opnemen met OPENCLAW_EXTENSIONS=diagnostics-otel. Om export in te schakelen, sta de diagnostics-otel Plugin toe en schakel deze in de configuratie in, en zet daarna diagnostics.otel.enabled=true of gebruik het configuratievoorbeeld in OpenTelemetry export. Collector-authheaders worden geconfigureerd via diagnostics.otel.headers, niet via Docker-omgevingsvariabelen.

Prometheus-metrics gebruiken de al gepubliceerde Gateway-poort. Installeer clawhub:@openclaw/diagnostics-prometheus, schakel de diagnostics-prometheus Plugin in en scrape daarna:

http://<gateway-host>:18789/api/diagnostics/prometheus

De route wordt beschermd door Gateway-authenticatie. Stel geen aparte openbare /metrics-poort of niet-geauthenticeerd reverse-proxy-pad bloot. Zie Prometheus-metrics.

Health checks

Containerprobe-eindpunten (geen authenticatie vereist):

curl -fsS http://127.0.0.1:18789/healthz   # livenesscurl -fsS http://127.0.0.1:18789/readyz     # readiness

De Docker-image bevat een ingebouwde HEALTHCHECK die /healthz pingt. Als controles blijven mislukken, markeert Docker de container als unhealthy en kunnen orkestratiesystemen deze opnieuw starten of vervangen.

Geauthenticeerde diepgaande statusmomentopname:

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

LAN versus loopback

scripts/docker/setup.sh gebruikt standaard OPENCLAW_GATEWAY_BIND=lan, zodat hosttoegang tot http://127.0.0.1:18789 werkt met Docker-portpublicatie.

• lan (standaard): hostbrowser en host-CLI kunnen de gepubliceerde Gateway-poort bereiken.
• loopback: alleen processen binnen de netwerknaamruimte van de container kunnen de Gateway rechtstreeks bereiken.

Lokale providers op host

Wanneer OpenClaw in Docker draait, is 127.0.0.1 binnen de container de container zelf, niet je hostmachine. Gebruik host.docker.internal voor AI-providers die op de host draaien:

De meegeleverde Docker-installatie gebruikt die host-URL's als de standaardwaarden voor onboarding van LM Studio en Ollama, en docker-compose.yml koppelt host.docker.internal aan Docker's host-Gateway voor Linux Docker Engine. Docker Desktop biedt dezelfde hostnaam al op macOS en Windows.

Hostservices moeten ook luisteren op een adres dat bereikbaar is vanuit Docker:

lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

Als je je eigen Compose-bestand of docker run-opdracht gebruikt, voeg dan zelf dezelfde hostkoppeling toe, bijvoorbeeld --add-host=host.docker.internal:host-gateway.

Claude CLI-backend in Docker

De officiële OpenClaw Docker-image installeert Claude Code niet vooraf. Installeer Claude Code en log erop in binnen de containergebruiker die OpenClaw uitvoert, en bewaar daarna die container-home zodat image-upgrades het binaire bestand of de Claude-authenticatiestatus niet wissen.

Schakel voor nieuwe Docker-installaties een persistent /home/node-volume in voordat je de installatie uitvoert:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"export OPENCLAW_HOME_VOLUME="openclaw_home"./scripts/docker/setup.sh

Stop voor een bestaande Docker-installatie eerst de stack en laad de huidige Docker-.env-waarden opnieuw voordat je setup opnieuw uitvoert. Het setupscript leest .env niet zelf; het herschrijft .env op basis van de huidige shell en standaardwaarden. Voer voor de gegenereerde .env uit:

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

Als je .env waarden bevat die je shell niet kan sourcen, exporteer dan eerst handmatig de bestaande waarden opnieuw waarop je vertrouwt, zoals OPENCLAW_IMAGE, poorten, bindmodus, aangepaste paden, OPENCLAW_EXTRA_MOUNTS, sandbox en instellingen om onboarding over te slaan. De gegenereerde overlay mount het homevolume voor zowel openclaw-gateway als openclaw-cli.

Voer de resterende opdrachten uit met de gegenereerde Compose-overlay, zodat beide services de persistente home mounten. Als je installatie ook docker-compose.override.yml gebruikt, voeg die dan toe vóór docker-compose.extra.yml.

Installeer Claude Code in die persistente home:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

Het native installatieprogramma schrijft het claude-binaire bestand onder /home/node/.local/bin/claude. Laat OpenClaw dat containerpad gebruiken:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

Log in en verifieer vanuit dezelfde persistente container-home:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

Daarna kun je de meegeleverde claude-cli-backend gebruiken:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME behoudt de native Claude Code-installatie onder /home/node/.local/bin en /home/node/.local/share/claude, plus Claude Code- instellingen en authenticatiestatus onder /home/node/.claude en /home/node/.claude.json. Alleen /home/node/.openclaw persistent maken is niet genoeg om Claude CLI opnieuw te gebruiken. Als je OPENCLAW_EXTRA_MOUNTS gebruikt in plaats van een homevolume, mount dan al die Claude-paden in beide Docker-services.

Bonjour / mDNS

Docker-bridgenetwerken sturen Bonjour/mDNS-multicast (224.0.0.251:5353) meestal niet betrouwbaar door. De meegeleverde Compose-installatie gebruikt daarom standaard OPENCLAW_DISABLE_BONJOUR=1, zodat de Gateway niet in een crash-loop terechtkomt of herhaaldelijk opnieuw begint met adverteren wanneer de bridge multicastverkeer laat vallen.

Gebruik de gepubliceerde Gateway-URL, Tailscale of wide-area DNS-SD voor Docker-hosts. Stel OPENCLAW_DISABLE_BONJOUR=0 alleen in wanneer je draait met hostnetwerken, macvlan of een ander netwerk waarvan bekend is dat mDNS-multicast werkt.

Zie Bonjour-detectie voor valkuilen en probleemoplossing.

Opslag en persistentie

Docker Compose bind-mount OPENCLAW_CONFIG_DIR naar /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR naar /home/node/.openclaw/workspace en OPENCLAW_AUTH_PROFILE_SECRET_DIR naar /home/node/.config/openclaw, zodat die paden containervervanging overleven. Wanneer een variabele niet is ingesteld, valt het meegeleverde docker-compose.yml terug onder ${HOME}, of onder /tmp wanneer HOME zelf ook ontbreekt. Dat voorkomt dat docker compose up een volumespecificatie met lege bron uitvoert in kale omgevingen.

Die gemounte configuratiemap is waar OpenClaw het volgende bewaart:

• openclaw.json voor gedragsconfiguratie
• agents/<agentId>/agent/auth-profiles.json voor opgeslagen OAuth/API-key-authenticatie van providers
• .env voor runtimegeheimen op basis van omgevingsvariabelen, zoals OPENCLAW_GATEWAY_TOKEN

De map met geheime sleutels voor authenticatieprofielen bewaart de lokale versleutelingssleutel die wordt gebruikt voor tokenmateriaal van OAuth-ondersteunde authenticatieprofielen. Bewaar deze bij je Docker-hoststatus, maar gescheiden van OPENCLAW_CONFIG_DIR.

Geïnstalleerde downloadbare Plugins bewaren hun pakketstatus onder de gemounte OpenClaw-home, zodat Plugin-installatierecords en pakketroots containervervanging overleven. Het opstarten van de Gateway genereert geen dependency-trees voor meegeleverde Plugins.

Zie voor volledige persistentiedetails op VM-deployments Docker-VM-runtime - wat waar behouden blijft.

Hotspots voor schijfgroei: let op media/, sessie-JSONL-bestanden, de gedeelde SQLite-statusdatabase, pakketroots van geïnstalleerde Plugins en roterende bestandslogs onder /tmp/openclaw/.

Shellhelpers (optioneel)

Installeer ClawDock voor eenvoudiger dagelijks Docker-beheer:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Als je ClawDock hebt geïnstalleerd vanaf het oudere raw-pad scripts/shell-helpers/clawdock-helpers.sh, voer dan de bovenstaande installatieopdracht opnieuw uit zodat je lokale helperbestand de nieuwe locatie volgt.

Gebruik daarna clawdock-start, clawdock-stop, clawdock-dashboard, enzovoort. Voer clawdock-help uit voor alle opdrachten. Zie ClawDock voor de volledige helperhandleiding.

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probedocker compose run -T --rm openclaw-cli devices list --json

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

Draaien op een VPS?

Zie Hetzner (Docker-VPS) en Docker-VM-runtime voor gedeelde VM-implementatiestappen, waaronder binaries inbouwen, persistentie en updates.

Agentsandbox

Wanneer agents.defaults.sandbox is ingeschakeld met de Docker-backend, voert de Gateway agenttooluitvoering (shell, bestanden lezen/schrijven, enzovoort) uit in geïsoleerde Docker- containers, terwijl de Gateway zelf op de host blijft. Dit geeft je een harde scheiding rond niet-vertrouwde of multi-tenant agentsessies zonder de volledige Gateway in een container te plaatsen.

Het sandboxbereik kan per agent (standaard), per sessie of gedeeld zijn. Elk bereik krijgt een eigen workspace die is aangekoppeld op /workspace. Je kunt ook toestaan/weigeren-toolbeleid, netwerkisolatie, resourcelimieten en browsercontainers configureren.

Voor de volledige configuratie, images, beveiligingsnotities en multi-agentprofielen, zie:

• Sandboxing -- volledige sandboxreferentie
• OpenShell -- interactieve shelltoegang tot sandboxcontainers
• Multi-agent sandbox en tools -- overschrijvingen per agent

Snel inschakelen

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

Bouw de standaard sandboximage (vanuit een source checkout):

scripts/sandbox-setup.sh

Voor npm-installaties zonder source checkout, zie Sandboxing § Images en installatie voor inline docker build-opdrachten.

Problemen oplossen

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

Gerelateerd

• Installatieoverzicht — alle installatiemethoden
• Podman — Podman-alternatief voor Docker
• ClawDock — communityopstelling met Docker Compose
• Updaten — OpenClaw up-to-date houden
• Configuratie — Gatewayconfiguratie na installatie