Docker

Docker è opzionale. Usalo solo se vuoi un gateway containerizzato o convalidare il flusso Docker.

Docker fa al caso mio?

• Sì: vuoi un ambiente gateway isolato e temporaneo, oppure eseguire OpenClaw su un host senza installazioni locali.
• No: stai eseguendo sul tuo computer e vuoi solo il ciclo di sviluppo più rapido. Usa invece il normale flusso di installazione.
• Nota sul sandboxing: il backend sandbox predefinito usa Docker quando il sandboxing è abilitato, ma il sandboxing è disattivato per impostazione predefinita e non richiede che l'intero gateway venga eseguito in Docker. Sono disponibili anche i backend sandbox SSH e OpenShell. Vedi Sandboxing.

Prerequisiti

• Docker Desktop (o Docker Engine) + Docker Compose v2
• Almeno 2 GB di RAM per la build dell'immagine (pnpm install potrebbe essere terminato per OOM su host da 1 GB con codice di uscita 137)
• Spazio su disco sufficiente per immagini e log
• Se esegui su un VPS/host pubblico, consulta Rafforzamento della sicurezza per l'esposizione di rete, in particolare la policy firewall Docker DOCKER-USER.

Gateway containerizzato

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

Flusso manuale

Se preferisci eseguire ogni passaggio manualmente invece di usare lo script di configurazione:

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

Variabili di ambiente

Lo script di configurazione accetta queste variabili di ambiente opzionali:

L'immagine Docker ufficiale non include Homebrew. Durante l'onboarding, OpenClaw nasconde gli installer delle dipendenze delle skill solo brew quando è in esecuzione in un container Linux senza brew; tali dipendenze devono essere fornite da un'immagine personalizzata o installate manualmente. Per le dipendenze disponibili dai pacchetti Debian, usa OPENCLAW_IMAGE_APT_PACKAGES durante la build dell'immagine. Il nome legacy OPENCLAW_DOCKER_APT_PACKAGES è ancora accettato. Per le dipendenze Python, usa OPENCLAW_IMAGE_PIP_PACKAGES. Questo esegue python3 -m pip install --break-system-packages durante la build dell'immagine, quindi fissa le versioni dei pacchetti e usa solo indici di pacchetti di cui ti fidi. Le build da sorgente impostano per impostazione predefinita OPENCLAW_DOCKER_BUILD_NODE_OPTIONS su --max-old-space-size=8192 e lasciano OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB non impostato, così il wrapper tsdown può rispettare i limiti di memoria del container. Impostano inoltre per impostazione predefinita OPENCLAW_DOCKER_BUILD_SKIP_DTS=1 perché le immagini runtime eliminano i file di dichiarazione dopo la build. Se Docker segnala ResourceExhausted, cannot allocate memory o si interrompe durante tsdown, aumenta il limite di memoria del builder Docker o riprova con heap espliciti più piccoli, ad esempio OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

I maintainer possono testare il sorgente dei plugin inclusi rispetto a un'immagine pacchettizzata montando una directory sorgente di plugin sopra il relativo percorso sorgente pacchettizzato, ad esempio OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Quella directory sorgente montata sovrascrive il bundle compilato corrispondente /app/dist/extensions/synology-chat per lo stesso id plugin.

Osservabilità

L'export OpenTelemetry è in uscita dal container Gateway verso il tuo collector OTLP. Non richiede una porta Docker pubblicata. Se crei l'immagine localmente e vuoi che l'exporter OpenTelemetry incluso sia disponibile dentro l'immagine, includi le sue dipendenze runtime:

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

Installa il plugin ufficiale @openclaw/diagnostics-otel da ClawHub nelle installazioni Docker pacchettizzate prima di abilitare l'export. Le immagini personalizzate buildate da sorgente possono comunque includere il sorgente del plugin locale con OPENCLAW_EXTENSIONS=diagnostics-otel. Per abilitare l'export, consenti e abilita il plugin diagnostics-otel nella configurazione, quindi imposta diagnostics.otel.enabled=true oppure usa l'esempio di configurazione in Export OpenTelemetry. Gli header di autenticazione del collector sono configurati tramite diagnostics.otel.headers, non tramite variabili di ambiente Docker.

