Claude Code Router: eseguire Claude Code su altri modelli (e quando un gateway è più semplice)

Che cosa fa Claude Code Router

Claude Code Router di musistudio, spesso abbreviato in CCR, si descrive come un «gateway locale per modelli e piano di controllo per agenti di programmazione». Fornisce un endpoint locale stabile per Claude Code e altri client, con credenziali dei provider, regole di instradamento, nuovi tentativi, fallback ordinati e log delle richieste.

La v3.1.1 README elenca il supporto per i formati OpenAI Chat e Responses, Anthropic Messages e Gemini Generate Content e Interactions. L'adattamento dei protocolli rende possibile utilizzare Claude Code con altri modelli tramite CCR.

CCR è distribuito con licenza MIT, con copyright 2025 di musistudio, ed è fornito «COSÌ COM'È». Il permesso di usare il software non rende gratuita l'inferenza presso i provider a monte. I costi e le quote dei provider restano separati; i prezzi storici dei provider e le quote in dollari di OpenCode Go non sono stati verificati per questa data di pubblicazione.

La versione di Claude Code Router 3.1 di riferimento

La versione 3.1.1 è stata rilasciata il 16 settembre 2026. Aggiunge il supporto nativo all'importazione locale di OpenCode Go, rende visibili i singoli tentativi falliti del gateway e corregge il calcolo dei costi di utilizzo per i modelli instradati.

La versione accetta inoltre --daemon su start e serve, corregge il worker del corpo dei log nell'interfaccia Docker e fornisce build per macOS Apple Silicon e Intel, un programma di installazione per Windows e un'AppImage per Linux. La configurazione seguente utilizza la distribuzione npm e la documentazione fissata alla versione v3.1.1.

Installa CCR e collega Claude Code

La distribuzione npm richiede Node.js 22 o successivo. La guida CLI della versione di riferimento documenta questi comandi:

npm install -g @musistudio/claude-code-router
ccr --help
ccr ui

Per avviare senza aprire un browser:

ccr ui --no-open

L'interfaccia di gestione e il gateway dei modelli hanno indirizzi predefiniti separati:

Tenere ben distinti questi ruoli aiuta a individuare dove una connessione non è riuscita. Il fatto che la pagina di gestione funzioni non dimostra, da solo, che il gateway dei modelli abbia accettato la propria configurazione.

Aggiungi un provider e una chiave client

Apri Provider → Aggiungi provider, scegli una configurazione predefinita oppure Altro / endpoint API personalizzato, quindi inserisci l'endpoint e la chiave API. CCR rileva protocolli e modelli; Impostazioni avanzate consente di selezionare manualmente un protocollo.

Usa Verifica connessione per testare il provider. Questa operazione invia una richiesta reale, quindi può consumare token o parte della quota di richieste del provider.

Crea una chiave client CCR su Chiavi API per le richieste ai modelli. Questa chiave è separata dal token dell'interfaccia di gestione/RPC: considera l'accesso client e l'accesso di gestione come elementi di configurazione distinti.

Crea un profilo Claude Code

In Configurazione agente, crea un profilo abilitato per Claude Code, seleziona un modello come Provider/modele salvalo. Per un profilo denominato «Claude Code - Work», avvia con:

ccr "Claude Code - Work"

I comandi di avvio generati dall'app desktop utilizzano ccr-app. La guida ai profili Claude Code distingue due ambiti:

• Solo avvii da CCR applica la configurazione agli avvii da CCR.
• Predefinito di sistema influisce anche sugli avvii diretti di Claude Code.

I profili supportano le sostituzioni per Fable, Opus, Sonnet e Haiku. Verifica la selezione attiva con /model, quindi esamina in CCR Log delle richieste per vedere le richieste che passano attraverso il gateway. Tieni a portata di mano guida ai modelli di Claude Code quando pianifichi queste selezioni.

Configura instradamento, nuovi tentativi e fallback

Le regole di instradamento di CCR possono esaminare request.header e request.bodye possono riscrivere request.body.model. Questo consente di controllare la selezione del modello in base alla richiesta in arrivo, oltre al modello scelto nel profilo di un agente.

La configurazione dei fallback utilizza mode, modelse retryCount. Le tre modalità sono off, retrye model-chain.

La distinzione tra l'idoneità a un nuovo tentativo e l'idoneità al fallback è importante. Una risposta che non consente un nuovo tentativo può comunque consentire il passaggio a una destinazione di fallback.

