Eseguire OpenClaw in Docker: Una Guida alla Distribuzione Passo-Passo

Perché Docker?

Eseguire OpenClaw in Docker offre tre vantaggi chiave rispetto a un'installazione bare-metal:

1. 1.Isolamento di sicurezza: L'agente viene eseguito all'interno di un container con accesso limitato al sistema host. Se una skill malevola o un'iniezione di prompt tenta di accedere ai propri file, il confine del container limita il raggio d'azione.
2. 2.Riproducibilità: La stessa immagine Docker viene eseguita in modo identico su qualsiasi macchina — il proprio laptop, un VPS o un Raspberry Pi.
3. 3.Pulizia facile: Si desidera ricominciare da capo? Rimuovere il container e avviarne uno nuovo. Nessun file residuo, nessuna installazione Node.js compromessa.

Prerequisiti

• •Docker Desktop (macOS/Windows) o Docker Engine (Linux)
• •Docker Compose v2 (incluso con Docker Desktop)
• •Almeno 2 GB di RAM disponibili per il container
• •Una chiave API IA (Anthropic, OpenAI o altro provider supportato)

Avvio Rapido

Opzione A: Docker Compose Ufficiale (Raccomandato)

Clonare il repository OpenClaw e utilizzare la configurazione Docker integrata:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Eseguire lo script di configurazione, che crea le directory e la configurazione necessarie:

bash docker-setup.sh

• •~/.openclaw/ — configurazione, SOUL.md, chiavi API
• •~/openclaw/workspace/ — file accessibili all'agente

Eseguire la procedura guidata di onboarding all'interno del container:

docker compose run --rm openclaw-cli onboard

Seguire le istruzioni per configurare la propria chiave API e collegare una piattaforma di chat. Poi avviare il gateway:

docker compose up -d openclaw-gateway

Il proprio agente è ora in esecuzione in background.

Opzione B: Immagine Pre-costruita

Se non si desidera clonare il repository, utilizzare l'immagine pre-costruita ufficiale:

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -v ~/.openclaw:/root/.openclaw \
  -v ~/openclaw/workspace:/root/workspace \
  -p 3000:3000 \
  ghcr.io/openclaw/openclaw:latest

Riferimento Docker Compose

Ecco un docker-compose.yml annotato per l'uso in produzione:

version: "3.8"
services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"        # Web UI
    volumes:
      - ~/.openclaw:/root/.openclaw          # Config and data
      - ~/openclaw/workspace:/root/workspace  # Agent workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - TZ=Asia/Shanghai     # Set your timezone
    mem_limit: 2g            # Prevent runaway memory usage
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Creare un file .env nella stessa directory con le proprie chiavi API:

ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx

Variabili d'Ambiente

*È richiesta almeno una chiave di un provider IA.

Gestire il Proprio Container

# View logs
docker logs -f openclaw

# Stop the agent
docker compose stop

# Start the agent
docker compose up -d

# Restart after config changes
docker compose restart

# Update to latest version
docker compose pull
docker compose up -d

# Enter the container shell
docker exec -it openclaw bash

# Run CLI commands inside container
docker exec openclaw openclaw skill list
docker exec openclaw openclaw status

Rafforzamento della Sicurezza

Limitare l'accesso al filesystem

Montare solo le directory di cui il proprio agente ha realmente bisogno. Evitare di montare l'intera directory home:

volumes:
  - ~/.openclaw:/root/.openclaw:rw     # Config (read-write)
  - ~/documents:/root/docs:ro           # Documents (read-only)

Isolamento di rete

Se il proprio agente non ha bisogno di accedere ai servizi della rete locale, limitare la sua rete:

networks:
  openclaw-net:
    driver: bridge
    internal: false    # Set to true to block all external access

Filesystem root in sola lettura

Per la massima sicurezza, rendere il filesystem root in sola lettura e permettere le scritture solo in percorsi specifici:

read_only: true
tmpfs:
  - /tmp
  - /run

Aggiornamento

OpenClaw rilascia aggiornamenti frequentemente. Per aggiornare la propria distribuzione Docker:

docker compose pull           # Pull latest image
docker compose up -d          # Recreate container with new image
docker image prune -f         # Clean up old images

La propria configurazione e i dati persistono nei volumi montati, quindi gli aggiornamenti non sono distruttivi.

Risoluzione dei Problemi

Il container si blocca immediatamente: Controllare i log con docker logs openclaw. Cause comuni: chiavi API mancanti, memoria insufficiente o conflitti di porta.

Il codice QR di WhatsApp non viene mostrato: Eseguire l'onboarding in modalità interattiva: docker compose run --rm openclaw-cli onboard. Il codice QR necessita di un terminale che supporti il rendering.

Errori di permessi sui volumi montati: Assicurarsi che le directory host esistano e siano di proprietà del proprio utente: mkdir -p ~/.openclaw ~/openclaw/workspace.

Uso elevato della memoria: Impostare mem_limit: 2g in docker-compose.yml per impedire al container di consumare RAM eccessiva.

Per maggiori dettagli, consultare la documentazione Docker ufficiale e il docker-compose.yml nel repository.