Docker

Docker è opzionale. Va utilizzato per un ambiente Gateway isolato e temporaneo o per un host privo di installazioni locali. Se lo sviluppo avviene già sulla propria macchina, utilizzare invece il normale flusso di installazione.

Il backend sandbox predefinito utilizza Docker quando agents.defaults.sandbox è abilitato, ma il sandboxing è disattivato per impostazione predefinita e non richiede che il Gateway stesso venga eseguito in Docker. Sono disponibili anche i backend sandbox SSH e OpenShell; vedere Sandboxing.

Si ospitano più utenti? Vedere Hosting multi-tenant per il modello con una cella per tenant.

Prerequisiti

• Docker Desktop (o Docker Engine) + Docker Compose v2
• Almeno 2 GB di RAM per la creazione dell'immagine (pnpm install potrebbe essere terminato per esaurimento della memoria negli host con 1 GB, con codice di uscita 137)
• Spazio su disco sufficiente per immagini e log
• Su un VPS/host pubblico, consultare Rafforzamento della sicurezza per l'esposizione di rete, in particolare la catena firewall Docker DOCKER-USER

Gateway in 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 (codice 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>"

Flusso manuale

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

Il contesto Docker esclude .git. Passare l'identità del sorgente come argomenti di build, come mostrato sopra, affinché la schermata Informazioni dell'immagine riporti il commit estratto e un singolo timestamp di build. scripts/docker/setup.sh risolve e passa automaticamente entrambi i valori.

Aggiornamento delle immagini dei container

Quando si sostituisce l'immagine OpenClaw mantenendo lo stesso stato e la stessa configurazione montati, il nuovo Gateway esegue migrazioni di aggiornamento sicure all'avvio e la convergenza dei plugin prima di risultare pronto. Gli aggiornamenti ordinari delle immagini non dovrebbero richiedere un'esecuzione separata di openclaw doctor --fix.

Se all'avvio non è possibile completare queste riparazioni in modo sicuro, il Gateway termina anziché segnalare uno stato integro. In presenza di un criterio di riavvio, Docker, Podman o Kubernetes potrebbero mostrare il riavvio del container del Gateway. Mantenere montato il volume di stato, quindi eseguire una volta la stessa immagine con openclaw doctor --fix come comando del container, utilizzando gli stessi montaggi di stato/configurazione utilizzati dal Gateway:

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

Al termine di doctor, riavviare il container del Gateway con il comando predefinito. In Kubernetes, eseguire lo stesso comando in un Job temporaneo o in un pod di debug montato sullo stesso PVC, quindi riavviare il Deployment o lo StatefulSet.

Variabili di ambiente

Variabili facoltative accettate da scripts/docker/setup.sh (e, per il container del Gateway, direttamente da docker-compose.yml):

L'immagine ufficiale non include Homebrew. Durante l'onboarding, OpenClaw nasconde gli installer delle dipendenze delle Skills disponibili solo tramite brew in un container Linux privo di brew; fornire tali dipendenze tramite un'immagine personalizzata oppure installarle manualmente. Utilizzare OPENCLAW_IMAGE_APT_PACKAGES per le dipendenze distribuite come pacchetti Debian e OPENCLAW_IMAGE_PIP_PACKAGES per le dipendenze Python (esegue python3 -m pip install --break-system-packages durante la build, quindi fissare le versioni e utilizzare esclusivamente indici attendibili).

Se Docker segnala ResourceExhausted, cannot allocate memory o si interrompe durante tsdown, aumentare il limite di memoria del builder Docker oppure riprovare con heap espliciti più piccoli:

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

Immagini create dai sorgenti con plugin selezionati

OPENCLAW_EXTENSIONS seleziona gli ID dei manifest dei plugin dal checkout sorgente; sono accettati anche i nomi esistenti delle directory sorgente quando differiscono. La build Docker risolve una sola volta la selezione nelle directory sorgente, installa le dipendenze di produzione e, quando un plugin selezionato viene pubblicato separatamente con openclaw.build.bundledDist: false, ne compila il runtime nella distribuzione inclusa nel bundle principale. Questo processo di pacchettizzazione esclusivo di Docker non modifica il contratto dell'artefatto npm o ClawHub del plugin. Gli ID sconosciuti, non validi o ambigui causano il fallimento della build dell'immagine. Gli ID noti riservati alle dipendenze o al sorgente mantengono la gestione temporanea esistente del sorgente e delle dipendenze senza ottenere una voce compilata nella distribuzione principale. Un plugin selezionato con voci di build unificate deve essere compilato correttamente; il sorgente e l'output di runtime dei plugin esterni non selezionati vengono rimossi.

Ad esempio, questi comandi creano immagini gateway FakeCo autonome, separate e multiarchitettura per ClickClack, Slack e Microsoft Teams. ClawRouter fa già parte del runtime principale di OpenClaw, quindi l'immagine ClickClack seleziona solo clickclack. L'argomento esplicitamente vuoto per il browser mantiene l'immagine predefinita priva di 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

Utilizzare --platform linux/arm64 --load o --platform linux/amd64 --load per una singola build locale nativa. L'output multipiattaforma e le attestazioni SBOM/provenienza allegate richiedono un registro o un altro output Buildx che conservi le attestazioni. Dopo il push, esaminare il manifest e distribuire il digest immutabile anziché il tag SHA del sorgente modificabile:

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

Queste immagini sono destinate ai gateway autonomi basati su OCI e agli utenti Docker generici. I gateway gestiti da Crabhelm non le utilizzano: quel percorso di distribuzione crea un archivio appliance x86_64 separato contenente un tarball npm di OpenClaw e blocca i digest di Node, dell'archivio e del manifest. Creare tale appliance separatamente dallo stesso sorgente OpenClaw integrato.

Per testare il sorgente di un plugin incluso nel bundle rispetto a un'immagine pacchettizzata, montare una directory sorgente del plugin sul relativo percorso sorgente pacchettizzato, ad esempio OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Ciò sostituisce il bundle compilato /app/dist/extensions/synology-chat corrispondente per lo stesso ID plugin.

Osservabilità

L'esportazione OpenTelemetry è in uscita dal contenitore Gateway verso il collector OTLP; non richiede la pubblicazione di alcuna porta Docker. Per includere l'esportatore incluso nel bundle in un'immagine creata localmente:

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

Le immagini ufficiali precompilate includono già diagnostics-otel; installare autonomamente clawhub:@openclaw/diagnostics-otel solo se è stato rimosso. Per abilitare l'esportazione, consentire e abilitare il plugin diagnostics-otel nella configurazione, quindi impostare diagnostics.otel.enabled=true (vedere l'esempio completo in Esportazione OpenTelemetry). Le intestazioni di autenticazione del collector vengono gestite tramite diagnostics.otel.headers, non tramite variabili di ambiente Docker.

