Di Usare Ollama con il tuo coding agent
Configura un coding agent con Ollama: base URL sulla porta 11434, API key fittizia, contesto che può rompere tutto e attività adatte al modello locale.
A cosa ti stai connettendo
Puoi usare Ollama con il tuo coding agent. La configurazione richiede meno modifiche di quanto si pensi. Devi cambiare un solo base URL e scegliere un solo nome modello. Il campo della API key richiede comunque un valore, ma il server locale lo ignora. Puoi quindi usare qualsiasi stringa.
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, usato da Claude Code. Il tuo agent supporta già uno dei due formati. Non devi quindi modificare 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 dal tipo di attività assegnata al modello. A ciascuna impostazione è dedicata una sezione. I limiti effettivi 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 ad agosto 2026 vengono definiti coding agent. Non usano tutti lo stesso formato, ed è questa differenza a causare il fallimento delle configurazioni.
- La maggior parte degli agenti richiede un endpoint compatibile con OpenAI. Imposta il base URL su
http://localhost:11434/v1e usa una stringa API key non vuota. - Claude Code non accetta alcun base URL OpenAI. Usa l'Anthropic Messages API, quindi richiede che
ANTHROPIC_BASE_URLsia impostato suhttp://localhost:11434, dove Ollama espone/v1/messages. - Codex usa l'OpenAI Responses API. Ollama espone anche
/v1/responses, a partire dalla versione 0.13.3. - Un agente privo di un'impostazione per il base URL non può essere reindirizzato, perché l'endpoint è definito direttamente nel client. Inserisci invece un livello di traduzione davanti al client, ad esempio un gateway LiteLLM self-hosted, e pubblica di nuovo 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 esegue la stessa operazione per Claude Code e ollama launch droid --config scrive la configurazione senza avviare lo strumento.
Installa Ollama e scarica un modello che supporti le chiamate agli 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 mostra il motivo.
Il modello deve supportare le chiamate agli strumenti, perché un agente opera 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 descriverà la modifica in prosa invece di applicarla, causando un ciclo o l'arresto dell'agente. Prima di scaricare il modello, cerca l'etichetta tools nella relativa pagina su ollama.com. qwen3-coder:30b include questa funzionalità e, ad agosto 2026, questo 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, il calcolo della memoria per il tag Qwen 27B su un VPS mostra quali configurazioni rientrano effettivamente in 8-64 GB prima di avviare il download.
Ora verifica quali nomi il server espone effettivamente:
curl http://localhost:11434/v1/modelsLe stringhe presenti nella risposta devono comparire nella configurazione dell'agente, carattere per carattere. Questa verifica risolve la maggior parte degli errori relativi a modelli non trovati. Se Ollama non è ancora installato, consulta la guida più dettagliata per eseguire autonomamente un LLM con Ollama su un VPS.
Punta OpenCode a Ollama
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 è solo l'etichetta visualizzata 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 e non a un'altra destinazione. La configurazione dell'agent è descritta in esecuzione di OpenCode su un VPS.
Configura Claude Code per usare 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 inviate invece all’API ospitata, con conseguenti costi e senza inferenza locale. ollama launch claude configura automaticamente tutti questi parametri.
È importante conoscere i limiti del livello di compatibilità. Non implementa tool_choice né il prompt caching e non dispone di un endpoint per il conteggio dei token. Di conseguenza, i numeri dei token visualizzati sono approssimazioni basate sul tokenizer del modello. Claude Code include inoltre un system prompt esteso e un ampio insieme di strumenti, quindi richiede più contesto rispetto a un client di chat. La questione più ampia di quali funzionalità siano trasferibili e quali no è trattata nella sezione se è possibile eseguire Claude in modalità self-hosted.
Indicare a Ollama il server da utilizzare
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, utile quando un modello richiede una finestra diversa da quella predefinita del 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 rileva, 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 agente passa 4096 token prima di iniziare qualsiasi attività. Il prompt di sistema, le definizioni degli strumenti, l'elenco del repository e il primo file che apre superano già questa dimensione. Da quel momento si verifica il problema principale: non viene restituito alcun errore. La documentazione di Aider indica 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 spiega la maggior parte delle segnalazioni secondo cui un modello locale è troppo limitato per scrivere codice.
La documentazione di Ollama indica che attività come gli agenti e gli strumenti di coding devono essere configurati con almeno 64000 token. Imposta questo valore 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 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 nowImposta il valore sul server anziché nell'agente, per due motivi. Lo schema OpenAI chat completions non contiene un campo per la lunghezza del contesto, quindi un client compatibile con OpenAI non può richiederla. Inoltre, l'impostazione è applicata al server, quindi ogni agente collegato a quel server la eredita. 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 monitora la colonna PROCESSOR. 100% GPU è il valore desiderato. Quando una parte del modello viene eseguita sulla CPU, il numero di token al secondo diminuisce al punto che il ciclo dell'agente diventa inutilizzabile. Misurare i token al secondo su un LLM locale consente di individuare il limite effettivo del server. Il dimensionamento della macchina prima dell'acquisto è descritto 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 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 esiste soltanto negli endpoint nativi /api/generate e /api/chat di Ollama, non negli endpoint di compatibilità. Di conseguenza, un agente non può impostarlo per ogni 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.
Eseguire Ollama su un server separato
Ollama si associa a localhost. Per raggiungerlo da un altro computer, imposta OLLAMA_HOST=0.0.0.0:11434 nello stesso override di systemd e riavvia il servizio.
Esegui questa configurazione solo su una rete privata. La documentazione di Ollama indica che l'API locale non richiede autenticazione. Pertanto, se la porta 11434 è aperta a Internet, chiunque può usare il tuo hardware e leggere tutto ciò che il tuo agente 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 agente continua a puntare a http://localhost:11434/v1 e non rileva alcuna differenza. L'altra opzione è una VPN, con Ollama associato all'indirizzo della VPN anziché a 0.0.0.0. Se più persone o più agenti 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 penalizzante.
Quando un modello di coding locale è vantaggioso e quando non lo è
Un agent basato su un modello che ospiti in locale non sostituisce un’API frontier per ogni attività. È nettamente vantaggioso per quattro tipi di lavoro.
- Modifiche meccaniche su larga scala, quando ogni cambiamento è limitato e verificabile. Rinominare elementi in un repository, aggiungere type hints, scrivere docstring, tradurre commenti. Il modello può funzionare per ore senza aumentare la spesa.
- Attività che non devono lasciare il tuo hardware. Ad esempio, codice client soggetto a un accordo di riservatezza o un repository interno che non puoi inviare a terzi.
- Macchine offline o air-gapped, dove non è possibile chiamare alcuna API ospitata.
- Costi prevedibili. Una volta pagato il server, un agent che consuma token in un loop non genera costi aggiuntivi. È l’opposto di un’API con fatturazione a consumo. Quando un GPU VPS raggiunge il pareggio rispetto ai token dell’API contiene i relativi calcoli.
È invece svantaggioso per le attività lunghe e composte da più passaggi. «Individua il motivo per cui questo test fallisce, correggi la causa 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 di fascia media può generare una chiamata allo strumento non valida oppure perdere il piano dopo pochi turni. In questo caso impieghi più tempo a guidarlo di quanto ne avrebbe richiesto l’attività. Non è un problema di prompt che puoi risolvere scrivendo istruzioni migliori. È un limite di capacità.
È inoltre svantaggioso quando un errore ha conseguenze rilevanti e non puoi leggere ogni riga. Assegna al modello locale attività circoscritte, il cui output puoi verificare, e riserva il modello ospitato al 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 offerto dal server. Confrontalo con curl http://localhost:11434/v1/models e copia la stringa da lì. Il tag fa parte del nome. Di conseguenza, 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 e le relative definizioni degli strumenti occupano già tutta la 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 appena letto. Si è verificato un troncamento del contesto. ollama ps mostra generalmente 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 e il relativo contesto non entrano nella VRAM. Riduci la lunghezza del contesto oppure usa un modello più piccolo o una quantizzazione più compatta.
FAQ
Posso indicare Ollama a Claude Code?
Sì, ma non con un URL compatibile con OpenAI. Claude Code usa l'API Anthropic Messages e Ollama espone quel formato su /v1/messages, sulla stessa porta 11434. Esporta ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama e un ANTHROPIC_API_KEY vuoto, quindi avvialo con claude --model qwen3-coder:30b. ollama launch claude scrive al posto tuo 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 errori. Ollama determina il contesto predefinito in base alla VRAM rilevata e, al di sotto di 24 GiB, tale valore è di 4,096 token. Il prompt di sistema dell'agente e le definizioni degli strumenti superano da sole questo limite. 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 devo eseguire per un agente di programmazione su un VPS?
Scegli il modello più grande con etichetta tools che rientra nella memoria con una finestra di contesto di 64k e preferisci un modello ottimizzato per il codice. qwen3-coder:30b è la scelta comune su un server GPU con VRAM sufficiente. Al di sotto di circa 14B parametri, un modello può ancora rispondere bene a domande sul codice ma fallire nelle modifiche in più passaggi, perché il lavoro degli agenti risente degli errori di formattazione anche piccoli 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 agente di programmazione sul mio modello?
In pratica, sì. L'inferenza eseguita solo sulla CPU funziona ed è sufficiente per singole domande, ma un agente invia molte richieste per ogni attività e rilegge ogni volta una cronologia lunga. 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à dei token diminuisce drasticamente.