OpenClaw

Una voce models.providers in ~/.openclaw/openclaw.json — baseUrl https://api.kunavo.com, api "anthropic-messages" — consente a un agente OpenClaw sempre attivo di usare Claude; cacheRetention è impostato accanto, perché un endpoint Anthropic personalizzato non riceve marcatori di cache finché questa opzione non è configurata.

// ~/.openclaw/openclaw.json — merge into the file you already have
{
  models: {
    mode: "merge",
    providers: {
      kunavo: {
        baseUrl: "https://api.kunavo.com",   // origin — no /v1 on this wire
        apiKey: "${KUNAVO_API_KEY}",         // from the environment or ~/.openclaw/.env
        api: "anthropic-messages",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
            contextTokens: 200000,           // optional: compact here, not at 1M
            maxTokens: 32000,
          },
          {
            id: "claude-haiku-4-5",
            name: "Claude Haiku 4.5",
            input: ["text", "image"],
            contextWindow: 200000,
            maxTokens: 16000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "kunavo/claude-sonnet-5" },
      models: {
        // Required for caching: a custom Anthropic endpoint gets no cache
        // markers from OpenClaw until cacheRetention is set explicitly.
        "kunavo/claude-sonnet-5": { params: { cacheRetention: "short" } },
        "kunavo/claude-haiku-4-5": { params: { cacheRetention: "short" } },
      },
    },
  },
}

Passo dopo passo

1. Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
2. Fornisci la chiave al Gateway: aggiungi KUNAVO_API_KEY=sk-kn-... a ~/.openclaw/.env oppure esportala nell'ambiente in cui viene avviato il Gateway. Al caricamento della configurazione, il valore ${KUNAVO_API_KEY} nel blocco viene sostituito con quello definito lì.
3. Unisci il blocco a ~/.openclaw/openclaw.json, conservando i provider, gli agenti e i canali che hai già. Il file è in formato JSON5, quindi i commenti possono rimanere.
4. Esegui openclaw config validate. OpenClaw non si avvia se il file contiene un’impostazione che non riconosce, quindi è meglio individuare qui un refuso che al riavvio successivo.
5. Esegui openclaw models list --provider kunavo e verifica che siano elencati entrambi gli ID. Se un Gateway in esecuzione non ha recepito la modifica, openclaw gateway restart.
6. Apri una nuova sessione con /new — una sessione esistente continua a usare il modello già assegnato — invia due messaggi e poi consulta /usage tokens: il secondo turno dovrebbe riportare cacheRead.

Verificato rispetto a Riferimento ai provider personalizzati di OpenClaw il 5 ottobre 2026. Le impostazioni di terze parti cambiano; se il nome di un campo qui non corrisponde più a quello visualizzato, fa fede quella pagina, non questa.

Verifica prima di eseguire il debug del client

Una sola richiesta stabilisce se il problema riguarda l'endpoint, la chiave o il file di configurazione. Se restituisce JSON, lo stesso base URL e la stessa chiave funzionano in OpenClaw.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Quale model id inserire nel campo

Ogni modello di testo è raggiungibile come model id: l'elenco aggiornato è GET /v1/models e il catalogo con i prezzi è nella pagina dei modelli. Le tariffe sono in USD per 1M di token, input / output.

Il protocollo compatibile con OpenAI

La stessa chiave consente di raggiungere tutte le altre famiglie di modelli tramite /v1/chat/completions. Registrala in una seconda voce provider, così i due protocolli rimangono separati, e usa i riferimenti kunavo-openai/<id> per i suoi modelli:

