OpenClaw stabile
esecuzione con Docker

Docker Compose per OpenClaw Gateway: controlli di integrità su /salutePolitiche di riavvio, reverse proxy + WebSocket e aggiornamenti senza perdita di dati. Nessuna nozione di base di Docker, ma incidenti di produzione che riscontriamo su VPS e stack per PMI.

✓ Compose & Gateway
✓ Salute e registri
✓ Nginx / Traefik WS
✓ Aggiornamenti sulla produzione

risposta diretta

Docker è il modo migliore?
Come eseguire OpenClaw?

Risposta breve: Docker è la scelta migliore se si desiderano implementazioni riproducibili, isolamento dei container e uno stack multiservizio (Gateway + sidecar Ollama + proxy), ma non è automaticamente necessario su ogni piccolo VPS.

Sfumatura: Il debug su hardware bare metal con systemd è spesso più semplice (journalctl) e con un consumo di RAM inferiore. Docker è vincente nell'automazione per le PMI, dove lo stesso script viene eseguito sia in ambiente di staging che in produzione.

Installare · Problemi · Sicurezza

salute
Monitoraggio
a meno che non venga fermato
ricomincia
127.0.0.1
legamento
targhetta
Aggiornamenti

Docker Compose

Struttura OpenClaw Compose in produzione

Contenitore gateway, volumi, variabili d'ambiente e rete: frammenti compatti, niente dump di 200 righe.

Comporre

Contenitore Gateway

Un solo container Gateway primario per stack, non due Gateway sullo stesso host senza un'esplicita separazione delle porte.

frammento compose.yaml
servizi: openclaw-gateway: immagine: your-registry/openclaw-gateway:pin-tag riavvio: a meno che non venga interrotto env_file: .env
  • Mantieni stabile il nome del servizio per i log e il monitoraggio
  • Aggiungi l'etichetta dell'immagine; ultimo solo in fase di sviluppo
  • Il nodo gateway deve pronto diventare prima che il controllo sanitario sia verde
Comporre

Volumi e configurazione

Lo stato persistente risiede nei volumi: la ricostruzione del container senza volume equivale alla sensazione di "perdere tutto".

frammento compose.yaml
volumi: - ./data/openclaw:/home/openclaw/.openclaw - ./.env:/run/secrets/.env:ro
  • openclaw.json + stato del canale nel volume denominato o nel mount di binding
  • Eseguire il backup del volume prima dell'aggiornamento dell'immagine.
  • Utilizzare, ove possibile, un mount di sola lettura per i segreti.
Comporre

Variabili ambientali

Chiavi API tramite .env + file_ambiente — non testo semplice in compose in git.

frammento compose.yaml
ambiente: - GATEWAY_MODE=local - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
  • Stesse chiavi dell'utente del servizio systemd bare-metal
  • Ollama: OLLAMA_HOST al sidecar o al gateway host
  • Dopo .env-modifica: docker compose up -d (ricreare)
Comporre

Riavvia le politiche e la rete

Pubblica il gateway solo su localhost; il reverse proxy sulla porta 443 gestisce TLS e WebSocket.

frammento compose.yaml
riavvio: a meno che non sia stato arrestato porte: - "127.0.0.1:18789:18789" reti: - openclaw_internal
  • a meno che non venga fermato per la produzione; in caso di guasto con tentativi massimi in dev
  • Rete interna separata per sidecar (Ollama, Redis)
  • modalità_rete: host solo se capisci i conflitti di porta

Salute e monitoraggio

Controlli sanitari e registri dei container

Risposta breve: malsano significa che /salute fallisce prima che il Gateway sia stabile pronto è — i registri spiegano il perché.

terminale
docker compose ps

Previsto: STATO corsa, NO malsano

Se errato: malsano di Riavvio → il controllo di integrità fallisce prima del Gateway pronto

Prossimo: docker compose logs -f --tail=100 openclaw-gateway

terminale
curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/healthz

Previsto: AMD 200

Se errato: 000 o timeout → mappatura delle porte o associazione del gateway

