Come usare Ollama con il tuo coding agent

Cosa stai collegando

Puoi usare Ollama con il tuo coding agent. La configurazione richiede meno modifiche di quanto si pensi. Devi cambiare un solo URL di base e scegliere il nome di un modello. Il campo della chiave API richiede comunque un valore, ma il server locale lo ignora, quindi puoi inserire una stringa qualsiasi.

Ollama è in ascolto sulla porta 11434 e fornisce contemporaneamente tre superfici API. /api è l'API nativa di Ollama. /v1 è il livello compatibile con OpenAI, che a sua volta supporta diverse modalità: /v1/chat/completions, /v1/responses, /v1/completions, /v1/models e /v1/embeddings. La documentazione di Ollama indica che la chiave è obbligatoria, ma viene ignorata. La terza superficie è compatibile con Anthropic: il client usa http://localhost:11434 come URL di base e aggiunge /v1/messages, che è il formato usato da Claude Code. La maggior parte degli agent usa /v1/chat/completions, Codex usa /v1/responses e Claude Code usa /v1/messages. Il tuo agent supporta già una di queste modalità, quindi non devi modificarne altro.

Questa configurazione richiede cinque minuti. L'utilizzabilità del risultato dipende da due impostazioni che quasi nessuno modifica: la lunghezza del contesto e il keep-alive. Dipende anche dall'assegnare al modello il tipo di attività per cui è adatto. Ognuno di questi aspetti ha una sezione dedicata. I limiti reali sono descritti alla fine.

Quali agent di coding accettano un base URL locale

La verifica consiste in una sola domanda: lo strumento espone un'impostazione per il base URL? Se sì, può comunicare con il tuo server.

Ollama pubblica pagine di integrazione per Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, gli IDE JetBrains e VS Code. Aider documenta separatamente il proprio supporto per Ollama. Questo copre la maggior parte degli strumenti che, a ottobre 2026, rientrano nella definizione di coding agent. Non utilizzano tutti lo stesso formato, e proprio questa differenza causa i problemi di configurazione.

• La maggior parte degli agent richiede un endpoint compatibile con OpenAI. Imposta il base URL su http://localhost:11434/v1 e usa una stringa API key non vuota.
• Claude Code non accetta in alcun modo un base URL OpenAI. Utilizza l'API Anthropic Messages, quindi richiede ANTHROPIC_BASE_URL impostato su http://localhost:11434, dove Ollama espone /v1/messages.
• Codex utilizza l'API OpenAI Responses. Ollama espone anche /v1/responses, disponibile dalla versione 0.13.3.
• Un agent che non dispone di un'impostazione per il base URL non può essere reindirizzato, perché l'endpoint è incorporato nel client. Inserisci invece un livello di traduzione, ad esempio un gateway LiteLLM self-hosted, quindi riesponi il modello nel formato richiesto dal client.

Ollama può generare queste configurazioni. ollama launch opencode avvia OpenCode con una configurazione inline per il modello scelto, ollama launch claude fa lo stesso per Claude Code e ollama launch droid --config scrive la configurazione senza avviare lo strumento.

Installare Ollama e scaricare un modello in grado di usare gli strumenti

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

Il programma di installazione aggiunge un'unità systemd e la avvia, quindi systemctl status ollama dovrebbe restituire active (running). In caso contrario, journalctl -e -u ollama mostra il motivo.

Il modello deve supportare le chiamate agli strumenti, perché un agente funziona in questo modo. Legge un file, scrive una patch, esegue il test, quindi legge l'errore e riprova. Un modello che non sa generare una chiamata a uno strumento descrive la modifica in prosa invece di applicarla, e l'agente entra in un ciclo oppure si arresta. Prima di scaricarlo, cerca l'etichetta tools nella pagina del modello su ollama.com. qwen3-coder:30b la include e, a ottobre 2026, questa variante richiede un download di 19 GB e offre una finestra di contesto di 256K. Se il server usa soltanto la CPU o ha poca RAM, il calcolo della memoria per la variante Qwen 27B su un VPS mostra cosa può essere eseguito realmente con 8-64 GB, prima di avviare il download. Dopo averlo scaricato, quei gigabyte occupano il disco root del server, che in un VPS è la risorsa con meno spazio disponibile; per questo conviene leggere dove Ollama conserva i file dei modelli e come spostarli altrove prima che il disco si riempia.

Ora verifica quali nomi il server espone realmente:

curl http://localhost:11434/v1/models

Le stringhe presenti nella risposta sono quelle che devono comparire nella configurazione dell'agente, carattere per carattere. Verificarle prima risolve la maggior parte degli errori relativi a modelli non trovati. Se Ollama non è ancora installato, la procedura completa è disponibile in eseguire in self-hosting un LLM con Ollama su un VPS.

