Guida all'Agente Autonomo OpenClaw: Architettura, Docker e Costi

### Risposta Rapida: Cos'è OpenClaw e perché si distingue?

OpenClaw è un assistente AI personale autonomo ed open-source basato su un'architettura Gateway disaccoppiata, compatibilità con oltre 20 canali di messaggistica ed esecuzione multi-agente in sandbox. A differenza degli agenti SaaS proprietari da $20–$50 al mese, OpenClaw non ha costi di abbonamento ($0) e costa solo $0,003–$0,042 per esecuzione via API diretta.

1. Panoramica: Cosa rappresenta OpenClaw nel 2026?

Nel 2026, lo sviluppo degli agenti intelligenti si è spostato dai semplici bot di risposta a cicli di esecuzione autonomi continui, attivi 24 ore su 24 e guidati da eventi. Sebbene strumenti come Claude Code e OpenAI Codex eccellano nel terminale locale degli sviluppatori, OpenClaw (precedentemente openclaw.ai) è diventato lo standard di riferimento open-source per gli assistenti personali capaci di interagire tramite decine di canali di messaggistica, automazioni Cron e sandbox multi-agente.

I tre pilastri architetturali di OpenClaw sono:

1. Protocollo Gateway Disaccoppiato: Un demone centrale sulla porta 18789 che governa l'instradamento dei canali, la persistenza delle sessioni, lo scheduler Cron e la ricezione di webhook.
2. Supporto Multicanale Nativo: Integrazione per oltre 20 piattaforme, tra cui Telegram, WhatsApp (Baileys), Discord (Bot API + Gateway), Slack (Bolt SDK), Signal, iMessage, Matrix e WebChat.
3. Skill Modulari ed Esecuzione Sicura: Uno standard basato su Markdown (SKILL.md) sincronizzato con il registro ClawHub, combinato con isolamento in container Docker e riduzione dei privilegi POSIX.

2. Architettura di OpenClaw: Gateway, Canali e Workspace

La caratteristica fondante di OpenClaw risiede nel disaccoppiamento tra piano di controllo ed esecuzione. Il demone centrale (OpenClaw Gateway) comunica tramite WebSockets e socket Unix sia con le interfacce client sia con le API dei servizi di messaggistica.

+-----------------------------------------------------------------------------------+
|                            Canali di Messaggistica Esterni                        |
|   Telegram  |  WhatsApp  |  Discord  |  Slack  |  Signal  |  iMessage  |  Matrix  |
+-----------------------------------------------------------------------------------+
                                          | (Webhook / WebSocket / Bot API)
                                          v
+-----------------------------------------------------------------------------------+
|                            OpenClaw Gateway (Porta 18789)                         |
|  - Meccanismo DM Pairing e Allowlist       - Memoria di contesto e sessioni       |
|  - Motore di pianificazione (CronTab)     - Router per l'acquisizione di Webhook  |
|  - Ricarica a caldo (Hybrid Watch)        - Failover e commutazione tra modelli   |
+-----------------------------------------------------------------------------------+
       |                                      |                              |
       v                                      v                              v
+------------------+                  +------------------+         +-------------------+
|  Agente: Casa    |                  |  Agente: Lavoro  |         |  Agente: DevOps   |
|  - Workspace-Home|                  |  - Workspace-Work|         |  - Workspace-Ops  |
|  - SOUL.md       |                  |  - SOUL.md       |         |  - SOUL.md        |
|  - CRM Personale |                  |  - Jira / Linear |         |  - CI/CD e SSH    |
+------------------+                  +------------------+         +-------------------+
       |                                      |                              |
       +--------------------------------------+------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
|                     Livello di Esecuzione in Sandbox Multi-Agente                 |
|  - Isolamento tramite container Docker (`mode: non-main` / `mode: all`)           |
|  - Privilegi POSIX rimossi (`cap_drop: ALL`, UID senza privilegi 10001)           |
|  - Montaggi in sola lettura (`:ro`) e memoria effimera Tmpfs (`/tmp:noexec`)      |
|  - Runtime delle skill ClawHub (parser `SKILL.md` e test dinamico dei binari)     |
+-----------------------------------------------------------------------------------+

Struttura delle Directory del Workspace

~/.openclaw/
├── openclaw.json          # Configurazione principale dichiarativa (JSON5)
├── cron.json              # Attività pianificate e orari di esecuzione
├── state/                 # Database SQLite di sessione, cache e token
├── skills/                # Skill globali condivise
└── workspace/             # Directory operativa principale dell'agente
    ├── AGENTS.md          # Linee guida e vincoli comportamentali
    ├── SOUL.md            # Personalità, registro comunicativo e limiti
    ├── TOOLS.md           # Specifiche e documentazione degli strumenti locali
    └── skills/            # Skill specifiche per lo spazio di lavoro
        └── repo-analyzer/
            └── SKILL.md   # Dichiarazione operativa della skill

Comandi Fondamentali del Gateway

# Verificare lo stato del demone, porte e consumo RAM
openclaw gateway status

# Avviare il Gateway come demone in background
openclaw gateway start

