Documentazione

CC Switch

CC Switch alterna Claude Code e Codex tra diversi provider da un'app desktop. Kunavo si configura come configurazione personalizzata: root del servizio, autenticazione Bearer, API Anthropic Messages nativa, nessun routing locale.

Tre campi e due menu a discesa. https://api.kunavo.com come endpoint, la tua chiave sk-kn-… e — il dettaglio che la maggior parte delle guide omette — lascia API Format su Anthropic Messages (Native) e Auth Field su ANTHROPIC_AUTH_TOKEN. Kunavo supporta nativamente l'API Messages, quindi sul lato di Claude Code non serve alcun routing locale.

CC Switch → scheda Claude Code → Add provider

Provider Name   Kunavo
API Key         sk-kn-...
API Endpoint    https://api.kunavo.com      <- service root, no /v1, no trailing slash

Advanced Options
  API Format    Anthropic Messages (Native) <- the default; do NOT switch
  Auth Field    ANTHROPIC_AUTH_TOKEN (Default)

L'endpoint è la root del servizio: niente /v1, niente barra finale. I client in stile Anthropic aggiungono autonomamente /v1/messages: ecco perché questo campo è diverso da tutti gli esempi OpenAI, in cui /v1 fa parte dell'URL di base. La spiegazione completa è disponibile nella pagina ANTHROPIC_BASE_URL.

Procedura dettagliata (scheda Claude Code)

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
Apri CC Switch nella scheda principale Claude Code e fai clic sul pulsante più. Mantieni l'impostazione predefinita Custom Configuration invece di scegliere un preset.
Compila Provider Name, API Key e imposta API Endpoint = https://api.kunavo.com.
Espandi Advanced Options e verifica che API Format sia impostato su Anthropic Messages (Native) e Auth Field su ANTHROPIC_AUTH_TOKEN (Default). Sono entrambi valori predefiniti: l'importante è controllarli, non modificarli.
Salva, poi Activate. La scheda non dovrebbe mostrare l'indicatore Needs Routing: compare solo per i provider il cui protocollo deve essere tradotto.

Perché non compare l'indicatore «Needs Routing»

Il routing locale di CC Switch serve a fare da ponte tra protocolli. Claude Code invia richieste Anthropic Messages a /v1/messages; un gateway che espone solo OpenAI Chat Completions o l'API Responses non può rispondere, quindi il routing converte la richiesta in uscita e la risposta al ritorno. È durante questa conversione che gli eventi di streaming, le chiamate agli strumenti e la configurazione del thinking vengono rielaborati: funziona, ma aggiunge un passaggio tra l'editor e il modello.

Kunavo fornisce direttamente POST /v1/messages, quindi sul lato di Claude Code non c'è nulla da convertire: il provider resta Anthropic Messages (Native) e il routing non entra affatto nel percorso. Kunavo fornisce anche POST /v1/chat/completions e POST /v1/responses con la stessa chiave: è questo che rende possibile la configurazione Codex descritta qui sotto.

Scheda CC Switch	Imposta il formato su	Routing locale
Claude Code	`Anthropic Messages (Native)`	Non necessario
Codex	`Anthropic Messages (routing required)`	Obbligatorio: il routing riscrive /responses in /v1/messages

Eseguire modelli Claude all'interno di Codex

Questa è la configurazione che le guide degli altri provider non trattano. Codex usa l'API OpenAI Responses, quindi se lo si punta direttamente a un endpoint /v1/messages restituisce 404. CC Switch risolve il problema mantenendo Codex sul routing locale e traducendo le richieste. Nella scheda Codex non c'è un preset Anthropic, quindi anche questa è una Custom Configuration:

CC Switch → scheda Codex → Add provider

Provider Name      Kunavo
API Key            sk-kn-...
API Request URL    https://api.kunavo.com
Default Model      claude-sonnet-5

Advanced Options
  Upstream Format  Anthropic Messages (routing required)

La guida di CC Switch include un avviso che vale la pena ripetere: alcuni provider limitano l'uso della propria API Claude al client Claude Code, quindi una chiave di questo tipo potrebbe generare un errore se usata tramite Codex. Kunavo non applica questa limitazione: la stessa chiave sk-kn-… serve l'endpoint Messages e quello Responses, e nessuno dei due prevede una lista di client consentiti. Se preferisci evitare del tutto la traduzione, anche Codex CLI può puntare direttamente all'endpoint nativo di Kunavo /v1/responses; la procedura è descritta nella pagina Codex CLI.

Associazione dei modelli

CC Switch associa i tre livelli di Claude Code a ID di modelli reali. Compila tutti e tre i campi e anche Default fallback model: altrimenti, le richieste non corrispondenti vengono inoltrate con il nome Claude originale e generano un errore upstream. Le tariffe sono in USD per 1M token, input / output, e vengono lette in tempo reale dal catalogo.

Livello	ID del modello	Kunavo ingresso / uscita	Perché
Haiku	`claude-haiku-4-5`	$0.70 / $3.50	Claude Code instrada qui le attività secondarie in background: il livello più economico è quello giusto
Sonnet	`claude-sonnet-5`	$1.40 / $7.00	L'impostazione predefinita più adatta per modificare il codice
Opus	`claude-opus-5-5`	$2.80 / $14.00	Modifiche a livello di architettura

Lascia deselezionata la casella 1M, a meno che il livello non supporti davvero una finestra di contesto da un milione di token. Dichiarare una capacità di contesto che il servizio upstream non ha non la estende: sposta soltanto l'errore più avanti, nel mezzo di una conversazione lunga.

Verifica prima di eseguire il debug dell'app

