Roo Code con l'API Claude — configurazione del provider e un modello per modalità

Roo Code è un agente di coding autonomo open source per VS Code — un fork della famiglia Cline, contraddistinto dal suo sistema di modalità e dal routing del modello per modalità. Non include alcun modello proprio, quindi richiede una chiave API. Questa guida descrive la configurazione esatta per eseguire Claude in Roo Code con una chiave sk-kn- a circa il 30% in meno rispetto al prezzo di listino Anthropic sui modelli principali, come usare i profili di configurazione per spendere sui modelli potenti solo dove conviene, quanto costa una sessione e il compromesso reale rispetto a chiamare direttamente Anthropic.

Perché Roo Code richiede una chiave API

Ogni passaggio eseguito da Roo Code — leggere un file, scrivere un diff, eseguire un comando, leggere il risultato — è una chiamata al modello fatturata per token. Un abbonamento claude.ai Pro o Max non lo copre: i piani chat e l'accesso API sono prodotti separati, e Roo Code comunica con l'API. Poiché un ciclo agentico reinvia il contesto dell'attività in crescita a ogni passaggio, la tariffa per token è la leva maggiore sul costo della sessione — come nel caso di un gateway: pay-as-you-go a partire da una ricarica di $10, una chiave che raggiunge anche GPT e un saldo che non scade mai.

Configurazione — i tre campi

Apri Impostazioni → Provider e imposta il provider API su OpenAI Compatible. Tre valori:

API Provider   OpenAI Compatible
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...              # create at kunavo.com/app/keys
Model ID       claude-sonnet-5        # or claude-opus-5 / claude-haiku-4-5

Crea la chiave da dashboard dopo esserti registrato e aver effettuato una ricarica — viene mostrata una sola volta, quindi conservala subito; la documentazione della chiave API Claude descrive la rotazione e i limiti di spesa. Se Roo Code richiede metadati del modello come la finestra di contesto o il limite di output, usa i valori della pagina del modello — una finestra di contesto sottostimata lo fa troncare prima del necessario.

Esegui un test con qualcosa di breve prima di lasciargli modificare il codice. Un 401 qui dipende quasi sempre dalla chiave; un 404 quasi sempre dall'URL di base o da uno slug di modello inesistente — Kunavo verifica gli slug esattamente e non crea alias per i nomi con suffisso di data, quindi claude-sonnet-4-5-20250929 restituisce 404 mentre claude-sonnet-4-6 viene risolto.

Modalità e profili di configurazione — la leva sui costi

Roo Code include diverse modalità predefinite — Code, Architect, Ask e Debug — oltre alle modalità personalizzate che definisci tu. L'aspetto importante per i costi è che Roo Code memorizza profili di configurazione API nominati e ricorda quale profilo hai usato per ultimo in ogni modalità. Così il modello diventa una proprietà della modalità, non qualcosa che devi ricordarti di cambiare:

# One API configuration profile per job, all on the same sk-kn- key.
# Roo Code remembers the profile you last used in each mode.

Profile "strong"         model claude-opus-5        -> bind to Architect and Debug
Profile "code-default"   model claude-sonnet-5      -> bind to Code mode
Profile "ask-cheap"      model claude-haiku-4-5     -> bind to Ask mode

Il motivo per cui funziona è che le modalità hanno profili di token molto diversi. Architect consiste in pochi turni ad alto contenuto di ragionamento, nei quali la qualità del modello determina se i venti passaggi successivi saranno produttivi — rappresenta una piccola parte dei token totali, quindi un modello potente costa poco in termini assoluti. Code consiste in molti passaggi meccanici, ciascuno dei quali reinvia il contesto: è qui che la tariffa per token si accumula. Ask è solitamente una richiesta singola e non ha affatto bisogno di un modello frontier.

I numeri dell'esempio sono riportati di seguito: tre passaggi Architect su Opus 5 più diciassette passaggi Code su Sonnet 5 arrivano a circa $1,06 rispetto a $0,87 per l'esecuzione interamente su Sonnet — circa il 23% in più per una pianificazione sensibilmente migliore, e molto meno che eseguire tutto su Opus.

La rotta Anthropic nativa (e perché potresti volerla)

Roo Code offre anche un provider nativo Anthropic con un campo personalizzato per l'URL di base. Indirizzandolo a https://api.kunavo.com — solo l'origine, senza /v1, perché quel client aggiunge autonomamente /v1/messages — il traffico passa attraverso la Messages API nativa. Incollare qui la forma /v1 produce un 404 che sembra indicare un modello mancante.