// ~/.openclaw/openclaw.json — a second entry, beside "kunavo"
{
  models: {
    providers: {
      "kunavo-openai": {
        baseUrl: "https://api.kunavo.com/v1",   // this wire keeps /v1
        apiKey: "${KUNAVO_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gpt-6-sol",
            name: "GPT-6 Sol",
            reasoning: true,
            input: ["text"],
            contextWindow: 1050000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

// then: /model kunavo-openai/gpt-6-sol

Tre aspetti differiscono dal blocco in alto. L'URL di base mantiene /v1, nella forma usata dagli esempi di provider personalizzati di OpenClaw. api è impostato su openai-completions — che OpenClaw presuppone anche quando un provider personalizzato specifica baseUrl senza indicare api. Inoltre, nella pratica maxTokens non è facoltativo: quando il limite di output di un modello è sconosciuto, su questo protocollo OpenClaw non invia alcun limite e Kunavo termina quindi una risposta di Claude dopo 4096 token.

Anche gli ID Claude funzionano qui, ed è questo il protocollo da usare se vuoi una sola voce per tutto. Per questi ID cambiano due aspetti: i livelli di ragionamento non vengono inoltrati per Claude con chat completions e i punti di interruzione della cache sono inseriti da Kunavo, non da OpenClaw.

Memorizzazione nella cache dei prompt per ciascun protocollo

Con il protocollo Anthropic, OpenClaw inserisce direttamente i punti di interruzione della cache, ma per un endpoint personalizzato lo fa solo se è impostato cacheRetention. Il riferimento di OpenClaw sulla memorizzazione nella cache dei prompt è esplicito: il valore predefinito short è preconfigurato solo per i provider anthropic e anthropic-vertex, mentre per ogni altro endpoint della famiglia Anthropic è necessario specificare un valore. L'endpoint Kunavo /v1/messages inoltra il corpo della richiesta così com'è e non aggiunge punti di interruzione; quindi, se la configurazione non include queste righe, nulla viene memorizzato nella cache.

short richiede una voce di cinque minuti e long una di un'ora. Kunavo inoltra entrambi i marcatori e addebita la scrittura alla stessa tariffa. Prima di pianificare una cadenza basata su una voce di un'ora, conviene verificare in base ai propri dati di utilizzo che sia ancora disponibile quando arriva il heartbeat successivo: un turno che riporta cacheRead ha riutilizzato la cache, mentre uno che riporta nuovamente cacheWrite non l'ha fatto. /usage tokens e /status mostrano entrambi i contatori.

Con il protocollo compatibile con OpenAI, il funzionamento è inverso. OpenClaw non invia suggerimenti sulla cache agli endpoint proxy e Kunavo inserisce direttamente i punti di interruzione per i modelli Claude — nel prompt di sistema, nelle definizioni degli strumenti e alla fine della conversazione — non appena il prompt è abbastanza lungo da essere memorizzato nella cache. Non c'è nulla da configurare e il fornitore memorizza implicitamente nella cache i modelli GPT.

A prescindere da quale componente inserisca i punti di interruzione, il costo è lo stesso. Su Claude Sonnet 5 una lettura dalla cache costa $0.14 per 1M token, rispetto a $1.40 per gli input non memorizzati in cache; una scrittura nella cache costa $1.75: il sovrapprezzo che Claude applica alla scrittura rispetto all'input, addebitato alla stessa tariffa quando la voce richiede una durata di un'ora. Una voce dura cinque minuti e ogni lettura ne rinnova la durata, quindi il costo per un agente dipende meno dal modello che dal fatto che la richiesta successiva arrivi entro questa finestra. Le tariffe della cache per ogni modello sono indicate nella pagina sulla memorizzazione nella cache dei prompt.

OpenClaw può mostrare localmente lo stesso calcolo. Il riepilogo /usage cost e la riga del costo in /status richiedono un oggetto cost per ogni riga del modello; senza, indicano zero mentre Kunavo continua ad addebitare i costi normalmente. Queste voci vengono generate dal catalogo aggiornato:

// merge into the rows of models.providers.kunavo.models — USD per 1M tokens
{ id: "claude-sonnet-5", cost: { input: 1.4, output: 7, cacheRead: 0.14, cacheWrite: 1.75 } },
{ id: "claude-haiku-4-5", cost: { input: 0.7, output: 3.5, cacheRead: 0.07, cacheWrite: 0.875 } },
{ id: "claude-opus-5-5", cost: { input: 2.8, output: 14, cacheRead: 0.14, cacheWrite: 3.5 } },
{ id: "claude-fable-5", cost: { input: 7, output: 35, cacheRead: 0.7, cacheWrite: 8.75 } },

Costo giornaliero di un agente sempre attivo

Un agente OpenClaw genera costi anche quando nessuno interagisce con lui, a causa dell’heartbeat: un turno pianificato dell’agente, eseguito ogni 30 minuti per impostazione predefinita, cioè 48 al giorno. Se non gli viene indicato diversamente, viene eseguito nella sessione principale e invia di nuovo la conversazione: la documentazione di riferimento di OpenClaw stima circa 100.000 token per un’esecuzione di questo tipo, e alcune migliaia quando è isolata. Trenta minuti superano la finestra della cache di cinque minuti, quindi ogni esecuzione addebita nuovamente l’intero prompt: alla tariffa di input oppure, se è impostato un breakpoint, alla tariffa di scrittura più alta. La tabella calcola il costo di un giorno di inattività alla tariffa di input, con 5000 token per l’esecuzione isolata:

Il blocco qui sotto rappresenta lo scenario meno costoso della tabella: heartbeat con Haiku, in una sessione isolata, senza i file di inizializzazione del workspace e solo durante le ore di veglia. Tutte le impostazioni provengono dalla documentazione di riferimento sull’heartbeat di OpenClaw. Un intervallo every più lungo è l’altra leva; "0m" disattiva l’esecuzione ricorrente.

// ~/.openclaw/openclaw.json — what decides the cost of an idle day
{
  agents: {
    defaults: {
      utilityModel: "kunavo/claude-haiku-4-5",   // titles and other short internal tasks
      heartbeat: {
        every: "30m",                            // the default with an API key
        model: "kunavo/claude-haiku-4-5",        // wake-ups on the cheapest tier
        isolatedSession: true,                   // a fresh session, not the whole conversation
        lightContext: true,                      // skip the workspace bootstrap files
        activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}

Le ore in cui l’agente è effettivamente al lavoro costituiscono l’altra metà della spesa, e in quel caso è la cache a fare la differenza. Considera 100 richieste consecutive, ognuna delle quali invia nuovamente un contesto di 100.000 token, aggiunge 2000 nuovi token e restituisce 800 token in output. Su Claude Sonnet 5, il costo è di circa $2.31 mentre il contesto viene letto dalla cache e di circa $14.84 quando ogni richiesta lo addebita come input nuovo. Stesso lavoro, stesso modello: la differenza dipende dalla presenza dei breakpoint e dal fatto che le richieste siano distanziate da meno di cinque minuti.

Per avere un riferimento concreto, basato su misurazioni e non su supposizioni: tra gli account Kunavo che eseguono un agente sempre attivo, il costo mediano di una giornata attiva è $12.67 e quello di una giornata al 90° percentile è circa $163. Sono importi fatturati fino a 5 ottobre 2026, alle tariffe in vigore in ciascun giorno. Il gruppo è piccolo: considera questi dati come un’indicazione dell’ampiezza dell’intervallo, non come una previsione per il tuo agente.

Quando il saldo si esaurisce

Kunavo è prepagato: ogni chiamata viene pagata dal portafoglio e un agente che lavora mentre dormi lo svuota mentre dormi. Una richiesta che il portafoglio non può coprire viene rifiutata con HTTP 402 e il codice insufficient_balance, indipendentemente dal protocollo; non viene addebitato alcun importo. Il rifiuto avviene prima che il saldo del portafoglio raggiunga zero: ogni richiesta riserva prima il costo massimo possibile, cioè il prompt più la risposta più lunga che è autorizzata a produrre. Di conseguenza, più alto è il limite di output richiesto da un agente, prima le sue chiamate iniziano a essere rifiutate. L’errore indica l’importo mancante nei campi balance_usd e needed_usd.

OpenClaw determina il significato di un 402 in base al messaggio. Secondo le regole di OpenClaw 2026.9.8, il rifiuto del portafoglio è un errore di fatturazione; la sua documentazione di riferimento sul failover descrive cosa accade poi: la credenziale viene disabilitata per dieci minuti, l’esecuzione passa al modello successivo in agents.defaults.model.fallbacks e la ricarica non azzera l’intervallo. Dopo una ricarica, quindi, l’agente può continuare a non usare kunavo/… fino al termine dell’intervallo. Il rifiuto dovuto al limite mensile di una chiave viene interpretato diversamente. Il messaggio indica un limite che si azzera, che le stesse regole trattano come un limite di frequenza: OpenClaw riprova, poi impone alla credenziale un periodo di attesa iniziale di 30 secondi, che può arrivare al massimo a cinque minuti. openclaw models status mostra una credenziale disabilitata e quando tornerà disponibile.

Due impostazioni impediscono a un agente non presidiato di trovarsi in questa situazione, e svolgono funzioni diverse:

• Ricarica automatica, in Fatturazione. Salva una carta una sola volta e imposta tre importi: il saldo al di sotto del quale ricaricare, l’importo da aggiungere ogni volta e un limite mensile. Il portafoglio si ricarica quindi entro pochi secondi da una chiamata che porta il saldo sotto la soglia. Una richiesta che arriva mentre il saldo del portafoglio è ancora insufficiente attende l’addebito e viene quindi evasa invece di essere rifiutata. Un 402 viene comunque restituito se non è possibile effettuare l’addebito — per una carta rifiutata o perché è stato raggiunto il limite mensile — oppure se una richiesta riserva un importo superiore a quello disponibile nel portafoglio dopo la ricarica. È necessaria una carta o Link: Alipay, WeChat Pay, Pix e gli altri metodi di pagamento locali non possono essere addebitati automaticamente.
• Un limite mensile per la chiave, in Chiavi API. Assegna all’agente una chiave dedicata e imposta la spesa massima consentita a tale chiave in un mese di calendario. Superato tale importo, le sue chiamate vengono rifiutate con un 402 e non viene addebitato nulla, mentre le altre chiavi continuano a funzionare. Questo è il limite massimo necessario per contenere un ciclo incontrollato, che il portafoglio non può fornire perché tutte le chiavi attingono allo stesso portafoglio.

Imposta la soglia di ricarica sopra l'importo riservato da una singola richiesta e scegli l'importo in base a una giornata di attività del tuo agente, non al minimo: la ricarica minima è $10 e la giornata mediana di un agente sempre attivo indicata sopra è $12.67. I limiti della ricarica automatica sono riportati nella pagina di fatturazione e il corpo completo dell'errore nella pagina degli errori.

Guide correlate

• Migliore API per OpenClaw — scelta del provider e del modello per ogni tipo di attività.
• Prezzi di OpenClaw — il costo operativo complessivo: software, hosting, modelli e strumenti.
• OpenClaw con più agenti e modelli — instradamento di ogni agente al proprio modello e attribuzione dei costi in base al percorso.
• Hermes e OpenClaw a confronto — e la stessa configurazione per l'altro agente, nella pagina di Hermes Agent.