Una coppia di richieste basta a capire se il problema riguarda la chiave, l'endpoint o CC Switch. Se entrambe restituiscono 200, ciò che resta da correggere è un campo del modulo: quasi sempre Auth Field oppure un /v1 che non dovrebbe essere nell'endpoint.

# Settles whether a failure is the key, the endpoint, or CC Switch.
# 200 + a JSON list of model ids means the same key works in the app.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

# The Anthropic face, which is the one the Claude Code tab actually calls.
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-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

Riferimenti

CC Switch è open source su github.com/farion1231/cc-switch. I nomi dei campi e il comportamento descritti sopra provengono dalle guide ufficiali del progetto: la guida al routing per Claude Code e la guida al routing per Codex, entrambe valide dalla versione 3.17.0 in poi. Nelle versioni precedenti il modulo è diverso; se manca un campo citato qui, controlla il pannello Informazioni dell'app. La configurazione di Kunavo è documentata nelle pagine dedicate all'API Messages, a chat completions e all'hub delle integrazioni.

Domande frequenti

Come si aggiunge un provider personalizzato in CC Switch?

Nella scheda Claude Code, fai clic sul pulsante con il segno più, lascia selezionato Custom Configuration e compila Provider Name, API Key e API Endpoint. API Endpoint è la radice del servizio del gateway, senza barra finale: per Kunavo è https://api.kunavo.com, senza /v1. Poi apri Advanced Options e controlla due campi: API Format e Auth Field. Determinano entrambi se il provider funziona e sono quelli che la maggior parte delle guide di configurazione tralascia.

Devo attivare l’instradamento locale di CC Switch per usare Kunavo?

No. L’instradamento locale serve a convertire i protocolli: converte le richieste /v1/messages di Claude Code in OpenAI Responses o Chat Completions quando il servizio upstream supporta solo questi formati. Kunavo offre nativamente l’API Anthropic Messages all’indirizzo https://api.kunavo.com/v1/messages; quindi API Format rimane sull’opzione predefinita Anthropic Messages (Native). Sulla scheda del provider non compare mai l’indicatore Needs Routing e le richieste vanno direttamente al servizio upstream. Per un gateway che offre solo Chat Completions, invece, è necessario instradare localmente ogni richiesta.

Perché l’API Endpoint non include /v1, mentre gli esempi OpenAI sì?

Perché le due convenzioni sono volutamente diverse. I client in stile Anthropic aggiungono autonomamente /v1/messages, quindi richiedono solo l’origine: https://api.kunavo.com. Gli SDK OpenAI si aspettano invece che /v1 sia già incluso in base_url, quindi richiedono https://api.kunavo.com/v1. La scheda Claude Code di CC Switch usa la convenzione Anthropic, perciò si omette /v1. Invertire i due formati è l’errore di configurazione più comune in tutti i client; la pagina ANTHROPIC_BASE_URL illustra entrambe le opzioni.

Devo impostare Auth Field su ANTHROPIC_API_KEY?

No: mantieni il valore predefinito, ANTHROPIC_AUTH_TOKEN. Con questa impostazione, CC Switch invia Authorization: Bearer <key>. Selezionando ANTHROPIC_API_KEY, invia invece un’intestazione x-api-key, che Kunavo accetta altrettanto bene. Il problema non è quindi l’intestazione, ma l’autorizzazione. Prima di usare ANTHROPIC_API_KEY in una sessione interattiva, Claude Code chiede un’autorizzazione una tantum; se la rifiuti, ignorerà la chiave in seguito. L’errore di autenticazione risultante fa pensare che la chiave sia errata, anche quando è valida.

Posso eseguire modelli Claude in Codex tramite CC Switch?

Sì, ed è proprio la parte che la maggior parte delle guide sui provider tralascia. Nella scheda Codex, aggiungi una Custom Configuration con API Request URL https://api.kunavo.com e un Default Model come claude-sonnet-5; poi, in Advanced Options, imposta Upstream Format su Anthropic Messages (routing required). Per questa direzione l’instradamento locale deve essere attivo, perché Codex usa l’API Responses e la route converte /responses in /v1/messages. La guida di CC Switch avverte che alcuni provider limitano la propria API Claude al client Claude Code e che le relative chiavi non funzionano tramite Codex. Kunavo non ha questa limitazione: la stessa chiave sk-kn- funziona con entrambi i client.

Quali ID modello devo inserire nella mappatura dei modelli di CC Switch?

Usa gli ID del catalogo Kunavo. Una buona suddivisione predefinita è claude-haiku-4-5 ($0.70 / $3.50 per 1 milione di token) per il livello Haiku, perché Claude Code vi invia le attività secondarie in background; claude-sonnet-5 ($1.40 / $7.00) per Sonnet; e claude-opus-5-5 ($2.80 / $14.00) per Opus. Compila sempre anche il modello di fallback predefinito: se lo lasci vuoto, CC Switch inoltra le richieste non corrispondenti con il nome Claude originale e queste falliscono upstream. L'elenco aggiornato è disponibile su GET /v1/models.

Dove salva CC Switch la mia chiave API?

Nel proprio archivio, non nella configurazione del client. CC Switch conserva i provider in ~/.cc-switch/cc-switch.db e, quando l’instradamento locale prende in carico un client, scrive solo l’indirizzo della route locale in ~/.claude/settings.json, inserendo un segnaposto nel campo di autenticazione: la route aggiunge la chiave effettiva al momento dell’inoltro. È una caratteristica di CC Switch, non di Kunavo; è utile saperlo perché la chiave incollata non è quella che si trova nel file che potresti stare per includere in un commit.