ZeroClaw è un potente runtime per agenti AI progettato per l'autonomia e l'integrazione con flussi di lavoro esterni. Per chi si approccia per la prima volta a questo strumento, l'interfaccia a riga di comando (CLI) rappresenta il punto di controllo principale per configurare l'ambiente, gestire l'agente e monitorare i servizi.

In questa guida analizzeremo i 10 comandi fondamentali per trasformare un'installazione pulita in un sistema autonomo e operativo, spiegando non solo come usarli, ma quando e perché farlo.

1. Il punto di partenza: onboard

Il comando onboard è l'operazione preliminare obbligatoria. Serve a inizializzare l'area di lavoro di ZeroClaw nella directory utente (~/.zeroclaw/) e a generare il file di configurazione config.toml.

Modalità di configurazione

• Quick Setup: Eseguendo zeroclaw onboard senza flag, il sistema applica impostazioni predefinite.
• Interactive Wizard: Utilizzando il flag --interactive, l'utente viene guidato attraverso un processo di 7 passaggi per una personalizzazione completa.
• Channel Repair: Il flag --channels-only permette di riconfigurare esclusivamente le allowlist dei canali di comunicazione.

Esempio pratico: Per una configurazione rapida specificando il provider AI e la chiave API, è possibile utilizzare:

zeroclaw onboard --provider anthropic --api-key YOUR_API_KEY --memory sqlite

2. Interazione diretta: agent

Il comando agent avvia il loop di interazione con l'. È lo strumento principale per testare le capacità dell'agente prima di renderlo autonomo.

Due modalità di utilizzo

1. Modalità Interattiva (REPL): Avviando zeroclaw agent, si entra in una chat in tempo reale dove è possibile scambiare messaggi con l'AI.
2. Modalità Messaggio Singolo: Utilizzando il flag -m o --message, l'agente processa un singolo input e termina immediatamente l'esecuzione.

È possibile sovrascrivere le impostazioni del file di configurazione tramite flag come --model per cambiare il modello AI o --temperature (da 0.0 a 2.0) per regolare la creatività delle risposte.

3. L'ingresso dei dati: gateway

Il gateway è un server HTTP basato sul framework Axum che espone endpoint webhook. È essenziale per permettere a servizi esterni (come WhatsApp o altri strumenti di integrazione) di inviare dati a ZeroClaw.

Per impostazione predefinita, il gateway si lega all'indirizzo 127.0.0.1:8080. Per motivi di sicurezza, il binding pubblico (0.0.0.0) è consentito solo se è configurato un tunnel o se l'opzione allow_public_bind è attiva nel config.

4. Il cuore autonomo: daemon

Se il gateway gestisce solo l'ingresso HTTP, il comando daemon avvia l'intero runtime autonomo. È la modalità consigliata per l'implementazione a lungo termine.

Il daemon coordina simultaneamente diversi servizi critici:

• Gateway Server: Gestisce gli endpoint HTTP.
• Channel Listeners: Monitora i canali di comunicazione configurati.
• Heartbeat Scheduler: Esegue i task periodici di controllo.
• Cron Scheduler: Gestisce i task pianificati nella directory cron/.
• Memory Hygiene: Esegue l'archiviazione e la pulizia della memoria ogni 12 ore.

5. Gestione del sistema: service

Per evitare di dover avviare manualmente il daemon ogni volta che si riavvia il computer, ZeroClaw offre il comando service. Questo permette di installare il runtime come servizio a livello di sistema operativo.

Sottocomandi principali

• install: Crea il file di unità del servizio.
• start: Avvia il servizio daemon.
• stop: Ferma il servizio.
• status: Verifica se il servizio è in esecuzione.
• uninstall: Rimuove il file di unità.

Il sistema supporta launchd su macOS (tramite launchctl) e systemd su Linux (tramite systemctl --user).

6. Diagnostica rapida: doctor

Quando qualcosa non funziona come previsto, il comando doctor è lo strumento di prima scelta. Esegue una serie di controlli diagnostici per individuare problemi di configurazione o stati obsoleti.

Le verifiche principali includono:

• Freshness del Daemon: Verifica se il daemon ha riportato uno stato recente.
• Freshness dello Scheduler: Controlla che i task pianificati vengano effettivamente eseguiti.
• Health dei Canali: Testa la connettività dei canali configurati.

7. Monitoraggio in tempo reale: status

Il comando status fornisce una panoramica immediata dello stato attuale del sistema. A differenza di doctor, che cerca errori, status mostra l'operatività corrente dei moduli attivi.

8. Pianificazione dei task: cron

Il comando cron permette di gestire i task pianificati. ZeroClaw utilizza un sistema di scheduling che permette all'agente di eseguire azioni in momenti specifici o a intervalli regolari, rendendo l'AI proattiva anziché solo reattiva.

9. Gestione della comunicazione: channel

Il comando channel serve a configurare e gestire i canali attraverso i quali l'agente comunica. Questo include la gestione delle allowlist, assicurando che l'agente interagisca solo con entità autorizzate.

10. Espansione delle capacità: skills e integrations

Per rendere l'agente più utile, ZeroClaw mette a disposizione due comandi per l'estensione delle funzionalità:

• skills: Permette di gestire le capacità definite dall'utente (User-defined capabilities).
• integrations: Consente di esplorare il catalogo delle integrazioni disponibili per collegare l'agente a software terzi.

Tabella Riassuntiva dei Comandi

Conclusioni per l'utente

Il flusso di lavoro ideale per un principiante dovrebbe seguire questo ordine: onboard $\rightarrow$ agent (per i test) $\rightarrow$ daemon (per l'operatività) $\rightarrow$ service (per la persistenza). In caso di anomalie, l'uso di doctor e status permetterà di risolvere rapidamente i problemi di configurazione senza dover reinstallare l'intero sistema.