Usa Ollama in Claude Code e Cursor (modelli locaux)

#Perché usare Ollama in Claude Code o Cursor?

Tre ragioni che tornano sempre. Prima la riservatezza: un progetto per un cliente coperto da un NDA, codice proprietario, segreti in chiaro nei file — niente di tutto questo dovrebbe essere inviato a terzi. Poi il costo: Cursor Pro costa 20 $/mese, Claude Code consuma token Anthropic la cui spesa arriva rapidamente a 50-100 $/mese con un uso intensivo. Con Ollama, il costo è zero dopo l'acquisto della GPU. Infine la resilienza: il tuo assistente non si ferma quando l'API di Anthropic ha un problema o quando la tua connessione ADSL si interrompe.

Il compromesso è onesto: un Qwen3-Coder 30B in locale non eguaglia Claude Sonnet 4.6 o GPT-5 nei compiti complessi svolti da agenti su più file. Ma per l'80% degli usi quotidiani — completare, rifattorizzare, scrivere un test, spiegare un blocco, generare un commit — un modello per il codice da 9 a 30B in Q4 svolge il lavoro più che adeguatamente. E puoi sempre mantenere il cloud in parallelo per i compiti più impegnativi.

#L'endpoint di Ollama compatibile con OpenAI

Dalla versione 0.1.24, Ollama espone, oltre alla sua API nativa, un endpoint compatibile con l'API OpenAI ChatCompletions. È questo a rendere possibile tutto il resto: qualsiasi client OpenAI (SDK Python, SDK Node, Cursor, Cline, Aider, Continue, ecc.) può comunicare con Ollama senza modifiche, semplicemente cambiando l'URL di base.

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-coder:30b",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

Il formato della risposta è identico a quello di OpenAI: choices[0].message.content, usage con prompt_tokens e completion_tokens, supporto dello streaming tramite stream: true. La chiave API viene ignorata — puoi inviare qualsiasi cosa nell'header Authorization, Ollama l'accetta. Molti client, però, rifiutano un campo vuoto: inserisci ollama o anything per accontentarli.

#Prerequisiti

Ollama 0.5+

ollama --version deve rispondere. Su Windows, l'icona nell'area di notifica deve essere attiva. Se parti da zero, consultare la guida all'installazione di Ollama per il tuo sistema operativo.

GPU con 12 GB di VRAM o Mac M-series 16 GB+

Un Qwen 3.5 9B Q4 = circa 6,6 GB, un Devstral 24B Q4 = circa 14 GB, un Qwen3-Coder 30B-A3B Q4 = circa 19 GB. RTX 3060 12 GB = soglia minima utile (Qwen 3.5 9B); RTX 4070/4080 16 GB o Mac M3/M4 = Devstral 24B e Qwen3-Coder 30B interamente caricati.

Cursor 0.40+ o Claude Code CLI

Cursor dal sito cursor.com (modalità OpenAI custom integrata). Claude Code tramite npm install -g @anthropic-ai/claude-code.

Minima familiarità con le variabili d'ambiente

Per Claude Code, si utilizzeranno ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN.

#1. Collega Cursor a Ollama

Cursor ha un'opzione ufficiale per collegarsi a un endpoint compatibile con OpenAI. Funziona molto bene per la chat (Ctrl+L) e l'editing inline (Ctrl+K). L'agente Composer e il completamento automatico Tab, invece, restano vincolati ai modelli cloud di Cursor — è una limitazione del prodotto che Anthysphere accetta esplicitamente.

1. 01
   Scaricare un modello per la programmazione

   Con 12 GB di VRAM, Qwen 3.5 9B (qwen3.5:9b) è un ottimo punto di partenza: se la cava discretamente in francese, supporta il tool calling e offre 256k di contesto. Con 16 GB, passa a Devstral 24B (devstral:24b); con 24 GB, a Qwen3-Coder 30B-A3B (qwen3-coder:30b), il MoE di riferimento per il codice.
2. 02
   Aprire le impostazioni di Cursor

   Ctrl+Shift+J (Cmd+, su Mac) → scheda Models. Vedi l'elenco dei modelli Cursor (claude-3.5-sonnet, gpt-5, ecc.) con degli interruttori.
3. 03
   Aggiungere un modello personalizzato

   Fai clic su Add Model in basso. Inserisci il nome esatto del modello Ollama: qwen3-coder:30b. Seleziona la casella per attivarlo.
4. 04
   Configurare l'URL base

   Nella sezione OpenAI API Key, espandi Override OpenAI Base URL. Inserisci http://localhost:11434/v1, poi clicca su Save. Per API Key, inserisci un valore qualsiasi (ollama basta): Cursor non accetta un campo vuoto.
