Prezzi e configurazione API di PicoClaw: modelli, protocolli e chiavi

Il software PicoClaw è gratuito: il repository è distribuito con licenza MIT e le FAQ di picoclaw.io dichiarano: "The software is free. You only pay for the LLM API usage" — quindi "prezzi di PicoClaw" indica la fattura dell'API del tuo modello, oltre all'eventuale costo del dispositivo. Sipeed non pubblicizza alcun abbonamento PicoClaw né alcun livello ospitato. Il dato da mettere a budget è il numero di token per turno dell'agente, e l'impostazione che più probabilmente sorprenderà è il limite di iterazioni degli strumenti di PicoClaw: 50 quando il campo è assente, 20 nel file di configurazione di esempio incluso.

Prima due disambiguazioni, perché la pagina dei risultati le mescola. Il dominio ufficiale è picoclaw.io — è il campo homepage di github.com/sipeed/picoclaw. Il dominio simile pico-claw.com dichiara nel proprio piè di pagina di "non essere ufficialmente affiliato a Sipeed o PicoClaw", e il prezzo mensile indicato appartiene al modulo di hosting gestito di quel sito, non a PicoClaw. Anche picoclaw.net non è il dominio ufficiale. Presenta i titoli "95% AI-Generated Code" e "3 Supported Architectures" — x86_64, ARM64 e RISC-V — mentre le FAQ su picoclaw.io ne elencano sei. Inoltre PicoClaw non è un fork di OpenClaw; è un'implementazione indipendente in Go che confronta le proprie prestazioni con OpenClaw e NanoBot.

Prezzi di PicoClaw, voce per voce

Tutto verificato il 21 settembre 2026. Versione, per completezza: l'ultima release contrassegnata è v0.3.1, pubblicata il 3 luglio 2026, mentre l'ultimo push del repository risale al 17 settembre 2026 — quindi il codice su main è più avanti del tag, e l'elenco delle novità nel README è ancora più obsoleto, con come voce più recente la release v0.2.9 del 28 maggio 2026. Ogni comportamento riportato di seguito è stato letto su main, non dal binario v0.3.1 che scaricheresti; chi usa la release contrassegnata potrebbe osservare qualcosa di diverso. Una condizione effettiva alla data della verifica: il certificato TLS di picoclaw.io era scaduto (valido dal 25 febbraio al 10 settembre 2026), quindi un browser mostra un avviso di sicurezza nella pagina ufficiale dei download. Potrebbe essere risolto in qualsiasi momento e non dice nulla sul progetto; GitHub Releases non è interessato.

Configurazione della chiave API PicoClaw: model_list e .security.yml

picoclaw onboard crea ~/.picoclaw/config.json e l'area di lavoro. I modelli sono dichiarati in un array model_list e selezionati per nome da agents.defaults.model_name; i due valori devono corrispondere, ed è l'unico caso trattato dal documento di risoluzione dei problemi di PicoClaw.

{
  "agents": {
    "defaults": {
      "model_name": "gateway-sonnet"
    }
  },
  "model_list": [
    {
      "model_name": "gateway-sonnet",
      "provider": "openai",
      "model": "claude-sonnet-4-6",
      "api_base": "https://api.kunavo.com/v1",
      "enabled": true
    }
  ]
}

Le chiavi risiedono in un secondo file. La documentazione sulla sicurezza di PicoClaw chiama config.json "Configurazione principale (sicura da condividere)" e .security.yml "Dati di sicurezza (da non condividere mai)" e indica di eseguire chmod 600. La struttura YAML è una mappa indicizzata da model_name, non l'array usato in config.json, e api_keys è plurale ed è un array anche per una singola chiave.

# The map key must equal the model_name in config.json.
# api_keys is plural and is an array even for one key.
model_list:
  gateway-sonnet:
    api_keys:
      - "sk-kn-..."

Quattro dettagli che spesso sorprendono. provider è facoltativo: se lo imposti, model viene inviato al provider senza modifiche; se lo ometti, PicoClaw legge come provider tutto ciò che precede il primo / in model, ovvero il formato legacy protocol/model. La configurazione è dotata di versione dello schema e la versione corrente è la 3; la migrazione crea un backup con data, e la documentazione avverte che un file V3 non può essere caricato in sicurezza da build precedenti che supportano solo V2. Durante la migrazione da V1 a V2 enabled viene dedotto automaticamente — le voci senza chiave API e non denominate local-model vengono impostate per impostazione predefinita su disabled — motivo per cui l'esempio sopra imposta esplicitamente enabled dopo aver spostato le chiavi in .security.yml. Inoltre, lo streaming è disattivato per impostazione predefinita e subordinato a due condizioni: sia streaming.enabled della voce del modello sia settings.streaming.enabled del canale devono essere true.

