Docker

Docker is optioneel. Gebruik het voor een geïsoleerde, tijdelijke Gateway-omgeving of een host zonder lokale installaties. Als je al op je eigen machine ontwikkelt, gebruik dan de normale installatiestroom.

De standaardsandboxbackend gebruikt Docker wanneer agents.defaults.sandbox is ingeschakeld, maar sandboxing is standaard uitgeschakeld en vereist niet dat de Gateway zelf in Docker wordt uitgevoerd. SSH- en OpenShell-sandboxbackends zijn ook beschikbaar; zie Sandboxing.

Host je meerdere gebruikers? Zie Multitenanthosting voor het model met één cel per tenant.

Vereisten

• Docker Desktop (of Docker Engine) + Docker Compose v2
• Minstens 2 GB RAM voor het bouwen van de image (pnpm install kan op hosts met 1 GB wegens onvoldoende geheugen worden beëindigd met afsluitcode 137)
• Voldoende schijfruimte voor images en logboeken
• Controleer op een VPS/openbare host Beveiligingsversterking voor netwerktoegang, met name de Docker-firewallketen DOCKER-USER

Gateway in een container

./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 stroom

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \  -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

De Docker-context sluit .git uit. Geef de bronidentiteit door als buildargumenten, zoals hierboven weergegeven, zodat in het scherm Info van de image de uitgecheckte commit en één buildtijdstempel worden weergegeven. scripts/docker/setup.sh bepaalt beide waarden en geeft ze automatisch door.

Containerimages upgraden

Wanneer je de OpenClaw-image vervangt maar dezelfde gekoppelde status/configuratie behoudt, voert de nieuwe Gateway vóór gereedheid opstartveilige upgrademigraties en Plugin-convergentie uit. Voor routinematige image-upgrades zou geen afzonderlijke uitvoering van openclaw doctor --fix nodig moeten zijn.

Als tijdens het opstarten deze reparaties niet veilig kunnen worden voltooid, wordt de Gateway afgesloten in plaats van zich als gezond te melden. Met een herstartbeleid kunnen Docker, Podman of Kubernetes aangeven dat de Gateway-container opnieuw wordt gestart. Behoud het gekoppelde statusvolume en voer vervolgens dezelfde image eenmaal uit met openclaw doctor --fix als containeropdracht, met dezelfde status-/configuratiekoppelingen die de Gateway gebruikt:

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

Nadat doctor is voltooid, start je de Gateway-container opnieuw met de standaardopdracht. Voer in Kubernetes dezelfde opdracht uit in een eenmalige Job of debugpod die aan hetzelfde PVC is gekoppeld en start vervolgens de Deployment of StatefulSet opnieuw.

Omgevingsvariabelen

Optionele variabelen die door scripts/docker/setup.sh worden geaccepteerd (en, voor de Gateway-container, rechtstreeks door docker-compose.yml):

De officiële image bevat geen Homebrew. Tijdens de onboarding verbergt OpenClaw installatieprogramma's voor Skill-afhankelijkheden die alleen brew ondersteunen in een Linux-container zonder brew; lever deze afhankelijkheden via een aangepaste image of installeer ze handmatig. Gebruik OPENCLAW_IMAGE_APT_PACKAGES voor afhankelijkheden uit Debian-pakketten en OPENCLAW_IMAGE_PIP_PACKAGES voor Python-afhankelijkheden (voert python3 -m pip install --break-system-packages uit tijdens de build; zet versies daarom vast en gebruik alleen indexen die je vertrouwt).

Als Docker ResourceExhausted of cannot allocate memory meldt, of tijdens tsdown wordt afgebroken, verhoog dan de geheugenlimiet van de Docker-builder of probeer het opnieuw met kleinere expliciete heaps:

OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

Vanuit bron gebouwde images met geselecteerde plugins