Indicare Ollama in OpenCode

Modifica ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "qwen3-coder 30b"
        }
      }
    }
  }
}

La chiave in models è il nome del modello inviato a Ollama, quindi deve corrispondere esattamente a ollama ls. Il campo name è soltanto l'etichetta mostrata nel selettore dei modelli. Avvia opencode, passa al provider Ollama e monitora journalctl -e -u ollama per verificare che la richiesta sia arrivata al tuo server, anziché a un'altra destinazione. La configurazione dell'agente è descritta in eseguire OpenCode su un VPS.

Indirizzare Claude Code a Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

ANTHROPIC_API_KEY è impostato intenzionalmente su una stringa vuota. Se nell'ambiente è presente una chiave reale, le richieste vengono invece inviate all'API in hosting: questo comporta costi e impedisce l'inferenza locale. ollama launch claude configura tutto automaticamente.

È importante sapere cosa non offre il livello di compatibilità. Non implementa tool_choice né la memorizzazione nella cache dei prompt e non dispone di un endpoint per il conteggio dei token; i numeri dei token visualizzati sono quindi approssimazioni basate sul tokenizer del modello. Claude Code include inoltre un prompt di sistema ampio e un insieme esteso di strumenti, quindi richiede più contesto rispetto a un client di chat. La questione più ampia di cosa sia possibile trasferire e cosa invece no è trattata nella sezione possibilità di self-hosting di Claude.

Indirizzare Aider verso Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

La documentazione di Aider consiglia il prefisso ollama_chat/ invece di ollama/. Consente inoltre di impostare la finestra di contesto per ogni modello in .aider.model.settings.yml. Questa opzione è utile quando un modello richiede una finestra diversa da quella predefinita dal server:

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

Perché una configurazione funzionante produce comunque risultati senza senso

Questa è la sezione più importante. Ollama sceglie la lunghezza del contesto predefinita in base alla VRAM (la memoria video della GPU) rilevata e pubblica questi valori predefiniti:

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

La maggior parte dei piani VPS, e tutti i server con sola CPU, rientrano nella prima riga: 4,096 token. Solo una GPU di grandi dimensioni consente di usare i 262,144 token dell'ultima riga.

Un agente consuma 4096 token prima di eseguire qualsiasi operazione. Il prompt di sistema, le definizioni degli strumenti, l'elenco del repository e il primo file aperto superano già questa dimensione. Da qui nasce il problema principale: non viene generato alcun errore. La documentazione di Aider specifica che Ollama elimina in modo silenzioso il contesto che supera la finestra disponibile. I token più vecchi vengono rimossi; di conseguenza, il modello risponde con sicurezza su un file che non può più vedere oppure dimentica un'istruzione fornita due passaggi prima. Questo meccanismo è alla base della maggior parte delle segnalazioni secondo cui un modello locale è troppo poco efficace per scrivere codice. Anche la scelta del valore è una decisione separata e vale la pena leggere quanto costa num_ctx in memoria della cache KV per ogni dimensione prima di stabilire il valore da usare.

La documentazione di Ollama indica che attività come gli agenti e gli strumenti di coding devono usare almeno 64000 token. Impostalo sul server:

sudo systemctl edit ollama.service

Aggiungi queste righe al file di override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Quindi ricarica la configurazione e riavvia il servizio:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps è il controllo da eseguire. Stampa una colonna CONTEXT e il relativo valore indica il contesto effettivamente ricevuto dal modello. I valori di ID e SIZE saranno diversi:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Imposta il valore sul server anziché nell'agente per due motivi. Lo schema OpenAI per il completamento delle chat non dispone di un campo per la lunghezza del contesto, quindi un client compatibile con OpenAI non può richiederne una specifica. Inoltre, l'impostazione è per server, quindi ogni agente indirizzato a quel server la eredita. Anche l'output ha un limite massimo e, a differenza della lunghezza del contesto, questo valore viene trasmesso tramite l'endpoint di compatibilità; perciò num_predict e il campo max_tokens che vi corrisponde sono le impostazioni da usare quando una risposta si interrompe a metà di una patch. Se un modello richiede una finestra diversa, incorporala in una copia tramite un Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Il contesto non è gratuito. Una finestra più ampia richiede più memoria, quindi monitora la colonna PROCESSOR. 100% GPU è il valore da raggiungere. Quando una parte del modello viene trasferita sulla CPU, la velocità di generazione dei token diminuisce al punto che il ciclo dell'agente diventa inutilizzabile; misurare i token al secondo su un LLM locale permette di individuare il limite effettivo del server. Il dimensionamento della macchina prima dell'acquisto è trattato in quanta RAM e CPU richiede un VPS per un agente di coding.

