Docker (opzionale)

Docker e opzionale. Usalo solo se vuoi un gateway containerizzato o per validare il flusso Docker.

Docker fa al caso mio?

  • Si: vuoi un ambiente gateway isolato e usa-e-getta, oppure vuoi eseguire OpenClaw su un host senza installazioni locali.
  • No: stai lavorando sulla tua macchina e vuoi il ciclo di sviluppo piu veloce. Usa il flusso di installazione normale.
  • Nota sul sandboxing: il sandboxing degli agenti usa Docker, ma non richiede che l’intero gateway giri in Docker. Vedi Sandboxing.

Questa guida copre:

  • Gateway Containerizzato (OpenClaw completo in Docker)
  • Sandbox Agente per Sessione (gateway su host + strumenti agente isolati in Docker)

Dettagli sandboxing: Sandboxing

Requisiti

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

Gateway Containerizzato (Docker Compose)

Avvio rapido (consigliato)

Nota: I valori predefiniti Docker qui presuppongono modalita bind (lan/loopback), non alias host. Usa valori di modalita bind in gateway.bind (ad esempio lan o loopback), non alias host come 0.0.0.0 o localhost.

Dalla root del repository:

./docker-setup.sh

Questo script:

  • costruisce l’immagine del gateway localmente (o scarica un’immagine remota se OPENCLAW_IMAGE e impostato)
  • esegue il wizard di onboarding
  • stampa suggerimenti opzionali per la configurazione del provider
  • avvia il gateway tramite Docker Compose
  • genera un token gateway e lo scrive in .env