Le metriche Prometheus riutilizzano la porta Gateway già pubblicata. Installare clawhub:@openclaw/diagnostics-prometheus, abilitare il plugin diagnostics-prometheus, quindi eseguire lo scraping:

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

La route è protetta dall'autenticazione del Gateway; non esporre una porta pubblica /metrics separata né un percorso di reverse proxy non autenticato. Vedere Metriche Prometheus.

Controlli di integrità

Endpoint di verifica del contenitore (nessuna autenticazione richiesta):

curl -fsS http://127.0.0.1:18789/healthz   # operativitàcurl -fsS http://127.0.0.1:18789/readyz     # disponibilità

Il HEALTHCHECK integrato nell'immagine interroga /healthz; i fallimenti ripetuti contrassegnano il contenitore come unhealthy, consentendo agli orchestratori di riavviarlo o sostituirlo.

Snapshot approfondito e autenticato dello stato di integrità:

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

LAN e loopback

scripts/docker/setup.sh usa come valore predefinito OPENCLAW_GATEWAY_BIND=lan, affinché http://127.0.0.1:18789 sull'host funzioni con la pubblicazione delle porte Docker.

• lan (predefinito): il browser e la CLI dell'host possono raggiungere la porta pubblicata del gateway.
• loopback: solo i processi nello spazio dei nomi di rete del contenitore possono raggiungere direttamente il gateway.

