Costo e configurazione dell’API ZeroClaw: runtime gratuito, provider personalizzati, costo reale dei token

Il runtime ZeroClaw costa $0: è open source, con doppia licenza MIT OR Apache-2.0, e le FAQ ufficiali di zeroclaw.com affermano che non esiste alcun abbonamento né alcuna postazione ospitata; paghi solo i costi del tuo provider LLM, oppure nulla se esegui un modello locale con Ollama. La documentazione sulla filosofia del progetto è ancora più esplicita: "Non è un SaaS. Non esiste una versione ospitata, un sistema di account né fatturazione." Quindi, in pratica, "prezzi ZeroClaw" significa due altre fatture: i token del modello all’endpoint a cui indirizzi un alias e la macchina su cui gira il daemon. Entrambi verificati il 21 settembre 2026.

Due elementi ti costeranno denaro o tempo se li ignori. ZeroClaw Labs non pubblica alcun prezzo mensile, quindi un abbonamento mensile "ZeroClaw" che hai già visto appartiene al prodotto di qualcun altro. Inoltre, il registro dei costi di ZeroClaw segnalerà spesa zero su un gateway di terze parti finché non inserisci manualmente le tariffe, perché lo slot provider custom non dispone di un catalogo prezzi. Entrambi gli aspetti sono trattati di seguito.

Prezzi di ZeroClaw: quanto costa il software e cosa viene effettivamente addebitato

L'ultima riga è il risultato sbagliato su cui può approdare una ricerca di "zeroclaw pricing". Il README di ZeroClaw indica github.com/zeroclaw-labs/zeroclaw come unico repository ufficiale e dichiara che qualsiasi altro repository, organizzazione, dominio o pacchetto che sostenga di essere ZeroClaw è non autorizzato e non affiliato. Nei frammenti dei risultati di ricerca circola una seconda cifra mensile per agente per zeroclaw.live; il 21 settembre 2026 quel sito ha restituito un errore anziché una pagina, quindi il numero non ha potuto essere letto sulla pagina e viene deliberatamente omesso qui. Separatamente, tratta con cautela le cifre di marketing anche sui domini utilizzati dal progetto stesso: le landing page di zeroclaw.dev, zeroclaw.org e zeroclaw.net pubblicizzano tutte un binario da 3.4MB, mentre la pagina della filosofia del progetto afferma che una build di release tipica è di circa 26 MiB. Si tratta di una discrepanza tra documentazione e landing page, non di una prova di imitazione — il README indirizza le segnalazioni di sicurezza a un indirizzo su zeroclaw.dev. ZeroClaw vs OpenClaw analizza in dettaglio questo problema di identificazione.

Una nota sull'ambito, perché i due fatti sembrano contraddittori. "Nessuna fatturazione" è vero per il runtime ZeroClaw e falso per ZeroClaw Labs come organizzazione: la stessa organizzazione GitHub distribuisce ZeroRouter, un gateway AGPL la cui descrizione del repository indica la fatturazione Stripe prepagata, raggiungibile da ZeroClaw tramite il proprio slot zerorouter. È un prodotto diverso in beta, non un abbonamento ZeroClaw, e i suoi prezzi in hosting rappresentano lo stato live del gateway, non un listino prezzi pubblicato.

La struttura di configurazione da scrivere oggi: schema 3, non il frammento piatto

La documentazione ufficiale è aggiornata; gran parte della configurazione ZeroClaw che troverai nei risultati di ricerca non lo è. La versione corrente dello schema di configurazione è 3 — CURRENT_SCHEMA_VERSION: u32 = 3 in crates/zeroclaw-config/src/migration.rs al tag di release v0.8.5, con una catena di migrazione da V1 a V2 a V3. La struttura piatta che circola nei tutorial più vecchi è lo schema 1. Un file di configurazione privo di schema_version viene trattato come versione 1 e migrato in memoria al caricamento, quindi il file su disco non viene riscritto dal caricamento stesso.

Nota sulla denominazione: "ZeroClaw V3" non è una release. L'ultima release è v0.8.5, pubblicata il 5 settembre 2026 (API GitHub, verificata il 21 settembre 2026); lo schema 3 è il formato di configurazione al suo interno. I due numeri non sono correlati.