Un limite da chiarire prima di creare le voci: la tabella dei vendor di PicoClaw elenca Groq come "LLM + trascrizione vocale (Whisper)" e Kunavo non offre conversione da voce a testo, da testo a voce o embeddings — una voce per trascrizione o embeddings deve puntare a un altro provider e solo le voci di chat sono candidate per una chiave Kunavo.

I nomi dei protocolli sono invertiti, ed è questa l'insidia principale

In PicoClaw, anthropic indica modelli in stile Claude sul formato wire OpenAI, mentre anthropic-messages indica la Messages API nativa di Anthropic. La documentazione lo afferma esplicitamente: "Il protocollo anthropic usa il formato compatibile con OpenAI (/v1/chat/completions), mentre anthropic-messages usa il formato nativo di Anthropic (/v1/messages)." Anche il codice concorda — factory_provider.go crea il provider HTTP condiviso compatibile con OpenAI per anthropic e un provider nativo separato per anthropic-messages. La tabella "All Supported Vendors" di PicoClaw contraddice entrambi, etichettando la colonna del protocollo della riga anthropic come "Anthropic"; chi legge solo quella tabella configura quello sbagliato.

Letto da openai_compat/provider.go, common/anthropic_common.go, anthropic_messages/provider.go e factory_provider.go su main, 21 settembre 2026 — dedotto dal codice, non osservato sul wire. La conseguenza è concreta: non puoi indirizzare anthropic o anthropic-messages verso un gateway il cui percorso non deve terminare con /v1, perché PicoClaw lo aggiunge comunque. Un gateway su https://gw.example.com/anthropic diventa https://gw.example.com/anthropic/v1/messages. Per un endpoint di questo tipo, il protocollo openai, che rispetta il percorso alla lettera, è l'unico in grado di esprimere l'URL. Sono stati verificati solo questi tre protocolli; non estendere la regola a gemini, azure o agli altri.

Altri due limiti del percorso nativo, entrambi letti nello stesso file. anthropic-messages richiede una chiave API e genera un errore bloccante senza di essa, quindi il ramo OAuth — che factory_provider.go collega a anthropic e openai, insieme ai bridge CLI e a antigravity — non può essere raggiunto tramite questo percorso. Inoltre, mentre cinque rami in factory_provider.go inoltrano cfg.CustomHeaders, il ramo anthropic-messages non è tra questi: il suo costruttore accetta solo la chiave, l'URL di base, lo user agent e il timeout. Quindi l'escape hatch custom_headers documentato per un gateway con autenticazione non standard sembra raggiungere i protocolli compatibili con OpenAI, ma non quello Messages nativo. Questa è una lettura del codice sorgente, non un test a runtime. Ciò che il percorso nativo non ti fa perdere è il tool calling: costruisce tools nativo con input_schema e gestisce i blocchi tool_use e tool_result.

Per Kunavo i due URL di base documentati sono https://api.kunavo.com/v1 per i completamenti chat e https://api.kunavo.com/v1/messages per il percorso Messages; il gestore Messages di Kunavo legge la chiave sia da x-api-key sia da Authorization: Bearer. Sulla carta, questi valori soddisfano l'aritmetica degli URL di PicoClaw in entrambe le direzioni. Si tratta però di aritmetica basata su due insiemi di documentazione — qui non è stata effettuata alcuna richiesta PicoClaw a Kunavo e questa pagina non dichiara che alcun protocollo PicoClaw sia stato testato con esso. Consulta la documentazione sull'URL di base Anthropic e la documentazione sull'endpoint chat per le strutture esatte, quindi invia tu una richiesta con limiti definiti.

Una stima dei costi dell'API PicoClaw con un esempio concreto

Questi sono calcoli illustrativi dei token, non costi misurati di un'attività né un limite massimo della fattura. Supponiamo un turno dell'agente che si risolva in 8 cicli di strumenti, in cui ogni ciclo reinvia una trascrizione con una media di 12.000 token di input e restituisce 700 token di output. Questi rapporti sono ipotesi illustrative. La seconda colonna applica la stessa struttura al valore predefinito compilato max_tool_iterations di 50 in pkg/config/defaults.go, applicato quando il campo è assente — il file config/config.example.json incluso scrive 20, quindi leggi il tuo file prima di considerare 50 il tuo limite. Le tariffe sono i prezzi del catalogo Kunavo aggiornati, per milione di token.