Verifica quale modello ha effettivamente gestito la richiesta

Una catena di modelli può cambiare il modello che alla fine gestisce una richiesta. I log di CCR mostrano il provider e il modello finali: usali quindi per verificare comportamenti o consumi inattesi.

Inizia con un profilo di cui puoi identificare il provider e il modello. Aggiungi regole di instradamento e destinazioni di fallback in modo ponderato, quindi verifica la destinazione finale dopo averle messe alla prova. In questo modo è più facile collegare un cambiamento nelle risposte o nell'andamento dei costi alla configurazione di instradamento.

La versione 3.1.1 rende visibili anche i singoli tentativi falliti del gateway. Questi record aiutano a distinguere una risposta finale riuscita dai tentativi che l'hanno preceduta.

Usa l'importazione di OpenCode Go nella versione v3.1.1

La versione v3.1.1 di Claude Code Router di musistudio aggiunge il supporto nativo all'importazione locale di OpenCode Go. L'integrazione separa Zen, identificato come opencode, da Go, identificato come opencode-go, comprese le rispettive credenziali e gli ID dei modelli sovrapposti.

Lo strumento di importazione legge la configurazione di OpenCode, auth.jsone i metadati dei modelli memorizzati nella cache. OPENCODE_API_KEY si applica a entrambi i servizi; OPENCODE_GO_API_KEY fornisce una configurazione alternativa specifica per Go. Il rilevamento filtra i modelli in base al protocollo e riconcilia i metadati nella cache con i risultati in tempo reale di /models .

Perché l'header di sessione è importante

La La PR di integrazione di OpenCode Go indica che le richieste a https://opencode.ai/zen/go/v1 richiedono x-opencode-session. In sua assenza, l'endpoint restituisce 400 MissingSessionID.

CCR seleziona il valore di sessione in questo ordine: configurazione esplicita, un header esplicito del client, gli header di sessione di Claude, metadata.user_ide infine un valore di ripiego stabile per il processo. L'inserimento dell'header è limitato all'endpoint ufficiale di Go.

Questo spiega perché inserire soltanto un endpoint e una credenziale potrebbe non essere sufficiente per Go. Il requisito relativo alla sessione fa parte dell'integrazione del provider.

Aggiornare il rilevamento e consultare i limiti di utilizzo

Se l'importazione da Go non è disponibile, collega OpenCode Go in OpenCode, aggiorna la cache locale dei modelli e ripeti la scansione in CCR.

CCR recupera i dati di utilizzo da GET https://opencode.ai/zen/go/v1/usage e mostra le percentuali rimanenti per le finestre di cinque ore, settimanali e mensili. La documentazione fissata come riferimento non specifica le quote in dollari. Interpreta questi valori come percentuali rimanenti per le finestre indicate; non definiscono un saldo monetario.

Diagnosticare la connessione per fasi

Il materiale di CCR sulla risoluzione dei problemi tratta l'instradamento aggirato, gli errori di autenticazione, i modelli mancanti, la selezione inattesa dei modelli, i picchi di costo, i timeout e le tracce degli agenti mancanti. Una sequenza diagnostica utile segue la richiesta dalla configurazione di avvio fino al provider finale.

Claude Code aggira CCR

Verifica che il profilo Agent Config desiderato sia abilitato e che l'avvio sia avvenuto tramite quel profilo. Un profilo impostato su Solo avvii da CCR limita la propria configurazione agli avvii tramite CCR; gli avvii diretti sono interessati quando è selezionato Predefinito di sistema .

Usa /model insieme ai log delle richieste di CCR per verificare la configurazione. La riferimento della CLI di Claude Code fornisce un riferimento più ampio per lavorare con il client.

Errori di autenticazione o modelli mancanti

Per gli errori 401/403, controlla le credenziali a ogni livello pertinente: la chiave API del provider, la chiave client di CCR per le richieste ai modelli e il token di gestione separato. Queste credenziali svolgono ruoli diversi.

Per model not found, controlla i modelli rilevati, il protocollo selezionato e la selezione del provider e del modello nel profilo. Con OpenCode Go, aggiorna la cache locale e ripeti la scansione se l'importazione non è disponibile.

Errori di avvio e timeout