Nomi dei campi dello schema 1 letti dalla lente di migrazione V1 alla versione v0.8.5; le righe dello schema 2 provengono dai commenti di documentazione della lente V2 su master, entrambi del 21 settembre 2026. Queste lenti definiscono come viene interpretato un vecchio file durante la migrazione, motivo per cui costituiscono una buona prova dei nomi dei vecchi campi. Nell'ultima riga due fonti di date diverse non concordano: la lente V2 registra che V3 ha rimosso cost.prices e spostato i prezzi inline su ciascun provider di modelli, mentre la documentazione corrente sul monitoraggio dei costi definisce il campo inline per alias pricing come legacy e indica [cost.rates.*] come superficie futura che prevale in caso di conflitto. Scrivi [cost.rates.*].

Nello schema 3, ogni provider di modelli si trova in [providers.models.<type>.<alias>], dove il tipo è uno slot di famiglia canonico — "Esiste uno slot per ogni vendor, senza sinonimi" — e l'alias è scelto da te. La panoramica dei provider dichiara esplicitamente che "non esiste un parametro globale 'default provider' o 'default model'", e che Config::validate() fallisce esplicitamente all'avvio se un riferimento non viene risolto. Un frammento dello schema 1 copiato non viene rifiutato perché obsoleto — la catena di migrazione incorpora i suoi api_key, api_url e default_model di livello superiore in una voce provider denominata da default_provider, e la lente V1 sostituisce openrouter quando quella chiave è assente, quindi un frammento piatto contenente solo una chiave e un URL finisce in una voce openrouter anziché nel gateway desiderato. La modalità di errore è un riferimento non risolvibile, non un vecchio nome di campo.

Provider personalizzato ZeroClaw: indirizzare un alias a un'API compatibile con OpenAI

Un endpoint che parla il formato OpenAI chat-completions va nello slot custom, e la pagina sui provider personalizzati a v0.8.5 afferma che si tratta di una modifica solo alla configurazione: "Lo slot custom richiede uri (l'enum degli endpoint della famiglia non ha un valore predefinito)." Un endpoint che parla il formato Anthropic Messages va nello slot anthropic con uri impostato su override invece — non su custom. Kunavo serve entrambi i formati tramite https://api.kunavo.com/v1 con una sola chiave, quindi sulla carta entrambi gli slot sono adatti. Il frammento seguente unisce i campi documentati dello slot personalizzato alla struttura a quattro intestazioni dell'esempio completo della documentazione; è un adattamento, non un blocco ufficiale copiato.

# Four section headers is the smallest config that loads clean.
[providers.models.custom.kunavo]
uri     = "https://api.kunavo.com/v1"   # REQUIRED: the custom family has no default endpoint
model   = "claude-sonnet-4-6"
api_key = "sk-kn-..."                   # or the secrets store, op://, or a ZEROCLAW_ env override

[agents.assistant]
model_provider  = "custom.kunavo"       # there is no global default provider
risk_profile    = "supervised"
runtime_profile = "resident"

[risk_profiles.supervised]
level                            = "supervised"
workspace_only                   = true
require_approval_for_medium_risk = true
block_high_risk_commands         = true

[runtime_profiles.resident]
max_actions_per_hour   = 10             # example values from the docs, not defaults
max_cost_per_day_cents = 100
max_tool_iterations    = 4
agentic_timeout_secs   = 120

Quattro note pratiche. Le credenziali possono essere fornite in quattro modi — inline api_key, un riferimento 1Password op://vault/item/field, l'archivio crittografato in ~/.zeroclaw/secrets o l'override generico tramite env ZEROCLAW_providers__models__custom__kunavo__api_key, dove un doppio underscore corrisponde a un punto. Un nome di shell predefinito dell'ecosistema come $ANTHROPIC_API_KEY non viene letto direttamente a meno che la famiglia del provider non documenti il proprio bridge env nativo — la documentazione indica di espanderlo autonomamente nel nome speculare dello schema — e una variabile env speculare dello schema è un'iniezione runtime che non diventa mai configurazione persistente. Lo slot custom usa per impostazione predefinita il formato chat-completions, e wire_api viene rispettato nelle famiglie con endpoint fornito dall'utente (openai, llamacpp, custom), mentre gli slot dei vendor con marchio hanno un formato fisso e lo ignorano, con opencode indicato come unica eccezione. Se il tuo gateway rifiuta un campo temperature, lascialo non impostato: la documentazione afferma che un temperature non impostato viene omesso completamente dal corpo della richiesta. E un avvio senza errori dimostra meno di quanto sembri — il riscaldamento della connessione è una GET che consuma il corpo e accetta codici di stato non riusciti, quindi il daemon si avvia in entrambi i casi; la pagina sui provider personalizzati su master lo documenta come GET {base_url}/models, mentre il codice v0.8.5 riscalda invece l'URL chat-completions.