Il vantaggio di questa rotta è il prompt caching: cache_control passa senza traduzione e l'input memorizzato nella cache viene fatturato al 10% della tariffa di input (come funziona). In un ciclo che reinvia un prefisso stabile a ogni passaggio, questo è il maggiore risparmio disponibile — superiore a qualsiasi sostituzione del modello. Entrambe le rotte funzionano; OpenAI Compatible è più semplice per iniziare, e passare dall'una all'altra richiede solo una modifica nelle impostazioni.

Il prompt caching in sé, però, non richiede la rotta nativa. Con un prompt lungo, Kunavo imposta da sé i punti di interruzione della cache sulla rotta OpenAI Compatible: sul prompt di sistema, sulle definizioni degli strumenti e sull'ultimo messaggio non appena la conversazione contiene un turno dell'assistente, cioè, in un ciclo agentico, a ogni passaggio dopo il primo. Un cache_control impostato da Roo Code su quella rotta viene mantenuto. Sulla rotta nativa la richiesta viene inoltrata così come Roo Code l'ha inviata e non viene aggiunto alcun punto di interruzione, quindi ciò che finisce nella cache dipende dai punti di interruzione impostati da Roo Code.

Quale modello Claude associare a ciascuna modalità

Tutti usano la stessa chiave e lo stesso endpoint — cambia solo lo slug del modello, quindi un profilo richiede una modifica di una sola parola. Le tariffe complete per modello rispetto al listino ufficiale Anthropic sono nella lista dei prezzi dell'API Anthropic Claude, mentre il catalogo aggiornato è nella pagina dei prezzi.

Roo Code su Kunavo rispetto a chiamare direttamente Anthropic

Il confronto onesto, compresi i casi in cui chiamare direttamente è la scelta migliore:

Quella riga sulla capacità è il vero compromesso, espresso chiaramente. Se ti servono una quota garantita, uno SLA contrattuale o un rapporto di approvvigionamento con il fornitore del modello, scegli l'accesso diretto — è questo che acquista la differenza di prezzo. Per uno sviluppatore individuale o un piccolo team che usa Roo Code, il compromesso di solito va nella direzione opposta.

Quanto costa davvero una sessione Roo Code

Gli strumenti agentici consumano molti token per progettazione: ogni passaggio reinvia il prompt di sistema, la cronologia dell’attività e il nuovo contesto dei file. Numeri realistici alle tariffe Kunavo:

Il calcolo, eseguibile:

# Kunavo Claude rates (USD per 1M tokens): (input, output)
RATES = {
    "claude-haiku-4-5":  (0.70, 3.50),
    "claude-sonnet-5":   (1.40, 7.00),
    "claude-opus-5":     (3.50, 17.50),
}

def step_cost(model, in_tokens, out_tokens):
    i, o = RATES[model]
    return in_tokens / 1_000_000 * i + out_tokens / 1_000_000 * o

# One Code-mode step: Roo resends the task context plus the files it read.
print(step_cost("claude-sonnet-5", 25_000, 1_200))         # -> $0.0434
# A realistic 20-step task on the Code-mode default:
print(20 * step_cost("claude-sonnet-5", 25_000, 1_200))    # -> ~$0.87
# Architect mode on Opus 5 for 3 steps, Code mode on Sonnet 5 for 17:
print(3 * step_cost("claude-opus-5", 25_000, 1_200)
      + 17 * step_cost("claude-sonnet-5", 25_000, 1_200))   # -> ~$1.06

Ridurre la fattura

1. Inizia nuove attività invece di estenderne una all'infinito. Roo Code reinvia l'intera conversazione a ogni passaggio, quindi il costo di un'attività lunga cresce quadraticamente. Una nuova attività significa un contesto nuovo e ridotto — l'abitudine con il maggiore impatto in questo caso.
2. Associa un profilo a ogni modalità. Come spiegato sopra: trasforma il routing del modello in configurazione, invece di qualcosa che devi ricordarti durante l'attività.
3. Usa la rotta Anthropic nativa per il caching. L'input memorizzato nella cache al 10% della tariffa di input è il maggiore risparmio strutturale in un ciclo che reinvia un prefisso stabile.
4. Dai all'editor una chiave con limiti di spesa propri. Crea una chiave separata nella dashboard e controlla l'utilizzo dopo una settimana reale — è l'unica stima onesta di quanto ti costa.

Domande frequenti