CC Switch per Claude Code: gestione di account, provider e configurazioni

Cosa fa davvero CC Switch nella gestione di Claude Code

CC Switch è un gestore desktop open source delle configurazioni per agenti di programmazione. Le integrazioni supportate si sono ampliate nel tempo, quindi consulta il repository e le note di rilascio aggiornati prima di adottare un elenco fisso come standard. Claude Code è una delle integrazioni principali; le versioni attuali si rivolgono anche ad altri agenti di programmazione da riga di comando, come Codex e Gemini CLI.

Per Claude Code, un profilo del provider combina solitamente:

• Un endpoint API compatibile con Anthropic
• Una chiave API o un token di autenticazione
• Mappature dei modelli o valori di ambiente relativi ai modelli
• Variabili di ambiente aggiuntive
• Definizioni dei server MCP
• Impostazioni di Claude Code che devono essere associate al profilo

Questo è utile quando «account» non significa semplicemente un accesso ad Anthropic. Negli ambienti reali, gli sviluppatori possono alternare:

• Accesso diretto all'API di Anthropic
• Il gateway API autenticato di un'organizzazione
• Un provider di terze parti compatibile con Anthropic
• Account di fatturazione separati per uso personale, staging e produzione
• Un proxy locale o remoto che espone una semantica delle richieste compatibile

CC Switch centralizza queste scelte e attiva la configurazione selezionata. Non fa sì che tutti gli endpoint compatibili si comportino in modo identico. Le differenze nei nomi dei modelli, nelle intestazioni di autenticazione, nei limiti di frequenza, nella memorizzazione dei prompt nella cache e nei campi API non supportati restano di competenza del provider.

La tabella mette in evidenza il compromesso: CC Switch riduce gli errori dell'operatore, ma diventa un'ulteriore applicazione locale con privilegi.

Installazione e piattaforme supportate

CC Switch viene distribuito tramite la pagina GitHub Releases del progetto. Il repository descrive attualmente il supporto desktop per macOS, Windows e Linux, con artefatti di rilascio che variano in base alla piattaforma e alla versione. Verifica i file allegati alla release che intendi distribuire; la disponibilità del codice sorgente non garantisce che ogni release includa una build per ogni versione del sistema operativo, architettura CPU o formato di pacchetto.

Su macOS, il progetto offre un flusso di installazione tramite cask Homebrew:

brew tap farion1231/cc-switch
brew install --cask cc-switch

Prima di utilizzare un binario scaricato in un ambiente gestito, verifica cosa ha installato Homebrew:

brew info --cask cc-switch
brew list --cask cc-switch
codesign -dv --verbose=4 "/Applications/CC Switch.app" 2>&1

Gli utenti Windows e Linux devono procurarsi il programma di installazione o il pacchetto dai file pubblicati con la release. I nomi dei pacchetti e i canali possono cambiare, quindi evito di inserire negli script di configurazione iniziale delle postazioni un comando potenzialmente obsoleto per winget, Scoop, .deb o AppImage senza fissare e testare la release esatta.

Per una distribuzione controllata:

1. Fissa una versione di CC Switch.
2. Registra il checksum previsto della release.
3. Testala con una configurazione di Claude Code usa e getta.
4. Censisci tutti i file modificati durante l'attivazione del profilo.
5. Definisci un processo di aggiornamento invece di passare automaticamente all'ultima release senza segnalarlo.

Una semplice istantanea prima dell'installazione è utile:

mkdir -p /tmp/claude-config-before
cp -R ~/.claude /tmp/claude-config-before/ 2>/dev/null || true

# Install CC Switch, create a test profile, and activate it.

diff -ru /tmp/claude-config-before/.claude ~/.claude || true

Questo permette di rilevare comportamenti che la documentazione può non riportare, tra cui riscritture della formattazione, campi rimossi o voci MCP unite a un ambito inatteso.

Creazione e cambio dei profili dei provider

Un profilo dovrebbe rappresentare un contesto coerente di sicurezza e fatturazione. Uso nomi che rendono chiaro l'impatto, come:

• anthropic-personal
• company-gateway-dev
• customer-a-restricted
• local-proxy-test

Evita etichette come default-2. Quando si verifica un incidente in produzione, il nome del profilo attivo dovrebbe rispondere alla domanda «dove verrà inviata questa richiesta?» senza dover aprire un editor.