Provider locali dell'host

All'interno del contenitore, 127.0.0.1 indica il contenitore stesso, non l'host. Utilizzare host.docker.internal per i provider in esecuzione sull'host:

La configurazione inclusa nel bundle utilizza tali URL come valori predefiniti per l'onboarding di LM Studio/Ollama e docker-compose.yml associa host.docker.internal al gateway dell'host su Docker Engine per Linux (Docker Desktop fornisce lo stesso alias su macOS/Windows). I servizi dell'host devono essere in ascolto su un indirizzo raggiungibile da Docker:

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

Si utilizza un file Compose personalizzato o docker run? Aggiungere autonomamente la stessa associazione, ad esempio --add-host=host.docker.internal:host-gateway.

Backend Claude CLI in Docker

L'immagine ufficiale non preinstalla Claude Code. Installarlo ed effettuare l'accesso all'interno dell'utente node del contenitore, quindi rendere persistente la home del contenitore affinché gli aggiornamenti dell'immagine non eliminino il binario o lo stato di autenticazione.

Per una nuova installazione, abilitare un volume /home/node persistente prima di eseguire la configurazione:

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

Per un'installazione esistente, arrestare lo stack e ricaricare prima i valori .env correnti: lo script di configurazione riscrive sempre .env utilizzando la shell corrente e i valori predefiniti, senza leggere autonomamente il file:

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