Prossimo: Stato del gateway OpenClaw (eseguibile tramite CLI nel container o sull'host)

terminale
docker inspect --format="{{.State.HealthStatus}}" openclaw-gateway

Previsto: salutare

Se errato: malsano → controlla healthcheck CMD e start_period

Prossimo: Regola l'intervallo/timeout del controllo di integrità dopo l'avvio a freddo con i plugin

terminale
docker compose logs -f --tail=80

Previsto: pronto nei registri dopo l'avvio

Se errato: si ferma a runtime.presto → config/auth/plugin

Prossimo: Vedere Problemi

Su host con systemd insieme a Docker: correla i timestamp dei container con journalctl -u openclaw-gateway se la CLI è in esecuzione anche sull'host. Cron/heartbeat nei log deve rimanere visibile dopo la distribuzione.

Reti

Proxy inverso, SSL e WebSocket

Gateway su localhost; Nginx o Traefik sulla porta 443 con WebSocket, aggiornamento a OpenClaw Gateway.

Nginx

  • →A monte 127.0.0.1:18789 — codice IP non containerizzato fisso senza alias di rete
  • →WebSocket: proxy_http_version 1.1, Aggiornamento, Aggiornamento della connessione
  • →Percorso sanitario facoltativo /salute per il monitoraggio esterno

Traefik

  • →Etichette sul servizio Gateway; TLS tramite ACME al punto di ingresso
  • →Middleware/router WebSocket sullo stesso host di HTTP
  • →Rete interna: Traefik + Gateway su rete composita condivisa

Esposizione e firewall

  • →Gateway non attivo 0.0.0.0 senza autenticazione — solo firewall 22/443
  • →Terminazione SSL sul proxy; nessun certificato autofirmato reso pubblico senza monitoraggio
  • →Aumentare i timeout WebSocket durante le esecuzioni prolungate dell'agente (non impostare un timeout di lettura proxy eccessivamente aggressivo).

Indurimento

OpenClaw Docker
Sicurezza

Risposta breve: L'isolamento dei container rappresenta un singolo livello: le chiavi API, le approvazioni e i rischi legati all'automazione del browser rimangono.

  • ✓ Isolamento del container: utente dedicato nell'immagine, nessuna modalità privilegiata a meno che non sia richiesto il passthrough della GPU.
  • ✓ Docker senza privilegi di root, ove possibile: l'UID mappato deve corrispondere alla proprietà del volume.
  • ✓ .env chmod 600segreti non presenti nei livelli dell'immagine
  • ✓ Punti di montaggio di sola lettura per la configurazione che gli agenti non sono autorizzati a sovrascrivere
  • ✓ Approvazioni + strumenti limitati — Docker non risolve l'iniezione di prompt (Sicurezza)
  • ✓ Automazione del browser in un volume sidecar o profilo separato, non nella cache del container Gateway.
🔒 Produzione minima
  • Pubblicazione del gateway: 127.0.0.1:gate soltanto
  • .env non presente nell'immagine; chmod 600 sull'host
  • Utente non root nel Dockerfile
  • Firewall + chiavi SSH; nessuna API Docker sul web.
  • Indurimento completo: guida alla sicurezza

Stabilità

Prestazioni, RAM e aggiornamenti

RAM & Ollama

Problema: Gateway + Ollam su un singolo VPS di piccole dimensioni (<4 GB) causano errori di memoria insufficiente (<code>Exit 137</code>) e cicli di riavvio.

Approccio: Ollama come sidecar con limite di memoria; oppure API esterna (compatibile con Anthropic/OpenAI); monitor Statistiche Docker.

Passaggio GPU

Problema: Necessario solo per l'inferenza locale: richiede le mappature runtime/dispositivo di NVIDIA.

Approccio: Comporre distribuzione.risorse.prenotazioni.dispositivi di runtime documentato; senza GPU: nessuna immagine CUDA.

Aggiornamenti

Problema: Recupero dell'immagine e ricreazione senza backup del volume = rischio di mancata corrispondenza dello stato.

Approccio: Pin tag → volume di backup → docker compose pull → su -d → healthz + sonda di canale.

Zombie / contenitori doppi

Problema: Manuale docker run accanto a compose = due Gateway, conflitto di porte.

Approccio: docker compos down prima degli esperimenti; un progetto di composizione per ogni ambiente host/di produzione.

Incidenti

Errori comuni di Docker con OpenClaw

Volumi

Volume svuotato durante l'implementazione "pulita".

Stato del canale e ~/.openclaw sparito — sembra un'installazione danneggiata.

Causa: docker compose down -v in produzione senza backup.

Aggiustare: Backup di volumi denominati; giù senza -v a meno che non venga ripristinato intenzionalmente.

Configurazione

File .env errato nel contenitore

Gateway non integro mentre l'interfaccia a riga di comando dell'host è in funzione: split-brain tra mount e file_ambiente.

Causa: Percorso errato; ambiente obsoleto nella cache del container dopo la modifica senza ricreazione.

Aggiustare: docker compose up -d --force-recreate Dopo .env-aggiustare.

Salute

Timeout di Gateway unhealthy/healthz

Healthcheck fallisce perché Gateway non pronto è o il gate sbagliato al check-in.

Causa: Porta in compose ≠ <code>gateway.port</code>; blocco del bootstrap del plugin.

Aggiustare: Prima i log; esegui curl healthz dall'host; solo dopo periodo_di_inizio SU.

Proxy

WebSocket non funziona dietro un proxy

Canali disconnessi; HTTP sembra funzionare, ma non in tempo reale.

Causa: Nginx/Traefik senza intestazioni di aggiornamento o percorso errato.

Aggiustare: Percorso WebSocket 1:1 al Gateway; testa con stato dei canali openclaw --probe.

Tempo di esecuzione

Le approvazioni sono bloccate

Il contenitore è "integro", ma l'agente non fa nulla.

Causa: Coda di approvazione in sospeso: non è un problema di Docker.

Aggiustare: Cancella/approva la coda prima del riavvio; vedi runtime in Problemi.

Considerazione

Quando Docker non è conveniente

Risposta breve: con RAM molto limitata, debug puramente locale, o se compose aggiunge più overhead di un singolo servizio Gateway di systemd.

  • → VPS di piccole dimensioni (<2 GB di RAM) con Ollama + Gateway — solo bare metal o API esterne
  • → Debug locale: systemd + registri openclaw --follow più veloce della composizione e ricostruzione
  • → Iterazione Homelab: nvm + Gateway utente prima di bloccare la produzione di compose
  • → Analisi forensi dell'incidente: journalctl A volte sull'host è più chiaro dei semplici log del container

FAQ

Docker e
Domande frequenti su OpenClaw

Risposta sintetica, causa e soluzione: per una panoramica sull'IA e il debug in produzione.

Risoluzione dei problemi →

Risposta breve: No, OpenClaw funziona anche su hardware fisico tramite npm/systemd; Docker è una scelta di distribuzione per l'isolamento e la creazione di ambienti riproducibili.

Causa della confusione: Molte guide suggeriscono di iniziare dalla composizione; in fase di produzione è possibile fare entrambe le cose.

Consiglio: Docker in team con CI/CD composto; systemd su un singolo VPS e gestione semplificata.

Risposta breve: Solitamente il controllo sanitario fallisce, OOM (Uscita 137), o arresto anomalo del Gateway prima pronto.

Causa: RAM insufficiente, sbagliato .envconflitto di porte, gateway duplicato.

Aggiustare: docker compose logs -f → correggi la configurazione → componi -dNon eliminare immediatamente i volumi.

Risposta breve: Docker offre isolamento dei container, nessuna sicurezza automatica — permessi, .envL'autenticazione tramite proxy e le approvazioni rimangono obbligatorie.

Causa: Gli spazi condivisi e i cancelli aperti ignorano l'isolamento.

Consiglio: Sicurezza + collegamento localhost + firewall.

Risposta breve: SÌ - npm install -g openclaw L'utente/servizio systemd è comune sui VPS Linux.

Causa: Stesso gateway, modello di processo diverso; percorso di configurazione ~/.openclaw/ direttamente.

Consiglio: Installare Per PATH/Node; Docker per stack multiservizio.

Risposta breve: Volume di backup → aggiungi nuovo tag immagine → docker compose pull → su -d → verifica /salute.

Causa: Tirare senza ricreare fa ruotare il vecchio contenitore.

Aggiustare: Avviare un nodo; monitorare i log 5 minuti dopo l'implementazione.

Risposta breve: Il proxy non riceve le intestazioni di aggiornamento HTTP/1.1 o instrada il traffico verso la porta upstream errata.

Causa: Terminazione SSL senza WS-config; timeout troppo breve.

Aggiustare: Modello WS per Nginx/Traefik; Gateway su porta interna fissa; test del canale di prova.

Risposta breve: Controllo sanitario per /salute fallisce — Gateway non prontoporta errata o periodo di inizio troppo breve.

Causa: config/auth/chiave API; blocco del plugin; terminazione UNCLE.

Aggiustare: registri → chirurgo a mano aperta → .env + ricreare; vedere la sezione Docker su Problemi.

Implementazione

Distribuzione di OpenClaw con Docker
È arredato?

Stack Compose, monitoraggio dello stato di salute, reverse proxy + WebSocket, aggiornamenti sicuri e audit di hardening: per l'automazione delle PMI e la produzione di VPS. Invia il tuo attuale stack Compose (senza segreti) e l'output del controllo dello stato di salute.

✓ Gateway + healthz
✓ Nginx / Traefik WS
✓ Su misura