Convalida nell'ordine documentato, tutte e tre a v0.8.5: zeroclaw config list carica la configurazione e stampa gli errori di convalida su stderr, zeroclaw models refresh --model-provider custom.kunavo elenca ciò che l'endpoint pubblicizza e zeroclaw agent -a assistant -m "hello" esegue uno smoke test dell'agente. L'endpoint /v1/models di Kunavo risponde HTTP 401 senza una chiave (verificato il 21 settembre 2026), il che non è un blocco: il comando di aggiornamento invia la chiave dell'alias. Kunavo non ha testato ZeroClaw a runtime — tutto ciò che è presente in questa sezione è una revisione dei documenti sorgente di ZeroClaw, quindi esegui una tua attività vincolata prima di fidarti della route.

Kunavo non offre modelli di embedding, text-to-speech o speech-to-text, quindi un agente che necessita di questi passaggi li indirizza a un endpoint diverso, indipendentemente dallo slot ZeroClaw in cui si trova il modello chat.

Il contatore dei costi indica $0 finché non scrivi il listino delle tariffe

ZeroClaw misura la propria spesa e, su un gateway di terze parti, quel contatore parte dal valore sbagliato. Il monitoraggio dei costi è controllato da cost.enabled, e i record vengono scritti in un ledger append-only in <workspace>/state/costs.jsonl, un oggetto JSON per riga. Il problema è da dove provengono i prezzi. In catalog.rs a v0.8.5, catalog_source_for non restituisce né una chiave models.dev né un prefisso vendor OpenRouter per la famiglia custom — la maggior parte degli slot con marchio contiene almeno uno dei due, anche se diversi (zerorouter, telnyx, nearai) non contengono nessuno dei due. L'opt-in live_pricing è disattivato per impostazione predefinita e, quando è attivo, legge prima l'elenco /models dell'endpoint e ricorre a models.dev indicizzato con il nome models.dev della famiglia; la famiglia custom non ha una chiave simile, quindi per questo slot l'elenco dell'endpoint è l'unica fonte. L'elenco di Kunavo non contiene un campo di prezzo per token, letto dalla fonte della route e non da una risposta di produzione autenticata. Pertanto un alias di slot personalizzato registra cost_usd = 0 con unpriced_tokens superiore a zero finché non inserisci manualmente le tariffe.

[cost]
enabled = true

# Keyed by the UPSTREAM model id as it appears in usage telemetry,
# not by your alias. USD per 1M tokens.
[cost.rates.providers.models.custom.claude-sonnet-4-6]
input        = 2.1
output       = 10.5
cached_input = 0.21

Da ciò derivano tre comportamenti, tutti dalla documentazione sul monitoraggio dei costi, verificata il 21 settembre 2026. Le voci delle tariffe sono indicizzate dall'ID del modello upstream così come appare nella telemetria di utilizzo, non dal tuo alias. I confronti con il budget usano cost_usd registrato, quindi un totale giornaliero o mensile sotto il proprio limite non è una garanzia di sicurezza mentre il mese contiene token senza prezzo. E le righe già presenti nel ledger non vengono mai ricalcolate: "non esiste un ricalcolo retroattivo", quindi le tariffe si applicano solo alle richieste effettuate dopo la loro configurazione. L'applicazione ha tre modalità — warn (quella predefinita), block e route_down, che sostituisce con un route_down_model più economico — più allow_override, che per impostazione predefinita è false e consente a una richiesta di bypassare block con un token di override sulla CLI.

Una stima completa usando il limite giornaliero di ZeroClaw