Se .env contiene valori che la shell non può importare, riesportare prima manualmente quelli utilizzati (OPENCLAW_IMAGE, porte, modalità di binding, percorsi personalizzati, OPENCLAW_EXTRA_MOUNTS, sandbox, esclusione dell'onboarding). L'overlay generato monta il volume home sia per openclaw-gateway sia per openclaw-cli; eseguire i comandi rimanenti con tale overlay (e prima docker-compose.override.yml, se utilizzato):

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'

L'installer nativo scrive claude in /home/node/.local/bin/claude. Configurare OpenClaw affinché utilizzi tale percorso:

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

Effettuare l'accesso e verificare dalla stessa home persistente:

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

Quindi utilizzare il backend claude-cli incluso nel bundle:

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 "Saluta da Docker Claude CLI"

OPENCLAW_HOME_VOLUME rende persistente l'installazione nativa in /home/node/.local/bin e /home/node/.local/share/claude, oltre alle impostazioni e all'autenticazione di Claude Code in /home/node/.claude e /home/node/.claude.json. Rendere persistente solo /home/node/.openclaw non è sufficiente; se si utilizza OPENCLAW_EXTRA_MOUNTS anziché un volume home, montare tutti questi percorsi Claude in entrambi i servizi.

Bonjour / mDNS

La rete bridge Docker generalmente non inoltra in modo affidabile il multicast Bonjour/mDNS (224.0.0.251:5353). Quando OPENCLAW_DISABLE_BONJOUR non è impostato, il plugin Bonjour incluso nel bundle disabilita automaticamente la pubblicizzazione LAN quando rileva di essere in esecuzione in un contenitore, evitando così un ciclo di arresti anomali dovuto ai tentativi ripetuti di inviare multicast scartato dal bridge. Impostare OPENCLAW_DISABLE_BONJOUR=1 per disabilitarlo forzatamente indipendentemente dal rilevamento oppure 0 per abilitarlo forzatamente (solo con rete host, macvlan o un'altra rete in cui è noto che il multicast mDNS funzioni).

Negli altri casi, per gli host Docker utilizzare l'URL Gateway pubblicato, Tailscale o DNS-SD geografico. Vedere Rilevamento Bonjour per le problematiche note e la risoluzione dei problemi.

Archiviazione e persistenza

Docker Compose monta tramite bind OPENCLAW_CONFIG_DIR in /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR in /home/node/.openclaw/workspace e OPENCLAW_AUTH_PROFILE_SECRET_DIR in /home/node/.config/openclaw, affinché tali percorsi sopravvivano alla sostituzione del contenitore. Quando una variabile non è impostata, docker-compose.yml utilizza un percorso di fallback in ${HOME}, oppure /tmp se HOME stesso è assente, affinché docker compose up non generi mai una specifica del volume con un'origine vuota negli ambienti essenziali.

La directory di configurazione montata contiene:

• openclaw.json per la configurazione del comportamento
• agents/<agentId>/agent/auth-profiles.json per l'autenticazione OAuth/con chiave API archiviata dei provider
• .env per i segreti di runtime basati sull'ambiente, come OPENCLAW_GATEWAY_TOKEN

La directory dei segreti del profilo di autenticazione archivia la chiave di crittografia locale per il materiale dei token dei profili di autenticazione basati su OAuth. Conservarla con lo stato dell'host Docker, ma separata da OPENCLAW_CONFIG_DIR.

I plugin scaricabili installati archiviano lo stato dei pacchetti nella home OpenClaw montata, affinché i record di installazione e le directory principali dei pacchetti sopravvivano alla sostituzione del contenitore; l'avvio del gateway non rigenera gli alberi delle dipendenze dei plugin inclusi nel bundle.

Per tutti i dettagli sulla persistenza della macchina virtuale, vedere Runtime della VM Docker - Cosa viene mantenuto e dove.

Principali fonti di crescita dell'utilizzo del disco: media/, database SQLite per agente, trascrizioni JSONL delle sessioni precedenti, database SQLite condiviso dello stato, directory principali dei pacchetti dei plugin installati e log su file a rotazione in /tmp/openclaw/.

Helper della shell (facoltativi)

Per abbreviare i comandi quotidiani, installare ClawDock:

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

Se l'installazione è stata eseguita dal precedente percorso scripts/shell-helpers/clawdock-helpers.sh, eseguire nuovamente il comando precedente affinché l'helper locale utilizzi il percorso corrente. Quindi usare clawdock-start, clawdock-stop, clawdock-dashboard, ecc. (eseguire clawdock-help per l'elenco completo).

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

Esecuzione su un VPS?

Vedere Hetzner (VPS Docker) e Runtime VM Docker per i passaggi di distribuzione su VM condivise, tra cui l'integrazione dei binari, la persistenza e gli aggiornamenti.

Sandbox dell'agente

Quando agents.defaults.sandbox è abilitato con il backend Docker, il Gateway esegue gli strumenti dell'agente (shell, lettura/scrittura di file, ecc.) all'interno di container Docker isolati, mentre il Gateway stesso rimane sull'host: una barriera rigida attorno alle sessioni degli agenti non attendibili o multi-tenant, senza inserire l'intero Gateway in un container.

L'ambito della sandbox può essere per agente (impostazione predefinita), per sessione o condiviso; ogni ambito dispone di un proprio spazio di lavoro montato in /workspace. È inoltre possibile configurare criteri di autorizzazione/negazione degli strumenti, isolamento della rete, limiti delle risorse e container per browser.

Per la configurazione completa, le immagini, le note sulla sicurezza e i profili multi-agente:

• Sandboxing -- riferimento completo della sandbox
• OpenShell -- accesso interattivo tramite shell ai container sandbox
• Sandbox e strumenti multi-agente -- override per agente

Abilitazione rapida

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

Compilare l'immagine sandbox predefinita (da un checkout del codice sorgente):

scripts/sandbox-setup.sh

Per le installazioni npm senza checkout del codice sorgente, vedere Sandboxing § Immagini e configurazione per i comandi docker build in linea.

Risoluzione dei problemi

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

Risorse correlate

• Panoramica dell'installazione — tutti i metodi di installazione
• Podman — alternativa a Docker basata su Podman
• ClawDock — configurazione Docker Compose della community
• Aggiornamento — mantenere OpenClaw aggiornato
• Configurazione — configurazione del Gateway dopo l'installazione