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 lavorando sulla tua macchina e vuoi solo il ciclo di sviluppo più rapido. Usa invece il flusso di installazione normale.
• 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 può 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, consulta Rafforzamento della sicurezza per l'esposizione in 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

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

# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

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

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

# Flusso manuale

Se preferisci eseguire ogni passaggio autonomamente 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-daemon
docker 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:

I maintainer possono testare il sorgente di Plugin in bundle rispetto a un'immagine pacchettizzata montando una directory sorgente Plugin sopra il suo 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 rendere disponibile nell'immagine l'exporter OpenTelemetry in bundle, includi le sue dipendenze di 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'esportazione. Le immagini personalizzate create da sorgente possono comunque includere il sorgente 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:

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

La route è protetta dall'autenticazione Gateway. Non esporre una porta /metrics pubblica 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   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

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

Snapshot approfondito di integrità autenticato:

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

# LAN vs loopback

scripts/docker/setup.sh imposta per impostazione predefinita OPENCLAW_GATEWAY_BIND=lan così 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 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 AI che vengono eseguiti sull'host:

Il setup Docker in bundle usa questi URL host come impostazioni predefinite di onboarding 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 host devono rimanere in ascolto su un indirizzo raggiungibile da Docker:

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

Se usi un file Compose o un comando docker run personalizzato, aggiungi tu stesso la stessa mappatura 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 il setup Compose in bundle imposta per impostazione predefinita OPENCLAW_DISABLE_BONJOUR=1, così il Gateway non entra in crash-loop né riavvia ripetutamente la pubblicazione quando il bridge scarta il traffico multicast.

Usa l'URL Gateway pubblicato, Tailscale o DNS-SD wide-area per gli 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 insidie e risoluzione dei problemi, vedi Rilevamento Bonjour.

# Archiviazione e persistenza

Docker Compose monta con bind OPENCLAW_CONFIG_DIR su /home/node/.openclaw e OPENCLAW_WORKSPACE_DIR su /home/node/.openclaw/workspace, così quei percorsi sopravvivono alla sostituzione del container. Quando una delle due variabili non è impostata, il docker-compose.yml in bundle ripiega su ${HOME}/.openclaw (e ${HOME}/.openclaw/workspace per il mount dello spazio di lavoro), oppure su /tmp/.openclaw quando manca anche HOME. Questo evita che docker compose up emetta una specifica di 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/chiave API dei provider archiviata
• .env per segreti di runtime basati su env come OPENCLAW_GATEWAY_TOKEN

I Plugin scaricabili installati salvano il loro stato pacchetto sotto la home OpenClaw montata, quindi i record di installazione Plugin e le root dei pacchetti sopravvivono alla sostituzione del container. L'avvio del Gateway non genera alberi di dipendenze per i Plugin in bundle.

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 delle sessioni, cron/runs/*.jsonl, le radici dei pacchetti Plugin installati e i log su file a rotazione in /tmp/openclaw/.

# Helper shell (opzionali)

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.sh
echo '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 qui sopra affinché il 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.

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

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

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

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

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

# Esecuzione su un VPS?

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

# Sandbox agenti

Quando agents.defaults.sandbox è abilitato con il backend Docker, il gateway esegue gli strumenti dell’agente (shell, lettura/scrittura file, ecc.) all’interno di container Docker isolati, mentre il gateway stesso resta sull’host. Questo offre una barriera rigida attorno 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 di rete, limiti di risorse e container browser.

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

• Sandboxing -- riferimento completo per la 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
      },
    },
  },
}

Costruisci l’immagine sandbox predefinita (da un checkout dei sorgenti):

scripts/sandbox-setup.sh

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

# Risoluzione dei problemi

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>

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 installazione — tutti i metodi di installazione
• Podman — alternativa Podman a Docker
• ClawDock — configurazione community Docker Compose
• Aggiornamento — mantenere OpenClaw aggiornato
• Configurazione — configurazione del gateway dopo l’installazione