Mantieni il modello caricato tra le richieste

Per impostazione predefinita, Ollama scarica un modello 5 minuti dopo l'ultima richiesta. Questo comportamento è adatto a una casella di chat, ma non al lavoro degli agenti. Metti in pausa il lavoro per leggere un diff, il timer scade e la richiesta successiva ricarica dal disco decine di gigabyte di pesi prima che venga visualizzato il primo token. Il risultato sembra un blocco.

OLLAMA_KEEP_ALIVE accetta una stringa di durata come 10m o 24h, un semplice numero di secondi, -1 per mantenere il modello caricato indefinitamente oppure 0 per scaricarlo immediatamente. Impostalo insieme alla lunghezza del contesto:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

Il campo di richiesta keep_alive esiste solo negli endpoint nativi /api/generate e /api/chat di Ollama, non negli endpoint di compatibilità; pertanto un agente non può impostarlo per singola richiesta. La variabile d'ambiente è l'unico meccanismo disponibile. Quando devi liberare la memoria, ollama stop qwen3-coder:30b scarica il modello senza arrestare il server. Se vuoi mantenere l'impostazione dopo un riavvio, oppure vuoi valutare se conservare i pesi in memoria per tutta la giornata o recuperare quella memoria, mantenere un modello Ollama caricato in memoria funziona in entrambi i casi.

Eseguire Ollama su un server separato

Ollama si associa a localhost. Per raggiungerlo da un'altra macchina, imposta OLLAMA_HOST=0.0.0.0:11434 nello stesso override di systemd e riavvia il servizio.

Esegui questa operazione soltanto su una rete privata. La documentazione di Ollama specifica che l'API locale non richiede autenticazione. Di conseguenza, se la porta 11434 è aperta a Internet, chiunque può usare il tuo hardware e leggere tutto ciò che il tuo agent invia. Esistono due opzioni sicure. Mantieni il binding su localhost e inoltra la porta tramite SSH dal tuo laptop:

ssh -N -L 11434:localhost:11434 you@your-vps

Il tuo agent continua a puntare a http://localhost:11434/v1 e non rileva alcuna differenza. L'altra opzione consiste nell'usare una VPN, associando Ollama all'indirizzo della VPN invece che a 0.0.0.0. Se più persone o più agent devono condividere lo stesso server, lo scheduler di Ollama non è progettato per questo carico. il confronto tra Ollama e vLLM mostra da quale punto la differenza di throughput inizia a diventare significativa.

Quando un modello di coding locale è vantaggioso e quando non lo è

Un agent basato su un modello ospitato da te non sostituisce un’API frontier per ogni attività. È chiaramente vantaggioso in quattro tipi di lavoro.

• Modifiche meccaniche in massa, quando ogni cambiamento è circoscritto e puoi verificarlo. Rinomina in un repository, aggiunta di type hint, scrittura di docstring, traduzione dei commenti. Il modello può funzionare per ore senza aumentare la spesa.
• Attività per le quali i dati non devono lasciare il tuo hardware. Ad esempio, codice client coperto da un accordo di riservatezza o un repository interno che non puoi inviare a terzi.
• Macchine offline o air-gapped, sulle quali non è disponibile alcuna API ospitata da chiamare.
• Costi prevedibili. Una volta pagato il server, un agent che consuma token in un loop non comporta costi aggiuntivi. È l’opposto di un’API con tariffazione a consumo. Quando un GPU VPS raggiunge il punto di pareggio rispetto ai token API contiene i calcoli.

È meno efficace nelle attività lunghe e con più passaggi. "Individua la causa del fallimento di questo test, correggila e aggiorna i chiamanti" richiede molte chiamate corrette agli strumenti in sequenza, mantenendo l’intera cronologia nel contesto. Un modello nella fascia da 8B a 14B eseguito su un server modesto può generare una chiamata allo strumento non valida o perdere il piano dopo pochi turni. In questi casi dedichi più tempo a guidarlo di quanto ne avrebbe richiesto l’attività. Non è un problema di prompt che puoi risolvere scrivendo un prompt migliore. È un limite di capacità.

È meno efficace anche quando un errore ha conseguenze costose e non leggerai ogni riga. Assegna al modello locale attività circoscritte, il cui output puoi verificare, e conserva un modello ospitato per il lavoro che non controlleresti passo per passo.

Modalità di errore e stringhe visualizzate

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Il server non è in esecuzione oppure l'agent è configurato per un host diverso. Esegui systemctl status ollama, quindi journalctl -e -u ollama.

