Containers

Docker

Edit source

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 usa e getta oppure eseguire OpenClaw su un host senza installazioni locali.
No: stai lavorando sulla tua macchina 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 uscita 137)
Spazio su disco sufficiente per immagini e log
Se esegui su un VPS/host pubblico, rivedi Rafforzamento della sicurezza per l'esposizione di rete, in particolare la policy firewall Docker DOCKER-USER.

Gateway containerizzato

Crea l'immagine

Dalla radice del repository, esegui lo script di configurazione:

bash

./scripts/docker/setup.sh

Questo crea localmente l'immagine del Gateway. Per usare invece un'immagine precompilata:

bash

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

Le immagini precompilate sono pubblicate nel GitHub Container Registry. Tag comuni: main, latest, <version> (ad es. 2026.2.26).

Completa la configurazione iniziale

Lo script di configurazione esegue automaticamente la configurazione iniziale. Eseguirà queste operazioni:

richiedere le chiavi API del provider
generare un token del Gateway e scriverlo in .env
creare la directory della chiave segreta dell'auth-profile
avviare il Gateway tramite Docker Compose

Durante la configurazione, la configurazione iniziale prima dell'avvio e le scritture di configurazione passano direttamente tramite openclaw-gateway. openclaw-cli è per i comandi che esegui dopo che il container del Gateway esiste già.

Apri la UI di controllo

Apri http://127.0.0.1:18789/ nel browser e incolla il segreto condiviso configurato in Settings. Per impostazione predefinita lo script di configurazione scrive un token in .env; se cambi la configurazione del container per usare l'autenticazione con password, usa invece quella password.

Ti serve di nuovo l'URL?

bash

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

Configura i canali (opzionale)

Usa il container CLI per aggiungere canali di messaggistica:

bash

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

Documentazione: WhatsApp, Telegram, Discord

Flusso manuale

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

bash

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 d'ambiente

Lo script di configurazione accetta queste variabili d'ambiente opzionali:

Variabile	Scopo
`OPENCLAW_IMAGE`	Usa un'immagine remota invece di crearla localmente
`OPENCLAW_DOCKER_APT_PACKAGES`	Installa pacchetti apt aggiuntivi durante la build (separati da spazi)
`OPENCLAW_EXTENSIONS`	Include helper Plugin in bundle selezionati durante la build
`OPENCLAW_EXTRA_MOUNTS`	Bind mount aggiuntivi dell'host (`source:target[:opts]` separati da virgole)
`OPENCLAW_HOME_VOLUME`	Persiste `/home/node` in un volume Docker nominato
`OPENCLAW_SANDBOX`	Abilita esplicitamente il bootstrap sandbox (`1`, `true`, `yes`, `on`)
`OPENCLAW_SKIP_ONBOARDING`	Salta il passaggio interattivo di configurazione iniziale (`1`, `true`, `yes`, `on`)
`OPENCLAW_DOCKER_SOCKET`	Sostituisce il percorso del socket Docker
`OPENCLAW_DISABLE_BONJOUR`	Disabilita l'annuncio Bonjour/mDNS (predefinito a `1` per Docker)
`OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS`	Disabilita gli overlay bind-mount del sorgente dei Plugin in bundle
`OTEL_EXPORTER_OTLP_ENDPOINT`	Endpoint collector OTLP/HTTP condiviso per l'esportazione OpenTelemetry
`OTEL_EXPORTER_OTLP_*_ENDPOINT`	Endpoint OTLP specifici per segnale per tracce, metriche o log
`OTEL_EXPORTER_OTLP_PROTOCOL`	Override del protocollo OTLP. Oggi è supportato solo `http/protobuf`
`OTEL_SERVICE_NAME`	Nome del servizio usato per le risorse OpenTelemetry
`OTEL_SEMCONV_STABILITY_OPT_IN`	Abilita esplicitamente gli attributi semantici GenAI sperimentali più recenti
`OPENCLAW_OTEL_PRELOADED`	Salta l'avvio di un secondo SDK OpenTelemetry quando uno è già precaricato

I maintainer possono testare il sorgente di un Plugin in bundle 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 sostituisce il bundle compilato corrispondente /app/dist/extensions/synology-chat per lo stesso ID Plugin.

Osservabilità

L'esportazione 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 in bundle sia disponibile dentro l'immagine, includi le sue dipendenze runtime:

bash

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'esportazione. Le immagini personalizzate create dai sorgenti possono comunque includere il sorgente del Plugin locale con OPENCLAW_EXTENSIONS=diagnostics-otel. Per abilitare l'esportazione, consenti e abilita il Plugin diagnostics-otel nella configurazione, quindi imposta diagnostics.otel.enabled=true oppure usa l'esempio di configurazione in Esportazione OpenTelemetry. Gli header di autenticazione del collector sono configurati tramite diagnostics.otel.headers, non tramite variabili d'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:

text

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

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

Controlli di integrità

