Installazione con Ansible

Il modo consigliato per distribuire OpenClaw su server di produzione e tramite openclaw-ansible — un installer automatizzato con architettura security-first.

Avvio rapido

Installazione con un solo comando:

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

Guida completa: github.com/openclaw/openclaw-ansible

Il repo openclaw-ansible e la fonte autorevole per il deploy con Ansible. Questa pagina e solo una panoramica rapida.

Cosa ottieni

  • Sicurezza firewall-first: UFW + isolamento Docker (solo SSH + Tailscale accessibili)
  • VPN Tailscale: accesso remoto sicuro senza esporre servizi pubblicamente
  • Docker: container sandbox isolati, binding solo su localhost
  • Difesa in profondita: architettura di sicurezza a 4 livelli
  • Setup con un comando: deploy completo in pochi minuti
  • Integrazione systemd: avvio automatico al boot con hardening

Requisiti

  • SO: Debian 11+ o Ubuntu 20.04+
  • Accesso: privilegi root o sudo
  • Rete: connessione Internet per l’installazione dei pacchetti
  • Ansible: 2.14+ (installato automaticamente dallo script di avvio rapido)

Cosa viene installato

Il playbook Ansible installa e configura:

  1. Tailscale (VPN mesh per accesso remoto sicuro)
  2. Firewall UFW (solo porte SSH + Tailscale)
  3. Docker CE + Compose V2 (per i sandbox degli agent)
  4. Node.js 24 + pnpm (dipendenze runtime; Node 22 LTS, attualmente 22.16+, resta supportato per compatibilita)
  5. OpenClaw (installazione sull’host, non containerizzata)
  6. Servizio systemd (avvio automatico con hardening di sicurezza)

Nota: il gateway viene eseguito direttamente sull’host (non in Docker), ma i sandbox degli agent usano Docker per l’isolamento. Consulta Sandboxing per i dettagli.

Configurazione post-installazione

Al termine dell’installazione, passa all’utente openclaw:

sudo -i -u openclaw

Lo script post-installazione ti guidera attraverso:

  1. Wizard di onboarding: configura le impostazioni di OpenClaw
  2. Login provider: connetti WhatsApp/Telegram/Discord/Signal
  3. Test del gateway: verifica l’installazione
  4. Setup Tailscale: connettiti alla tua mesh VPN

Comandi rapidi

# Controlla lo stato del servizio
sudo systemctl status openclaw

# Visualizza i log in tempo reale
sudo journalctl -u openclaw -f

# Riavvia il gateway
sudo systemctl restart openclaw

# Login provider (esegui come utente openclaw)
sudo -i -u openclaw
openclaw channels login

Architettura di sicurezza

Difesa a 4 livelli

  1. Firewall (UFW): solo SSH (22) + Tailscale (41641/udp) esposti pubblicamente
  2. VPN (Tailscale): gateway accessibile solo tramite mesh VPN
  3. Isolamento Docker: catena iptables DOCKER-USER impedisce l’esposizione di porte esterne
  4. Hardening systemd: NoNewPrivileges, PrivateTmp, utente non privilegiato

Verifica

Testa la superficie di attacco esterna:

nmap -p- YOUR_SERVER_IP

Dovresti vedere solo la porta 22 (SSH) aperta. Tutti gli altri servizi (gateway, Docker) sono bloccati.

Disponibilita di Docker

Docker e installato per i sandbox degli agent (esecuzione isolata degli strumenti), non per eseguire il gateway stesso. Il gateway si collega solo a localhost ed e accessibile tramite VPN Tailscale.

Consulta Multi-Agent Sandbox & Tools per la configurazione dei sandbox.

Installazione manuale

Se preferisci il controllo manuale rispetto all’automazione:

# 1. Installa i prerequisiti
sudo apt update && sudo apt install -y ansible git

# 2. Clona il repository
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible

# 3. Installa le collection Ansible
ansible-galaxy collection install -r requirements.yml

# 4. Esegui il playbook
./run-playbook.sh

# Oppure esegui direttamente (poi lancia manualmente /tmp/openclaw-setup.sh dopo)
# ansible-playbook playbook.yml --ask-become-pass

Aggiornamento di OpenClaw

L’installer Ansible configura OpenClaw per gli aggiornamenti manuali. Consulta Aggiornamento per il flusso di aggiornamento standard.

Per rieseguire il playbook Ansible (ad esempio per modifiche alla configurazione):

cd openclaw-ansible
./run-playbook.sh

Nota: il playbook e idempotente e puo essere eseguito piu volte senza problemi.

Risoluzione problemi

Il firewall blocca la mia connessione

Se rimani bloccato fuori:

  • Assicurati di poter accedere prima tramite VPN Tailscale
  • L’accesso SSH (porta 22) e sempre consentito
  • Il gateway e accessibile solo tramite Tailscale per design

Il servizio non si avvia

# Controlla i log
sudo journalctl -u openclaw -n 100

# Verifica i permessi
sudo ls -la /opt/openclaw

# Prova l'avvio manuale
sudo -i -u openclaw
cd ~/openclaw
pnpm start

Problemi con il sandbox Docker

# Verifica che Docker sia in esecuzione
sudo systemctl status docker

# Controlla l'immagine del sandbox
sudo docker images | grep openclaw-sandbox

# Compila l'immagine del sandbox se mancante
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh

Il login del provider fallisce

Assicurati di eseguire come utente openclaw:

sudo -i -u openclaw
openclaw channels login

Configurazione avanzata

Per l’architettura di sicurezza dettagliata e la risoluzione dei problemi:

Correlati

arrow_back
Precedente
Nix
Successivo
Bun
arrow_forward