Come è costruito ClawAI

Diciotto servizi distribuibili in modo indipendente, ciascuno proprietario del proprio database, coordinati da una struttura orientata agli eventi. Le risposte vengono trasmesse mentre sono generate e ogni livello è protetto separatamente.

Ultima revisione 2026-07-25

Com’è costruito ClawAI

ClawAI è formato da diciotto servizi distribuibili in modo indipendente dietro un unico reverse proxy. Autenticazione, chat, instradamento, connettori, memoria, file, ricerca, spazio di lavoro, generazione di immagini, esportazione di documenti, fatturazione, audit e logging girano ciascuno come processo a sé con il proprio database. L’app web li raggiunge tutti attraverso un’unica superficie API.

Il motivo è il contenimento. Un provider lento, una conversione di file bloccata o un’esportazione fallita non possono trascinarsi dietro la chat, perché non condividono processo, pool di connessioni né database. Ogni servizio viene rilasciato, scalato e riportato indietro per conto proprio.

18: Servizi distribuibili in modo indipendente
Uno per servizio: Nessun database condiviso, mai
HTTP + eventi: Chiamate sincrone più un bus di eventi asincrono
Un solo punto d’ingresso: Un unico reverse proxy davanti a tutto

I servizi

Non tutti i servizi sono interessanti visti da fuori. Questi sono quelli che una singola richiesta tende a toccare, più o meno nell’ordine in cui li tocca.

AutenticazionePostgreSQL: Account, sessioni, emissione dei token e rotazione dei refresh, ruoli e set di permessi.
ChatPostgreSQL: Conversazioni e messaggi, assemblaggio del contesto, esecuzione in streaming e orchestrazione multi-modello.
InstradamentoPostgreSQL: Classifica ogni messaggio, applica la modalità attiva e le eventuali policy e registra la decisione con la sua catena di fallback.
ConnettoriPostgreSQL: Credenziali dei provider, cataloghi dei modelli, flag di capacità e controlli di salute continui.
Memoria e contestoPostgreSQL + pgvector: Voci di memoria, coda delle proposte, context pack e relative versioni, e recupero semantico.
FilePostgreSQL: Caricamenti, analisi di sicurezza, estrazione del testo, OCR, suddivisione in chunk e conservazione.
RicercaPostgreSQL: Ricerca sul web, recupero delle pagine e raccolta delle evidenze per risposte con fonti.
Spazio di lavoroPostgreSQL: Connessioni OAuth a dodici strumenti di terze parti, webhook, sincronizzazione pianificata e ricerca trasversale.
Generazione di immaginiPostgreSQL: Richieste di immagini, adattatori dei provider e avanzamento passo dopo passo mentre un’immagine viene generata.
Generazione di documentiPostgreSQL: Trasformazione delle risposte in PDF, DOCX, CSV, HTML, Markdown, TXT e JSON.
FatturazionePostgreSQL: Piani, abbonamenti, prezzi versionati, fatture e applicazione dei plafond.
AuditMongoDB: Il registro immutabile di chi ha fatto cosa, più il libro mastro dell’utilizzo da cui deriva ogni valore di plafond.
LoggingMongoDB: Log strutturati da ogni servizio e dal browser, conservati su una finestra scorrevole.

Ogni servizio indica il database che possiede. Nient’altro vi si collega: un servizio che ha bisogno dei dati di un altro li chiede via HTTP oppure reagisce a un evento.

Un database per servizio

Ogni servizio possiede esattamente un database ed è l’unico a collegarvisi. Non esistono schemi condivisi, join tra servizi né database di reporting che leggono in silenzio le tabelle di tutti.

Il prezzo è che alcune domande richiedono due chiamate invece di un join. Il vantaggio è che una modifica dello schema della fatturazione non può rompere la chat, e una query fuori controllo nel logging non può esaurire il pool di connessioni da cui dipende la tua conversazione.

Nessuna query tra database: Un servizio legge le proprie tabelle e nessun’altra. I dati altrui arrivano tramite una chiamata API o un evento.
Gli schemi sono privati: Un servizio può modificare le proprie tabelle senza coordinarsi con nessuno, perché nessun consumatore esterno dipende dalla loro forma.
Le migrazioni girano per servizio: Ogni servizio migra il proprio database all’avvio. Non esiste una migrazione globale che tutti devono attendere.
I guasti restano locali: Un database lento o non disponibile degrada una singola funzionalità anziché l’intero prodotto.

La vita di una richiesta

Cosa succede tra il momento in cui premi invio e quello in cui leggi la risposta.