Le metriche Prometheus usano la porta Gateway già pubblicata. Installa clawhub:@openclaw/diagnostics-prometheus, abilita il plugin diagnostics-prometheus, quindi esegui lo scrape:

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

La route è protetta dall'autenticazione del Gateway. Non esporre una porta pubblica /metrics separata o un percorso reverse proxy non autenticato. Vedi Metriche Prometheus.

Controlli di integrità

Endpoint di probe del container (nessuna autenticazione richiesta):

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

L'immagine Docker include un HEALTHCHECK integrato che esegue un ping su /healthz. Se i controlli continuano a fallire, Docker contrassegna il container come unhealthy e i sistemi di orchestrazione possono riavviarlo o sostituirlo.

Snapshot di integrità profondo autenticato:

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

LAN vs loopback

scripts/docker/setup.sh imposta come predefinito OPENCLAW_GATEWAY_BIND=lan, quindi l'accesso host a http://127.0.0.1:18789 funziona con la pubblicazione delle porte Docker.

• lan (predefinito): il browser host e la CLI host possono raggiungere la porta Gateway pubblicata.
• loopback: solo i processi all'interno del namespace di rete del container possono raggiungere direttamente il Gateway.

Provider locali sull'host

Quando OpenClaw viene eseguito in Docker, 127.0.0.1 all'interno del container è il container stesso, non la macchina host. Usa host.docker.internal per i provider IA che vengono eseguiti sull'host:

La configurazione Docker inclusa usa questi URL host come valori predefiniti di onboarding per LM Studio e Ollama, e docker-compose.yml mappa host.docker.internal al Gateway host di Docker per Docker Engine su Linux. Docker Desktop fornisce già lo stesso nome host su macOS e Windows.

Anche i servizi host devono rimanere 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

Se usi un tuo file Compose o un comando docker run, aggiungi tu stesso la stessa mappatura host, per esempio --add-host=host.docker.internal:host-gateway.

Backend Claude CLI in Docker

L'immagine Docker ufficiale di OpenClaw non preinstalla Claude Code. Installa ed esegui l'accesso a Claude Code all'interno dell'utente del container che esegue OpenClaw, poi rendi persistente la home di quel container affinché gli aggiornamenti dell'immagine non cancellino il binario o lo stato di autenticazione Claude.

Per nuove installazioni Docker, abilita 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 Docker esistente, arresta prima lo stack e ricarica i valori correnti Docker .env prima di rieseguire la configurazione. Lo script di configurazione non legge .env autonomamente; riscrive .env dalla shell corrente e dai valori predefiniti. Per il .env generato, esegui:

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

Se il tuo .env contiene valori che la tua shell non può caricare, riesporta manualmente prima i valori esistenti da cui dipendi, come OPENCLAW_IMAGE, porte, modalità di bind, percorsi personalizzati, OPENCLAW_EXTRA_MOUNTS, sandbox e impostazioni skip-onboarding. L'overlay generato monta il volume home sia per openclaw-gateway sia per openclaw-cli.

Esegui i comandi rimanenti con l'overlay Compose generato, così entrambi i servizi montano la home persistente. Se la tua configurazione usa anche docker-compose.override.yml, includilo prima di docker-compose.extra.yml.

Installa Claude Code in quella home persistente:

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 il binario claude in /home/node/.local/bin/claude. Indica a OpenClaw di usare quel percorso del container:

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

Accedi e verifica dall'interno della stessa home persistente del container:

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

Dopo, puoi usare il backend claude-cli incluso:

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 mantiene persistente l'installazione nativa di Claude Code in /home/node/.local/bin e /home/node/.local/share/claude, oltre alle impostazioni e allo stato di autenticazione di Claude Code in /home/node/.claude e /home/node/.claude.json. Rendere persistente solo /home/node/.openclaw non è sufficiente per riutilizzare Claude CLI. Se usi OPENCLAW_EXTRA_MOUNTS invece di un volume home, monta tutti quei percorsi Claude in entrambi i servizi Docker.

Bonjour / mDNS