La versione 3.1.1 aumenta il tempo concesso per l'accettazione della configurazione del gateway da cinque secondi a 30 secondi. Questo risolve i casi in cui l'interfaccia di gestione si avvia ma il gateway non riesce ad avviarsi quando l'host è sotto carico, soprattutto su Windows.

CCR_GATEWAY_CONFIG_TIMEOUT_MS sovrascrive il timeout. I valori non validi o inferiori a 1,000 millisecondi comportano il ripristino del valore predefinito.

La configurazione si trova in ~/.claude-code-router su macOS/Linux e in %APPDATA%\claude-code-router su Windows. Tra i file pertinenti figurano config.sqlite, il file generato gateway.config.jsone service.json. I comandi del servizio includono ccr start, ccr stope, per l'esecuzione in primo piano, ccr serve.

Quando un gateway ospitato è più semplice

CCR si adatta ai flussi di lavoro che richiedono la gestione locale dei provider, l'instradamento basato sulle richieste, pool di credenziali o catene di fallback esplicite. Un gateway ospitato può ridurre i passaggi di configurazione locale quando l'obiettivo immediato è collegare Claude Code a un servizio a monte.

L'annuncio di OpenRouter del 4 agosto 2026 documenta queste impostazioni di connessione:

ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=<openrouter-api-key>
ANTHROPIC_API_KEY=

L'annuncio specifica anche ulteriori impostazioni per modelli e funzionalità. Queste tre variabili sono le impostazioni di connessione, non una configurazione completa per ogni modello. OpenRouter avverte che la maggior parte dei modelli aperti non supporta la ricerca di strumenti, quindi le impostazioni variano in base al modello.

La sua CLI Ori automatizza la configurazione tramite:

ori login
ori claude

Gli stessi flussi di lavoro possono essere eseguiti anche tramite un gateway API come AI Prime Tech, un servizio indipendente non affiliato ad Anthropic o OpenAI; consulta la guida a usare Claude Code con una chiave API.

Scegli in base ai controlli di cui hai bisogno. CCR offre un punto di gestione locale per amministrare le rotte, esaminare i tentativi e configurare i fallback; l'approccio ospitato documentato elimina la necessità di eseguire CCR localmente.

Punti chiave

• Claude Code Router collega Claude Code e altri client ai provider tramite un endpoint locale stabile con adattamento dei protocolli.
• La distribuzione npm richiede Node.js 22+ e l'interfaccia di gestione e il gateway dei modelli utilizzano porte predefinite separate.
• L'ambito di Agent Config determina se un profilo si applica soltanto agli avvii tramite CCR o anche agli avvii diretti.
• I fallback possono cambiare il modello che serve la richiesta; esamina i log delle richieste per individuare il provider e il modello finali.
• La versione v3.1.1 aggiunge l'importazione da OpenCode Go con credenziali separate e la gestione obbligatoria dell'header di sessione.
• Un gateway ospitato può ridurre la configurazione locale quando non hai bisogno dei controlli di instradamento locale di CCR.

FAQ

Claude Code Router è gratuito?

Claude Code Router è distribuito con licenza MIT, che concede il permesso di utilizzare il software. Questo non implica che l'inferenza a monte sia gratuita, e i prezzi storici dei provider o le quote in dollari di OpenCode Go non sono verificati qui.

Posso usare Claude Code con altri modelli tramite CCR?

Sì. CCR offre l'adattamento dei protocolli e la selezione del provider e del modello, e i suoi profili Claude Code consentono di selezionare un modello come Provider/model. I formati a monte supportati includono OpenAI Chat/Responses, Anthropic Messages e Gemini Generate Content/Interactions.

Che cosa è cambiato in Claude Code Router 3.1.1?

Rilasciata il 16 settembre 2026, la versione v3.1.1 aggiunge il supporto nativo all'importazione locale da OpenCode Go, la visibilità dei singoli tentativi falliti e prezzi di utilizzo corretti per i modelli instradati. Inoltre, aumenta a 30 secondi il tempo concesso per l'accettazione della configurazione del gateway e accetta --daemon su start e serve.

Perché OpenCode Go restituisce MissingSessionID?

L'endpoint ufficiale di OpenCode Go richiede l'header x-opencode-session e restituisce 400 MissingSessionID quando è assente. L'integrazione Go di CCR seleziona un valore di sessione secondo un ordine di precedenza definito e inserisce l'header soltanto per l'endpoint ufficiale di Go.