<p align="center">
  <img src="zeroclaw.png" alt="ZeroClaw" width="200" />
</p>

<h1 align="center">ZeroClaw 🦀</h1>

<p align="center">
  <strong>Zero overhead. Zero compromesso. 100% Rust. 100% Agnostico.</strong><br>
  ⚡️ <strong>Gira su hardware da $10 con <5MB di RAM: È il 99% di memoria in meno di OpenClaw e il 98% più economico di un Mac mini!</strong>
</p>

<p align="center">
  <a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
  <a href="NOTICE"><img src="https://img.shields.io/badge/contributors-27+-green.svg" alt="Contributors" /></a>
  <a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
  <a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
  <a href="https://zeroclawlabs.cn/group.jpg"><img src="https://img.shields.io/badge/WeChat-Group-B7D7A8?logo=wechat&logoColor=white" alt="WeChat Group" /></a>
  <a href="https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search"><img src="https://img.shields.io/badge/Xiaohongshu-Official-FF2442?style=flat" alt="Xiaohongshu: Official" /></a>
  <a href="https://t.me/zeroclawlabs"><img src="https://img.shields.io/badge/Telegram-%40zeroclawlabs-26A5E4?style=flat&logo=telegram&logoColor=white" alt="Telegram: @zeroclawlabs" /></a>
  <a href="https://www.facebook.com/groups/zeroclaw"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
  <a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
</p>
<p align="center">
Costruito da studenti e membri delle comunità Harvard, MIT e Sundai.Club.
</p>

<p align="center">
  🌐 <strong>Lingue:</strong><a href="README.md">🇺🇸 English</a> ·
  <a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
  <a href="README.ja.md">🇯🇵 日本語</a> ·
  <a href="README.ko.md">🇰🇷 한국어</a> ·
  <a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
  <a href="README.tl.md">🇵🇭 Tagalog</a> ·
  <a href="README.es.md">🇪🇸 Español</a> ·
  <a href="README.pt.md">🇧🇷 Português</a> ·
  <a href="README.it.md">🇮🇹 Italiano</a> ·
  <a href="README.de.md">🇩🇪 Deutsch</a> ·
  <a href="README.fr.md">🇫🇷 Français</a> ·
  <a href="README.ar.md">🇸🇦 العربية</a> ·
  <a href="README.hi.md">🇮🇳 हिन्दी</a> ·
  <a href="README.ru.md">🇷🇺 Русский</a> ·
  <a href="README.bn.md">🇧🇩 বাংলা</a> ·
  <a href="README.he.md">🇮🇱 עברית</a> ·
  <a href="README.pl.md">🇵🇱 Polski</a> ·
  <a href="README.cs.md">🇨🇿 Čeština</a> ·
  <a href="README.nl.md">🇳🇱 Nederlands</a> ·
  <a href="README.tr.md">🇹🇷 Türkçe</a> ·
  <a href="README.uk.md">🇺🇦 Українська</a> ·
  <a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
  <a href="README.th.md">🇹🇭 ไทย</a> ·
  <a href="README.ur.md">🇵🇰 اردو</a> ·
  <a href="README.ro.md">🇷🇴 Română</a> ·
  <a href="README.sv.md">🇸🇪 Svenska</a> ·
  <a href="README.el.md">🇬🇷 Ελληνικά</a> ·
  <a href="README.hu.md">🇭🇺 Magyar</a> ·
  <a href="README.fi.md">🇫🇮 Suomi</a> ·
  <a href="README.da.md">🇩🇰 Dansk</a> ·
  <a href="README.nb.md">🇳🇴 Norsk</a>
</p>

<p align="center">
  <a href="#avvio-rapido">Avvio Rapido</a> |
  <a href="bootstrap.sh">Configurazione con Un Clic</a> |
  <a href="docs/README.md">Hub Documentazione</a> |
  <a href="docs/SUMMARY.md">Indice Documentazione</a>
</p>

<p align="center">
  <strong>Accessi rapidi:</strong>
  <a href="docs/reference/README.md">Riferimento</a> ·
  <a href="docs/operations/README.md">Operazioni</a> ·
  <a href="docs/troubleshooting.md">Risoluzione Problemi</a> ·
  <a href="docs/security/README.md">Sicurezza</a> ·
  <a href="docs/hardware/README.md">Hardware</a> ·
  <a href="docs/contributing/README.md">Contribuire</a>
</p>

<p align="center">
  <strong>Infrastruttura assistente AI veloce, leggera e completamente autonoma</strong><br />
  Distribuisci ovunque. Scambia qualsiasi cosa.
</p>

<p align="center">
  ZeroClaw è il <strong>sistema operativo runtime</strong> per i workflow degli agenti — un'infrastruttura che astrae modelli, strumenti, memoria ed esecuzione per costruire agenti una volta e eseguirli ovunque.
</p>

<p align="center"><code>Architettura basata su trait · runtime sicuro di default · provider/canale/strumento intercambiabili · tutto è collegabile</code></p>

### 📢 Annunci

