Claude Code Router: tutorial passo passo per orchestrare Ollama, Claude e Codex

🧭 Cos'è un orchestratore (router) di modelli

Un orchestratore (o router di modelli) è un piccolo programma che si mette tra il tuo strumento — qui Claude Code — e i vari provider di modelli. Riceve ogni richiesta e decide dove mandarla: a un modello che gira sul tuo computer o a un'API nel cloud.

Il principio è semplice: una sola interfaccia, più motori dietro. Cambi modello senza cambiare strumento e senza riscrivere niente — sposti l'ago tra costo, privacy e qualità a seconda del task. Lo schema qui sotto è la mappa mentale di tutto il tutorial.

Il router sceglie il provider in base a costo, privacy e difficoltà del task.

✅ Prerequisiti: cosa ti serve prima di iniziare

Prima di partire servono quattro cose. Non spaventarti: si installano in pochi minuti e una — la chiave cloud — è opzionale se vuoi restare al 100% in locale.

• Node.js 18+: i due strumenti si installano via npm. Verifica con `node -v`.
• Claude Code: l'interfaccia da terminale di Anthropic (la installiamo al passo 2).
• Ollama: il motore che fa girare i modelli in locale.
• Una API key cloud (Anthropic e/o OpenAI): serve solo per i backend nel cloud.

# Node.js deve essere installato (versione 18 o superiore)
$ node -v
v20.11.0

# questi due li installiamo al passo 1 e 2, poi verificherai con:
$ ollama --version
$ claude --version

1️⃣ Installare Ollama e scaricare un modello locale

Ollama è il motore che fa girare i modelli sul tuo computer. Si installa con un comando e poi si scarica un modello da coding che supporti le function call (servono a Claude Code per usare gli strumenti). Una buona scelta è qwen2.5-coder.

L'inferenza gira sul tuo hardware: zero token da pagare e dati che non escono dalla macchina. La resa dipende dalla RAM/GPU: con 16 GB giri comodo i modelli da 7-8B.

# 1) installa Ollama (macOS/Linux). Su Windows usa l'installer dal sito
$ curl -fsSL https://ollama.com/install.sh | sh

# 2) scarica un modello da coding con tool calling
$ ollama pull qwen2.5-coder

# 3) avvia il server (di solito parte da solo)
$ ollama serve   # endpoint: http://localhost:11434

# 4) prova al volo
$ ollama run qwen2.5-coder "scrivi una funzione fizzbuzz in TypeScript"

2️⃣ Installare Claude Code e il Claude Code Router

Ora i due pezzi software. Prima Claude Code (l'interfaccia di Anthropic), poi il Claude Code Router — il proxy della community, comando `ccr`, che intercetta le richieste e le instrada. Si installano entrambi con npm, a livello globale.

# Claude Code (l'interfaccia da terminale di Anthropic)
$ npm install -g @anthropic-ai/claude-code

# Claude Code Router (il proxy che instrada le richieste)
$ npm install -g @musistudio/claude-code-router

# verifica che il comando 'ccr' sia disponibile
$ ccr -v

3️⃣ Creare e capire il config.json

Tutta la logica vive in un unico file: ~/.claude-code-router/config.json. Ha due sezioni che contano. Providers elenca i backend disponibili (Ollama in locale, Anthropic e OpenAI nel cloud), ognuno con il suo endpoint, la chiave e i modelli. Router decide quale provider usare per ogni tipo di task.

La regola d'oro sulle chiavi: non scriverle in chiaro. Il router supporta le variabili d'ambiente con la sintassi `$NOME_VARIABILE`, così i segreti restano fuori dal file. Lo schema qui sotto è il config annotato, punto per punto.

Quattro punti chiave: provider locale, provider cloud con chiave sicura, e due regole di routing.

📋 Il config.json completo (da copiare)

Ecco una configurazione minima ma completa con i tre backend del tutorial. Salvala in ~/.claude-code-router/config.json, sostituisci i modelli con quelli che hai scaricato/abilitato e ricordati di esportare le chiavi cloud come variabili d'ambiente.

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen2.5-coder:latest"]
    },
    {
      "name": "anthropic",
      "api_base_url": "https://api.anthropic.com/v1/messages",
      "api_key": "$ANTHROPIC_API_KEY",
      "models": ["claude-sonnet-4", "claude-opus-4-1"],
      "transformer": { "use": ["Anthropic"] }
    },
    {
      "name": "openai",
      "api_base_url": "https://api.openai.com/v1/chat/completions",
      "api_key": "$OPENAI_API_KEY",
      "models": ["gpt-5", "gpt-5-mini"]
    }
  ],
  "Router": {
    "background": "ollama,qwen2.5-coder:latest",
    "default": "anthropic,claude-sonnet-4",
    "think": "anthropic,claude-opus-4-1",
    "longContext": "openai,gpt-5",
    "longContextThreshold": 60000
  }
}

4️⃣ Le regole di routing: quale task a quale modello

La sezione Router è il cuore dell'orchestratore. A ogni tipo di richiesta assegni un provider e un modello, nella forma `provider,modello`. Claude Code etichetta da solo le richieste, e il router le smista.

La strategia che consigliamo: i task minori in locale, quelli difficili nel cloud. Così tieni basso il costo e proteggi i dati sui lavori ripetitivi, e chiami il cloud solo quando serve davvero la qualità.

