Cambio del provider in Claude Code: tutorial su CC Switch in 5 minuti

Questo tutorial si basa su CC Switch v4.0.26 (novembre 2026). Le etichette dei pulsanti potrebbero cambiare nelle versioni successive; il modello di configurazione rimane stabile.

Di solito, per passare da un provider all'altro in Claude Code bisogna modificare ~/.claude/settings.json: l'URL di base, la chiave API e, a volte, il modello. Con un solo provider è gestibile. Con due o tre, diventa una piccola attività di manutenzione; e il problema può passare inosservato, perché una vecchia variabile ANTHROPIC_* esportata nella shell può sovrascrivere il file appena modificato.

CC Switch trasforma il cambio di provider in una scheda su cui basta fare clic. Il preset AiHubMix integrato inserisce l'endpoint e tu devi solo incollare una chiave API. Di solito Claude Code ricarica le modifiche senza riavviarsi. Questo tutorial illustra la configurazione completa, spiega cosa scrive CC Switch, la trappola delle variabili d'ambiente e quando basta la modalità diretta.

Se vuoi solo la versione breve: installa CC Switch, crea una chiave AIHubMix, scegli il preset AiHubMix in Claude Code, incolla la chiave, aggiungi ANTHROPIC_MODEL=claude-sonnet-5-5 al provider, fai clic su Cambia ed esegui claude -p "1+1, output only the answer" --model claude-sonnet-5-5. Il resto dell'articolo spiega nel dettaglio questi passaggi.

Cos'è CC Switch

CC Switch è un'app desktop open source (MIT, Tauri + Rust + React) per gestire le configurazioni dei provider in Claude Code, Codex, Gemini CLI, OpenCode e altri strumenti di programmazione. Include oltre 90 preset per provider e supporta provider personalizzati.

È più di un semplice selettore di chiavi:

• Modalità diretta riscrive i campi relativi alla chiave nel file di configurazione del client, che comunica direttamente con il provider.
• Modalità di instradamento avvia un gateway locale su 127.0.0.1:15721, con conversione dei formati API, failover, controlli di integrità e log delle richieste.
• Modalità di aggregazione riunisce in un unico elenco /model i modelli di più provider.

Il repository e il manuale utente sono disponibili su github.com/farion1231/cc-switch. Solo ccswitch.io e la pagina GitHub Releases sono fonti ufficiali per il download; i siti che chiedono pagamenti o credenziali dell'account non sono ufficiali.

Prima di iniziare

Ti servono tre cose:

• Claude Code installato e avviabile da un terminale. Verifica con claude --version. Se non è installato, usa il programma d'installazione ufficiale: curl -fsSL https://claude.ai/install.sh | bash, oppure npm i -g @anthropic-ai/claude-code con Node.js 22 o versione successiva.
• Un account AIHubMix e una chiave API. Creane una nella console AIHubMix. Di solito la chiave inizia con sk-.
• Un programma d'installazione di CC Switch. Scaricalo da ccswitch.io o da GitHub Releases.

Passaggio 1: installa CC Switch

Al primo avvio, CC Switch importa la configurazione esistente di Claude Code come provider denominato default e aggiunge un provider ufficiale. La configurazione originale non viene persa: puoi tornare a usarla in qualsiasi momento.

Se Claude Code non è ancora installato, la pagina App di CC Switch permette di installarlo o aggiornarlo.

Passaggio 2: crea una chiave API AIHubMix

Apri la pagina delle chiavi API AIHubMix, creane una e copiala.

Il segnaposto AIHUBMIX_API_KEY nella documentazione non è una chiave reale. Se lo incolli così com'è, la richiesta fallisce con 401 invalid key: AIHUBMIX_API_KEY.

Passaggio 3: aggiungi AIHubMix a Claude Code

1. Seleziona Claude Code nella barra laterale a sinistra.
2. Fai clic sul pulsante + nell'angolo in alto a destra.
3. Cerca AiHubMix oppure trovalo nella categoria delle piattaforme di terze parti.
4. Il nome e l'endpoint vengono compilati automaticamente: https://aihubmix.com. Incolla la chiave in API Key.
5. Fai clic su Aggiungi.