Endpoint probe del container (autenticazione non richiesta):

bash

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 interroga /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à approfondito autenticato:

bash

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

LAN e loopback

scripts/docker/setup.sh imposta per impostazione predefinita OPENCLAW_GATEWAY_BIND=lan così l'accesso dall'host a http://127.0.0.1:18789 funziona con la pubblicazione della porta Docker.

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

Provider locali dell'host

Quando OpenClaw viene eseguito in Docker, 127.0.0.1 dentro il container è il container stesso, non la tua macchina host. Usa host.docker.internal per i provider IA che girano sull'host:

Provider	URL predefinito dell'host	URL di configurazione Docker
LM Studio	`http://127.0.0.1:1234`	`http://host.docker.internal:1234`
Ollama	`http://127.0.0.1:11434`	`http://host.docker.internal:11434`

La configurazione Docker in bundle usa quegli URL dell'host come valori predefiniti di configurazione iniziale per LM Studio e Ollama, e docker-compose.yml mappa host.docker.internal al gateway host di Docker per Linux Docker Engine. Docker Desktop fornisce già lo stesso hostname su macOS e Windows.

Anche i servizi dell'host devono restare in ascolto su un indirizzo raggiungibile da Docker:

bash

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 personalmente la stessa mappatura dell'host, ad esempio --add-host=host.docker.internal:host-gateway.

Bonjour / mDNS

La rete bridge Docker di solito non inoltra in modo affidabile il multicast Bonjour/mDNS (224.0.0.251:5353). Per questo la configurazione Compose in bundle imposta per impostazione predefinita OPENCLAW_DISABLE_BONJOUR=1 così il Gateway non entra in crash loop né riavvia ripetutamente l'annuncio quando il bridge scarta il traffico multicast.

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

Per problemi comuni e risoluzione, vedi Rilevamento Bonjour.

Archiviazione e persistenza

Docker Compose esegue bind-mount di 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 in bundle ripiega sotto ${HOME}, oppure su /tmp quando anche HOME manca. Questo impedisce a docker compose up di emettere una specifica volume con sorgente vuota in ambienti minimi.

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/API-key del provider archiviata
.env per segreti runtime basati su env come OPENCLAW_GATEWAY_TOKEN

La directory della chiave segreta dell'auth-profile archivia la chiave di crittografia locale usata per il materiale dei token del profilo di autenticazione basato su OAuth. Tienila insieme allo stato del tuo host Docker, ma separata da OPENCLAW_CONFIG_DIR.

I Plugin scaricabili installati memorizzano lo stato del loro pacchetto nella home OpenClaw montata, quindi 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, consulta Runtime Docker VM - Cosa persiste dove.