L'agent segnala che il modello non esiste. Il nome nella configurazione non corrisponde a un nome fornito dal server. Confrontalo con curl http://localhost:11434/v1/models e copia la stringa da lì. Il tag fa parte del nome: se nella configurazione indichi un tag che non hai mai eseguito con pull, la configurazione non funziona anche se è installato un modello simile.

L'agent risponde in prosa e non modifica mai un file. Il modello non supporta gli strumenti oppure la richiesta, insieme alle relative definizioni degli strumenti, occupa già tutta la context window. Controlla l'etichetta tools nella pagina del modello, quindi verifica la colonna CONTEXT in ollama ps.

Lunga attesa prima del primo token, quindi velocità normale. Il keep-alive è scaduto e i pesi vengono nuovamente letti dal disco. Imposta OLLAMA_KEEP_ALIVE.

Il modello contraddice un file che ha appena letto. Si tratta di un troncamento del contesto. ollama ps mostra generalmente un valore CONTEXT inferiore a quello impostato, perché la variabile d'ambiente è stata assegnata alla shell invece che all'unità systemd.

Tutto funziona, ma lentamente, e PROCESSOR non è 100% GPU. Di solito il modello e il relativo contesto non entrano nella VRAM. Se PROCESSOR restituisce 100% CPU su una macchina dotata di GPU, escludi prima l'altra causa: Ollama potrebbe non aver rilevato affatto la GPU. La documentazione di Ollama segnala che su Linux, dopo una sospensione e ripresa del sistema, a volte il programma non rileva una GPU NVIDIA e passa alla CPU; il ricaricamento del driver con sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm aggira il problema. Se la GPU viene rilevata e la suddivisione rimane, riduci la lunghezza del contesto oppure passa a un modello più piccolo o a una quantizzazione più compatta. Prima di eseguire nuovamente il pull, quanto consumano in memoria q4_K_M, q8_0 e fp16 e dove si verifica effettivamente il calo di qualità spiega quanto spazio recuperi con il formato inferiore e a cosa rinunci.

FAQ

Posso usare Claude Code con Ollama?

Sì, ma non con un URL compatibile con OpenAI. Claude Code utilizza l'Anthropic Messages API e Ollama espone questo formato all'indirizzo /v1/messages sulla stessa porta 11434. Esporta ANTHROPIC_BASE_URL=http://localhost:11434 e ANTHROPIC_AUTH_TOKEN=ollama e imposta ANTHROPIC_API_KEY su una stringa vuota, quindi avvialo con claude --model qwen3-coder:30b. ollama launch claude applica automaticamente le stesse impostazioni. Il livello di compatibilità non implementa tool_choice né il prompt caching e non dispone di un endpoint per il conteggio dei token, quindi i conteggi riportati sono approssimativi.

Perché il mio modello locale risponde su codice che non può vedere?

Perché la richiesta non rientra più nella finestra di contesto e la parte più vecchia viene eliminata senza generare errori. Ollama imposta il contesto predefinito in base alla VRAM rilevata. Con meno di 24 GiB, il valore predefinito è di 4,096 token, una quantità già superata dal prompt di sistema e dalle definizioni degli strumenti dell'agente. Imposta OLLAMA_CONTEXT_LENGTH=64000 nell'unità systemd, riavvia Ollama e verifica che la colonna CONTEXT di ollama ps riporti il nuovo valore.

Quale modello dovrei eseguire per un agente di coding su un VPS?

Scegli il modello più grande con etichetta tools che rientri nella memoria disponibile usando una finestra di contesto da 64k e preferisci un modello ottimizzato per il codice. qwen3-coder:30b è la scelta comune su un server GPU con VRAM sufficiente. Se questa variante è troppo grande per il tuo server, i valori della RAM e le velocità in modalità solo CPU di Nemotron 3.5 Lightning offrono un confronto utile prima di avviare il download. Al di sotto di circa 14B parametri, un modello può ancora rispondere bene a domande sul codice, ma fallire nelle modifiche articolate in più passaggi, perché il lavoro degli agenti risente degli errori di formattazione anche minimi nelle chiamate agli strumenti. Esegui un test con un'attività reale del tuo repository, invece di usare un prompt di esempio.

Per eseguire un agente di coding sul mio modello ho bisogno di una GPU?

In pratica, sì. L'inferenza solo CPU funziona ed è adeguata per domande singole, ma un agente invia molte richieste per ogni attività e rilegge ogni volta una cronologia estesa. Di conseguenza, una bassa velocità di generazione dei token può trasformare un'attività di due minuti in un'ora. Controlla la colonna PROCESSOR in ollama ps: qualsiasi valore diverso da 100% GPU indica che una parte del modello viene eseguita sulla CPU e la velocità di generazione dei token diminuisce nettamente.