Il preset memorizza due variabili d'ambiente:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com"
  }
}

Il preset non imposta un modello. La guida di AIHubMix considera ANTHROPIC_MODEL una variabile essenziale, quindi aggiungila allo stesso blocco env prima di cambiare provider:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}

Se non imposti un modello, Claude Code invia l'ID del proprio modello predefinito, che potrebbe non essere disponibile su AIHubMix.

Ci sono due dettagli da tenere a mente.

Non aggiungere /v1 all'URL di base. Claude Code usa il protocollo Anthropic Messages e compone autonomamente il percorso della richiesta. https://aihubmix.com è corretto; https://aihubmix.com/v1 è l'URL di base compatibile con OpenAI per altri client, a cui Claude Code aggiungerebbe il proprio /v1/messages.

Il preset usa ANTHROPIC_API_KEY, mentre la guida di AIHubMix per Claude Code usa ANTHROPIC_AUTH_TOKEN. AIHubMix accetta entrambi: ANTHROPIC_AUTH_TOKEN invia un'intestazione Bearer, mentre ANTHROPIC_API_KEY invia x-api-key. Scegline uno. Non compilare entrambi con valori diversi. I dettagli di configurazione AIHubMix, gli ID dei modelli e il riferimento agli errori sono nella documentazione di AIHubMix per Claude Code.

Se il preset non è disponibile, per esempio in una versione precedente o dopo aver eliminato la scheda, scegli Configurazione personalizzata e incolla il JSON qui sopra. Il gestore degli endpoint della scheda del provider può testare la latenza; il preset include anche https://api.aihubmix.com come endpoint alternativo nel caso in cui aihubmix.com non venga risolto.

Passaggio 4: cambia provider e verifica

Nella scheda Diretta, fai clic su Cambia nella scheda AiHubMix. Quando la configurazione è stata scritta, il pulsante diventa In uso.

Claude Code ricarica automaticamente la configurazione; di solito non è necessario riavviarlo. Se la sessione corrente continua a usare il vecchio provider, chiudila e riavviala.

Verifica che il flusso funzioni dall'inizio alla fine:

claude -p "1+1, output only the answer" --model claude-sonnet-5-5

Una risposta 2 significa che la richiesta ha raggiunto AIHubMix. In una sessione interattiva, la riga Anthropic base URL in /status dovrebbe mostrare https://aihubmix.com.

Per cambiare rapidamente provider, usa l'area di notifica: fai clic destro sull'icona di CC Switch, apri il sottomenu Claude Code e seleziona un provider. Il titolo del sottomenu mostra il provider attivo e un riepilogo della quota.

Per tornare al provider ufficiale, passa a Claude Official, riavvia Claude Code e completa la procedura di accesso.

Cosa modifica davvero il cambio di provider

In modalità diretta, CC Switch sostituisce solo i campi relativi alla connessione e alla compatibilità in ~/.claude/settings.json: ANTHROPIC_*, AWS_*, selettori di protocollo come CLAUDE_CODE_USE_BEDROCK, model, apiKeyHelper e alcune opzioni di compatibilità specifiche del provider, come CLAUDE_CODE_DISABLE_ARTIFACT e la finestra di contesto.

permissions, hooks, enabledPlugins, statusLine, la configurazione MCP, i commenti e tutto ciò che hai aggiunto rimangono invariati. L'elenco completo è nel riferimento ai file di configurazione.

Prima di modificare per la prima volta la configurazione di uno strumento, CC Switch salva una copia di backup dell'originale in ~/.cc-switch/backups/live-first-write/. Se il JSON non è valido, rifiuta di scriverlo, segnala la riga e la colonna e lascia il file invariato.

La trappola: variabili ANTHROPIC_* obsolete

È questo il problema che fa sembrare che CC Switch non abbia funzionato.