Si tratta di un calcolo illustrativo dei token, non del costo misurato di un'attività né di un limite di fatturazione. L'esempio completo della documentazione con [runtime_profiles] limita un agente a max_actions_per_hour = 10 e max_cost_per_day_cents = 100 — valori di esempio per un piccolo modello locale, non impostazioni predefinite. Considera letteralmente questo limite per otto ore attive al giorno: 80 turni al giorno, ciascuno con 6.000 token di input non memorizzati nella cache e 500 token di output. Le tariffe sono i prezzi live del catalogo Kunavo per milione di token.

La lettura utile non è la classifica, ma l'interazione con il limite. Un profilo scritto per un piccolo modello locale colloca un modello frontier sotto gli stessi limiti: max_actions_per_hour vincola il volume dei turni e il limite giornaliero dei costi rifiuta una richiesta solo quando enforcement.mode è block. Con warn, l'impostazione predefinita, il limite non blocca affatto — registra l'evento e lascia passare la richiesta. (warn_at_percent, predefinito all'80%, è un parametro separato: controlla quando il gateway mostra un avviso prima del limite rigido.) Peggio ancora, se non hai mai scritto il listino delle tariffe sopra, nulla di tutto questo si attiva, perché il limite non può vedere i token senza prezzo. Ridimensiona la tabella in base al tuo volume di turni e al rapporto input-output prima di considerarla un budget; esclude i costi della cache, le chiamate agli strumenti e i retry, e presuppone che il modello più economico completi il lavoro senza tentativi aggiuntivi.

L'importo del catalogo Kunavo è un minimo di fatturazione, non un limite: quando l'upstream comunica il proprio addebito, la fattura è il maggiore tra il costo del catalogo e il costo upstream moltiplicato per il markup applicabile. La ricarica minima è $10 di credito prepagato, che rappresenta un minimo di finanziamento, non una tariffa per attività né un abbonamento — vedi i dettagli di fatturazione.

Miglior modello e migliore API per ZeroClaw: cosa il progetto dirà e non dirà

ZeroClaw non pubblica alcun modello consigliato e si rifiuta di indicarne uno ufficialmente. La sua pagina sulla configurazione multi-modello afferma che "questo flusso di lavoro non stabilisce un elenco di modelli verificati da ZeroClaw" e che "le prove per una build, un modello, una quantizzazione e un'impostazione del contesto non verificano altre combinazioni". Questa è la risposta onesta a "qual è il miglior modello per ZeroClaw": non esiste una classifica ufficiale da citare, quindi scegli in base a due proprietà verificabili.

La prima è il tool calling nativo, per il quale la stessa pagina stabilisce un requisito rigoroso: "Esamina l'esecuzione alla ricerca di una chiamata effettiva allo strumento, del relativo risultato eseguito e di una continuazione dell'assistente che utilizzi quel risultato. Una risposta plausibile o il solo markup stampato della chiamata allo strumento non costituiscono un test dello strumento superato." Il parametro del profilo runtime strict_tool_parsing tratta il testo di fallback che sembra XML o JSON come semplice testo dell'assistente, a meno che il provider non restituisca chiamate reali agli strumenti, quindi un modello che si limita a descrivere una chiamata allo strumento sembrerà funzionare ma non agirà mai. La seconda è se il modello completa la tua attività senza tentativi aggiuntivi — motivo per cui il prezzo elencato più basso e il costo più basso per completare il lavoro sono affermazioni diverse.

Due comportamenti da considerare nel budget prima di abilitare il failover. Lo streaming ha il contratto più restrittivo: la pagina sul ciclo di vita del routing dei provider afferma che il wrapper "sceglie la prima voce ordinata che supporta le capacità di streaming richieste e non è in raffreddamento", quindi "apre quello stream una sola volta" e "non cambia voce dopo l'avvio dello stream" — tuttavia uno stream che fallisce prima che venga confermato qualsiasi output viene ritentato tramite il percorso non-streaming, che rientra nel percorso completo di affidabilità su fallback_models e fallback. Questi retry non-streaming coprono timeout, errore di connessione, 429 e 503, ed escludono esplicitamente 400, errori permanenti di autenticazione o errori nell'output del modello. Inoltre, una voce di fallback può spostare il lavoro su un livello di prezzo diverso, quindi assegnale prima un budget. Per un confronto più ampio delle route del gateway, vedi la guida all'API compatibile con OpenAI e le alternative a OpenRouter.