5. 05
   Verificare la connessione

   Fai clic su Verify. Cursor invia una richiesta di test alla tua istanza di Ollama. Se Ollama risponde con il codice 200, il pulsante diventa verde e il modello appare nel selettore della chat.

ollama pull qwen3-coder:30b

Una volta completata la configurazione, la chat di Cursor (Ctrl+L) e l'editing inline (Ctrl+K) funzionano con il tuo modello locale. Il selettore del modello in alto nel pannello della chat elenca qwen3-coder:30b; i modelli cloud di Cursor restano accessibili se vuoi passare occasionalmente a uno di essi.

#2. Collega Claude Code a Ollama

Claude Code (la CLI di Anthropic) usa nativamente l'API Messages di Anthropic, non l'API Chat Completions di OpenAI. I due protocolli differiscono (ruoli, formato delle chiamate agli strumenti, streaming). Per far dialogare Claude Code con Ollama serve quindi un piccolo traduttore — un proxy che riceve richieste nel formato Anthropic Messages da un lato e le invia nel formato OpenAI Chat Completions dall'altro.

Il progetto di riferimento per questo si chiama claude-code-router (musistudio/claude-code-router su GitHub). Si installa con un comando, funziona localmente su una porta e accetta regole di routing per modello (es.: inviare haiku a Ollama, sonnet al vero Claude).

1. 01
   Installare Claude Code

   npm install -g @anthropic-ai/claude-code se non è già stato fatto. claude --version deve restituire una risposta.
2. 02
   Installare claude-code-router

   npm install -g @musistudio/claude-code-router. Le binaire ccr est ajouté au PATH.
3. 03
   Pull del modello su Ollama

   Preferisci un modello che supporti le chiamate agli strumenti: qwen3-coder:30b, devstral:24b o glm-4.7-flash. Senza questo supporto, Claude Code non potrà chiamare i suoi strumenti interni (Read, Edit, Bash, ecc.) e perde il 90% della sua utilità.
4. 04
   Configurare il router

   Crea ~/.claude-code-router/config.json con una voce Providers che punti a Ollama e una regola Router che associ i modelli Claude al tuo modello locale.
5. 05
   Avviare tramite ccr

   ccr code al posto di claude. Il wrapper avvia il proxy in background, esporta ANTHROPIC_BASE_URL in modo che punti al proxy, poi avvia Claude Code. Al suo interno, /model permette di passare da una route all'altra.

ollama pull qwen3-coder:30b
# ou pour du pur agent de code
ollama pull devstral:24b

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

ccr code
# Claude Code démarre, mais les requêtes filent vers Ollama
# Vérifier : /model affiche qwen3-coder:30b

Approccio minimalista senza router: puoi anche esportare direttamente ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN impostandoli per un proxy compatibile con Anthropic (LiteLLM in modalità --anthropic o y-router sono esempi di questi proxy). È più leggero, ma non offre la flessibilità delle regole per singola attività.

#3. Quale modello per programmare scegliere: Qwen3-Coder vs Devstral in locale

Su Ollama, alcune famiglie dominano nell'ambito del codice nell'estate 2026: Qwen3-Coder (Alibaba), Devstral (Mistral AI) e i modelli MoE versatili come GLM 4.7 Flash (Z.ai) o gpt-oss (OpenAI). Tutte sono open-weight e funzionano in Q4 su hardware di largo consumo.

Qwen3-Coder 30B-A3B (Alibaba, Apache 2.0)

Il modello di riferimento versatile nel 2026. Supporto solido per il tool calling, multilingue (francese corretto), buono in Python/JS/Go/Rust, 256k di contesto. È un MoE con 3B attivi: veloce come un modello denso da 14B, con la qualità di un modello da 30B. ≈ 19 GB in Q4. Pull: qwen3-coder:30b.

Devstral 24B (Mistral AI, Apache 2.0)

Pensato specificamente per gli agenti SWE (modifica di più file, navigazione della codebase). Eccellente in Aider, OpenHands e — per estensione — Claude Code. Modello denso da 24B ≈ 14 GB in Q4, entra in 16 GB. Pull: devstral:24b.

GLM 4.7 Flash (Z.ai, MIT) / gpt-oss 20B (OpenAI)

Due MoE molto performanti in modalità agente. GLM 4.7 Flash (30B-A3B, ≈ 19 GB) è un eccellente orchestratore di chiamate a strumenti; gpt-oss 20B (≈ 14 GB, MXFP4, 131k di contesto) è più veloce e si può caricare su 16 GB. Pull: glm-4.7-flash o gpt-oss:20b.

Qwen 3.5 9B (alternativa di ripiego per GPU da 8-12 GB)

Solo 6,6 GB, un modello generalista valido nella programmazione, con 256k di contesto e capacità di visione. Una buona alternativa quando la VRAM è limitata, prima di passare ai modelli da 24B in su. Pull: qwen3.5:9b.