Punti critici di crescita del disco: monitora media/, i file JSONL delle sessioni, cron/runs/*.jsonl, le radici dei pacchetti Plugin installati e i log su file a rotazione sotto /tmp/openclaw/.

Helper shell (facoltativi)

Per una gestione quotidiana di Docker più semplice, installa ClawDock:

bash

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 in modo che 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. Consulta ClawDock per la guida completa agli helper.

Abilitare la sandbox dell'agente per il Gateway Docker

bash

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

Percorso socket personalizzato (per esempio Docker rootless):

bash

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

Lo script monta docker.sock solo dopo il superamento dei prerequisiti della sandbox. Se la configurazione della sandbox non può essere completata, lo script reimposta agents.defaults.sandbox.mode su off. I turni in modalità codice di Codex restano comunque vincolati al workspace-write di Codex mentre la sandbox OpenClaw è attiva; non montare il socket Docker dell'host nei container sandbox degli agenti.

Automazione / CI (non interattiva)

Disabilita l'allocazione pseudo-TTY di Compose con -T:

bash

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

Nota sulla sicurezza della rete condivisa

openclaw-cli usa network_mode: "service:openclaw-gateway" in modo che i comandi CLI possano raggiungere il Gateway su 127.0.0.1. Trattalo come un confine di fiducia condiviso. La configurazione compose rimuove NET_RAW/NET_ADMIN e abilita no-new-privileges sia su openclaw-gateway sia su openclaw-cli.

Errori DNS di Docker Desktop in openclaw-cli

Alcune configurazioni di Docker Desktop non riescono a risolvere DNS dal sidecar openclaw-cli sulla rete condivisa dopo la rimozione di NET_RAW, manifestandosi come EAI_AGAIN durante comandi basati su npm come openclaw plugins install. Mantieni il file compose predefinito rafforzato per il normale funzionamento del Gateway. L'override locale qui sotto allenta la postura di sicurezza del container CLI ripristinando le capability predefinite di Docker, quindi usalo solo per il comando CLI una tantum che necessita di accesso al registro dei pacchetti, non come invocazione Compose predefinita:

bash

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>

Se hai già creato un container openclaw-cli di lunga durata, ricrealo con lo stesso override. docker compose exec e docker exec non possono modificare le capability Linux su un container già creato.

Permessi ed EACCES

L'immagine viene eseguita come node (uid 1000). Se vedi errori di permesso su /home/node/.openclaw, assicurati che i bind mount dell'host siano di proprietà dell'uid 1000:

bash

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

La stessa mancata corrispondenza può comparire come un avviso di Plugin, per esempio blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) seguito da plugin present but blocked. Significa che l'uid del processo e il proprietario della directory Plugin montata non coincidono. Preferisci eseguire il container con l'uid predefinito 1000 e correggere la proprietà del bind mount. Esegui chown di /path/to/openclaw-config/npm a root:root solo se intendi eseguire OpenClaw come root a lungo termine.

Ricompilazioni più rapide

Ordina il Dockerfile in modo che i layer delle dipendenze vengano memorizzati nella cache. Questo evita di rieseguire pnpm install a meno che i lockfile non cambino:

dockerfile

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

Opzioni container per utenti esperti

L'immagine predefinita dà priorità alla sicurezza e viene eseguita come node non root. Per un container più completo:

Persisti /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
Integra dipendenze di sistema: export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
Integra Playwright Chromium: export OPENCLAW_INSTALL_BROWSER=1

Oppure installa i browser Playwright in un volume persistente:

bash

docker compose run --rm openclaw-cli \  node /app/node_modules/playwright-core/cli.js install chromium

Persisti i download del browser: usa OPENCLAW_HOME_VOLUME o OPENCLAW_EXTRA_MOUNTS. OpenClaw rileva automaticamente Chromium gestito da Playwright nell'immagine Docker su Linux.

OAuth OpenAI Codex (Docker headless)

Se scegli OAuth OpenAI Codex nella procedura guidata, si apre un URL del browser. In Docker o in configurazioni headless, copia l'URL di reindirizzamento completo su cui arrivi e incollalo di nuovo nella procedura guidata per completare l'autenticazione.

Metadati dell'immagine di base

L'immagine runtime Docker principale usa node:24-bookworm-slim e include tini come processo init dell'entrypoint (PID 1) per garantire che i processi zombie vengano raccolti e che i segnali siano gestiti correttamente nei container di lunga durata. Pubblica annotazioni OCI dell'immagine di base, incluse org.opencontainers.image.base.name, org.opencontainers.image.source e altre. Il digest di base Node viene aggiornato tramite PR Dependabot per l'immagine di base Docker; le build di rilascio non eseguono un layer di upgrade della distribuzione. Consulta annotazioni immagine OCI.

In esecuzione su una VPS?

Consulta Hetzner (Docker VPS) e Runtime Docker VM per i passaggi condivisi di distribuzione VM, inclusi integrazione dei binari, persistenza e aggiornamenti.

Sandbox agente

Quando agents.defaults.sandbox è abilitato con il backend Docker, il Gateway esegue l'esecuzione degli strumenti dell'agente (shell, lettura/scrittura file, ecc.) dentro container Docker isolati mentre il Gateway stesso resta sull'host. Questo offre una barriera netta intorno a 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 riceve il proprio workspace montato in /workspace. Puoi anche configurare policy allow/deny per gli strumenti, isolamento della rete, limiti di risorse e container browser.

Per configurazione completa, immagini, note di sicurezza e profili multi-agente, consulta:

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

Abilitazione rapida

json5

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

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

bash

scripts/sandbox-setup.sh

Per installazioni npm senza checkout sorgente, consulta Sandboxing § Immagini e configurazione per comandi docker build inline.

Risoluzione dei problemi

Immagine mancante o container sandbox che non si avvia

Costruisci l'immagine sandbox con scripts/sandbox-setup.sh (checkout sorgente) o con il comando docker build inline da Sandboxing § Immagini e configurazione (installazione npm), oppure imposta agents.defaults.sandbox.docker.image sulla tua immagine personalizzata. I container vengono creati automaticamente per sessione su richiesta.

Errori di permesso nella sandbox

Imposta docker.user su un UID:GID che corrisponde alla proprietà del workspace montato, oppure esegui chown della cartella workspace.

Strumenti personalizzati non trovati nella sandbox

OpenClaw esegue i comandi con sh -lc (login shell), che carica /etc/profile e può reimpostare PATH. Imposta docker.env.PATH per anteporre i percorsi dei tuoi strumenti personalizzati, oppure aggiungi uno script sotto /etc/profile.d/ nel tuo Dockerfile.

Terminato per OOM durante la build dell'immagine (exit 137)

La VM richiede almeno 2 GB di RAM. Usa una classe di macchina più grande e riprova.

Non autorizzato o abbinamento richiesto nella UI di controllo

Recupera un nuovo link dashboard e approva il dispositivo browser:

bash

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

Maggiori dettagli: Dashboard, Dispositivi.

Il target Gateway mostra ws://172.x.x.x o errori di abbinamento dalla CLI Docker

Reimposta modalità e bind del Gateway:

bash

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

Was this useful?