Utilizzo di Ollama con Claude Code: Guida di configurazione di modelli locali

Claude Code è l’agente ufficiale per la programmazione da terminale di Anthropic e, per impostazione predefinita, comunica con l’API cloud di Anthropic. Ollama è invece un’esecutore locale di modelli che espone un’API HTTP compatibile con OpenAI. I due sistemi non parlano lo stesso protocollo di default, quindi il loro abbinamento richiede un piccolo livello proxy in grado di tradurre l’API Messages di Anthropic nell’API chat di Ollama. Questa guida spiega come funziona tale integrazione, quali modelli vale la pena eseguire e in quali casi la configurazione presenta limitazioni.

Perché Ollama e Claude Code non si connettono direttamente

Claude Code invia richieste nel formato dell’API Messages di Anthropic (/v1/messages), con campi specifici di Anthropic per l’uso degli strumenti, il controllo della cache e i prompt di sistema. Ollama espone invece un endpoint /api/chat e un endpoint compatibile con OpenAI /v1/chat/completions . Nessuno dei due parla il "dialetto" di Anthropic. Per collegarli è necessario un proxy che:

• Accetti richieste nel formato Anthropic su un endpoint HTTPS.
• Le riscriva nel formato OpenAI per le completazioni chat.
• Le inoltri a Ollama, quindi traduca le risposte in streaming e le chiamate agli strumenti nel flusso di eventi Anthropic atteso da Claude Code.

Due progetti gestiscono questa integrazione in modo affidabile al 2026: claude-code-router (un router appositamente progettato per Claude Code, che supporta Ollama, OpenRouter e altri backend) e LiteLLM (un proxy generico dotato di una modalità anthropic pass-through). Entrambi funzionano; claude-code-router ha meno componenti se Ollama è l’unico backend che intendi utilizzare.

Prerequisiti

• Ollama installato ed in esecuzione. Consulta come installare Ollama se ancora non lo hai installato.
• Claude Code installato (npm install -g @anthropic-ai/claude-code).
• Almeno un modello con capacità di programmazione scaricato localmente.
• Node.js 18+ per claude-code-router, oppure Python 3.10+ per LiteLLM.

Verifica che Ollama sia raggiungibile con:

curl http://localhost:11434/api/tags

Scelta di un modello locale

Claude Code fa ampio uso di strumenti, modifiche strutturate e ragionamento su contesti lunghi. Modelli più piccoli, pensati per conversazioni generali, gestiscono questi compiti in modo scadente. Prediligi modelli specificatamente ottimizzati per la programmazione o modelli di istruzione di grandi dimensioni.

Modello (tag Ollama)	Dimensioni notevoli	VRAM approssimativa (Q4)	Note
qwen3-coder	30B (A3B MoE), 480B (A35B MoE)	~18 GB (30B); la variante 480B è adatta solo a server	Linea di modelli per la programmazione del team Qwen; eccellente nell’uso agente degli strumenti.
deepseek-coder-v2	16B, 236B	~10 GB (16B lite)	Completamenti e refactoring solidi; la variante 236B è riservata ai server.
llama3.1	8B, 70B	~5 GB / ~40 GB	Modello generico di istruzione; la variante 70B rappresenta un valido sostituto di Claude, purché tu disponga della VRAM necessaria.
qwen2.5-coder	7B, 14B, 32B	~5 / ~9 / ~20 GB	Ancora molto utilizzato; precede qwen3-coder ma è estremamente stabile.

Il livello di quantizzazione, la lunghezza del contesto e le dimensioni della cache KV influenzano tutti i requisiti di VRAM. Usa il Calcolatore VRAM per calcolare le risorse necessarie per una configurazione specifica e consulta i migliori modelli linguistici locali per Ollama per un confronto più ampio.

Esegui questo comando prima di configurare il proxy:

ollama pull qwen3-coder:30b
ollama pull deepseek-coder-v2:16b

Opzione 1: claude-code-router

claude-code-router è la soluzione più rapida. Installalo globalmente:

npm install -g @musistudio/claude-code-router

Crea ~/.claude-code-router/config.json:

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen3-coder:30b", "deepseek-coder-v2:16b"]
    }
  ],
  "Router": {
    "default": "ollama,qwen3-coder:30b",
    "background": "ollama,deepseek-coder-v2:16b"
  }
}