VRAM per dimensione in Q4_K_M (la quantizzazione consigliata): 7B ≈ 5 GB, 14B ≈ 9 GB, 24B ≈ 14 GB, 32B ≈ 19 GB, 70B ≈ 40 GB. Il contesto consuma memoria in aggiunta: prevedi da 2 a 4 GB in più per 32k token di contesto, a seconda del modello.

#Limiti rispetto al cloud: dove i modelli locali restano indietro

Siamo onesti su ciò che i modelli locali non fanno altrettanto bene di Claude Sonnet 4.6 o GPT-5:

Finestra di contesto

Per impostazione predefinita, Ollama limita num_ctx a 4096 token; si può arrivare a 32k o persino a 128k a seconda del modello, ma consumando più VRAM. Cursor con Sonnet nel cloud gestisce 200k token senza problemi. In un grande monorepo, il modello nel cloud legge tutto, quello locale deve scegliere.

Ragionamento a più fasi

Un modello da 9-14B si perde quando l'agente concatena 10 chiamate a strumenti con dipendenze tra loro. Sonnet mantiene il filo. Per un'orchestrazione di agenti davvero complessa, il cloud resta in vantaggio — e di gran lunga.

Conoscenza delle API più recenti

I modelli open-weight hanno una data limite delle conoscenze (spesso il 2025) e non conoscono le API uscite successivamente. Cursor nel cloud beneficia dell'aggiornamento continuo e degli strumenti di ricerca web.

Latenza first-token

Paradossalmente, il cloud può essere più rapido all'avvio (nessun caricamento del modello). In locale, il modello resta caricato tra una chiamata e l'altra — dopo il primo prompt, il vantaggio torna alla soluzione locale.

Costo dell'elettricità

Una RTX 4090 sotto carico consuma 350 W. 8 ore al giorno di programmazione intensiva = ~70 kWh/mese = ~15 € in Francia. Il costo resta molto inferiore ai 20 $/mese di Cursor + 50 $/mese di Claude, ma non è gratis.

#Suggerimenti e risoluzione dei problemi

Cursor restituisce "OpenAI API key invalid"

Il campo API Key deve contenere un valore non vuoto. Metti ollama, sk-anything o qualcosa di plausibile. È solo un aspetto estetico: Ollama ignora l'intestazione.

Cursor non vede il modello

Il nome del modello in Cursor (Add Model) deve essere ESATTAMENTE quello restituito da ollama list (tag incluso, ad esempio qwen3-coder:30b). Non qwen3-coder da solo, né Qwen3 Coder.

Claude Code entra in un ciclo o chiede di nuovo la stessa cosa

Spesso il modello locale sbaglia le chiamate agli strumenti. Verifica che il modello supporti il function calling (ollama show qwen3-coder:30b → cerca la voce tools nelle capabilities). Passa a un modello più grande o semplifica il compito.

Risposte troncate dopo 2-3 frasi

num_ctx predefinito = 4096. Per Claude Code e Cursor con il contesto della base di codice, porta il valore a 16384 o 32768. Con Ollama: crea un Modelfile personalizzato con PARAMETER num_ctx 32768 ed esegui ollama create coder-32k -f Modelfile. Il costo in memoria è reale (+ 2-4 GB per la cache KV).

VRAM esaurita, OOM

Controlla ollama ps durante l'uso. Se vedi >100% loaded nella ripartizione GPU/CPU, il modello viene caricato in parte nella RAM di sistema e diventa molto lento. Soluzioni: quantizzazione più aggressiva (Q3_K_M), modello più piccolo o riduzione di num_ctx.

Latenza > 5 s per risposta

O il modello viene eseguito in parte sulla CPU (vedi il punto precedente), oppure Ollama ricarica il modello a ogni richiesta. Controlla OLLAMA_KEEP_ALIVE (valore predefinito: 5 min). Imposta OLLAMA_KEEP_ALIVE=2h per mantenere il modello caricato e pronto.

#Per approfondire

Hai Ollama che mette un modello per il codice a disposizione di Cursor o Claude Code. I passi successivi più naturali:

Completare nell'editor (FIM inline)

La guida «Copilot gratuito in locale» spiega come installare Continue.dev / Tabby / CodeGeeX per il completamento inline in stile Copilot, un complemento naturale alla chat in Cursor.

Scegliere la quantizzazione giusta

Q4_K_M, Q5_K_M, Q8_0: la guida Scegliere la quantizzazione confronta la perdita di qualità effettiva sui modelli di codice e spiega quando un Q3 rimane utilizzabile.

Personalizzare un modello per la programmazione

La guida Personalizzare un modello con Ollama Modelfile mostra come impostare num_ctx, il prompt di sistema e la temperatura per ottenere un modello di programmazione su misura per il tuo stack.