Usa questa tabella per avvisi importanti (cambiamenti di compatibilità, avvisi di sicurezza, finestre di manutenzione e blocchi di versione).

| Data (UTC) | Livello      | Avviso                                                                                                                                                                                                                                                                                                                                                                                                              | Azione                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-02-19 | _Critico_  | **Non siamo affiliati** con `openagen/zeroclaw` o `zeroclaw.org`. Il dominio `zeroclaw.org` punta attualmente al fork `openagen/zeroclaw`, e questo dominio/repository sta contraffacendo il nostro sito web/progetto ufficiale.                                                                                                                                                                                 | Non fidarti di informazioni, binari, raccolte fondi o annunci da queste fonti. Usa solo [questo repository](https://github.com/zeroclaw-labs/zeroclaw) e i nostri account social verificati.                                                                                                                                                                                                                                                                                                                                                          |
| 2026-02-21 | _Importante_ | Il nostro sito ufficiale è ora online: [zeroclawlabs.ai](https://zeroclawlabs.ai). Grazie per la pazienza durante l'attesa. Rileviamo ancora tentativi di contraffazione: non partecipare ad alcuna attività di investimento/finanziamento a nome di ZeroClaw se non pubblicata tramite i nostri canali ufficiali.                                                                                                                   | Usa [questo repository](https://github.com/zeroclaw-labs/zeroclaw) come unica fonte di verità. Segui [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Telegram (@zeroclawlabs)](https://t.me/zeroclawlabs), [Facebook (gruppo)](https://www.facebook.com/groups/zeroclaw), [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/), e [Xiaohongshu](https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search) per aggiornamenti ufficiali. |
| 2026-02-19 | _Importante_ | Anthropic ha aggiornato i termini di utilizzo di autenticazione e credenziali il 2026-02-19. L'autenticazione OAuth (Free, Pro, Max) è esclusivamente per Claude Code e Claude.ai; l'uso di token OAuth di Claude Free/Pro/Max in qualsiasi altro prodotto, strumento o servizio (incluso Agent SDK) non è consentito e può violare i Termini di Utilizzo del Consumatore. | Si prega di evitare temporaneamente le integrazioni OAuth di Claude Code per prevenire qualsiasi potenziale perdita. Clausola originale: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use).                                                                                                                                                                                                                                                                                                                      |

### ✨ Funzionalità

- 🏎️ **Runtime Leggero di Default:** I workflow CLI comuni e i comandi di stato girano all'interno di uno spazio di memoria di pochi megabyte nelle build di produzione.
- 💰 **Distribuzione Economica:** Progettato per schede a basso costo e piccole istanze cloud senza dipendenze runtime pesanti.
- ⚡ **Avvii a Freddo Rapidi:** Il runtime Rust a binario singolo mantiene l'avvio di comandi e demoni quasi istantaneo per le operazioni quotidiane.
- 🌍 **Architettura Portabile:** Un workflow a binario singolo su ARM, x86 e RISC-V con provider/canale/strumento intercambiabili.

### Perché i team scelgono ZeroClaw

- **Leggero di default:** binario Rust piccolo, avvio rapido, basso impatto di memoria.
- **Sicuro per design:** pairing, sandboxing rigoroso, liste di autorizzazione esplicite, scope del workspace.
- **Completamente intercambiabile:** i sistemi centrali sono trait (provider, canali, strumenti, memoria, tunnel).
- **Nessun lock-in del provider:** supporto provider compatibile OpenAI + endpoint personalizzati collegabili.

## Snapshot Benchmark (ZeroClaw vs OpenClaw, Riproducibile)

Benchmark rapido su macchina locale (macOS arm64, feb. 2026) normalizzato per hardware edge a 0.8 GHz.

|                              | OpenClaw      | NanoBot        | PicoClaw        | ZeroClaw 🦀           |
| ---------------------------- | ------------- | -------------- | --------------- | --------------------- |
| **Linguaggio**                  | TypeScript    | Python         | Go              | **Rust**              |
| **RAM**                      | > 1 GB        | > 100 MB       | < 10 MB         | **< 5 MB**            |
| **Avvio (core 0.8 GHz)** | > 500s        | > 30s          | < 1s            | **< 10ms**            |
| **Dimensione Binario**           | ~28 MB (dist) | N/A (Scripts)  | ~8 MB           | **3.4 MB**            |
| **Costo**                     | Mac Mini $599 | Linux SBC ~$50 | Scheda Linux $10 | **Qualsiasi hardware $10** |

> Note: I risultati di ZeroClaw sono misurati su build di produzione usando `/usr/bin/time -l`. OpenClaw richiede il runtime Node.js (tipicamente ~390 MB di overhead memoria aggiuntivo), mentre NanoBot richiede il runtime Python. PicoClaw e ZeroClaw sono binari statici. Le cifre RAM sopra sono memoria runtime; i requisiti di compilazione in build-time sono maggiori.

<p align="center">
  <img src="zero-claw.jpeg" alt="Confronto ZeroClaw vs OpenClaw" width="800" />
</p>

### Misurazione Locale Riproducibile

Le affermazioni di benchmark possono derivare man mano che il codice e le toolchain evolvono, quindi misura sempre la tua build attuale localmente:

```bash
cargo build --release
ls -lh target/release/zeroclaw

/usr/bin/time -l target/release/zeroclaw --help
/usr/bin/time -l target/release/zeroclaw status
```

Esempio di campione (macOS arm64, misurato il 18 febbraio 2026):

- Dimensione binario release: `8.8M`
- `zeroclaw --help`: tempo reale circa `0.02s`, impatto memoria massimo ~`3.9 MB`
- `zeroclaw status`: tempo reale circa `0.01s`, impatto memoria massimo ~`4.1 MB`

## Prerequisiti

<details>
<summary><strong>Windows</strong></summary>

### Windows — Richiesto

1. **Visual Studio Build Tools** (fornisce il linker MSVC e il Windows SDK):

    ```powershell
    winget install Microsoft.VisualStudio.2022.BuildTools
    ```

    Durante l'installazione (o via Visual Studio Installer), seleziona il carico di lavoro **"Sviluppo desktop con C++"**.

2. **Toolchain Rust:**

    ```powershell
    winget install Rustlang.Rustup
    ```

    Dopo l'installazione, apri un nuovo terminale ed esegui `rustup default stable` per assicurarti che la toolchain stabile sia attiva.

3. **Verifica** che entrambi funzionano:
    ```powershell
    rustc --version
    cargo --version
    ```

### Windows — Opzionale

- **Docker Desktop** — richiesto solo se usi il [runtime Docker sandboxed](#supporto-runtime-attuale) (`runtime.kind = "docker"`). Installa via `winget install Docker.DockerDesktop`.

</details>

<details>
<summary><strong>Linux / macOS</strong></summary>

### Linux / macOS — Richiesto

1. **Strumenti di build essenziali:**
    - **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
    - **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
    - **macOS:** Installa Xcode Command Line Tools: `xcode-select --install`

2. **Toolchain Rust:**

    ```bash
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    ```

    Vedi [rustup.rs](https://rustup.rs) per dettagli.

3. **Verifica:**
    ```bash
    rustc --version
    cargo --version
    ```

### Linux / macOS — Opzionale

- **Docker** — richiesto solo se usi il [runtime Docker sandboxed](#supporto-runtime-attuale) (`runtime.kind = "docker"`).
    - **Linux (Debian/Ubuntu):** vedi [docs.docker.com](https://docs.docker.com/engine/install/ubuntu/)
    - **Linux (Fedora/RHEL):** vedi [docs.docker.com](https://docs.docker.com/engine/install/fedora/)
    - **macOS:** installa Docker Desktop via [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/)

</details>

## Avvio Rapido

### Opzione 1: Configurazione automatizzata (consigliata)

Lo script `bootstrap.sh` installa Rust, clona ZeroClaw, lo compila, e configura il tuo ambiente di sviluppo iniziale:

```bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/bootstrap.sh | bash
```

Questo:

1. Installerà Rust (se non presente)
2. Clonerà il repository ZeroClaw
3. Compilerà ZeroClaw in modalità release
4. Installerà `zeroclaw` in `~/.cargo/bin/`
5. Creerà la struttura del workspace di default in `~/.zeroclaw/workspace/`
6. Genererà un file di configurazione iniziale `~/.zeroclaw/workspace/config.toml`

Dopo il bootstrap, ricarica la tua shell o esegui `source ~/.cargo/env` per usare il comando `zeroclaw` globalmente.

### Opzione 2: Installazione manuale

<details>
<summary><strong>Clicca per vedere i passaggi di installazione manuale</strong></summary>

```bash
# 1. Clona il repository
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

# 2. Compila in release
cargo build --release --locked

# 3. Installa il binario
cargo install --path . --locked

# 4. Inizializza il workspace
zeroclaw init

# 5. Verifica l'installazione
zeroclaw --version
zeroclaw status
```

</details>

### Dopo l'installazione

Una volta installato (via bootstrap o manualmente), dovresti vedere:

```
~/.zeroclaw/workspace/
├── config.toml          # Configurazione principale
├── .pairing             # Segreti di pairing (generati al primo avvio)
├── logs/                # Log di daemon/agent
├── skills/              # Competenze personalizzate
└── memory/              # Archiviazione contesto conversazionale
```

**Prossimi passi:**

1. Configura i tuoi provider AI in `~/.zeroclaw/workspace/config.toml`
2. Controlla la [riferimento configurazione](docs/config-reference.md) per opzioni avanzate
3. Avvia l'agente: `zeroclaw agent start`
4. Testa tramite il tuo canale preferito (vedi [riferimento canali](docs/channels-reference.md))

## Configurazione

Modifica `~/.zeroclaw/workspace/config.toml` per configurare provider, canali e comportamento del sistema.

### Riferimento Configurazione Rapida

```toml
[providers.anthropic]
api_key = "sk-ant-..."
model = "claude-sonnet-4-20250514"

[providers.openai]
api_key = "sk-..."
model = "gpt-4o"

[channels.telegram]
enabled = true
bot_token = "123456:ABC-DEF..."

[channels.matrix]
enabled = true
homeserver_url = "https://matrix.org"
username = "@bot:matrix.org"
password = "..."

[memory]
kind = "markdown"  # o "sqlite" o "none"

[runtime]
kind = "native"    # o "docker" (richiede Docker)
```

**Documenti di riferimento completi:**

- [Riferimento Configurazione](docs/config-reference.md) — tutte le impostazioni, validazioni, valori di default
- [Riferimento Provider](docs/providers-reference.md) — configurazioni specifiche per provider AI
- [Riferimento Canali](docs/channels-reference.md) — Telegram, Matrix, Slack, Discord e altro
- [Operazioni](docs/operations-runbook.md) — monitoraggio in produzione, rotazione segreti, scaling

### Supporto Runtime (attuale)

ZeroClaw supporta due backend di esecuzione del codice:

- **`native`** (default) — esecuzione processo diretta, percorso più veloce, ideale per ambienti fidati
- **`docker`** — isolamento container completo, politiche di sicurezza potenziate, richiede Docker

Usa `runtime.kind = "docker"` se hai bisogno di sandboxing rigoroso o isolamento rete. Vedi [riferimento configurazione](docs/config-reference.md#runtime) per dettagli completi.

## Comandi

```bash
# Gestione workspace
zeroclaw init                # Inizializza un nuovo workspace
zeroclaw status              # Mostra stato daemon/agent
zeroclaw config validate     # Verifica sintassi e valori di config.toml

# Gestione daemon
zeroclaw daemon start        # Avvia il daemon in background
zeroclaw daemon stop         # Ferma il daemon in esecuzione
zeroclaw daemon restart      # Riavvia il daemon (ricaricamento config)
zeroclaw daemon logs         # Mostra log del daemon

# Gestione agent
zeroclaw agent start         # Avvia l'agent (richiede daemon in esecuzione)
zeroclaw agent stop          # Ferma l'agent
zeroclaw agent restart       # Riavvia l'agent (ricaricamento config)

# Operazioni di pairing
zeroclaw pairing init        # Genera un nuovo segreto di pairing
zeroclaw pairing rotate      # Ruota il segreto di pairing esistente

# Tunneling (per esposizione pubblica)
zeroclaw tunnel start        # Avvia un tunnel verso il daemon locale
zeroclaw tunnel stop         # Ferma il tunnel attivo

# Diagnostica
zeroclaw doctor              # Esegue controlli di salute del sistema
zeroclaw version             # Mostra versione e informazioni di build
```

Vedi [Riferimento Comandi](docs/commands-reference.md) per opzioni ed esempi completi.

## Architettura

```
┌─────────────────────────────────────────────────────────────────┐
│                        Canali (trait)                           │
│  Telegram │ Matrix │ Slack │ Discord │ Web │ CLI │ Custom       │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Agente Orchestratore                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │   Routing    │  │   Contesto   │  │  Esecuzione  │          │
│  │   Messaggio  │  │   Memoria    │  │   Strumento  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│   Provider   │  │   Memoria    │  │  Strumenti   │
│   (trait)    │  │   (trait)    │  │   (trait)    │
├──────────────┤  ├──────────────┤  ├──────────────┤
│  Anthropic   │  │   Markdown   │  │  Filesystem  │
│   OpenAI     │  │    SQLite    │  │     Bash     │
│   Gemini     │  │     None     │  │   Web Fetch  │
│   Ollama     │  │    Custom    │  │   Custom     │
│   Custom     │  └──────────────┘  └──────────────┘
└──────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Runtime (trait)                               │
│                  Native │ Docker                                │
└─────────────────────────────────────────────────────────────────┘
```

**Principi chiave:**

- Tutto è un **trait** — provider, canali, strumenti, memoria, tunnel
- I canali chiamano l'orchestratore; l'orchestratore chiama provider + strumenti
- Il sistema memoria gestisce il contesto conversazionale (markdown, SQLite, o nessuno)
- Il runtime astrae l'esecuzione del codice (nativo o Docker)
- Nessun lock-in del provider — scambia Anthropic ↔ OpenAI ↔ Gemini ↔ Ollama senza modifiche al codice

Vedi [documentazione architettura](docs/architecture.svg) per diagrammi dettagliati e dettagli di implementazione.

## Esempi

### Bot Telegram

```toml
[channels.telegram]
enabled = true
bot_token = "123456:ABC-DEF..."
allowed_users = [987654321]  # Il tuo ID utente Telegram
```

Avvia il daemon + agent, poi invia un messaggio al tuo bot su Telegram:

```
/start
Ciao! Potresti aiutarmi a scrivere uno script Python?
```

Il bot risponde con codice generato dall'AI, esegue strumenti se richiesto, e mantiene il contesto della conversazione.

### Matrix (crittografia end-to-end)

```toml
[channels.matrix]
enabled = true
homeserver_url = "https://matrix.org"
username = "@zeroclaw:matrix.org"
password = "..."
device_name = "zeroclaw-prod"
e2ee_enabled = true
```

Invita `@zeroclaw:matrix.org` in una stanza crittografata, e il bot risponderà con crittografia completa. Vedi [Guida Matrix E2EE](docs/matrix-e2ee-guide.md) per la configurazione della verifica dispositivo.

### Multi-Provider

```toml
[providers.anthropic]
enabled = true
api_key = "sk-ant-..."
model = "claude-sonnet-4-20250514"

[providers.openai]
enabled = true
api_key = "sk-..."
model = "gpt-4o"

[orchestrator]
default_provider = "anthropic"
fallback_providers = ["openai"]  # Failover su errore del provider
```

Se Anthropic fallisce o va in rate-limit, l'orchestratore passa automaticamente a OpenAI.

### Memoria Personalizzata

```toml
[memory]
kind = "sqlite"
path = "~/.zeroclaw/workspace/memory/conversations.db"
retention_days = 90  # Eliminazione automatica dopo 90 giorni
```

O usa Markdown per un archiviazione leggibile dall'uomo:

```toml
[memory]
kind = "markdown"
path = "~/.zeroclaw/workspace/memory/"
```

Vedi [Riferimento Configurazione](docs/config-reference.md#memory) per tutte le opzioni memoria.

## Supporto Provider

| Provider       | Stato      | API Key             | Modelli di Esempio                                      |
| ----------------- | ----------- | ------------------- | ---------------------------------------------------- |
| **Anthropic**     | ✅ Stabile   | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514`, `claude-opus-4-20250514` |
| **OpenAI**        | ✅ Stabile   | `OPENAI_API_KEY`    | `gpt-4o`, `gpt-4o-mini`, `o1`, `o1-mini`             |
| **Google Gemini** | ✅ Stabile   | `GOOGLE_API_KEY`    | `gemini-2.0-flash-exp`, `gemini-exp-1206`            |
| **Ollama**        | ✅ Stabile   | N/A (locale)         | `llama3.3`, `qwen2.5`, `phi4`                        |
| **Cerebras**      | ✅ Stabile   | `CEREBRAS_API_KEY`  | `llama-3.3-70b`                                      |
| **Groq**          | ✅ Stabile   | `GROQ_API_KEY`      | `llama-3.3-70b-versatile`                            |
| **Mistral**       | 🚧 Pianificato | `MISTRAL_API_KEY`   | TBD                                                  |
| **Cohere**        | 🚧 Pianificato | `COHERE_API_KEY`    | TBD                                                  |

### Endpoint Personalizzati

ZeroClaw supporta endpoint compatibili con OpenAI:

```toml
[providers.custom]
enabled = true
api_key = "..."
base_url = "https://api.your-llm-provider.com/v1"
model = "your-model-name"
```

Esempio: usa [LiteLLM](https://github.com/BerriAI/litellm) come proxy per accedere a qualsiasi LLM tramite l'interfaccia OpenAI.

Vedi [Riferimento Provider](docs/providers-reference.md) per dettagli di configurazione completi.

## Supporto Canali

| Canale        | Stato      | Autenticazione         | Note                                                     |
| ------------ | ----------- | ------------------------ | --------------------------------------------------------- |
| **Telegram** | ✅ Stabile   | Bot Token                | Supporto completo inclusi file, immagini, pulsanti inline |
| **Matrix**   | ✅ Stabile   | Password o Token    | Supporto E2EE con verifica dispositivo              |
| **Slack**    | 🚧 Pianificato | OAuth o Bot Token       | Richiede accesso workspace                                    |
| **Discord**  | 🚧 Pianificato | Bot Token                | Richiede permessi guild                                |
| **WhatsApp** | 🚧 Pianificato | Twilio o API ufficiale | Richiede account business                                    |
| **CLI**      | ✅ Stabile   | Nessuno                    | Interfaccia conversazionale diretta                       |
| **Web**      | 🚧 Pianificato | API Key o OAuth         | Interfaccia chat basata su browser                        |

Vedi [Riferimento Canali](docs/channels-reference.md) per istruzioni di configurazione complete.

## Supporto Strumenti

ZeroClaw fornisce strumenti integrati per l'esecuzione del codice, l'accesso al filesystem e il recupero web:

| Strumento                | Descrizione                 | Runtime Richiesto                |
| -------------------- | --------------------------- | ----------------------------- |
| **bash**             | Esegue comandi shell | Nativo o Docker              |
| **python**           | Esegue script Python  | Python 3.8+ (nativo) o Docker |
| **javascript**       | Esegue codice Node.js     | Node.js 18+ (nativo) o Docker |
| **filesystem_read**  | Legge file            | Nativo o Docker              |
| **filesystem_write** | Scrive file          | Nativo o Docker              |
| **web_fetch**        | Recupera contenuti web     | Nativo o Docker              |

### Sicurezza dell'Esecuzione

- **Runtime Nativo** — gira come processo utente del daemon, accesso completo al filesystem
- **Runtime Docker** — isolamento container completo, filesystem e reti separati

Configura la politica di esecuzione in `config.toml`:

```toml
[runtime]
kind = "docker"
allowed_tools = ["bash", "python", "filesystem_read"]  # Lista di autorizzazione esplicita
```

Vedi [Riferimento Configurazione](docs/config-reference.md#runtime) per opzioni di sicurezza complete.

## Distribuzione

### Distribuzione Locale (Sviluppo)

```bash
zeroclaw daemon start
zeroclaw agent start
```

### Distribuzione Server (Produzione)

Usa systemd per gestire daemon e agent come servizi:

```bash
# Installa il binario
cargo install --path . --locked

# Configura il workspace
zeroclaw init

# Crea i file di servizio systemd
sudo cp deployment/systemd/zeroclaw-daemon.service /etc/systemd/system/
sudo cp deployment/systemd/zeroclaw-agent.service /etc/systemd/system/

# Abilita e avvia i servizi
sudo systemctl enable zeroclaw-daemon zeroclaw-agent
sudo systemctl start zeroclaw-daemon zeroclaw-agent

# Verifica lo stato
sudo systemctl status zeroclaw-daemon
sudo systemctl status zeroclaw-agent
```

Vedi [Guida Distribuzione di Rete](docs/network-deployment.md) per istruzioni complete di distribuzione in produzione.

### Docker

```bash
# Compila l'immagine
docker build -t zeroclaw:latest .

# Esegui il container
docker run -d \
  --name zeroclaw \
  -v ~/.zeroclaw/workspace:/workspace \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  zeroclaw:latest
```

Vedi [`Dockerfile`](Dockerfile) per dettagli di build e opzioni di configurazione.

### Hardware Edge

ZeroClaw è progettato per girare su hardware a basso consumo:

- **Raspberry Pi Zero 2 W** — ~512 MB RAM, singolo core ARMv8, < $5 costo hardware
- **Raspberry Pi 4/5** — 1 GB+ RAM, multi-core, ideale per workload concorrenti
- **Orange Pi Zero 2** — ~512 MB RAM, quad-core ARMv8, costo ultra-basso
- **SBC x86 (Intel N100)** — 4-8 GB RAM, build veloci, supporto Docker nativo

Vedi [Guida Hardware](docs/hardware/README.md) per istruzioni di configurazione specifiche per dispositivo.

## Tunneling (Esposizione Pubblica)

Espone il tuo daemon ZeroClaw locale alla rete pubblica tramite tunnel sicuri:

```bash
zeroclaw tunnel start --provider cloudflare
```

Provider di tunnel supportati:

- **Cloudflare Tunnel** — HTTPS gratuito, nessuna esposizione di porte, supporto multi-dominio
- **Ngrok** — configurazione rapida, domini personalizzati (piano a pagamento)
- **Tailscale** — rete mesh privata, nessuna porta pubblica

Vedi [Riferimento Configurazione](docs/config-reference.md#tunnel) per opzioni di configurazione complete.

## Sicurezza

ZeroClaw implementa molteplici livelli di sicurezza:

### Pairing

Il daemon genera un segreto di pairing al primo avvio memorizzato in `~/.zeroclaw/workspace/.pairing`. I client (agent, CLI) devono presentare questo segreto per connettersi.

```bash
zeroclaw pairing rotate  # Genera un nuovo segreto e invalida quello precedente
```

### Sandboxing

- **Runtime Docker** — isolamento container completo con filesystem e reti separati
- **Runtime Nativo** — gira come processo utente, con scope del workspace di default

### Liste di Autorizzazione

I canali possono limitare l'accesso per ID utente:

```toml
[channels.telegram]
enabled = true
allowed_users = [123456789, 987654321]  # Lista di autorizzazione esplicita
```

### Crittografia

- **Matrix E2EE** — crittografia end-to-end completa con verifica dispositivo
- **Trasporto TLS** — tutto il traffico API e tunnel usa HTTPS/TLS

Vedi [Documentazione Sicurezza](docs/security/README.md) per politiche e pratiche complete.

## Osservabilità

ZeroClaw registra i log in `~/.zeroclaw/workspace/logs/` di default. I log sono memorizzati per componente:

```
~/.zeroclaw/workspace/logs/
├── daemon.log           # Log del daemon (avvio, richieste API, errori)
├── agent.log            # Log dell'agent (routing messaggi, esecuzione strumenti)
├── telegram.log         # Log specifici del canale (se abilitato)
└── matrix.log           # Log specifici del canale (se abilitato)
```

### Configurazione Logging

```toml
[logging]
level = "info"                           # debug, info, warn, error
path = "~/.zeroclaw/workspace/logs/"
rotation = "daily"                       # daily, hourly, size
max_size_mb = 100                        # Per rotazione basata sulla dimensione
retention_days = 30                      # Eliminazione automatica dopo N giorni
```

Vedi [Riferimento Configurazione](docs/config-reference.md#logging) per tutte le opzioni di logging.

### Metriche (Pianificato)

Supporto metriche Prometheus per il monitoraggio in produzione in arrivo. Tracciamento in [#234](https://github.com/zeroclaw-labs/zeroclaw/issues/234).

## Competenze (Skills)

ZeroClaw supporta competenze personalizzate — moduli riutilizzabili che estendono le capacità del sistema.

### Definizione Competenza

Le competenze sono memorizzate in `~/.zeroclaw/workspace/skills/<skill-name>/` con questa struttura:

```
skills/
└── my-skill/
    ├── skill.toml       # Metadati competenza (nome, descrizione, dipendenze)
    ├── prompt.md        # Prompt di sistema per l'AI
    └── tools/           # Strumenti personalizzati opzionali
        └── my_tool.py
```

### Esempio Competenza

```toml
# skills/web-research/skill.toml
[skill]
name = "web-research"
description = "Cerca sul web e riassume i risultati"
version = "1.0.0"

[dependencies]
tools = ["web_fetch", "bash"]
```

```markdown
<!-- skills/web-research/prompt.md -->

Sei un assistente di ricerca. Quando ti viene chiesto di cercare qualcosa:

1. Usa web_fetch per recuperare il contenuto
2. Riassume i risultati in un formato facile da leggere
3. Cita le fonti con gli URL
```

### Uso delle Competenze

Le competenze sono caricate automaticamente all'avvio dell'agent. Fai riferimento ad esse per nome nelle conversazioni:

```
Utente: Usa la competenza web-research per trovare le ultime notizie AI
Bot: [carica la competenza web-research, esegue web_fetch, riassume i risultati]
```

Vedi sezione [Competenze (Skills)](#competenze-skills) per istruzioni complete sulla creazione di competenze.

## Open Skills

ZeroClaw supporta [Open Skills](https://github.com/openagents-com/open-skills) — un sistema modulare e agnostico del provider per estendere le capacità degli agent AI.

### Abilita Open Skills

```toml
[skills]
open_skills_enabled = true
# open_skills_dir = "/path/to/open-skills"  # opzionale
```

Puoi anche sovrascrivere a runtime con `ZEROCLAW_OPEN_SKILLS_ENABLED` e `ZEROCLAW_OPEN_SKILLS_DIR`.

## Sviluppo

```bash
cargo build              # Build di sviluppo
cargo build --release    # Build release (codegen-units=1, funziona su tutti i dispositivi incluso Raspberry Pi)
cargo build --profile release-fast    # Build più veloce (codegen-units=8, richiede 16 GB+ RAM)
cargo test               # Esegue la suite di test completa
cargo clippy --locked --all-targets -- -D clippy::correctness
cargo fmt                # Formattazione

# Esegue il benchmark di confronto SQLite vs Markdown
cargo test --test memory_comparison -- --nocapture
```

### Hook pre-push

Un hook git esegue `cargo fmt --check`, `cargo clippy -- -D warnings`, e `cargo test` prima di ogni push. Attivalo una volta:

```bash
git config core.hooksPath .githooks
```

### Risoluzione Problemi di Build (errori OpenSSL su Linux)

Se incontri un errore di build `openssl-sys`, sincronizza le dipendenze e ricompila con il lockfile del repository:

```bash
git pull
cargo build --release --locked
cargo install --path . --force --locked
```

ZeroClaw è configurato per usare `rustls` per le dipendenze HTTP/TLS; `--locked` mantiene il grafo transitivo deterministico in ambienti puliti.

Per saltare l'hook quando hai bisogno di un push veloce durante lo sviluppo:

```bash
git push --no-verify
```

## Collaborazione e Docs

Inizia con l'hub della documentazione per una mappa basata sui task:

- Hub Documentazione: [`docs/README.md`](docs/README.md)
- Indice Unificato Docs: [`docs/SUMMARY.md`](docs/SUMMARY.md)
- Riferimento Comandi: [`docs/commands-reference.md`](docs/commands-reference.md)
- Riferimento Configurazione: [`docs/config-reference.md`](docs/config-reference.md)
- Riferimento Provider: [`docs/providers-reference.md`](docs/providers-reference.md)
- Riferimento Canali: [`docs/channels-reference.md`](docs/channels-reference.md)
- Runbook Operazioni: [`docs/operations-runbook.md`](docs/operations-runbook.md)
- Risoluzione Problemi: [`docs/troubleshooting.md`](docs/troubleshooting.md)
- Inventario/Classificazione Docs: [`docs/docs-inventory.md`](docs/docs-inventory.md)
- Snapshot Triage PR/Issue (al 18 feb. 2026): [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)

Riferimenti principali di collaborazione:

- Hub Documentazione: [docs/README.md](docs/README.md)
- Modello Documentazione: [docs/doc-template.md](docs/doc-template.md)
- Checklist Cambio Documentazione: [docs/README.md#4-documentation-change-checklist](docs/README.md#4-documentation-change-checklist)
- Riferimento Configurazione Canali: [docs/channels-reference.md](docs/channels-reference.md)
- Operazioni Stanze Crittografate Matrix: [docs/matrix-e2ee-guide.md](docs/matrix-e2ee-guide.md)
- Guida Contribuzione: [CONTRIBUTING.md](CONTRIBUTING.md)
- Politica Workflow PR: [docs/pr-workflow.md](docs/pr-workflow.md)
- Playbook Revisore (triage + revisione profonda): [docs/reviewer-playbook.md](docs/reviewer-playbook.md)
- Mappa Proprietà e Triage CI: [docs/ci-map.md](docs/ci-map.md)
- Politica Divulgazione Sicurezza: [SECURITY.md](SECURITY.md)

Per distribuzione e operazioni runtime:

- Guida Distribuzione di Rete: [docs/network-deployment.md](docs/network-deployment.md)
- Playbook Agent Proxy: [docs/proxy-agent-playbook.md](docs/proxy-agent-playbook.md)

## Supportare ZeroClaw

Se ZeroClaw aiuta il tuo lavoro e desideri supportare lo sviluppo continuo, puoi donare qui:

<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Offrimi un Caffè" /></a>

### 🙏 Ringraziamenti Speciali

Un sincero ringraziamento alle comunità e istituzioni che ispirano e alimentano questo lavoro open-source:

- **Harvard University** — per favorire la curiosità intellettuale e spingere i confini del possibile.
- **MIT** — per difendere la conoscenza aperta, l'open source, e la convinzione che la tecnologia dovrebbe essere accessibile a tutti.
- **Sundai Club** — per la comunità, l'energia, e la volontà incessante di costruire cose che contano.
- **Il Mondo e Oltre** 🌍✨ — a ogni contributore, sognatore, e costruttore là fuori che rende l'open source una forza per il bene. Questo è per te.

Costruiamo in open source perché le migliori idee vengono da ovunque. Se stai leggendo questo, ne fai parte. Benvenuto. 🦀❤️

## ⚠️ Repository Ufficiale e Avviso di Contraffazione

**Questo è l'unico repository ufficiale di ZeroClaw:**

> <https://github.com/zeroclaw-labs/zeroclaw>

Qualsiasi altro repository, organizzazione, dominio o pacchetto che afferma di essere "ZeroClaw" o che implica affiliazione con ZeroClaw Labs è **non autorizzato e non affiliato a questo progetto**. I fork non autorizzati noti saranno elencati in [TRADEMARK.md](TRADEMARK.md).

Se incontri contraffazione o uso improprio del marchio, per favore [apri una issue](https://github.com/zeroclaw-labs/zeroclaw/issues).

---

## Licenza

ZeroClaw è doppia licenza per massima apertura e protezione dei contributori:

| Licenza                      | Casi d'Uso                                            |
| ---------------------------- | ------------------------------------------------------------ |
| [MIT](LICENSE-MIT)               | Open-source, ricerca, accademico, uso personale          |
| [Apache 2.0](LICENSE-APACHE) | Protezione brevetti, istituzionale, distribuzione commerciale |

Puoi scegliere una delle due licenze. **I contributori concedono automaticamente diritti sotto entrambe** — vedi [CLA.md](CLA.md) per l'accordo completo dei contributori.

### Marchio

Il nome **ZeroClaw** e il logo sono marchi registrati di ZeroClaw Labs. Questa licenza non concede il permesso di usarli per implicare approvazione o affiliazione. Vedi [TRADEMARK.md](TRADEMARK.md) per usi permessi e proibiti.

### Protezioni dei Contributori

- **Mantieni i diritti d'autore** dei tuoi contributi
- **Concessione brevetti** (Apache 2.0) ti protegge da reclami di brevetti da parte di altri contributori
- I tuoi contributi sono **attribuiti permanentemente** nella cronologia dei commit e [NOTICE](NOTICE)
- Nessun diritto di marchio viene trasferito contribuendo

## Contribuire

Vedi [CONTRIBUTING.md](CONTRIBUTING.md) e [CLA.md](CLA.md). Implementa un trait, invia una PR:

- Guida workflow CI: [docs/ci-map.md](docs/ci-map.md)
- Nuovo `Provider` → `src/providers/`
- Nuovo `Channel` → `src/channels/`
- Nuovo `Observer` → `src/observability/`
- Nuovo `Tool` → `src/tools/`
- Nuova `Memory` → `src/memory/`
- Nuovo `Tunnel` → `src/tunnel/`
- Nuova `Skill` → `~/.zeroclaw/workspace/skills/<n>/`

---

**ZeroClaw** — Zero overhead. Zero compromesso. Distribuisci ovunque. Scambia qualsiasi cosa. 🦀

## Storico Stelle

<p align="center">
  <a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
    <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
     <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
     <img alt="Grafico Storico Stelle" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
    </picture>
  </a>
</p>
