> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ansible

Distribuisci OpenClaw su server di produzione con **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** -- un installer automatizzato con un'architettura orientata prima di tutto alla sicurezza.

<Info>
  Il repository [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) è la fonte autorevole per la distribuzione con Ansible. Questa pagina è una panoramica rapida.
</Info>

## Prerequisiti

| Requisito   | Dettagli                                                    |
| ----------- | ----------------------------------------------------------- |
| **OS**      | 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 quick-start) |

## Cosa ottieni

* **Sicurezza firewall-first** -- isolamento UFW + Docker (accessibili solo SSH + Tailscale)
* **VPN Tailscale** -- accesso remoto sicuro senza esporre pubblicamente i servizi
* **Docker** -- container sandbox isolati, binding solo su localhost
* **Difesa in profondità** -- architettura di sicurezza a 4 livelli
* **Integrazione Systemd** -- avvio automatico al boot con hardening
* **Configurazione con un solo comando** -- distribuzione completa in pochi minuti

## Avvio rapido

Installazione con un solo comando:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash
```

## 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 il backend sandbox dell'agente predefinito
4. **Node.js 24 + pnpm** -- dipendenze di runtime (Node 22 LTS, attualmente `22.19+`, resta supportato)
5. **OpenClaw** -- basato sull'host, non containerizzato
6. **Servizio Systemd** -- avvio automatico con hardening di sicurezza

<Note>
  Il gateway viene eseguito direttamente sull'host (non in Docker). Il sandboxing degli agenti è
  facoltativo; questo playbook installa Docker perché è il backend sandbox
  predefinito. Vedi [Sandboxing](/it/gateway/sandboxing) per dettagli e altri backend.
</Note>

## Configurazione post-installazione

<Steps>
  <Step title="Passa all'utente openclaw">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo -i -u openclaw
    ```
  </Step>

  <Step title="Esegui la procedura guidata di onboarding">
    Lo script post-installazione ti guida nella configurazione delle impostazioni di OpenClaw.
  </Step>

  <Step title="Connetti i provider di messaggistica">
    Accedi a WhatsApp, Telegram, Discord o Signal:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw channels login
    ```
  </Step>

  <Step title="Verifica l'installazione">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo systemctl status openclaw
    sudo journalctl -u openclaw -f
    ```
  </Step>

  <Step title="Connettiti a Tailscale">
    Unisciti alla tua mesh VPN per l'accesso remoto sicuro.
  </Step>
</Steps>

### Comandi rapidi

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Check service status
sudo systemctl status openclaw

# View live logs
sudo journalctl -u openclaw -f

# Restart gateway
sudo systemctl restart openclaw

# Provider login (run as openclaw user)
sudo -i -u openclaw
openclaw channels login
```

## Architettura di sicurezza

La distribuzione usa un modello di 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** -- la catena iptables DOCKER-USER impedisce l'esposizione di porte esterne
4. **Hardening Systemd** -- NoNewPrivileges, PrivateTmp, utente non privilegiato

Per verificare la tua superficie di attacco esterna:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
nmap -p- YOUR_SERVER_IP
```

Solo la porta 22 (SSH) dovrebbe essere aperta. Tutti gli altri servizi (gateway, Docker) sono bloccati.

Docker viene installato per le sandbox degli agenti (esecuzione isolata degli strumenti), non per eseguire il gateway stesso. Vedi [Multi-Agent Sandbox and Tools](/it/tools/multi-agent-sandbox-tools) per la configurazione della sandbox.

## Installazione manuale

Se preferisci il controllo manuale rispetto all'automazione:

<Steps>
  <Step title="Installa i prerequisiti">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo apt update && sudo apt install -y ansible git
    ```
  </Step>

  <Step title="Clona il repository">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    git clone https://github.com/openclaw/openclaw-ansible.git
    cd openclaw-ansible
    ```
  </Step>

  <Step title="Installa le collection Ansible">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    ansible-galaxy collection install -r requirements.yml
    ```
  </Step>

  <Step title="Esegui il playbook">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    ./run-playbook.sh
    ```

    In alternativa, eseguilo direttamente e poi esegui manualmente lo script di configurazione:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    ansible-playbook playbook.yml --ask-become-pass
    # Then run: /tmp/openclaw-setup.sh
    ```
  </Step>
</Steps>

## Aggiornamento

L'installer Ansible configura OpenClaw per gli aggiornamenti manuali. Vedi [Aggiornamento](/it/install/updating) per il flusso di aggiornamento standard.

Per rieseguire il playbook Ansible (per esempio, per modifiche di configurazione):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cd openclaw-ansible
./run-playbook.sh
```

È idempotente e sicuro da eseguire più volte.

## Risoluzione dei problemi

<AccordionGroup>
  <Accordion title="Il firewall blocca la mia connessione">
    * Assicurati di poter accedere prima tramite VPN Tailscale
    * L'accesso SSH (porta 22) è sempre consentito
    * Il gateway è accessibile solo tramite Tailscale per progettazione
  </Accordion>

  <Accordion title="Il servizio non si avvia">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # Check logs
    sudo journalctl -u openclaw -n 100

    # Verify permissions
    sudo ls -la /opt/openclaw

    # Test manual start
    sudo -i -u openclaw
    cd ~/openclaw
    openclaw gateway run
    ```
  </Accordion>

  <Accordion title="Problemi con la sandbox Docker">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # Verify Docker is running
    sudo systemctl status docker

    # Check sandbox image
    sudo docker images | grep openclaw-sandbox

    # Build sandbox image if missing (requires source checkout)
    cd /opt/openclaw/openclaw
    sudo -u openclaw ./scripts/sandbox-setup.sh
    # For npm installs without a source checkout, see
    # https://docs.openclaw.ai/gateway/sandboxing#images-and-setup
    ```
  </Accordion>

  <Accordion title="L'accesso al provider non riesce">
    Assicurati di essere in esecuzione come utente `openclaw`:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo -i -u openclaw
    openclaw channels login
    ```
  </Accordion>
</AccordionGroup>

## Configurazione avanzata

Per l'architettura di sicurezza dettagliata e la risoluzione dei problemi, vedi il repository openclaw-ansible:

* [Architettura di sicurezza](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md)
* [Dettagli tecnici](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
* [Guida alla risoluzione dei problemi](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md)

## Correlati

* [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) -- guida completa alla distribuzione
* [Docker](/it/install/docker) -- configurazione del gateway containerizzato
* [Sandboxing](/it/gateway/sandboxing) -- configurazione della sandbox degli agenti
* [Multi-Agent Sandbox and Tools](/it/tools/multi-agent-sandbox-tools) -- isolamento per agente