Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

1

Crea l'immagine

Dalla radice del repository, esegui lo script di configurazione:
./scripts/docker/setup.sh
Questo crea localmente l’immagine del Gateway. Per usare invece un’immagine precompilata:
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).
2

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à.
3

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?
docker compose run --rm openclaw-cli dashboard --no-open
4

Configura i canali (opzionale)

Usa il container CLI per aggiungere canali di messaggistica:
# 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>"
Documentazione: WhatsApp, Telegram, Discord

​
Flusso manuale

Se preferisci eseguire ogni passaggio personalmente 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
Esegui docker compose dalla radice del repository. Se hai abilitato OPENCLAW_EXTRA_MOUNTS o OPENCLAW_HOME_VOLUME, lo script di configurazione scrive docker-compose.extra.yml; includilo con -f docker-compose.yml -f docker-compose.extra.yml.
Poiché openclaw-cli condivide il namespace di rete di openclaw-gateway, è uno strumento successivo all’avvio. Prima di docker compose up -d openclaw-gateway, esegui la configurazione iniziale e le scritture di configurazione al momento della configurazione tramite openclaw-gateway con --no-deps --entrypoint node.

​
Variabili d’ambiente

Lo script di configurazione accetta queste variabili d’ambiente opzionali:
VariabileScopo
OPENCLAW_IMAGEUsa un’immagine remota invece di crearla localmente
OPENCLAW_DOCKER_APT_PACKAGESInstalla pacchetti apt aggiuntivi durante la build (separati da spazi)
OPENCLAW_EXTENSIONSInclude helper Plugin in bundle selezionati durante la build
OPENCLAW_EXTRA_MOUNTSBind mount aggiuntivi dell’host (source:target[:opts] separati da virgole)
OPENCLAW_HOME_VOLUMEPersiste /home/node in un volume Docker nominato
OPENCLAW_SANDBOXAbilita esplicitamente il bootstrap sandbox (1, true, yes, on)
OPENCLAW_SKIP_ONBOARDINGSalta il passaggio interattivo di configurazione iniziale (1, true, yes, on)
OPENCLAW_DOCKER_SOCKETSostituisce il percorso del socket Docker
OPENCLAW_DISABLE_BONJOURDisabilita l’annuncio Bonjour/mDNS (predefinito a 1 per Docker)
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYSDisabilita gli overlay bind-mount del sorgente dei Plugin in bundle
OTEL_EXPORTER_OTLP_ENDPOINTEndpoint collector OTLP/HTTP condiviso per l’esportazione OpenTelemetry
OTEL_EXPORTER_OTLP_*_ENDPOINTEndpoint OTLP specifici per segnale per tracce, metriche o log
OTEL_EXPORTER_OTLP_PROTOCOLOverride del protocollo OTLP. Oggi è supportato solo http/protobuf
OTEL_SERVICE_NAMENome del servizio usato per le risorse OpenTelemetry
OTEL_SEMCONV_STABILITY_OPT_INAbilita esplicitamente gli attributi semantici GenAI sperimentali più recenti
OPENCLAW_OTEL_PRELOADEDSalta 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: 
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: 
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): 
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 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: 
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.
Usa i valori della modalità bind in gateway.bind (lan / loopback / custom / tailnet / auto), non alias dell’host come 0.0.0.0 o 127.0.0.1.

​
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:
ProviderURL predefinito dell’hostURL di configurazione Docker
LM Studiohttp://127.0.0.1:1234http://host.docker.internal:1234
Ollamahttp://127.0.0.1:11434http://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: 
lms server start --port 1234 --bind 0.0.0.0
OLLAMA_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: 
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 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. 
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh
Percorso socket personalizzato (per esempio Docker rootless):
export OPENCLAW_SANDBOX=1
export 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.
Disabilita l’allocazione pseudo-TTY di Compose con -T:
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json
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.
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:
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.
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:
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.
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:
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"]
L’immagine predefinita dà priorità alla sicurezza e viene eseguita come node non root. Per un container più completo:
  1. Persisti /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
  2. Integra dipendenze di sistema: export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
  3. Integra Playwright Chromium: export OPENCLAW_INSTALL_BROWSER=1
  4. Oppure installa i browser Playwright in un volume persistente: 
    docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium
  5. 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.
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.
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:

​
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 sorgente): 
scripts/sandbox-setup.sh
Per installazioni npm senza checkout sorgente, consulta Sandboxing § Immagini e configurazione per comandi docker build inline.

​
Risoluzione dei problemi

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.
Imposta docker.user su un UID:GID che corrisponde alla proprietà del workspace montato, oppure esegui chown della cartella workspace.
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.
La VM richiede almeno 2 GB di RAM. Usa una classe di macchina più grande e riprova.
Recupera un nuovo link dashboard 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.
Reimposta modalità e bind del Gateway:
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