SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Come usare Ollama con il tuo coding agent

Configura Ollama in locale con base URL, chiave fittizia e contesto corretto: scopri quale impostazione causa gli errori e per quali attività conviene.

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 URL di base locale

La verifica consiste in una sola domanda: lo strumento espone un'impostazione per l'URL di base? 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, vengono definiti agent di coding. Non usano 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 l'URL di base su http://localhost:11434/v1 e usa una stringa non vuota come chiave API.
  • Claude Code non accetta in alcun caso un URL di base OpenAI. Usa l'API Anthropic Messages, quindi richiede ANTHROPIC_BASE_URL impostato su http://localhost:11434, dove Ollama espone /v1/messages.
  • Codex usa l'API OpenAI Responses. Ollama espone anche /v1/responses, a partire dalla versione 0.13.3.
  • Un agent privo di un'impostazione per l'URL di base non può essere reindirizzato, perché l'endpoint è definito direttamente nel client. Se l'agent accetta un URL personalizzato ma richiede un formato API diverso, inserisci invece un livello di traduzione, ad esempio un gateway LiteLLM self-hosted, e riesponi il modello nel formato richiesto dal client.

Ollama può scrivere queste configurazioni per te. 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. L'URL di base controlla la destinazione delle richieste; svuotare la chiave impedisce di usare le credenziali del servizio hosted in questa configurazione locale. ollama launch claude esegue automaticamente tutta questa configurazione.

È importante sapere cosa non implementa il livello di compatibilità. Non supporta tool_choice né il prompt caching e non dispone di un endpoint per il conteggio dei token. I valori visualizzati per i token sono quindi approssimazioni basate sul tokenizer del modello. Claude Code invia inoltre un system prompt ampio e dispone di un insieme esteso di strumenti, quindi richiede più contesto rispetto a un client di chat. La questione più generale di ciò che viene mantenuto e di ciò che non viene mantenuto è trattata in possibilità di eseguire Claude in self-hosting.

Indicare Ollama ad Aider

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/. Per impostazione predefinita, Aider richiede un contesto sufficiente per ogni richiesta più 8k token per la risposta. Consente inoltre di fissare la finestra di contesto per ogni modello in .aider.model.settings.yml, utile quando un modello richiede una finestra diversa da quella predefinita del server:

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

Perché una configurazione funzionante produce comunque risultati insensati

Questa è la sezione più importante. Ollama sceglie la lunghezza del contesto predefinita in base alla VRAM complessiva (la memoria video delle GPU) che riesce a rilevare, sottraendo OLLAMA_GPU_OVERHEAD per ogni GPU rilevata. L'implementazione usa queste soglie:

GraficoOllama default context length by aggregate VRAM, checked 2026-10-26
I dati alla base di questo grafico
[
  {
    "label": "Under 23 GiB aggregate VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "23 to under 47 GiB aggregate VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "47 GiB aggregate VRAM or more",
    "default_context_tokens": "262,144"
  }
]

La maggior parte dei piani VPS e tutti i server che usano solo la CPU rientrano nella prima riga: 4,096 token. Più GPU di dimensioni ridotte possono raggiungere insieme la soglia di 47 GiB necessaria per i 262,144 token dell'ultima riga.

Un agent invia 4096 token prima di eseguire qualsiasi operazione. Il prompt di sistema, le definizioni degli strumenti, l'elenco del repository e il primo file che apre superano già questa dimensione. Qui si verifica il problema principale: non viene generato alcun errore. La documentazione di Aider specifica che Ollama scarta in modo silenzioso il contesto che supera la finestra disponibile. I token più vecchi vengono eliminati; 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 spiega la maggior parte delle segnalazioni secondo cui un modello locale è troppo poco efficace per scrivere codice. Anche scegliere il valore corretto richiede una decisione specifica, e vale la pena leggere quanto costa num_ctx nella memoria della KV cache per ogni dimensione prima di impostarlo.

La documentazione di Ollama indica che attività come gli agent e gli strumenti di coding devono essere configurati con almeno 64000 token. Impostalo sul server:

sudo systemctl edit ollama.service

Aggiungi queste righe nel 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

Dopo il riavvio, invia una richiesta dal tuo agent, quindi esegui di nuovo ollama ps per avere un modello caricato da ispezionare. ollama ps è il controllo da eseguire. Stampa una colonna CONTEXT, e quel numero indica il valore effettivamente ricevuto dal modello. I valori di ID e SIZE saranno diversi:

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

Impostalo sul server anziché nell'agent per due motivi. Lo schema OpenAI chat completions non include un campo per la lunghezza del contesto, quindi un client compatibile con OpenAI non può richiederne una. Inoltre, il valore predefinito del server si applica a ogni agent, a meno che un modello o una richiesta non lo sovrascriva. Anche l'output ha un limite massimo e, a differenza della lunghezza del contesto, viene trasmesso tramite l'endpoint di compatibilità. Per questo, num_predict e il campo max_tokens che viene associato a questo parametro sono i valori da usare quando una risposta si interrompe a metà di una patch. Se un modello richiede una finestra diversa, incorporala in una copia usando 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 controlla la colonna PROCESSOR. 100% GPU è il valore da raggiungere. Quando una parte del modello viene spostata sulla CPU, la velocità di generazione dei token diminuisce a tal punto che il ciclo di un agent diventa inutilizzabile. Misurare i token al secondo su un LLM locale permette di individuare il limite effettivo del tuo server. Il dimensionamento della macchina prima dell'acquisto è descritto in quanta RAM e CPU richiede un VPS per un agent 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 chat, ma non al lavoro degli agenti. Metti in pausa l'attività 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 accanto alla lunghezza del contesto:

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