Un profilo di Claude Code che utilizza un gateway compatibile con Anthropic potrebbe generare impostazioni concettualmente simili a queste:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai-gateway.example.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "${TOKEN_MANAGED_BY_PROFILE}",
    "ANTHROPIC_MODEL": "company-claude-default"
  },
  "permissions": {
    "defaultMode": "default"
  }
}

Le variabili esatte richieste dipendono dal provider e dalla versione di Claude Code. Alcuni servizi richiedono ANTHROPIC_API_KEY; alcune integrazioni con gateway usano ANTHROPIC_AUTH_TOKEN. Non valorizzarle entrambe soltanto per rendere «più probabile» il funzionamento dell'autenticazione. Determina quale credenziale avrà la precedenza in Claude Code, perché un valore obsoleto con precedenza maggiore può instradare le richieste tramite l'account sbagliato.

Dopo il cambio, avvia un nuovo processo di Claude Code:

claude

È facile fraintendere cosa accade realmente quando cambi profilo mentre Claude Code è già in esecuzione. L'utilità può aggiornare i file su disco, ma non può sostituire in modo affidabile i valori di ambiente già ereditati da un processo in esecuzione. Le sessioni esistenti possono quindi continuare a utilizzare il provider originale fino al riavvio.

Verifica la configurazione effettiva senza stampare segreti:

python3 - <<'PY'
import json
from pathlib import Path

path = Path.home() / ".claude" / "settings.json"
data = json.loads(path.read_text())
env = data.get("env", {})

for key, value in sorted(env.items()):
    if "KEY" in key or "TOKEN" in key or "SECRET" in key:
        value = "<redacted>"
    print(f"{key}={value}")
PY

Un errore comune è verificare soltanto se Claude risponde. Un proxy compatibile può restituire una risposta valida mentre associa silenziosamente il modello richiesto a un altro modello. Verifica i log delle richieste del provider o il registro di audit del gateway quando l'identità del modello è importante.

Impostazioni MCP tra agenti

È nella configurazione MCP che la centralizzazione diventa più utile di un semplice selettore di token. Uno sviluppatore può avere server per filesystem, tracciamento delle issue, database e browser configurati in diversi agenti, ciascuno con il proprio schema o percorso di archiviazione.

Una tipica definizione di server MCP contiene un comando e degli argomenti:

{
  "mcpServers": {
    "project-files": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/alex/work/customer-a"
      ]
    }
  }
}

Trattala come una configurazione eseguibile. L'attivazione del profilo può consentire a un agente di avviare npx, eseguire un pacchetto ed esporre la directory specificata al livello degli strumenti accessibili al modello.

In pratica, separo i profili MCP in base alla sensibilità dei repository:

• Un profilo generale espone documentazione e strumenti a basso rischio.
• Un profilo cliente espone soltanto la directory di lavoro di quel cliente.
• I server di database e di controllo della produzione non sono abilitati globalmente.
• I token utilizzati dai server MCP hanno un ambito definito indipendentemente dal token del provider del modello.

Confronta inoltre il risultato generato da CC Switch con il comando MCP nativo dell'agente, quando disponibile. Per Claude Code, controlla i server attivi dopo il cambio:

claude mcp list

Non dare per scontato che un oggetto MCP JSON possa essere copiato senza modifiche in ogni agente di programmazione. CC Switch può uniformare la gestione nella propria interfaccia, ma ogni agente a valle mantiene il proprio schema, le proprie regole di ambito e il proprio comportamento durante il ciclo di vita.

Dove vengono memorizzate le credenziali

Ci sono due livelli di archiviazione da sottoporre a verifica:

1. I dati dell'applicazione CC Switch, utilizzati per conservare i profili.
2. La configurazione nativa dell'agente di programmazione, scritta o aggiornata quando viene attivato un profilo.

CC Switch utilizza l'archiviazione locale dell'applicazione anziché un servizio di account ospitato. Il percorso esatto dipende dalla piattaforma ed è cambiato con l'evoluzione dell'applicazione, quindi ricavalo dalla build installata invece di affidarti a un percorso copiato da una vecchia issue. Le directory radice comuni per i dati delle applicazioni nei sistemi operativi sono:

macOS:   ~/Library/Application Support/
Windows: %APPDATA%
Linux:   ~/.local/share/ or an XDG data directory

Esegui la ricerca senza stampare il contenuto delle credenziali:

find "$HOME/Library/Application Support" \
  -maxdepth 3 -iname '*cc*switch*' -print 2>/dev/null