• background: task minori e in sottofondo → Ollama in locale, a costo zero.
• default: il lavoro quotidiano → Claude Sonnet nel cloud (o locale, se preferisci).
• think: ragionamento e Plan Mode → un modello forte come Claude Opus.
• longContext: oltre ~60K token → un modello cloud con finestra ampia (qui gpt-5).

Cambi una riga del config e sposti l'ago tra costo, privacy e qualità.

5️⃣ Avviare il router con ccr code

Tutto pronto: si parte. Invece di `claude`, lanci `ccr code` — apri Claude Code esattamente come sempre, ma ogni richiesta passa dal router (in ascolto su `127.0.0.1:3456`). La status line mostra quale modello sta lavorando in quel momento.

Due comandi utili: `ccr ui` apre un'interfaccia web per modificare il config senza toccare il JSON a mano, e `ccr restart` riavvia il servizio (serve dopo ogni modifica al file).

La status line tiene sotto controllo modello attivo, contesto e costo della sessione.

6️⃣ Aggiungere Codex / OpenAI (e usarlo come fallback)

Per avere anche OpenAI/Codex come backend basta il provider `openai` che hai già nel config. Esporti la chiave una volta (come variabile d'ambiente) e lo instradi dove vuoi: tipicamente sul contesto lungo o come fallback quando un altro provider non risponde.

Nota utile: anche la Codex CLI di OpenAI può fare il percorso inverso — puntarla a Ollama per girare in locale — impostando le sue variabili di base URL su un endpoint compatibile. Il principio dell'orchestratore vale in entrambe le direzioni.

# 1) esporta la chiave una volta sola (mettila nel tuo ~/.zshrc)
$ export OPENAI_API_KEY="sk-..."

# 2) il provider openai è già nel config.json (modelli gpt-5)
#    nella sezione Router lo usi per longContext o come fallback

# 3) oppure forzalo al volo dentro Claude Code
$ ccr code
> /model openai,gpt-5

7️⃣ Cambiare modello al volo e verificare il routing

Dentro Claude Code puoi cambiare backend senza riavviare con il comando `/model provider,modello`. Per gestire provider e modelli da terminale c'è `ccr model`, mentre `ccr restart` applica le modifiche al config.

Per essere sicuro che le richieste vadano dove vuoi, tieni d'occhio il log del router: ci trovi le decisioni di instradamento, una per una.

# cambia modello al volo dentro Claude Code
> /model ollama,qwen2.5-coder:latest   # locale, 0 token
> /model anthropic,claude-sonnet-4     # cloud, qualità

# gestione interattiva di provider e modelli
$ ccr model

# dopo ogni modifica al config, riavvia il servizio
$ ccr restart

# controlla dove sono finite le richieste
$ tail -f ~/.claude-code-router/claude-code-router.log

🔁 Alternativa: LiteLLM come gateway

Il Claude Code Router è perfetto per restare dentro Claude Code. Se invece ti serve un gateway condiviso da più applicazioni — con load balancing, fallback automatico e log dei consumi — la scelta tipica è LiteLLM: un proxy open-source con interfaccia OpenAI-compatibile.

Il meccanismo è lo stesso: definisci i modelli (locali e cloud) in un file, avvii il proxy e punti i tuoi strumenti al suo endpoint. Con Claude Code basta impostare `ANTHROPIC_BASE_URL`.

# config.yaml di LiteLLM: stesso scopo, gateway OpenAI-compatibile
model_list:
  - model_name: local-coder
    litellm_params:
      model: ollama/qwen2.5-coder
      api_base: http://localhost:11434
  - model_name: cloud-claude
    litellm_params:
      model: anthropic/claude-sonnet-4

# avvia il proxy e punta Claude Code al suo endpoint
$ litellm --config config.yaml   # http://localhost:4000
$ export ANTHROPIC_BASE_URL=http://localhost:4000

⚖️ Quando conviene: costo, privacy, qualità

L'orchestratore non è un vezzo tecnico: è il modo per pagare il cloud solo quando serve e tenere in casa tutto il resto. Ecco come decidiamo noi cosa mandare dove.

🗓️ Bonus: schedulare i task pesanti negli orari di morbida

Un orchestratore dà il meglio quando lo abbini allo scheduling: i task pesanti e non urgenti — un refactor esteso, la generazione dei test su tutto il repo — puoi rimandarli alla notte, quando le API costano meno e nessuno aspetta la risposta. È lo stesso principio dei job pianificati a calendario.

Bastano un cron sul tuo computer o una GitHub Action che lancia `ccr code` in modalità non interattiva. Instradi quei job sul provider che preferisci — Ollama in locale a costo zero, oppure il cloud negli orari di morbida — e al mattino trovi il lavoro già fatto, pronto per la revisione umana.

• Cron locale: `0 2 * * *` lancia il job alle 2:00, instradato dal router.
• GitHub Actions: imposta `NON_INTERACTIVE_MODE: true` per gli ambienti CI/CD.
• Off-peak: meno costo e nessuna coda; il merge resta sempre una decisione umana.

Cron o GitHub Action lanciano il router di notte: meno costo, e al mattino il lavoro è pronto.

🧩 Checklist finale e prossimi passi

Ricapitoliamo il percorso in sette mosse. Se le hai seguite, ora hai un orchestratore funzionante che instrada i prompt tra locale e cloud — e puoi affinarlo quando vuoi cambiando una riga del config.

Altri articoli del blog