Il campo di richiesta keep_alive è disponibile negli endpoint nativi /api/generate e /api/chat di Ollama e come estensione Ollama in /v1/chat/completions. Un agente che espone campi di richiesta aggiuntivi può inviarlo in quel punto; in caso contrario, usa la variabile d'ambiente. Quando devi recuperare 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 tenere 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 è in ascolto su 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 configurazione soltanto su una rete privata. La documentazione di Ollama specifica che l'API locale non richiede autenticazione. Di conseguenza, lasciare la porta 11434 aperta su Internet consente a chiunque di utilizzare il tuo hardware. 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'utilizzare una VPN, configurando Ollama in ascolto sull'indirizzo della VPN invece che su 0.0.0.0. Se più persone o più agent condividono lo stesso server, Ollama supporta richieste parallele quando la memoria disponibile lo consente, mentre il confronto tra Ollama e vLLM mostra da quale punto la differenza di throughput inizia a penalizzare le prestazioni.

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 quel risultato. Il tag fa parte del nome: se la configurazione indica un tag che non hai mai scaricato, l'operazione fallisce 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à l'intera finestra di contesto. Controlla l'etichetta tools nella pagina del modello, quindi verifica la colonna CONTEXT in ollama ps.

Lunga attesa prima del primo token, poi 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 è verificata una troncatura del contesto. ollama ps mostra solitamente un valore CONTEXT più basso di quello impostato, perché la variabile d'ambiente è stata assegnata alla shell invece che all'unità systemd.

Tutto funziona, ma lentamente, e PROCESSOR mostra 100% CPU oppure una suddivisione tra CPU e GPU. Di solito il modello, insieme al relativo contesto, non entra 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 indica che, su Linux, dopo una sospensione e ripresa del sistema, a volte non riesce a rilevare una GPU NVIDIA e passa alla CPU; indica inoltre che il ricaricamento del driver con sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm risolve 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ù leggera. Prima di scaricare nuovamente il modello, quanto consumano in memoria q4_K_M, q8_0 e fp16 e dove si verifica effettivamente la riduzione della qualità spiega quanto spazio recuperi riducendo il formato e a cosa rinunci. Anche Unknown è un possibile valore PROCESSOR; questo non dimostra che sia attivo l'offloading sulla CPU.

FAQ

Posso indirizzare Claude Code a Ollama?

Sì, ma non con un URL compatibile con OpenAI. Claude Code usa l'API Anthropic Messages e Ollama espone questo formato su /v1/messages, sulla stessa porta 11434. Esporta ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama e un valore vuoto per ANTHROPIC_API_KEY, quindi avvialo con claude --model qwen3-coder:30b. ollama launch claude scrive automaticamente queste impostazioni. 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 conteggi riportati sono quindi 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 è stata eliminata senza errori. Ollama imposta il contesto predefinito in base alla VRAM rilevata complessivamente, dopo aver sottratto l'overhead configurato per ogni GPU: sotto 23 GiB il valore predefinito è di 4,096 token, da 23 a meno di 47 GiB è di 32,768 token e da 47 GiB in poi è di 262,144 token. Imposta OLLAMA_CONTEXT_LENGTH=64000 nell'unità systemd, riavvia Ollama e verifica che la colonna CONTEXT in ollama ps mostri il nuovo valore.

Quale modello dovrei eseguire per un coding agent su un VPS?

Scegli il modello più grande con etichetta tools che rientri nella memoria con una finestra di contesto di 64k e preferisci un modello ottimizzato per il codice. qwen3-coder:30b è la scelta più comune su un server con GPU e VRAM sufficiente. Se questa etichetta indica un modello troppo grande per il tuo server, i valori della RAM e le velocità in modalità solo CPU per 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 alle domande sul codice, ma fallire nelle modifiche in più passaggi, perché il lavoro degli agenti è particolarmente sensibile ai piccoli errori di formattazione nelle chiamate agli strumenti. Esegui un test con un'attività reale del tuo repository invece di usare un prompt di esempio.

Serve una GPU per eseguire un coding agent sul mio modello?

In pratica sì. L'inferenza solo CPU funziona ed è adeguata per singole domande, ma un agente invia molte richieste per ogni attività e rilegge una cronologia lunga a ogni richiesta; una bassa velocità di generazione dei token può quindi trasformare un'attività di due minuti in un'ora. Controlla la colonna PROCESSOR in ollama ps: 100% CPU oppure una suddivisione CPU/GPU indica l'uso della CPU, che rallenta l'inferenza. Unknown non dimostra che sia attivo l'offload sulla CPU.

Questo articolo ti è stato utile?

#ollama#coding-agent#openai-compatible#local-llm#self-hosted-ai