Avvia Claude Code tramite il router:

ccr code

Il router avvia un endpoint locale compatibile con Anthropic, imposta automaticamente le variabili d'ambiente per Claude Code e instrada il traffico verso Ollama. I nomi esatti dei campi di configurazione possono variare tra versioni minori: controlla il README del progetto se una chiave viene rifiutata.

Opzione 2: Proxy LiteLLM

Se utilizzi già LiteLLM per altri servizi, riutilizzalo. Crea config.yaml:

model_list:
  - model_name: claude-sonnet-4
    litellm_params:
      model: ollama_chat/qwen3-coder:30b
      api_base: http://localhost:11434
  - model_name: claude-haiku-4
    litellm_params:
      model: ollama_chat/deepseek-coder-v2:16b
      api_base: http://localhost:11434

Avvialo:

litellm --config config.yaml --port 4000

Quindi indirizza Claude Code verso il proxy (vedi la sezione successiva). LiteLLM gestisce automaticamente la traduzione da Anthropic a Ollama sul percorso /anthropic .

Configurare Claude Code per puntare al proxy

Claude Code legge due variabili d'ambiente per reindirizzare il proprio traffico API. Impostale nella tua shell prima di eseguire claude.

macOS e Linux

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-anything"
claude

Aggiungile a ~/.zshrc o ~/.bashrc per renderle persistenti. Il valore della chiave non viene utilizzato dal proxy locale, ma Claude Code rifiuta di avviarsi se non è impostato.

Windows (PowerShell)

$env:ANTHROPIC_BASE_URL="http://localhost:4000"
$env:ANTHROPIC_API_KEY="sk-anything"
claude

Per renderle persistenti tra le sessioni, usa [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "http://localhost:4000", "User"). Se Claude Code è installato tramite WSL, configura le variabili all'interno della shell WSL — Ollama in esecuzione su Windows è raggiungibile da WSL all'indirizzo http://host.docker.internal:11434 o all'IP dell'host Windows.

Windows (nativo, senza WSL)

Claude Code supporta ufficialmente macOS, Linux e WSL. Il supporto nativo per Windows è storicamente instabile; eseguilo invece su WSL2, a meno che tu non abbia verificato che la versione corrente funzioni correttamente sul tuo sistema.

Configurazione del contesto e dei timeout

Claude Code presuppone un contesto di 200K token e un tempo molto breve per il primo token. I modelli locali non soddisferanno né l'uno né l'altro requisito. Due parametri critici richiedono attenzione:

• Lunghezza del contesto in Ollama. Impostala esplicitamente per ogni modello tramite un Modelfile (PARAMETRO num_ctx 32768) o tramite la variabile d'ambiente OLLAMA_CONTEXT_LENGTH sul server Ollama. La lunghezza predefinita del contesto è ridotta e troncherà silenziosamente conversazioni lunghe.
• VRAM dedicata alla cache KV. Un contesto da 32K token su un modello da 30B consuma diversi GB di VRAM solo per la cache KV. Controlla l'utilizzo totale della memoria con ollama ps.

Per una panoramica completa dei requisiti di memoria a diverse lunghezze di contesto, vedi Requisiti VRAM per modello.

Limitazioni note

• L'uso degli strumenti è fragile. Gli strumenti di Claude Code per la modifica di file, l'esecuzione di comandi bash e la ricerca dipendono da output JSON rigorosamente conformi per le chiamate agli strumenti. I modelli locali falliscono più spesso in questo aspetto, generando chiamate malformate o immaginando contenuti di file. qwen3-coder e deepseek-coder-v2 sono tra i più affidabili, ma nessuno dei due eguaglia le prestazioni di Claude Sonnet.
• La cache dei prompt non ha effetto. di Anthropic I campi vengono ignorati dal proxy. I prompt di sistema lunghi vengono inviati nuovamente ad ogni turno.
• Velocità. Anche su una GPU da 24 GB, un modello da 30B con contesto da 32K genera 15–40 token/sec. Il ciclo agente di Claude Code effettua numerose chiamate per ogni attività, quindi il tempo reale può risultare 5–10 volte superiore rispetto all'API cloud.
• Sotto-agenti e MCP. Le funzionalità avanzate di Claude Code (agenti in background, server MCP) funzionano generalmente ancora, poiché passano tutte attraverso lo stesso proxy; tuttavia, qualsiasi funzionalità che dipenda da comportamenti specifici del server Anthropic potrebbe interrompersi in modo silenzioso.