find "${XDG_DATA_HOME:-$HOME/.local/share}" \
  -maxdepth 3 -iname '*cc*switch*' -print 2>/dev/null

Per Claude Code, esamina ~/.claude/, in particolare settings.json, oltre alla configurazione di Claude a livello di progetto, ove applicabile. Gli altri agenti usano comunemente directory separate, come ~/.codex/ o ~/.gemini/, ma i nomi dei file e i formati delle credenziali dipendono dalla versione dell’agente.

Non dare per scontato che “archiviato localmente” significhi “crittografato”. A meno che la versione di CC Switch installata non utilizzi esplicitamente un archivio di credenziali del sistema operativo per il segreto in questione, considera il database dell’applicazione e i file dell’agente generati come potenzialmente leggibili in chiaro dal tuo account utente. Verificalo ispezionando i file e revisionando il codice del repository, facendo attenzione a non incollare segreti in terminali, ticket o sessioni di chat.

Implicazioni di sicurezza dell’accesso ai token dal desktop

CC Switch opera necessariamente con le autorizzazioni del tuo utente desktop. Se quell’account può leggere un token, anche un malware o un altro processo eseguito dallo stesso utente potrebbe essere in grado di leggerlo. CC Switch non elimina i requisiti di sicurezza degli endpoint.

I rischi principali sono:

• Concentrazione delle credenziali: Più token di provider possono coesistere in un unico archivio locale dei profili.
• Sovrascrittura della configurazione: L’attivazione di un profilo può sostituire o unire i file utilizzati da un agente.
• Esposizione tramite backup: I dati dell’applicazione e i file di configurazione nascosti possono finire in backup non crittografati.
• Ereditarietà dei processi: I terminali già aperti e gli agenti in esecuzione possono conservare le credenziali precedenti.
• Esecuzione MCP: Un profilo può attivare comandi con accesso al filesystem o alla rete.
• Esposizione della catena di fornitura: L’installazione degli aggiornamenti consente a nuovo codice desktop di accedere ai token archiviati.
• Divulgazione tramite schermate e log: La diagnostica dell’interfaccia o le segnalazioni di bug possono rivelare dati sugli endpoint e sulle credenziali.

Applica controlli basati sul principio del privilegio minimo nell’uso dell’utilità:

chmod 700 ~/.claude
chmod 600 ~/.claude/settings.json

Preferisci token del gateway di breve durata o revocabili, se il provider li supporta. Non inserire mai una credenziale amministrativa di produzione in un profilo creato per comodità. Ruota i token dopo aver dismesso una macchina; eliminare un profilo non dimostra che la credenziale non sia mai stata copiata altrove.

Per un’implementazione aziendale, richiederei:

• Versioni fissate e revisionate
• Crittografia dell’intero disco
• Gestione dei backup con accesso limitato
• Limiti di spesa e log di audit lato provider
• Token separati per ogni sviluppatore e ambiente
• Una procedura di revoca documentata
• Revisione periodica dei comandi MCP e dei percorsi esposti

CC Switch è una soluzione pratica per i flussi di lavoro locali con più provider. Non è automaticamente adatto agli ambienti in cui le policy richiedono segreti protetti da hardware, credenziali effimere o una configurazione applicata centralmente. In questi casi, un gateway aziendale e un programma di avvio che si appoggia a un gestore di segreti possono costituire una soluzione più difendibile.

Indicazioni pratiche

• Usa CC Switch quando le modifiche manuali ripetute causano errori relativi ad account, endpoint o MCP.
• Verifica gli artefatti per le varie piattaforme nella release corrente del progetto su GitHub prima della distribuzione.
• Assegna a ogni profilo un nome che ne identifichi il provider, il proprietario e l’ambiente.
• Riavvia Claude Code dopo il cambio, perché i processi in esecuzione potrebbero conservare i vecchi valori.
• Ispeziona i file generati e usa claude mcp list per verificare lo stato effettivo.
• Tratta i dati locali di CC Switch e le configurazioni degli agenti a valle come archivi di credenziali sensibili.
• Definisci l’ambito di accesso dei server MCP con la stessa attenzione riservata ai token API; possono eseguire comandi ed esporre file.
• Fissa le versioni, verifica le differenze di configurazione e mantieni una procedura per la revoca dei token.
• Tieni le credenziali di produzione ad alto impatto fuori dagli strumenti desktop per il cambio di profilo, a meno che i controlli circostanti non consentano esplicitamente di gestire tale rischio.