Leggi le due colonne come un unico dato. Passare da 8 cicli al limite di 50 moltiplica ogni riga per lo stesso fattore 6,25x, perché la lunghezza del ciclo è indipendente dalla tariffa: un turno Claude Sonnet 4.6 costa $0,260 con 8 cicli e $1,627 al limite, mentre Claude Haiku 4.5 allo stesso limite costa $0,542. Quindi imposta max_tool_iterations a un numero che hai effettivamente osservato prima di cercare una tariffa più economica — si trova sotto agents.defaults e può essere sovrascritto dalla variabile d'ambiente PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS. Poi moltiplica per i turni giornalieri.

L'importo del catalogo Kunavo è un minimo di fatturazione, non un tetto massimo: quando il provider upstream comunica il proprio addebito, la fattura è il maggiore tra il costo del catalogo e il costo upstream moltiplicato per il markup applicabile. Le letture e scritture della cache hanno tariffe proprie e qui non sono modellate in nessuna delle due direzioni; anche le chiamate a strumenti esterni sono escluse dall'esempio. La ricarica minima è $10 di credito prepagato, un minimo di finanziamento e non un costo dell'attività o un abbonamento — consulta i dettagli di fatturazione e l'ottimizzazione dei costi AI per il metodo di misurazione.

La migliore API per PicoClaw: quale percorso vince e quando

Il numero di provider non è un asse di confronto utile in questo caso: i file di PicoClaw non concordano tra loro su quali provider esistano, quindi la formulazione del README, "30+ provider LLM", è quella più sicura da ripetere. Per capire dove si colloca PicoClaw tra gli altri agenti a binario singolo, la directory delle API per agenti AI elenca la sua superficie di configurazione accanto alle loro, mentre le alternative a OpenRouter confronta i percorsi gateway in base ai termini di finanziamento, non alla profondità dell'integrazione.

Prima richiesta, primo ciclo di strumenti e un 404

Esegui un'attività circoscritta e leggi tre elementi in ordine. Un errore modello non trovato in model_list è il caso documentato ed è dovuto a una mancata corrispondenza nei nomi: agents.defaults.model_name deve coincidere con una voce model_name, e un ID senza prefisso, per il quale non è impostato alcun provider, non seleziona il fornitore che intendevi usare: ricorre invece al protocollo openai, che corrisponde al caso documentato "model": "free" in cui OpenRouter riceve l'ID letterale free e lo rifiuta. Un 404 alla prima richiesta è il segnale documentato che hai scelto il protocollo Anthropic sbagliato: le indicazioni di PicoClaw stesso raccomandano di passare a anthropic-messages quando "il protocollo anthropic esistente restituisce errori 404 (indicando che l'endpoint non supporta il formato compatibile con OpenAI)". Verifica l'URL composto confrontandolo con la tabella sopra prima di modificare qualsiasi altra cosa; non esiste una voce ufficiale per la risoluzione di questo problema, quindi questa diagnosi deriva dalla nota sui fornitori e dal codice sorgente, non da una pagina di supporto. Terzo, se il primo ciclo di utilizzo degli strumenti fallisce mentre la normale chat funzionava, sospetta la rigidità dello schema anziché un problema di autenticazione: PicoClaw inoltra gli schemi degli strumenti senza modificarli per impostazione predefinita, e tool_schema_transform: "simple" è l'opzione per disattivare questo comportamento per singolo modello sugli endpoint che rifiutano $ref, $defs, anyOf, oneOf, allOf o pattern.

Kunavo non pubblica alcuna pagina di configurazione per PicoClaw e non ha eseguito test di compatibilità con PicoClaw; mantieni disponibile un percorso funzionante mentre lo provi, quindi leggi l'addebito effettivamente registrato dal tuo account per quell'attività invece di stimarlo da questa pagina. Crea un account Kunavo quando sei pronto a finanziare una chiave e confronta le tariffe dei modelli su API Claude più economica se hai scelto la famiglia Claude.

Domande frequenti

Verificato il 21 settembre 2026: il repository GitHub e l'API delle release, picoclaw.io (letto con la convalida del certificato disabilitata perché il certificato era scaduto), il README, docs/guides/providers.md, docs/security/security_configuration.md, docs/reference/config-versioning.md, docs/guides/configuration.md, docs/operations/troubleshooting.md, config/config.example.json, e sette file sorgente sul ramo main — factory_provider.go, openai_compat/provider.go, common/anthropic_common.go, anthropic_messages/provider.go, provider_metadata.go, pkg/config/defaults.go e pkg/config/config.go — oltre ai due domini simili. Non sono stati verificati: le quote di terze parti nella tabella comparativa di PicoClaw, i prezzi al dettaglio dell'hardware e le note sulla release v0.3.1. Non è stato installato né eseguito nulla: non è stata inviata alcuna richiesta PicoClaw a nessun endpoint. Le tariffe dei token Kunavo provengono dal catalogo aggiornato e ogni esempio in dollari qui riportato è un calcolo illustrativo dei token, non un costo misurato dell'attività.