Variabili d’ambiente opzionali:

  • OPENCLAW_IMAGE — usa un’immagine remota invece di costruirla localmente (es. ghcr.io/openclaw/openclaw:latest)
  • OPENCLAW_DOCKER_APT_PACKAGES — installa pacchetti apt extra durante la build
  • OPENCLAW_EXTENSIONS — pre-installa le dipendenze delle estensioni al momento della build (nomi separati da spazi, es. diagnostics-otel matrix)
  • OPENCLAW_EXTRA_MOUNTS — aggiungi bind mount host extra
  • OPENCLAW_HOME_VOLUME — mantieni /home/node in un volume nominato
  • OPENCLAW_SANDBOX — abilita il bootstrap sandbox del gateway Docker. Solo valori esplicitamente positivi lo abilitano: 1, true, yes, on
  • OPENCLAW_INSTALL_DOCKER_CLI — build arg passthrough per build di immagini locali (1 installa Docker CLI nell’immagine). docker-setup.sh lo imposta automaticamente quando OPENCLAW_SANDBOX=1 per build locali.
  • OPENCLAW_DOCKER_SOCKET — sovrascrivi il percorso del socket Docker (predefinito: DOCKER_HOST=unix://... path, altrimenti /var/run/docker.sock)

Al termine:

  • Apri http://127.0.0.1:18789/ nel tuo browser.
  • Incolla il token nella Control UI (Impostazioni → token).
  • Serve di nuovo l’URL? Esegui docker compose run --rm openclaw-cli dashboard --no-open.

Abilita sandbox agente per gateway Docker (opt-in)

docker-setup.sh puo anche inizializzare agents.defaults.sandbox.* per deployment Docker.

Abilita con:

export OPENCLAW_SANDBOX=1
./docker-setup.sh

Percorso socket personalizzato (ad esempio Docker rootless):

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

Usa un’immagine remota (salta la build locale)

Le immagini pre-costruite ufficiali sono pubblicate su:

Usa il nome immagine ghcr.io/openclaw/openclaw (non immagini Docker Hub con nomi simili).

Tag comuni:

  • main — ultima build da main
  • <version> — build da tag di rilascio (ad esempio 2026.2.26)
  • latest — ultimo tag di rilascio stabile

Per default lo script di setup costruisce l’immagine dal sorgente. Per scaricare un’immagine pre-costruita, imposta OPENCLAW_IMAGE prima di eseguire lo script:

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

Flusso manuale (compose)

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

Token Control UI + pairing (Docker)

Se vedi “unauthorized” o “disconnected (1008): pairing required”, ottieni un link dashboard aggiornato e approva il dispositivo browser:

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>

Maggiori dettagli: Dashboard, Dispositivi.

Configurazione canali (opzionale)

Usa il container CLI per configurare i canali, poi riavvia il gateway se necessario.

WhatsApp (QR):

docker compose run --rm openclaw-cli channels login

Telegram (token bot):

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord (token bot):

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Documentazione: WhatsApp, Telegram, Discord

Health check

Endpoint di verifica del container (nessuna autenticazione richiesta):

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

Alias: /health e /ready.

LAN vs loopback (Docker Compose)

docker-setup.sh imposta OPENCLAW_GATEWAY_BIND=lan di default cosi l’accesso dall’host a http://127.0.0.1:18789 funziona con la pubblicazione porte Docker.

  • lan (predefinito): il browser host + CLI host possono raggiungere la porta gateway pubblicata.
  • loopback: solo i processi all’interno del namespace di rete del container possono raggiungere il gateway direttamente; l’accesso tramite porta pubblicata sull’host potrebbe non funzionare.

Permessi + EACCES

L’immagine gira come node (uid 1000). Se vedi errori di permesso su /home/node/.openclaw, assicurati che i bind mount dell’host siano di proprieta dell’uid 1000.

Esempio (host Linux):

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

Modello di storage

  • Dati host persistenti: Docker Compose monta in bind OPENCLAW_CONFIG_DIR su /home/node/.openclaw e OPENCLAW_WORKSPACE_DIR su /home/node/.openclaw/workspace, cosi questi percorsi sopravvivono alla sostituzione del container.
  • tmpfs sandbox effimero: quando agents.defaults.sandbox e abilitato, i container sandbox usano tmpfs per /tmp, /var/tmp e /run. Questi mount sono separati dallo stack Compose principale e scompaiono con il container sandbox.

Sandbox Agente (gateway su host + strumenti Docker)

Approfondimento: Sandboxing

Cosa fa

Quando agents.defaults.sandbox e abilitato, le sessioni non principali eseguono strumenti all’interno di un container Docker. Il gateway resta sul tuo host, ma l’esecuzione degli strumenti e isolata:

  • scope: "agent" di default (un container + workspace per agente)
  • scope: "session" per isolamento per sessione
  • cartella workspace per scope montata in /workspace
  • accesso opzionale al workspace dell’agente (agents.defaults.sandbox.workspaceAccess)
  • policy di strumenti allow/deny (deny vince)

Abilita il sandboxing

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent e il default)
        workspaceAccess: "none", // none | ro | rw
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
        },
      },
    },
  },
}

Costruisci l’immagine sandbox predefinita

scripts/sandbox-setup.sh

Questo costruisce openclaw-sandbox:bookworm-slim usando Dockerfile.sandbox.

Policy strumenti (allow/deny)

  • deny vince su allow.
  • Se allow e vuoto: tutti gli strumenti (tranne deny) sono disponibili.
  • Se allow non e vuoto: solo gli strumenti in allow sono disponibili (meno deny).

Strategia di pulizia

Due parametri:

  • prune.idleHours: rimuovi container non usati in X ore (0 = disabilita)
  • prune.maxAgeDays: rimuovi container piu vecchi di X giorni (0 = disabilita)

Risoluzione problemi

  • Immagine mancante: costruisci con scripts/sandbox-setup.sh o imposta agents.defaults.sandbox.docker.image.
  • Container non in esecuzione: si crea automaticamente per sessione su richiesta.
  • Errori di permesso nel sandbox: imposta docker.user su un UID:GID che corrisponda alla proprieta del workspace montato.
arrow_back
Precedente
Installer
Successivo
Podman
arrow_forward