OPENCLAW_EXTENSIONS selecteert pluginmanifest-id's uit de broncheckout; bestaande namen van bronmappen worden ook geaccepteerd wanneer ze afwijken. De Docker- build zet de selectie eenmaal om naar bronmappen, installeert productie- afhankelijkheden en compileert, wanneer een geselecteerde plugin afzonderlijk wordt gepubliceerd met openclaw.build.bundledDist: false, de runtime ervan in de gebundelde hoofddistributie. Deze uitsluitend voor Docker bestemde verpakking wijzigt het npm- of ClawHub- artefactcontract van de plugin niet. Onbekende, ongeldige of dubbelzinnige id's laten de imagebuild mislukken. Bekende id's die alleen voor afhankelijkheden/bronnen dienen, behouden hun bestaande staging van bronnen en afhankelijkheden zonder een gecompileerde vermelding in de hoofddistributie te krijgen. Een geselecteerde plugin met geünificeerde buildvermeldingen moet met succes worden gecompileerd; bron- en runtime-uitvoer van niet-geselecteerde externe plugins worden verwijderd.

Deze opdrachten bouwen bijvoorbeeld afzonderlijke, zelfstandige FakeCo Gateway-images voor meerdere architecturen voor ClickClack, Slack en Microsoft Teams. ClawRouter maakt al deel uit van de OpenClaw-hoofdruntime, dus selecteert de ClickClack-image alleen clickclack. Het expliciete lege browserargument houdt de standaardimage vrij van Chromium:

SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() {  gateway="$1"  selected_plugin="$2"  docker buildx build \    --platform linux/amd64,linux/arm64 \    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \    --build-arg OPENCLAW_INSTALL_BROWSER= \    --provenance=mode=max \    --sbom=true \    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \    --push \    .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteams

Gebruik --platform linux/arm64 --load of --platform linux/amd64 --load voor één native lokale build. Uitvoer voor meerdere platforms en bijgevoegde SBOM/herkomstgegevens vereisen een registry of andere Buildx-uitvoer die attesten behoudt. Inspecteer na het pushen het manifest en implementeer de onveranderlijke digest in plaats van de wijzigbare bron-SHA-tag:

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# Implementeren: registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>

Deze images zijn bedoeld voor zelfstandige OCI-gebaseerde gateways en algemene Docker-gebruikers. Door Crabhelm beheerde gateways gebruiken ze niet: dat leveringspad bouwt een afzonderlijk x86_64-appliancearchief met een OpenClaw-npm-tarball en legt de digests van Node, het archief en het manifest vast. Bouw die appliance onafhankelijk vanuit dezelfde gelande OpenClaw-bron.

Als je gebundelde pluginbroncode wilt testen tegen een verpakte image, koppel je één pluginbronmap over het verpakte bronpad ervan, bijvoorbeeld OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Daarmee wordt de overeenkomstige gecompileerde /app/dist/extensions/synology-chat-bundel voor hetzelfde plugin-id overschreven.

Observeerbaarheid

OpenTelemetry-export verloopt uitgaand vanuit de Gateway-container naar je OTLP-collector; hiervoor hoeft geen Docker-poort te worden gepubliceerd. Zo neem je de gebundelde exporter op in een lokaal gebouwde image:

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

Officiële vooraf gebouwde images bundelen diagnostics-otel al; installeer clawhub:@openclaw/diagnostics-otel alleen zelf als je deze hebt verwijderd. Om export in te schakelen, sta je de plugin diagnostics-otel toe en schakel je deze in de configuratie in. Stel vervolgens diagnostics.otel.enabled=true in (zie het volledige voorbeeld in OpenTelemetry-export). Authenticatieheaders voor de collector worden doorgegeven via diagnostics.otel.headers, niet via Docker-omgevingsvariabelen.

Prometheus-metrieken gebruiken de al gepubliceerde Gateway-poort opnieuw. Installeer clawhub:@openclaw/diagnostics-prometheus, schakel de plugin diagnostics-prometheus in en scrape vervolgens:

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

De route wordt beschermd door Gateway-authenticatie; stel geen afzonderlijke openbare /metrics-poort of niet-geverifieerd reverse-proxypad beschikbaar. Zie Prometheus-metrieken.

Statuscontroles

Probe-eindpunten voor containers (geen authenticatie vereist):

curl -fsS http://127.0.0.1:18789/healthz   # activiteitcurl -fsS http://127.0.0.1:18789/readyz     # gereedheid

De ingebouwde HEALTHCHECK van de image pingt /healthz; bij herhaalde fouten wordt de container gemarkeerd als unhealthy, zodat orchestrators deze opnieuw kunnen starten of vervangen.

Diepgaande geverifieerde 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 http://127.0.0.1:18789 op de host werkt met Docker-poortpublicatie.

• lan (standaard): de 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

Binnen de container verwijst 127.0.0.1 naar de container zelf, niet naar de host. Gebruik host.docker.internal voor providers die op de host draaien:

De gebundelde installatie gebruikt die URL's als onboardingstandaarden voor LM Studio/Ollama, en docker-compose.yml wijst host.docker.internal toe aan de host-Gateway op Linux Docker Engine (Docker Desktop biedt dezelfde alias op macOS/Windows). Hostservices moeten luisteren op een adres dat Docker kan bereiken:

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

Gebruik je je eigen Compose-bestand of docker run? Voeg dan zelf dezelfde toewijzing toe, bijvoorbeeld --add-host=host.docker.internal:host-gateway.

Claude CLI-backend in Docker

De officiële image installeert Claude Code niet vooraf. Installeer deze en meld je aan binnen de gebruiker node van de container. Maak vervolgens die container-home permanent, zodat image-upgrades het binaire bestand of de authenticatiestatus niet wissen.

Schakel voor een nieuwe installatie een permanent /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 bij een bestaande installatie de stack en laad eerst de huidige waarden uit .env opnieuw — het installatiescript herschrijft .env altijd op basis van de huidige shell en standaardwaarden; het leest het bestand niet zelf:

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

Als .env waarden bevat die je shell niet kan inladen, exporteer dan eerst handmatig opnieuw wat je gebruikt (OPENCLAW_IMAGE, poorten, bindmodus, aangepaste paden, OPENCLAW_EXTRA_MOUNTS, sandbox, onboarding overslaan). De gegenereerde overlay koppelt het homevolume voor zowel openclaw-gateway als openclaw-cli; voer de overige opdrachten uit met die overlay (en eerst docker-compose.override.yml, als je die gebruikt):

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 claude naar /home/node/.local/bin/claude. De OpenClaw-image bevat /home/node/.local/bin in PATH, zodat de gebundelde Anthropic-plugin deze zonder overschrijving van de adapterconfiguratie kan vinden.

Meld je aan en verifieer vanuit dezelfde permanente 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

Gebruik vervolgens de gebundelde claude-cli-backend:

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 "Zeg hallo vanuit Docker Claude CLI"

OPENCLAW_HOME_VOLUME bewaart de native installatie onder /home/node/.local/bin en /home/node/.local/share/claude, plus de instellingen/authenticatie van Claude Code onder /home/node/.claude en /home/node/.claude.json. Alleen /home/node/.openclaw permanent maken is niet voldoende; als je OPENCLAW_EXTRA_MOUNTS gebruikt in plaats van een homevolume, koppel dan al die Claude-paden aan beide services.

Bonjour / mDNS

Docker-bridgenetwerken sturen Bonjour/mDNS-multicast (224.0.0.251:5353) doorgaans niet betrouwbaar door. Wanneer OPENCLAW_DISABLE_BONJOUR niet is ingesteld, schakelt de gebundelde Bonjour-plugin LAN-advertering automatisch uit zodra deze detecteert dat hij in een container draait. Zo blijft hij niet in een crashlus proberen multicast te verzenden die door de bridge wordt verworpen. Stel OPENCLAW_DISABLE_BONJOUR=1 in om dit ongeacht de detectie gedwongen uit te schakelen, of 0 om het gedwongen in te schakelen (alleen bij hostnetwerken, macvlan of een ander netwerk waarvan bekend is dat mDNS-multicast werkt).

Gebruik anders de gepubliceerde Gateway-URL, Tailscale of wide-area DNS-SD voor Docker-hosts. Zie Bonjour-detectie voor aandachtspunten en probleemoplossing.

Opslag en persistentie

Docker Compose koppelt OPENCLAW_CONFIG_DIR aan /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR aan /home/node/.openclaw/workspace en OPENCLAW_AUTH_PROFILE_SECRET_DIR aan /home/node/.config/openclaw, zodat die paden behouden blijven wanneer de container wordt vervangen. Wanneer een variabele niet is ingesteld, valt docker-compose.yml terug op een pad onder ${HOME}, of /tmp als HOME zelf ontbreekt, zodat docker compose up in kale omgevingen nooit een volumespecificatie met een lege bron genereert.

Die gekoppelde configuratiemap bevat:

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

De geheimenmap voor authenticatieprofielen bevat de lokale encryptiesleutel voor het tokenmateriaal van door OAuth ondersteunde authenticatieprofielen. Bewaar deze bij de statusgegevens van je Docker-host, maar gescheiden van OPENCLAW_CONFIG_DIR.

Geïnstalleerde downloadbare plugins slaan pakketstatus op onder de gekoppelde OpenClaw-home, zodat installatierecords en pakkethoofdmappen behouden blijven wanneer de container wordt vervangen; bij het starten van de Gateway worden afhankelijkheidsstructuren van gebundelde plugins niet opnieuw gegenereerd.

Zie Docker VM-runtime - Wat blijft waar behouden voor volledige details over persistentie van VM's.

Belangrijkste bronnen van schijfgroei: media/, SQLite-databases per agent, verouderde JSONL-transcripten van sessies, de gedeelde SQLite-statusdatabase, pakketbasismappen van geïnstalleerde plugins en roterende bestandslogboeken onder /tmp/openclaw/.

Shell-hulpfuncties (optioneel)

Installeer ClawDock voor kortere dagelijkse opdrachten:

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 via het oudere pad scripts/shell-helpers/clawdock-helpers.sh hebt geïnstalleerd, voer je de bovenstaande opdracht opnieuw uit, zodat je lokale hulpfunctie de huidige locatie volgt. Gebruik daarna clawdock-start, clawdock-stop, clawdock-dashboard, enzovoort (voer clawdock-help uit voor de volledige lijst).

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

Uitvoeren op een VPS?

Zie Hetzner (Docker-VPS) en Docker-VM-runtime voor implementatiestappen voor een gedeelde VM, waaronder het opnemen van binaire bestanden in de image, permanente opslag en updates.

Agentsandbox

Wanneer agents.defaults.sandbox is ingeschakeld met de Docker-backend, voert de Gateway agenttools (shell, bestanden lezen/schrijven enzovoort) uit in geïsoleerde Docker-containers, terwijl de Gateway zelf op de host blijft — een harde scheiding rond niet-vertrouwde agentsessies of agentsessies met meerdere tenants, zonder de volledige Gateway in een container uit te voeren.

Het sandboxbereik kan per agent (standaard), per sessie of gedeeld zijn; elk bereik krijgt een eigen werkruimte die op /workspace wordt gekoppeld. Je kunt ook beleid voor toegestane/geweigerde tools, netwerkisolatie, resourcelimieten en browsercontainers configureren.

Voor de volledige configuratie, images, beveiligingsopmerkingen en profielen met meerdere agents:

• Sandboxing -- volledige sandboxreferentie
• OpenShell -- interactieve shelltoegang tot sandboxcontainers
• Sandbox en tools voor meerdere agents -- overrides per agent

Snel inschakelen

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // uit | niet-main | alles        scope: "agent", // sessie | agent | gedeeld      },    },  },}

Bouw de standaard-sandboximage (vanuit een broncodecheckout):

scripts/sandbox-setup.sh

Zie voor npm-installaties zonder broncodecheckout Sandboxing § Images en configuratie 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 — communityconfiguratie met Docker Compose
• Bijwerken — OpenClaw up-to-date houden
• Configuratie — Gateway-configuratie na installatie