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, tijdelijke Gateway-omgeving of OpenClaw uitvoeren op een host zonder lokale installaties.
• Nee: je draait op je eigen machine en wilt alleen de snelste ontwikkelloop. Gebruik in plaats daarvan de normale installatieflow.
• 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-sandboxbackends 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 beëindigd 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

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

# 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>"

# 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-daemon
docker 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:

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

# Observability

OpenTelemetry-export loopt uitgaand van 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 in 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 uit ClawHub in verpakte Docker-installaties voordat je export inschakelt. Aangepaste images die vanuit broncode zijn gebouwd, kunnen nog steeds de lokale Plugin-broncode opnemen met OPENCLAW_EXTENSIONS=diagnostics-otel. Om export in te schakelen, sta je de diagnostics-otel Plugin toe en schakel je die in de configuratie in, stel daarna diagnostics.otel.enabled=true in 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 vervolgens:

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

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

# Health checks

Container-probe-endpoints (geen authenticatie vereist):

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

De Docker-image bevat een ingebouwde HEALTHCHECK die /healthz pingt. Als checks blijven falen, markeert Docker de container als unhealthy en kunnen orchestratiesystemen deze herstarten of vervangen.

Geauthenticeerde diepgaande health-snapshot:

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-poortpublicatie.

• 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 de 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 gebundelde Docker-setup gebruikt die host-URL's als onboardingstandaarden voor LM Studio en Ollama, en docker-compose.yml wijst host.docker.internal toe 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.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve

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

# Bonjour / mDNS

Docker bridge networking stuurt Bonjour/mDNS-multicast (224.0.0.251:5353) meestal niet betrouwbaar door. De gebundelde Compose-setup gebruikt daarom standaard OPENCLAW_DISABLE_BONJOUR=1, zodat de Gateway niet in een crash-loop raakt 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 host networking, 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 en OPENCLAW_WORKSPACE_DIR naar /home/node/.openclaw/workspace, zodat die paden containervervanging overleven. Wanneer een van beide variabelen niet is ingesteld, valt de gebundelde docker-compose.yml terug op ${HOME}/.openclaw (en ${HOME}/.openclaw/workspace voor de workspace-mount), of /tmp/.openclaw wanneer HOME zelf ook ontbreekt. Dat voorkomt dat docker compose up in kale omgevingen een volumespecificatie met lege bron emitteert.

Die gemounte configuratiemap is waar OpenClaw het volgende bewaart:

• openclaw.json voor gedragsconfiguratie
• agents/<agentId>/agent/auth-profiles.json voor opgeslagen OAuth/API-sleutelauthenticatie van providers
• .env voor door env ondersteunde runtimegeheimen zoals OPENCLAW_GATEWAY_TOKEN

Geïnstalleerde downloadbare Plugins slaan hun pakketstatus op onder de gemounte OpenClaw-home, zodat Plugin-installatierecords en pakketroots containervervanging overleven. Het starten van de Gateway genereert geen afhankelijkheidsbomen voor gebundelde Plugins.

Zie voor volledige persistentiedetails bij VM-implementaties Docker VM Runtime - Wat blijft waar bewaard.

Hotspots voor schijfgroei: let op media/, JSONL-sessiebestanden, cron/runs/*.jsonl, geïnstalleerde Plugin-pakketroots en roterende bestandslogs onder /tmp/openclaw/.

# Shell-helpers (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.sh
echo '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 je 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=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

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

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

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

# Draaien op een VPS?

Zie Hetzner (Docker VPS) en Docker VM Runtime voor implementatiestappen voor gedeelde VM's, waaronder binary baking, persistentie en updates.

# Agent-sandbox

Wanneer agents.defaults.sandbox is ingeschakeld met de Docker-backend, voert de gateway tooluitvoering door agents (shell, bestanden lezen/schrijven, enz.) uit binnen geïsoleerde Docker- containers terwijl de gateway zelf op de host blijft. Dit geeft je een harde muur rond niet-vertrouwde of multi-tenant agentsessies zonder de volledige gateway te containeriseren.

Sandbox-scope kan per agent (standaard), per sessie of gedeeld zijn. Elke scope krijgt een eigen werkruimte die is gemount op /workspace. Je kunt ook toestaan/weigeren-toolbeleid, netwerkisolatie, resourcelimieten en browser- containers configureren.

Zie voor volledige configuratie, images, beveiligingsopmerkingen en multi-agentprofielen:

• Sandboxing -- volledige sandboxreferentie
• OpenShell -- interactieve shelltoegang tot sandboxcontainers
• Multi-Agent Sandbox en Tools -- overrides 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 setup voor inline docker build-opdrachten.

# Problemen oplossen

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>

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 — communitysetup met Docker Compose
• Updaten — OpenClaw up-to-date houden
• Configuratie — gatewayconfiguratie na installatie