La richiesta viene autenticata
il reverse proxy la passa alla chat, che verifica il tuo token di accesso e i permessi legati al tuo ruolo.
Il plafond viene controllato
la fatturazione conferma che il tuo piano consente il modello richiesto e che il plafond giornaliero e mensile ha ancora spazio.
Il messaggio viene salvato e annunciato
la chat scrive il messaggio nel proprio database e pubblica un evento. L’instradamento è in ascolto.
L’instradamento sceglie un modello
il messaggio viene classificato, si applicano la modalità attiva e le policy, si consulta lo stato dei connettori e si registra una decisione con la sua catena di fallback.
Il contesto viene assemblato
la chat chiede alla memoria le voci e gli elementi dei pacchetti pertinenti e ai file i chunk rilevanti, poi li unisce al prompt entro un budget di token.
Il modello viene chiamato e trasmesso in streaming
la chat chiama il provider e inoltra al tuo browser fasi, testo, ragionamento e metriche tramite Server-Sent Events man mano che arrivano.
Il risultato viene persistito
la risposta, la sua decisione di instradamento, il conteggio dei token e la sua ricevuta di contesto vengono scritti insieme.
Utilizzo e audit vengono registrati
la fatturazione conteggia il costo sul tuo plafond e l’audit registra l’evento. Anche l’estrazione della memoria avviene qui.

I passaggi da 1 a 7 sono sincroni: li attendi. Il passaggio 8 e l’estrazione della memoria avvengono quando la risposta è già sul tuo schermo, quindi non aggiungono latenza a ciò che percepisci.

Il bus di eventi

Il lavoro che non deve concludersi prima che tu veda una risposta viene pubblicato come evento su un topic exchange RabbitMQ e gestito dai servizi che se ne interessano. Conteggio dell’utilizzo, registrazioni di audit ed estrazione della memoria funzionano tutti così.

Gli eventi sono il motivo per cui la chat non ha bisogno di sapere che l’audit esiste. La chat dichiara cos’è successo; chi deve reagire si iscrive. Aggiungere un consumatore non richiede alcuna modifica al pubblicatore.

Topic exchange: I pubblicatori dichiarano cos’è successo, non chi debba ascoltarlo. I consumatori si legano ai pattern che li interessano.
Nuovi tentativi con attesa crescente: Un handler fallito viene ritentato tre volte con ritardo crescente, cosa che assorbe i guasti transitori, che sono la maggioranza.
Coda dei messaggi non recapitati: Un messaggio che fallisce anche dopo i tentativi finisce in una dead-letter queue invece di essere perso o di bloccare tutto ciò che sta dietro.
Handler idempotenti: Gli handler tollerano l’arrivo doppio dello stesso evento, perché la consegna at-least-once garantisce che prima o poi accadrà.
Tutto è verificabile: L’audit si iscrive a ogni evento di dominio, così il registro di ciò che è successo non dipende dal fatto che ogni servizio si ricordi di scriverlo.

Streaming

Le risposte arrivano tramite Server-Sent Events, non con il polling. La connessione si apre quando invii un messaggio e trasporta tutto finché la risposta non è completata o annullata.

Il buffering è disattivato da un capo all’altro — sul proxy e in ogni servizio del percorso — perché uno stream con buffer è solo una risposta lenta con qualche passaggio in più.

Lo stesso canale trasporta la generazione di testo, l’avanzamento della generazione di immagini e le ricerche di lunga durata, così l’interfaccia ha un unico modo per mostrare il lavoro in corso anziché tre.

Cambi di fase: In coda, instradamento, assemblaggio del contesto, chiamata al modello, conclusione: così una pausa ha sempre un motivo visibile.
Delta di contenuto: Il testo della risposta man mano che il modello lo produce, token dopo token.
Delta di ragionamento: Per i modelli che espongono il proprio pensiero, il flusso di ragionamento viene consegnato separatamente dalla risposta e anche visualizzato a parte.
Aggiornamenti delle metriche: Token finora, token al secondo, tempo al primo token e dove è finito davvero il tempo: caricamento del modello, valutazione del prompt o generazione.
Eventi terminali: Un riepilogo finale dell’utilizzo, oppure un errore o un annullamento espliciti. Lo stream non si interrompe mai e basta.

Cosa memorizza cosa

Quattro tipi di archivio, ciascuno usato per ciò in cui è bravo.

PostgreSQL: Il registro di riferimento per account, conversazioni, decisioni di instradamento, memoria, file, connessioni e fatturazione — un database per servizio.
pgvector: Ricerca per similarità vettoriale dentro PostgreSQL, usata per recuperare memorie ed elementi dei context pack pertinenti senza gestire un database vettoriale separato.
MongoDB: Eventi di audit, libro mastro dell’utilizzo e log strutturati: dati ad alto volume in sola aggiunta, con una finestra di conservazione scorrevole.
Redis: Cache, contatori per i limiti di frequenza e stato di coordinamento di breve durata. Nulla di importante è conservato solo qui.

Meccanismi di sicurezza