Attività ricorrente: profili di rischio, limiti e il servizio che la riavvia

L'autonomia è per agente, non globale. La pagina sull'autonomia a v0.8.5 accetta esattamente tre livelli — readonly, supervised e full — e rifiuta read_only con un underscore al caricamento della configurazione. Con l'impostazione predefinita supervised, gli strumenti a basso rischio vengono eseguiti automaticamente, quelli a rischio medio mostrano una richiesta di approvazione dell'operatore e quelli ad alto rischio vengono bloccati. Le richieste di approvazione scadono dopo il approval_timeout_secs del canale, 120 secondi per la maggior parte dei canali, e un timeout equivale a un rifiuto — un agente non presidiato quindi si arresta in modo sicuro anziché accodare la richiesta.

Due limiti per le attività ricorrenti. Il comportamento al riavvio non è uniforme tra le piattaforme: l'unità user systemd installata imposta Restart=always con RestartSec=3 e senza una allowlist dei codici di uscita, quindi un daemon che fallisce rapidamente a causa di una configurazione errata entrerà in un ciclo di riavvii; il LaunchAgent macOS imposta RunAtLoad e KeepAlive; e su Windows zeroclaw service install registra un'attività dell'Utilità di pianificazione ONLOGON che avvia il daemon all'accesso senza aggiungere una policy di riavvio in caso di errore. Il lavoro pianificato è dichiarativo e indicizzato per alias in [cron.<alias>], separato dai parametri propri della sezione [scheduler]. Inoltre, il motore SOP deterministico è contrassegnato come experimental dalla matrice delle funzionalità del progetto — i trigger periferici e di calendario sono definiti e associati, ma non ancora instradati verso una fonte live — quindi non progettare ancora un flusso di lavoro non presidiato basato su di esso.

Configuralo e verifica il primo addebito

Kunavo non pubblica alcuna pagina di integrazione specifica per ZeroClaw e non ha testato il client a runtime, quindi considera la configurazione precedente una route basata sui documenti sorgente, non un risultato di compatibilità. La sequenza pratica è breve: crea una chiave, finanzia la ricarica minima, scrivi le quattro intestazioni, esegui i tre comandi di convalida nell'ordine, quindi scrivi il blocco [cost.rates.*] prima della prima esecuzione lunga, così il ledger avrà qualcosa da registrare. Inizia dal quickstart per l'URL di base e il formato della chiave, dal riferimento chat-completions per il formato utilizzato dallo slot custom, e crea un account Kunavo quando sei pronto a effettuare il finanziamento. Se il tuo agente utilizza invece il formato Anthropic, il documento sull'URL di base Anthropic descrive la route dello slot anthropic.

Domande frequenti

Verificato il 21 settembre 2026. Riletto direttamente per questa pagina: la FAQ di zeroclaw.com, il README del repository, l'API GitHub per lo stato del repository e la release v0.8.5, migration.rs, schema/v1.rs, catalog.rs, compatible.rs, providers/custom.md, security/autonomy.md e ops/service.md al tag v0.8.5, e su master la lente di migrazione V2, providers/overview.md, providers/configuration.md, providers/catalog.md, providers/routing.md, providers/custom.md, architecture/provider-routing-lifecycle.md, ops/cost-tracking.md, getting-started/multi-model-setup.md, philosophy/minimal.md, philosophy/what-this-isnt.md e reference/feature-matrix.md, oltre al repository zerorouter, ai siti di terze parti e alle landing page citati sopra, e a una GET non autenticata all'endpoint /v1/models di Kunavo. Qualsiasi contenuto citato da master è documentazione del ramo di sviluppo e può essere più avanti rispetto alla release stabile. Kunavo non ha testato ZeroClaw a runtime: non è stata eseguita alcuna installazione, né config list né un'esecuzione dell'agente, quindi streaming, tool calling nativo e visione tramite questa route non sono verificati in questa sede. Le tariffe dei token Kunavo vengono lette dal catalogo live e ogni cifra in dollari su questa pagina è un calcolo illustrativo dei token.