Quando utilizzare questa configurazione rispetto all’API cloud

Utilizzare Claude Code in locale ha senso quando: il codice non può lasciare la tua rete, sei soggetto a un budget API limitato e devi eseguire refactoring massivi, oppure stai sperimentando l'auto-hosting. Ha invece meno senso per un utilizzo quotidiano nell'attività di programmazione basata su agenti, dove la capacità di ragionamento alla pari di Sonnet è l'obiettivo principale.

Per decidere numericamente, calcola i costi e i benefici di entrambe le opzioni. Lo strumento Calcolatore costi API stima la spesa mensile su Anthropic, mentre quello Calcolatore del break-even self-hosting vs API confronta tale costo con l'ammortamento della GPU. Per la maggior parte degli sviluppatori singoli, l'API risulta più conveniente; per i team che ne fanno un uso intensivo, un server locale condiviso può ripagarsi entro un anno. Se stai definendo le specifiche di tale server, la guida migliori GPU per LLM locali copre l'attuale fascia di prestazioni.

Alternative a Ollama per questo flusso di lavoro

Se le prestazioni di Ollama risultano limitanti, altri runtime con API compatibili con OpenAI funzionano in modo identico dietro lo stesso proxy: LM Studio, vLLM e il server di llama.cpp sono tutti compatibili. Consulta guida LM Studio per un'opzione orientata all'interfaccia grafica, oppure Guida completa di Ollama for a deeper look at Ollama itself.

Domande frequenti

Claude Code può utilizzare Ollama senza un proxy?

No. Claude Code comunica tramite l'API Messages di Anthropic e Ollama non implementa questo protocollo. È necessario uno strato di traduzione, come claude-code-router o LiteLLM. Impostare ANTHROPIC_BASE_URL direttamente su http://localhost:11434 fallirà già alla prima richiesta.

Quale modello locale si avvicina di più a Claude Sonnet per la programmazione?

Alle dimensioni che la maggior parte degli utenti riesce effettivamente a eseguire, qwen3-coder (30B MoE) e deepseek-coder-v2 (16B lite) sono attualmente le scelte migliori. Nessuno dei due eguaglia Sonnet nei compiti agentic multi-file, ma entrambi sono utilizzabili per modifiche monofile, completamenti e revisione del codice. Confronta i punteggi di intelligenza su Classifica LLM.

La cache dei prompt funziona con Ollama dietro Claude Code?

No. La cache dei prompt di Anthropic è una funzionalità lato server dell’API. I proxy rimuovono o ignorano i campi I campi , quindi ogni richiesta elabora nuovamente l’intero prompt di sistema e la cronologia della conversazione. Questo è uno dei motivi per cui le configurazioni locali sembrano più lente per turno rispetto all’API cloud, anche con un throughput di token grezzo simile.

Quanta VRAM mi serve per un’esperienza soddisfacente?

Una singola GPU da 24 GB (classe RTX 3090/4090/5090) esegue un modello coder da 30B in quantizzazione Q4 con un contesto di circa 32K token. Per modelli da 70B o contesti più lunghi, prevedi almeno 48 GB (RTX 6000 Ada, due RTX 3090) o più. Usa il Calcolatore VRAM per ottenere cifre precise relative a ciascun modello e livello di quantizzazione.

Posso combinare modelli locali e cloud nella stessa sessione di Claude Code?

Sì, tramite un router. claude-code-router ti permette di assegnare modelli diversi a ruoli diversi — ad esempio, Sonnet cloud come agente principale e un modello locale per attività secondarie o completamenti. Ciò può ridurre notevolmente i costi API mantenendo comunque un’elevata qualità sul percorso critico.

Esiste un modo ufficiale supportato da Anthropic per eseguire Claude Code in locale?

No. Anthropic distribuisce Claude Code come client per la propria API e non rilascia i pesi di Claude. Tutte le configurazioni locali sono proxy comunitari che puntano a modelli di terze parti. Se Anthropic modifica l’API Messages, i proxy potrebbero richiedere aggiornamenti prima che Claude Code torni a funzionare correttamente con essi.