Controlli concreti presenti nel prodotto. Nessuna rivendicazione di certificazioni: vedi la nota finale.

Token di accesso e di refresh: Token di accesso a breve durata con rotazione dei refresh. Il riutilizzo di un token già ruotato invalida la sessione.
Hashing delle password: Argon2 con salt per utente. Le password non vengono mai memorizzate né registrate in una forma recuperabile.
Controllo degli accessi basato sui ruoli: I ruoli portano set di permessi espliciti, applicati da guardie su ogni endpoint di ogni servizio, non solo nell’interfaccia.
Credenziali cifrate: I segreti dei provider e dei connettori sono cifrati a riposo con AES-256-GCM e non vengono mai restituiti da un’API.
Validazione degli schemi: Ogni corpo di richiesta è validato con uno schema Zod, con limiti espliciti di lunghezza e dimensione, prima di raggiungere qualsiasi logica.
Limitazione della frequenza: Throttling per account su ogni servizio, così un singolo client non può esaurire la capacità di tutti gli altri.
Header di sicurezza: Una content security policy rigorosa con nonce per richiesta, HSTS e i consueti header di irrobustimento su ogni risposta.
TLS ovunque: TLS dal browser al perimetro e di nuovo su ogni passaggio interno, con verifica dei certificati tra i servizi.
Oscuramento nei log: Token, password, chiavi API e header di autorizzazione vengono rimossi prima che qualsiasi cosa venga scritta in un log.

Oggi ClawAI non possiede certificazioni di sicurezza di terze parti: né SOC 2, né ISO 27001, né HIPAA. Descriviamo i meccanismi qui sopra invece di lasciar intendere garanzie che non abbiamo ottenuto. Le organizzazioni con requisiti formali dovrebbero segnalarceli, così da poterli definire nell’ambito di un progetto dedicato.

Osservabilità

Ogni servizio emette gli stessi segnali nella stessa forma, e tutti finiscono in un posto interrogabile. Chi deve rispondere a “cos’è successo a questa richiesta” non dovrebbe aprire diciotto file di log.

Log strutturati: Log JSON da ogni servizio e dal browser, spediti sul bus di eventi e conservati su una finestra scorrevole.
Correlazione delle richieste: Un ID di richiesta viene generato nel browser e portato attraverso ogni passaggio tra i servizi, così un solo identificatore ricostruisce l’intero percorso.
Eventi di audit: Un registro separato e immutabile delle azioni rilevanti per la sicurezza e per il business, tenuto distinto dai log operativi.
Libro mastro dell’utilizzo: Ogni chiamata conteggiata viene scritta come voce di libro mastro. I valori del plafond derivano dal libro mastro, non da un contatore che potrebbe scostarsi.
Aggregazione dello stato di salute: Un servizio dedicato interroga tutti gli altri e riporta una vista consolidata di ciò che è attivo.

Quando qualcosa va storto

I provider di modelli hanno disservizi, limiti di frequenza e giornate lente. La piattaforma è costruita per assorbirli invece di scaricarteli addosso come una rotellina che gira all’infinito.

Catene di fallback: Ogni decisione di instradamento porta con sé un elenco ordinato di alternative. Se il modello scelto fallisce, il successivo viene provato automaticamente e la sostituzione viene registrata.
Esclusione in base allo stato di salute: I connettori sono sottoposti a controlli continui, e un provider in difficoltà viene saltato dall’instradamento finché non si riprende.
Nuovi tentativi sicuri: Gli handler degli eventi tollerano la consegna duplicata, così un nuovo tentativo corregge un guasto invece di addebitare due volte il tuo plafond.
Gli errori sono visibili: Quando tutte le opzioni falliscono, un errore esplicito viene scritto nella conversazione e spinto lungo lo stream. Non esiste un guasto silenzioso che lascia l’interfaccia in attesa.
Raggio d’impatto: Processi e database separati fanno sì che un guasto degradi una sola funzionalità. Se la generazione di immagini è ferma, puoi comunque chattare.

La stessa architettura, dentro la vostra rete

Tutto ciò che c’è in questa pagina descrive il servizio in hosting, ma l’architettura non è legata a esso. Gli stessi diciotto servizi, lo stesso bus di eventi e lo stesso modello di dati possono essere installati all’interno della rete di un’organizzazione.

In quella configurazione i provider di modelli esterni sono sostituiti da modelli a pesi aperti serviti sulle vostre GPU, così nessun prompt, documento o conversazione lascia la vostra infrastruttura. È un progetto definito su misura, non un piano acquistabile: lo dimensioniamo insieme al vostro team.

Parliamo di un’installazione privata

Guardala all’opera

Il modo più rapido per giudicare un’architettura è usare ciò che produce. Il piano Free richiede un minuto per essere attivato.

Crea il tuo account Parliamo di un’installazione privata