# Avviare in foreground con log dettagliati di debug
openclaw gateway --port 18789 --verbose

# Eseguire la diagnostica complessiva del sistema
openclaw doctor

# Riparare in automatico permessi e cartelle mancanti
openclaw doctor --fix

3. Deploy in Produzione con Docker: Guida Pratica

Assegnare privilegi di esecuzione shell a un agente direttamente sul sistema operativo host espone l'infrastruttura a rischi inaccettabili. L'approccio standard prevede l'uso di Docker Compose con profili di sicurezza avanzati.

File docker-compose.yml

version: "3.9"

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    user: "10001:10001"
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETUID
      - SETGID
    environment:
      - NODE_ENV=production
      - OPENCLAW_HOME=/home/openclaw/.openclaw
      - OPENCLAW_STATE_DIR=/home/openclaw/.openclaw/state
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - OPENCLAW_GATEWAY_PASSWORD=${OPENCLAW_GATEWAY_PASSWORD}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
    volumes:
      - openclaw-config:/home/openclaw/.openclaw
      - openclaw-workspace:/home/openclaw/.openclaw/workspace
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "127.0.0.1:18789:18789"
    networks:
      - openclaw-net
    healthcheck:
      test: ["CMD", "openclaw", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

  openclaw-sandbox:
    image: ghcr.io/openclaw/sandbox-runner:latest
    container_name: openclaw-sandbox
    restart: always
    network_mode: none
    read_only: true
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=256m
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    volumes:
      - openclaw-workspace:/workspace:rw
    environment:
      - RUNNER_UID=10001
      - RUNNER_GID=10001

volumes:
  openclaw-config:
    driver: local
  openclaw-workspace:
    driver: local

networks:
  openclaw-net:
    driver: bridge

File openclaw.json per Produzione

{
  agents: {
    defaults: {
      workspace: "/home/openclaw/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["deepseek/deepseek-chat", "openai/gpt-5.4"],
      },
      thinking: "high",
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent",   // session | agent | shared
        dockerImage: "ghcr.io/openclaw/sandbox-runner:latest",
        timeoutSeconds: 300,
        memoryLimitMb: 1024,
      },
    },
    list: [
      {
        id: "main",
        default: true,
        workspace: "/home/openclaw/.openclaw/workspace",
      },
      {
        id: "devops",
        workspace: "/home/openclaw/.openclaw/workspace-devops",
        sandbox: { mode: "all" },
      },
    ],
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "7123456789:AAFq_example_token_secret",
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["tg:987654321"],
    },
    discord: {
      enabled: true,
      botToken: "MTI4OTexampleDiscordBotToken",
      dmPolicy: "allowlist",
      allowFrom: ["dc:382910394857291029"],
    },
  },
  cron: {
    enabled: true,
    maxConcurrentRuns: 4,
  },
  hotReload: "hybrid",
}

4. Orchestrazione Multi-Agente e Sicurezza della Sandbox

Politiche di Messaggistica (DM Policy) e Livelli di Isolamento

1. Gestione del Traffico Entrante (DM Policy):

• pairing (Predefinito): Gli utenti sconosciuti ricevono un codice univoco di accoppiamento. L'amministratore convalida tramite openclaw pairing approve .
• allowlist: Risponde unicamente agli account inclusi in allowFrom.
• open: Accessibile a chiunque (consigliato solo per bot informativi pubblici con sandbox forzato su all).
• disabled: Blocca la ricezione dei messaggi diretti per limitarsi alle notifiche Cron.

---
name: github-pr-analyzer
description: Ispeziona le pull request GitHub, esegue test unitari e redige report di revisione.
metadata: {
  "openclaw": {
    "requires": {
      "bins": ["gh", "jq", "git"],
      "env": ["GITHUB_TOKEN"],
      "config": ["sandbox.enabled"]
    },
    "os": ["linux", "darwin"],
    "always": false,
    "primaryEnv": "GITHUB_TOKEN"
  }
}
---

# GitHub PR Analyzer Skill

Quando richiamato dall'utente o da webhook:
1. Recuperare il diff della PR tramite `gh pr diff <pr_number>`.
2. Individuare i file modificati e valutare l'impatto sui test.
3. Scrivere un report strutturato in Markdown con riferimenti al codice.

# Elencare le skill disponibili
openclaw skills list

# Installare una skill dal registro ufficiale ClawHub
openclaw skills install web-researcher

# Installare direttamente da un repository GitHub
openclaw skills install git:github.com/openclaw-community/postgres-inspector@v1.4.0

# Verificare autorizzazioni e firma digitale
openclaw skills verify web-researcher

# Aggiornare tutte le skill installate
openclaw skills update --all

# Monitorare lo stato operativo del Gateway
openclaw gateway status

# Analizzare i log in tempo reale
openclaw logs --follow --lines 50

# Validare l'integrità dei file di configurazione
openclaw config validate

# Interrogare l'agente con ragionamento avanzato
openclaw agent --message "Esegui un controllo di sicurezza sulle dipendenze del codice" --thinking high

# Inviare una notifica a una chat Telegram
openclaw message send --target "tg:987654321" --message "Deploy completato con successo."