IronClaw accetta un'API personalizzata in un unico blocco di quattro campi: uno slot [llm.default] in ~/.ironclaw/reborn/config.toml contenente provider_id, base_url, model e api_key_env — oppure, quando non esiste alcuno slot, le variabili d'ambiente LLM_BACKEND / LLM_BASE_URL / LLM_API_KEY su cui fa fallback. Entrambe le forme sono attuali e documentate. Ciò che le pagine di configurazione non raccolgono in un unico punto è l'elenco di ciò che un endpoint personalizzato non ottiene: streaming nativo, rilevamento dei modelli, punti di interruzione Anthropic cache_control e visualizzazione accurata dei costi, tra gli altri. È questa la parte che vale la pena leggere prima di scegliere un provider.
Prima una precisazione, perché i risultati di ricerca sono dominati da altri prodotti. Questa pagina riguarda github.com/nearai/ironclaw, descritto dai metadati del suo stesso repository come "IronClaw is an Agent OS focused on privacy, security and extensibility": Rust, non archiviato e non un fork, 12.626 stelle, creato il 3 febbraio 2026 e aggiornato l'ultima volta il 21 settembre 2026 (API GitHub, lo stesso giorno). Non è il mouse da gaming Corsair con quel nome, il gioco di ruolo da tavolo di Sanguine Productions, il token crypto IRONCLAW né il repository non correlato JoasASantos/ironclaw; i prezzi o le configurazioni di nessuno di questi devono comparire in questa pagina. La documentazione canonica è docs.ironclaw.com e l'albero docs/ del repository; un mirror di terze parti su Mintlify si posiziona per gli stessi titoli e potrebbe essere obsoleto.
Vale la pena riportare l'attribuzione anziché parafrasarla, perché le superfici del fornitore differiscono: ironclaw.com mette "Built by" accanto a un logo NEAR e alle parole "Near Foundation" nel corpo della pagina, e "— by NEAR AI" nel piè di pagina, mentre l'organizzazione GitHub è nearai.
La configurazione minima di un provider personalizzato IronClaw
La struttura dello slot in ironclaw_config accetta esattamente quattro campi opzionali e i relativi commenti documentali li descrivono come override della voce del catalogo: model sostituisce default_model del provider, api_key_env sostituisce api_key_env e base_url sostituisce default_base_url. La documentazione dei provider aggiunge che base_url "funziona anche con qualsiasi altro provider quando è necessario instradarlo tramite un proxy o un endpoint regionale"; non è quindi una funzionalità esclusiva dell'adattatore generico.
[llm.default]
provider_id = "openai_compatible"
base_url = "https://api.kunavo.com/v1"
model = "claude-sonnet-4-6"
api_key_env = "LLM_API_KEY"Tre regole importanti. L'assenza di base_url è fatale, non viene usato un valore predefinito: la documentazione afferma che "lascia lo slot senza destinazione e la risoluzione del modello fallisce", e la voce di catalogo openai_compatible contiene base_url_required: true. api_key_env richiede il nome di una variabile, mai una chiave: un segreto incollato viene "rifiutato al momento dell'analisi, non accettato silenziosamente", mentre ironclaw config set <provider>.api_key richiede l'input con il valore nascosto. Nulla viene applicato finché non riavvii: config set "non riavvia mai nulla", ma stampa il passaggio ironclaw service restart che devi ancora eseguire. E non aspettarti che config set scriva lo slot al posto tuo: la pagina della configurazione elenca [llm.default] tra le sezioni "modificate direttamente in config.toml", e config set "rifiuta una chiave non supportata anziché non fare nulla silenziosamente".
La forma basata sull'ambiente è il fallback documentato quando manca [llm.default] e la documentazione chiarisce la scelta: "Entrambe funzionano … Preferisci lo slot TOML per un'installazione permanente e la forma basata sull'ambiente per esecuzioni una tantum e container."
export LLM_BACKEND=openai_compatible
export LLM_BASE_URL=https://api.kunavo.com/v1
export LLM_API_KEY=sk-kn-...
export LLM_MODEL=claude-sonnet-4-6
# optional: LLM_EXTRA_HEADERS is the openai_compatible entry's
# extra_headers_env; the timeout is a general .env.example setting
export LLM_EXTRA_HEADERS=X-Title:MyAgent
export LLM_REQUEST_TIMEOUT_SECS=120L'ordine di risoluzione è compiled defaults < config.toml < environment variables < CLI flags, quindi una variabile esportata ha silenziosamente la precedenza sul file appena modificato. Il percorso CLI evita del tutto la modifica manuale: ironclaw models list, poi ironclaw models set-provider <id> --model <model>, quindi ironclaw models status. Conferma i percorsi con ironclaw config path invece di fidarti di una delle due posizioni documentate: la pagina di avvio rapido afferma che tutto si trova in ~/.ironclaw, mentre le pagine sulla configurazione e sull'onboarding indicano ~/.ironclaw/reborn. Una trappola operativa per gli utenti ospitati: la pagina della configurazione afferma che i comandi ironclaw service "non funzionano su un'istanza ospitata NEAR AI: non esiste alcun gestore di servizi utente con cui possano comunicare", quindi devi connetterti via SSH per ironclaw config e riavviare dall'Agent Dashboard. Tutte le citazioni sono state lette dal ramo main il 21 settembre 2026.
Ciò che un endpoint personalizzato non raggiunge
Queste sono le dichiarazioni di IronClaw sul comportamento previsto del runtime, ricavate dal codice sorgente e dai file di contratto su main. Non si tratta di esecuzioni osservate e main era precedente al tag di rilascio 1.4.0 — pubblicato il 28 agosto 2026, secondo l'API dei rilasci GitHub — quando sono state lette.
| Funzionalità | Su uno slot personalizzato compatibile con OpenAI | Dove viene dichiarato |
|---|---|---|
| Streaming SSE nativo | No, bufferizzato. Abilitato "solo dove IronClaw può osservare un evento terminale autorevole: NEAR AI, Anthropic OAuth e Codex Responses". Anche il trasporto Anthropic con chiave API e OpenRouter sono bufferizzati | ironclaw_llm/CONTRACT.md |
| Rilevamento dei modelli | No: can_list_models è falso per openai_compatible e openrouter, quindi gli id vengono digitati manualmente, esattamente | assets/providers.json |
| URL di base tramite l'ambiente | Sì, per questo caso: openai_compatible dichiara LLM_BASE_URL. È una delle sole 7 voci su 26 del catalogo che dichiarano una variabile per l'URL di base; openrouter, together, fireworks, groq, deepseek, mistral e tutte le altre devono usare il campo di config.toml | assets/providers.json |
| Schemi degli strumenti così come sono scritti | No: vengono riscritti in modalità strict di OpenAI al confine del provider: additionalProperties: false, tutte le proprietà forzate in required e i campi opzionali resi nullable | ironclaw_llm/CONTRACT.md |
| caching dei prompt | Misto, non semplicemente assente. I punti di interruzione Anthropic cache_control vengono emessi solo dai due trasporti Anthropic, quindi uno slot compatibile con OpenAI non ne invia alcuno. Tuttavia, anche prompt_cache_key di OpenAI lo raggiunge: il flag è "impostato su true dai factory generici compatibili con OpenAI, DeepSeek e OpenRouter", con il gateway loop-host come unico punto che fornisce un valore. Che il tuo endpoint memorizzi poi qualcosa nella cache è un comportamento proprio dell'endpoint, che IronClaw né richiede né osserva | ironclaw_llm/CONTRACT.md |
| Failover tra provider | No: il decoratore di failover cambia tra i modelli NEAR AI tramite NEARAI_FALLBACK_MODEL; qualsiasi passaggio tra tipi di provider "richiede una costruzione manuale" | ironclaw_llm/CONTRACT.md |
| Cache delle risposte dei turni con strumenti | Mai memorizzato nella cache: complete_with_tools() è escluso a causa degli effetti collaterali | ironclaw_llm/CONTRACT.md |
| Selezionabile dagli utenti in un'installazione multiutente | Non automaticamente: "La sola configurazione del provider non pubblica i modelli agli utenti"; un amministratore aggiunge ogni id in Impostazioni → Inferenza → Accesso ai modelli utente | Documentazione del provider |
Il catalogo di IronClaw è un catalogo di chat e Kunavo non offre alcun modello di embedding, text-to-speech o speech-to-text, quindi qualsiasi parte della tua configurazione che ne richieda uno deve puntare interamente altrove.
La visualizzazione dei costi di IronClaw non è il tuo conto
All'interno di IronClaw esistono due percorsi distinti che calcolano il denaro, non concordano tra loro e nessuno dei due legge il tuo provider. price_usage() in ironclaw_common calcola i prezzi usando una tabella hardcoded per token e ricade su default_cost() — 0.0000025 per l'input e 0.00001 per token, ovvero $2,50 / $10,00 per milione, con una tariffa modellata su GPT-4o — con la motivazione dichiarata che "un nuovo modello a pagamento non viene mai prezzato silenziosamente a zero". Nel frattempo, StaticModelCostTable dell'host del loop fa l'opposto per le prenotazioni di budget: un profilo assente dalla sua tabella "ricade su None, che il contabile tratta come a costo zero". E nel percorso llm_costs lo sconto per la lettura dalla cache viene indovinato dal nome del modello tramite sottostringa: claude divide per dieci, gpt o un prefisso o1/o3/o4 divide per due, tutto il resto per uno.
La conseguenza pratica è che budget.user_daily_usd, budget.pause_at e il resto delle chiavi [budget] di IronClaw controllano una stima, non un addebito. Vale comunque la pena impostarli su un agente sempre attivo: il punto è fermare presto un ciclo incontrollato; tuttavia, verifica i dati rispetto all'utilizzo registrato dal provider, non rispetto al numero visualizzato sullo schermo.
Una stima esemplificativa per una giornata dell'agente
Questo è un calcolo dei token, non un costo misurato di un'attività né un limite massimo del conto. Supponiamo una giornata di attività dell'agente per un totale di 1.000.000 di token di input non memorizzati nella cache e 40.000 token di output: un'ipotesi a scopo illustrativo, scelta perché un runtime sempre attivo accumula input attraverso heartbeat e routine anziché tramite risposte lunghe. Le tariffe sono i prezzi attuali del catalogo Kunavo per milione di token.
| Modello | Input / output per 1M | Giornata stimata dell'agente | I pattern della visione corrispondono a questo id? |
|---|---|---|---|
| Claude Haiku 4.5 | $0,70 / $3,50 | $0,840 | Sì |
| GPT-5.6 Terra | $0,70 / $4,20 | $0,868 | No |
| Claude Sonnet 4.6 | $2,10 / $10,50 | $2,520 | Sì |
| Claude Opus 5 | $3,50 / $17,50 | $4,200 | Sì |
L'ultima colonna è la sorpresa utile e dipende dalla stringa dell'id, non dal modello. vision_models.rs verifica per sottostringa un elenco fisso che include claude-opus-, claude-sonnet-, claude-haiku- e claude-fable-, quindi quegli id instradano gli allegati immagine; gli altri id nella tabella precedente non corrispondono a nessuno tra gpt-4o, gemini-1.5, gemini-2 o al resto dell'elenco e verrebbero classificati come solo testo. In caso di mancata corrispondenza, il gateway loop-host invia il testo del messaggio senza le parti immagine e non genera alcun errore: la trascrizione persistente conserva un riferimento <attachments>, ma il modello non vede l'immagine. Confronta l'elenco dei pattern con l'id esatto che intendi digitare prima di dare per scontato che l'input immagine funzioni. Ridimensiona le cifre in dollari in base ai tuoi giorni prima di considerarle un budget. L'importo del catalogo Kunavo è un minimo di fatturazione, non un limite massimo: quando l'upstream comunica il proprio addebito, il conto è il maggiore tra il costo del catalogo e il costo upstream moltiplicato per la maggiorazione applicabile. Gli addebiti per la cache e gli strumenti esterni non rientrano in questo esempio, e la ricarica minima è $10 in credito prepagato: un minimo di finanziamento, non una tariffa per attività né un abbonamento. Consulta dettagli sulla fatturazione.
Quale percorso vince e quanto costa IronClaw in sé
Il software è gratuito: nella radice del repository sono presenti sia LICENSE-APACHE sia LICENSE-MIT, e il README indica MIT OR Apache 2.0. Non esiste un'edizione a pagamento del binario né alcun costo di licenza. Si pagano i token, oltre all'hosting se si sceglie quello del fornitore.
| Percorso | Prezzo pubblicato | Vantaggioso quando |
|---|---|---|
| IronClaw self-hosted | Software a $0, MIT OR Apache-2.0 | Gestisci già un host e vuoi il pieno controllo dell'endpoint |
| ironclaw.com Starter | Attualmente $0, con $5 indicati e barrati; "$5 di crediti inclusi" | Stai provando il percorso hosted. Consideralo promozionale, non un piano permanente a $0 |
| ironclaw.com Basic | $20/mese, "$20 di crediti inclusi" | "fino a 2 istanze dell'agente", condivisione dell'utilizzo tra le implementazioni |
| ironclaw.com Pro+ | $200/mese, "$200 di crediti inclusi" | "fino a 5 istanze dell'agente", accesso anticipato ai modelli avanzati, supporto prioritario |
| Token NEAR AI Cloud | $0,15 / $0,50 per 1M (GLM 5.3 Flash) fino a $3,30 / $16,50 (Kimi K3) | Il valore predefinito consigliato dal fornitore e l'unico backend su cui il failover integrato cambia modello |
| Gateway compatibile con OpenAI | Tariffe per token del tuo gateway | Passi da una famiglia all'altra per attività e vuoi una sola chiave, accettando lo streaming bufferizzato e gli identificatori digitati manualmente |
| Modello locale tramite Ollama | Nessun costo per richiesta | Lavori piccoli o privati; aumenta LLM_REQUEST_TIMEOUT_SECS come suggerisce .env.example |
Prezzi dei piani hosted letti da ironclaw.com il 21 settembre 2026; non esiste una pagina /pricing, i piani sono nella homepage e il markup renderizzato mostra i $5 all'interno di uno span barrato, con $0 come prezzo attuale. La homepage afferma inoltre: "Avvia fino a 5 agenti in un Trusted Execution Environment con fino a 130M di token al mese" — questa frase si trova sopra tutte e tre le schede e non indica alcun piano, quindi non associarla a uno di essi. Tre aspetti che questa guida non ha potuto stabilire e non intende indovinare: se i piani hosted consentano affatto una chiave di terze parti, cosa acquistino realmente i crediti inclusi o cosa accada quando terminano, e a quale piano appartenga la cifra di 130M. Le tariffe dei token sono state lette da near.ai/pricing lo stesso giorno; la pagina dichiara: "Non c'è alcuna commissione di piattaforma oltre alla tariffa del modello" e riguarda esclusivamente i suoi modelli testuali riservati.
Un confine di privacy da enunciare chiaramente, perché è il motivo per cui si sceglie questo runtime. I controlli descritti dal README e dalla pagina di sicurezza di IronClaw — segreti "crittografati a riposo" e iniettati al confine dell'host, sandbox WASM per gli strumenti non attendibili, allowlist degli endpoint, rilevamento delle fughe di dati — sono controlli locali sulla macchina che esegue l'agente. L'attestazione hardware è una proprietà separata di NEAR AI Cloud: near.ai afferma che lì l'inferenza "viene eseguita in un enclave Intel TDX + NVIDIA confidential-GPU" e che "ogni risposta contiene una prova hardware verificabile". Puntare IronClaw a un endpoint di terze parti invia il contenuto dei prompt a quell'endpoint secondo i suoi termini, e nessuno dei due elenchi lo segue fin lì. La tabella "OpenClaw vs IronClaw" redatta dal fornitore su ironclaw.com è marketing di una delle parti, non un confronto neutrale — e fai attenzione ai risultati di ricerca: in un campione della pagina dei risultati acquisito il 17 settembre 2026, le quattro forme di query best api for ironclaw, cheapest api for ironclaw, best model for ironclaw e ironclaw custom provider hanno restituito ciascuna almeno otto risultati OpenClaw nei primi dieci, le cui classifiche dei modelli descrivono un prodotto diverso.
Configuralo, poi controlla il primo addebito
Kunavo pubblica un endpoint con struttura OpenAI all'indirizzo https://api.kunavo.com/v1 e uno con struttura Anthropic, che corrispondono agli identificatori dei provider openai_compatible e anthropic. Kunavo non ha testato IronClaw a runtime, quindi considera il blocco sopra un punto di partenza basato sul protocollo documentato e non una dichiarazione di compatibilità: mantieni disponibile un percorso funzionante, esegui un'attività limitata e leggi l'addebito effettivamente registrato dal tuo account. Se controlli Goose da IronClaw tramite ACP — .env.example documenta la sandbox dell'Agent Client Protocol e il comando ironclaw acp add goose — l'integrazione Goose tratta separatamente quel lato, mentre creare un account Kunavo finanzia una chiave quando sei pronto. Per le scelte circostanti, consulta il riferimento API compatibile con OpenAI, le alternative a OpenRouter e l'ottimizzazione dei costi dell'IA.
Domande frequenti
Come imposto un provider personalizzato in IronClaw?
Scrivi uno slot [llm.default] in ~/.ironclaw/reborn/config.toml con provider_id, base_url, model e api_key_env: questi sono i quattro campi opzionali accettati dalla struttura dello slot e base_url sostituisce default_base_url del provider per qualsiasi provider id, non solo per quello generico. Usa provider_id = "openai_compatible" quando il tuo endpoint non dispone di una voce dedicata nel catalogo; la documentazione dei provider di IronClaw indica vLLM, LiteLLM, LM Studio e un gateway interno come casi d'uso. api_key_env deve essere il NOME di una variabile d'ambiente, perché una chiave letterale incollata lì viene rifiutata durante l'analisi del file, anziché accettata silenziosamente. `ironclaw config set` non è lo strumento adatto: la documentazione della configurazione elenca `[llm.default]` tra le sezioni "modificate direttamente in config.toml" e afferma che `config set` accetta solo chiavi con una destinazione di instradamento e rifiuta una chiave non supportata. Modifica il file oppure usa `ironclaw models set-provider`, che secondo la documentazione dei provider scrive la selezione in config.toml come slot del modello. Poi riavvia: nulla viene applicato finché non esegui `ironclaw service restart`. Verificato rispetto al ramo main di nearai/ironclaw il 21 settembre 2026.
IronClaw funziona con OpenRouter?
Sì, e i due modi documentati per farlo non sono coerenti tra loro. Il catalogo dei provider compilato include una voce openrouter dedicata con il proprio protocollo open_router, identificata da OPENROUTER_API_KEY, e la documentazione dei provider afferma che OpenRouter, Together AI e Fireworks dispongono ora di proprie voci provider_id e devono essere utilizzati direttamente anziché tramite l'adattatore generico. Il file .env.example del repository include ancora la procedura precedente, impostando LLM_BACKEND=openai_compatible con LLM_BASE_URL indirizzato all'API di OpenRouter. Entrambi i file si trovavano nel ramo main il 21 settembre 2026. Preferisci l'id dedicato; nota che la voce openrouter non dichiara alcuna variabile d'ambiente per l'URL di base, quindi per instradarla tramite un proxy devi usare il campo base_url di config.toml. Per quanto riguarda il prezzo, le FAQ di OpenRouter (openrouter.ai/docs/faq, consultate il 21 settembre 2026) dichiarano che trasferisce i prezzi del provider sottostante senza maggiorazione, applica il 5,5% con un minimo di $0,80 agli acquisti di crediti con carta e il 5% alle criptovalute, e applica il 5% del costo equivalente di OpenRouter all'uso con chiavi proprie oltre una franchigia mensile che la stessa pagina indica in $25.000 con il pagamento a consumo.
Qual è la migliore API per IronClaw?
Non esiste un vincitore unico, e cercarne uno è particolarmente fuorviante in questo caso perché la pagina dei risultati riscrive questo brand: in un campione acquisito il 17 settembre 2026, "best api for ironclaw" e "cheapest api for ironclaw" hanno restituito ciascuno otto o più risultati OpenClaw nei primi dieci, quindi le classifiche trovate con quelle frasi spesso descrivono un prodotto diverso. Valutando ciò che fa il codice di IronClaw, quattro percorsi si distinguono nettamente. NEAR AI Cloud è il valore predefinito consigliato dal fornitore e l'unico backend su cui il failover integrato cambia effettivamente modello. Un'API diretta del provider è la scelta migliore quando usi un unico provider tutto il giorno e vuoi la sua cache nativa: IronClaw emette punti di interruzione Anthropic cache_control solo sui suoi due trasporti Anthropic, sebbene uno slot compatibile con OpenAI trasporti comunque il prompt_cache_key di OpenAI, quindi un endpoint con caching automatico del prefisso non è escluso. Un gateway compatibile con OpenAI è la scelta migliore quando vuoi una chiave e un saldo unici tra più famiglie, al costo di uno streaming bufferizzato anziché nativo e di id dei modelli digitati manualmente. Un modello locale tramite Ollama è la scelta migliore per attività private e ridotte senza costi per richiesta. Scegli in base ai vincoli che puoi sostenere, non sulla base di una tariffa in evidenza.
Qual è l'API più economica per IronClaw?
Il prezzo minimo pubblicizzato e il costo più basso per completare l'attività sono affermazioni diverse, e un agente sempre attivo amplia il divario perché heartbeat, routine e processi in background vengono fatturati indipendentemente dal fatto che tu stia digitando. Come riferimento di prezzo per il backend raccomandato dal fornitore, near.ai/pricing indicava GLM 5.3 Flash a $0,15 per l'input e $0,50 per l'output per milione di token come modello testuale riservato meno costoso, e Kimi K3 a $3,30 e $16,50 come il più costoso, senza costi di piattaforma aggiuntivi rispetto alla tariffa del modello, il 21 settembre 2026. Qualunque endpoint tu scelga, pianifica in base ai dati sull'utilizzo del provider, non al costo visualizzato da IronClaw, che viene calcolato da una tabella hardcoded e ricade su una tariffa modellata su GPT-4o per un model id che non riconosce.
Qual è il modello migliore per IronClaw?
Prima che entrino in gioco le capacità, IronClaw impone due vincoli meccanici su questa scelta, ed entrambi sono determinati dal testo letterale del model id. Gli allegati immagine vengono instradati tramite una corrispondenza per sottostringa con un elenco fisso di pattern per la visione in vision_models.rs; il commento nel codice avverte che una mancata corrispondenza comporta lo scarto silenzioso degli allegati immagine. Di conseguenza, un id rinominato o sostituito da un alias che si allontani da forme come claude-sonnet-, gpt-4o, gemini-2 o pixtral perde l'input immagine senza alcun errore. I prompt di ragionamento sono più sicuri: il relativo elenco di pattern è attualmente vuoto, quindi nomi sconosciuti, alias e modelli con ragionamento nativo ricadono tutti nel formato di risposta diretta. Oltre a questo, preferisci un modello che funzioni bene con le chiamate agli strumenti, perché le definizioni degli strumenti inviate tramite il percorso RigAdapter vengono riscritte in modalità strict di OpenAI al confine del provider. Tutti e tre i comportamenti risultano dal ramo main del 21 settembre 2026.
Posso indirizzare IronClaw a Kunavo?
Kunavo pubblica un endpoint con formato OpenAI all'indirizzo https://api.kunavo.com/v1 e uno con formato Anthropic all'indirizzo https://api.kunavo.com/v1/messages, che corrispondono rispettivamente agli id provider openai_compatible e anthropic di IronClaw. Si tratta di una corrispondenza di protocollo ricavata dalla documentazione di entrambe le parti, non di un'integrazione testata: Kunavo non ha eseguito alcuna richiesta IronClaw-Kunavo e non dichiara una compatibilità verificata. Ci sono due aspetti specifici da controllare autonomamente prima di farvi affidamento. La voce openai_compatible imposta base_url_required, quindi lo slot non riesce a risolvere il modello senza un URL di base. Inoltre, il suffisso esatto del percorso che IronClaw aggiunge con il protocollo anthropic non è stato confermato in questa ricerca: il valore predefinito documentato per ANTHROPIC_BASE_URL è l'host nudo https://api.anthropic.com, il che implica che il runtime aggiunga il percorso; tuttavia, confermalo con una richiesta prima di impegnarti su una configurazione. La ricarica minima Kunavo è di $10 in credito prepagato.
I metadati del repository, providers.json, CONTRACT.md, llm_costs.rs, vision_models.rs, l'albero docs/, ironclaw.com e near.ai/pricing sono stati tutti consultati il 21 settembre 2026 dal branch main, non dal tag di rilascio 1.4.0. Nessuna richiesta IronClaw è stata inviata a un endpoint Kunavo; ogni dichiarazione di compatibilità qui presente è una lettura della documentazione di entrambe le parti. Le tariffe dei token Kunavo provengono dal catalogo live e ogni esempio in dollari è un calcolo illustrativo dei token.