Se in passato hai seguito una guida alla configurazione manuale e hai aggiunto export ANTHROPIC_BASE_URL=... o export ANTHROPIC_AUTH_TOKEN=... a ~/.zshrc o ~/.bash_profile, queste variabili potrebbero sovrascrivere i valori scritti da CC Switch. Cambi la scheda in AiHubMix, ma le richieste continuano a raggiungere il vecchio endpoint.

CC Switch rileva il conflitto. Un banner giallo nella parte superiore della finestra avvisa che le variabili d'ambiente potrebbero sovrascrivere la configurazione; nei dettagli sono indicati il nome della variabile, il valore e la provenienza. Elimina selezionate le rimuove e, prima, crea una copia di backup in ~/.cc-switch/backups/env-backup-<timestamp>.json.

Per controllare manualmente:

grep -n "ANTHROPIC" ~/.zshrc ~/.bash_profile 2>/dev/null

Commenta le vecchie righe di esportazione, quindi esegui source ~/.zshrc oppure apri un nuovo terminale. La documentazione di AIHubMix consiglia di rimuovere le variabili globali ANTHROPIC_* quando CC Switch gestisce la configurazione. La procedura completa per risolvere i conflitti è descritta nel riferimento alle variabili d'ambiente.

Alias dei modelli e cambio di provider

Con ANTHROPIC_MODEL impostato, il modello predefinito di Claude Code è Sonnet 5.5. Gli alias di /model (opus, sonnet, haiku, fable) richiedono comunque una mappatura, se vuoi che corrispondano agli ID dei modelli AIHubMix. Aggiungi queste chiavi in env:

La configurazione completa del provider sarà quindi così:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-1"
  }
}

Priorità di selezione del modello, dalla più alta alla più bassa: /model <name> → claude --model <name> → ANTHROPIC_MODEL → il campo model in settings.json. Copia gli ID dei modelli dall'elenco dei modelli AIHubMix; distinguono tra maiuscole e minuscole.

Quando usare l'instradamento o l'aggregazione

La modalità diretta è la scelta consigliata per AIHubMix. L'endpoint supporta già Anthropic Messages, quindi non serve alcuna conversione del protocollo.

Usa l'instradamento quando vuoi una coda di failover o quando devi collegare a Claude Code un provider con formato OpenAI. L'instradamento indirizza Claude Code a http://127.0.0.1:15721, sostituisce la chiave nella configurazione con PROXY_MANAGED e inserisce la chiave reale tramite CC Switch. L'app deve rimanere in esecuzione; quando chiudi CC Switch, viene ripristinata la configurazione diretta. Gli abbonamenti ufficiali Claude non passano per l'instradamento: per quelli usa la modalità diretta.

Usa aggregazione se vuoi modelli di più fornitori in un'unica lista /model. Il fornitore predefinito gestisce le richieste senza prefisso; i modelli degli altri fornitori compaiono con il prefisso ccs-. L'aggregazione non esegue il failover. È disponibile solo per Claude Code e Codex e non supporta gli abbonamenti ufficiali Claude. Per la lista di modelli ccs- serve Claude Code 2.1.243 o versione successiva. Claude Code recepisce subito le modifiche alla lista dei modelli; Codex richiede un riavvio completo.

Cos'altro gestisce CC Switch

• Utilizzo: la dashboard combina i log delle richieste instradate con i log delle sessioni locali. La scansione delle sessioni funziona anche senza instradamento e calcola i costi in base al modello registrato nel log; le richieste instradate vengono registrate separatamente.
• MCP: un pannello unificato per i server MCP, sincronizzato con le app selezionate.
• Skills: scopri, installa e rimuovi skills da un unico posto.
• Sessioni: cerca, visualizza, esporta e riprendi le sessioni locali.
• Progetti: salva come istantanea il fornitore, i server MCP, le skills e i file di memoria di un progetto, quindi passa all'intero insieme per ciascun progetto.

I dati si trovano in ~/.cc-switch/, con un database SQLite al centro. I backup automatici conservano per impostazione predefinita i 10 più recenti; è disponibile la sincronizzazione tramite WebDAV o S3 compatibile. Il database e i backup esportati includono le configurazioni dei fornitori, comprese le chiavi: trattali come segreti.