La rete bridge di Docker di solito non inoltra in modo affidabile il multicast Bonjour/mDNS (224.0.0.251:5353). La configurazione Compose inclusa quindi imposta come predefinito OPENCLAW_DISABLE_BONJOUR=1, così il Gateway non entra in un ciclo di arresti anomali o riavvia ripetutamente l'annuncio quando il bridge scarta il traffico multicast.

Usa l'URL Gateway pubblicato, Tailscale o DNS-SD su rete geografica per gli host Docker. Imposta OPENCLAW_DISABLE_BONJOUR=0 solo quando esegui con networking host, macvlan, o un'altra rete in cui è noto che il multicast mDNS funzioni.

Per problemi comuni e risoluzione dei problemi, vedi rilevamento Bonjour.

Archiviazione e persistenza

Docker Compose monta tramite bind OPENCLAW_CONFIG_DIR su /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR su /home/node/.openclaw/workspace e OPENCLAW_AUTH_PROFILE_SECRET_DIR su /home/node/.config/openclaw, così quei percorsi sopravvivono alla sostituzione del container. Quando una variabile non è impostata, il docker-compose.yml incluso ricade sotto ${HOME}, o /tmp quando manca anche HOME. Questo impedisce a docker compose up di emettere una specifica di volume con origine vuota in ambienti essenziali.

Quella directory di configurazione montata è dove OpenClaw conserva:

• openclaw.json per la configurazione del comportamento
• agents/<agentId>/agent/auth-profiles.json per l'autenticazione OAuth/chiave API dei provider salvata
• .env per segreti runtime basati su env come OPENCLAW_GATEWAY_TOKEN

La directory della chiave segreta del profilo di autenticazione archivia la chiave di cifratura locale usata per il materiale dei token dei profili di autenticazione basati su OAuth. Conservala con lo stato del tuo host Docker, ma separata da OPENCLAW_CONFIG_DIR.

I Plugin scaricabili installati archiviano il proprio stato pacchetto sotto la home OpenClaw montata, così i record di installazione dei Plugin e le radici dei pacchetti sopravvivono alla sostituzione del container. L'avvio del Gateway non genera alberi di dipendenze dei Plugin inclusi.

Per i dettagli completi sulla persistenza nelle distribuzioni VM, vedi Runtime VM Docker - Cosa persiste dove.

Punti critici di crescita del disco: monitora media/, i file JSONL di sessione, il database di stato SQLite condiviso, le radici dei pacchetti dei Plugin installati e i log file rotanti sotto /tmp/openclaw/.

Helper shell (facoltativi)

Per semplificare la gestione quotidiana di Docker, installa 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 hai installato ClawDock dal vecchio percorso raw scripts/shell-helpers/clawdock-helpers.sh, riesegui il comando di installazione sopra così il tuo file helper locale segua la nuova posizione.

Poi usa clawdock-start, clawdock-stop, clawdock-dashboard, ecc. Esegui clawdock-help per tutti i comandi. Vedi ClawDock per la guida completa agli helper.

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?

Vedi Hetzner (VPS Docker) e Runtime VM Docker per i passaggi di distribuzione su VM condivisa, inclusi integrazione dei binari nell'immagine, persistenza e aggiornamenti.

Sandbox dell'agente

Quando agents.defaults.sandbox è abilitato con il backend Docker, il gateway esegue l'esecuzione degli strumenti dell'agente (shell, lettura/scrittura di file, ecc.) all'interno di container Docker isolati, mentre il gateway stesso resta sull'host. Questo offre una barriera robusta attorno alle sessioni agente non attendibili o multi-tenant senza containerizzare l'intero gateway.

L'ambito della sandbox può essere per agente (predefinito), per sessione o condiviso. Ogni ambito ottiene il proprio workspace montato in /workspace. Puoi anche configurare criteri di autorizzazione/negazione degli strumenti, isolamento di rete, limiti di risorse e container browser.

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

• Isolamento in sandbox -- riferimento completo della sandbox
• OpenShell -- accesso shell interattivo 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      },    },  },}

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

scripts/sandbox-setup.sh

Per installazioni npm senza checkout del sorgente, vedi Isolamento in sandbox § Immagini e configurazione per i comandi docker build inline.

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

Correlati

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