Di 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 e la configurazione della connessione è più semplice di quanto si pensi. Devi modificare 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 gestisce contemporaneamente due formati di richiesta. /v1/chat/completions è il formato compatibile con OpenAI; la documentazione di Ollama indica che la chiave è obbligatoria, ma viene ignorata. /v1/messages è il formato compatibile con Anthropic, utilizzato da Claude Code. Il tuo agent supporta già uno dei due formati, quindi non devi modificare altro.
Questa parte 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 dal tipo di attività assegnata al modello. A ciascuna impostazione è dedicata una sezione; i limiti effettivi sono descritti alla fine.
Quali agent di programmazione accettano un URL di base locale
Il test 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 ad agosto 2026 vengono definiti agenti di programmazione. Non usano tutti lo stesso formato, ed è questa differenza a causare i problemi di configurazione.
- La maggior parte degli agenti richiede un endpoint compatibile con OpenAI. Imposta l'URL di base
http://localhost:11434/v1e una stringa non vuota come chiave API. - Claude Code non accetta affatto un URL di base OpenAI. Usa l'API Anthropic Messages, quindi richiede che
ANTHROPIC_BASE_URLsia impostato suhttp://localhost:11434, dove Ollama espone/v1/messages. - Codex usa l'API OpenAI Responses. Ollama espone anche
/v1/responses, disponibile a partire dalla versione 0.13.3. - Un agente che non dispone di un'impostazione per l'URL di base non può essere reindirizzato, perché l'endpoint è incorporato nel client. Inserisci invece un livello di traduzione, ad esempio un gateway LiteLLM self-hosted, e ripubblica 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 chiamare gli strumenti
curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama lsIl 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 stampa il motivo.
Il modello deve supportare la chiamata degli strumenti, perché è così che funziona un agente. L'agente legge un file, scrive una patch, esegue il test, quindi legge l'errore e riprova. Un modello che non può emettere una chiamata a uno strumento descriverà la modifica in prosa invece di applicarla, causando un ciclo o l'arresto dell'agente. Prima di scaricarlo, cerca l'etichetta tools nella pagina del modello su ollama.com. qwen3-coder:30b la include e, ad agosto 2026, quel tag richiede un download di 19 GB e offre una finestra di contesto di 256K. Se il server usa soltanto la CPU o dispone di poca RAM, l'analisi della memoria per il tag Qwen 27B su un VPS mostra cosa entra effettivamente in 8-64 GB prima di avviare il download. Dopo il download, quei gigabyte vengono salvati sul disco root del server, che su 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 rende effettivamente disponibili:
curl http://localhost:11434/v1/modelsLe stringhe nella risposta sono quelle che la configurazione dell'agente deve contenere, carattere per carattere. Verificarle prima risolve la maggior parte degli errori di modello non trovato. Se Ollama non è ancora installato, trovi la procedura completa in come eseguire autonomamente 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:30bANTHROPIC_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:30bLa 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: 65536Perché 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) che riesce a rilevare, e questi valori predefiniti sono pubblicati:
The data behind this chart
[
{
"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, così come ogni server che usa soltanto la CPU, rientra nella prima riga: 4,096 token. Solo una GPU di grandi dimensioni consente di usare i 262,144 token dell'ultima riga.
Un agent consuma 4096 token prima di iniziare qualsiasi operazione. Il prompt di sistema, le definizioni degli strumenti, l'elenco del repository e il primo file che apre superano già questa dimensione. Da qui nasce 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 la scelta del valore è una decisione separata, e vale la pena leggere quanto costa num_ctx in memoria della KV cache a 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.serviceAggiungi 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 psollama ps è il controllo da eseguire. Stampa una colonna CONTEXT, e quel valore indica ciò che il modello ha effettivamente ricevuto. 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 nowImposta il valore sul server, non nell'agent, per due motivi. Lo schema OpenAI Chat Completions non dispone di un campo per la lunghezza del contesto, quindi un client compatibile con OpenAI non può richiederne una specifica. Inoltre, l'impostazione vale per il server, quindi ogni agent collegato a quel server la eredita. Anche l'output ha un limite massimo proprio e, diversamente dalla lunghezza del contesto, questo limite viene trasmesso tramite l'endpoint di compatibilità; quindi, quando una risposta si interrompe a metà di una patch, devi usare num_predict e il campo max_tokens che viene mappato su questo parametro. Se un modello richiede una finestra diversa, incorporala in una copia usando un Modelfile:
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f ModelfileIl contesto non è gratuito. Una finestra più lunga richiede più memoria, quindi controlla la colonna PROCESSOR. 100% GPU è il valore da preferire. Quando una parte del modello viene spostata sulla CPU, la velocità di generazione dei token diminuisce al punto che un ciclo dell'agent 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 quanta CPU servono a 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 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-vpsIl 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 quell’output. Il tag fa parte del nome: una configurazione che specifica un tag mai scaricato 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 controlla 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 appena letto. Si è verificato un troncamento del contesto. ollama ps mostra spesso un valore CONTEXT inferiore a quello impostato, perché la variabile d’ambiente è stata applicata alla shell invece che all’unità systemd.
Tutto funziona, ma lentamente, e PROCESSOR non è 100% GPU. Il modello, insieme al contesto, non entra nella VRAM. Riduci la lunghezza del contesto oppure passa a un modello più piccolo o a una quantizzazione più compatta. Prima di scaricare nuovamente il modello, quanto consumano in memoria q4_K_M, q8_0 e fp16 e dove si verifica realmente la perdita di qualità spiega quanto spazio aggiunge il passaggio a un livello inferiore e quali compromessi comporta.
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.