Risoluzione dei problemi

Le stringhe di errore qui sotto sono citate dalla documentazione Claude Code di AIHubMix.

Per i sintomi che non sono errori:

• Schermata di accesso o Not logged in: controlla /status; in Settings → App config → Claude Code, abilita Skip Claude Code first-run confirmation; riavvia; verifica che la chiave sia inserita.
• Il passaggio non ha effetto: potrebbe esserci una variabile della shell obsoleta o una sessione memorizzata nella cache; apri un nuovo terminale o riavvia Claude Code.
• Il test di connessione della scheda ha esito positivo, ma le richieste falliscono: il test verifica la raggiungibilità, non la chiave o il modello; esegui il comando end-to-end claude -p.
• Vuoi tornare al fornitore ufficiale: passa a Claude Official, riavvia Claude Code ed effettua di nuovo l'accesso.

Se il comando claude non viene trovato su macOS, di solito l'installer ufficiale lo colloca in ~/.local/bin/claude. Aggiungi export PATH="$HOME/.local/bin:$PATH" al profilo della shell e apri un nuovo terminale.

Elenco di controllo

• [ ] Installa CC Switch da ccswitch.io o da GitHub Releases.
• [ ] Crea una chiave API nella console AIHubMix.
• [ ] In Claude Code → + → AiHubMix → incolla la chiave → Aggiungi.
• [ ] Aggiungi ANTHROPIC_MODEL=claude-sonnet-5-5 al JSON del fornitore.
• [ ] Fai clic su Passa e verifica che sulla scheda compaia In uso.
• [ ] Rimuovi dal profilo della shell le esportazioni obsolete ANTHROPIC_*.
• [ ] Esegui claude -p "1+1, output only the answer" --model claude-sonnet-5-5 e verifica che restituisca 2.

Se l'ultimo comando restituisce 2, il passaggio al fornitore è completato. Non resta che aggiungere eventuali alias di modello e decidere se ti servono l'instradamento o l'aggregazione; per la maggior parte degli utenti di AIHubMix è sufficiente la modalità diretta.

Domande frequenti

CC Switch è gratuito?
Sì. È un software open source con licenza MIT. Paghi solo il fornitore la cui API utilizzi.

Il passaggio elimina hook, server MCP o plugin?
No. Il passaggio diretto sostituisce l'endpoint, la chiave, il modello e alcune opzioni associate al fornitore. Hook, autorizzazioni, server MCP, plugin e impostazioni della barra di stato restano nel file.

CC Switch carica la mia chiave API?
Le configurazioni dei fornitori vengono salvate localmente in ~/.cc-switch/cc-switch.db. Se attivi la sincronizzazione WebDAV o S3, vengono sincronizzate con uno spazio di archiviazione che controlli tu. Database e backup contengono chiavi, quindi trattali come segreti.

Devo lasciare CC Switch in esecuzione?
Non in modalità diretta. L'instradamento e l'aggregazione richiedono che l'app sia in esecuzione; chiudendo CC Switch, il client torna alla modalità diretta.

Posso usare Claude Official e AIHubMix contemporaneamente?
La modalità diretta consente un solo fornitore attivo alla volta. L'aggregazione può inserire i modelli di più fornitori in un'unica lista, ma non supporta l'abbonamento ufficiale Claude; per usarlo, torna alla modalità diretta.

Funziona su Windows?
Sì. CC Switch supporta Windows 10 e versioni successive con un installer .msi o una versione portatile. Linux richiede glibc 2.35+ e WebKitGTK 4.1.

Perché la scheda del fornitore indica una connessione funzionante, ma Claude Code continua a non funzionare?
Il test di connettività della scheda verifica che l'endpoint sia raggiungibile. Non convalida la chiave API né il modello. Usa il comando end-to-end claude -p per testare l'intero percorso.

Fonti

• Repository di CC Switch
• Manuale utente di CC Switch: aggiungere un fornitore
• Manuale utente di CC Switch: passare a un altro fornitore
• Manuale utente di CC Switch: file di configurazione
• Documentazione AIHubMix: Claude Code