Ollama koppelen aan uw coding agent

De verbinding tot stand brengen

U kunt Ollama gebruiken met uw programmeer-agent; de verbinding is eenvoudiger dan vaak wordt aangenomen. U wijzigt één base URL en kiest één modelnaam. Het veld voor de API key vereist nog steeds een waarde, maar de lokale server negeert deze, dus elke willekeurige tekenreeks volstaat.

Ollama luistert op poort 11434 en ondersteunt gelijktijdig twee verzoekstructuren. /v1/chat/completions is de OpenAI-compatibele structuur, waarbij de documentatie van Ollama aangeeft dat de sleutel verplicht is maar wordt genegeerd. /v1/messages is de Anthropic-compatibele structuur, die door Claude Code wordt gebruikt. Uw agent ondersteunt al een van deze twee, dus er hoeft verder niets te worden aangepast.

Dit onderdeel kost vijf minuten. Of het resultaat bruikbaar is, hangt af van twee instellingen die bijna niemand wijzigt: de contextlengte en de keep-alive, en van het toewijzen van taken waar het model in uitblinkt. Beide krijgen een eigen sectie, en de reële beperkingen staan aan het einde.

Welke coding agents accepteren een lokale base URL

De test is simpel: biedt de tool een instelling voor een base URL? Als dat zo is, kan deze communiceren met uw server.

Ollama publiceert integratiepagina's voor Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDEs en VS Code. Aider documenteert zijn eigen Ollama-ondersteuning afzonderlijk. Dat dekt het merendeel van wat men in augustus 2026 onder een coding agent verstaat. Ze hanteren niet allemaal hetzelfde formaat, en dat verschil is waar configuraties vaak falen.

• De meeste agents vereisen een OpenAI-compatibel eindpunt. Geef ze de base URL http://localhost:11434/v1 en een willekeurige, niet-lege API-key string.
• Claude Code accepteert geen OpenAI base URL. Deze tool gebruikt de Anthropic Messages API, dus u moet ANTHROPIC_BASE_URL instellen op http://localhost:11434, waarbij Ollama /v1/messages serveert.
• Codex gebruikt de OpenAI Responses API. Ollama serveert ook /v1/responses, toegevoegd in versie 0.13.3.
• Een agent zonder instelling voor een base URL kan niet worden omgeleid, omdat het eindpunt in de client is ingebakken. Plaats in dat geval een vertaallaag voor de client, zoals een zelfgehoste LiteLLM gateway, en stel uw model opnieuw beschikbaar in het formaat dat de client vereist.

Ollama kan deze configuraties voor u schrijven. ollama launch opencode start OpenCode met een inline configuratie voor het model van uw keuze, ollama launch claude doet hetzelfde voor Claude Code, en ollama launch droid --config schrijft de configuratie zonder de tool te starten.

Installeer Ollama en haal een model op dat tools kan aanroepen

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

Het installatieprogramma voegt een systemd-unit toe en start deze, dus systemctl status ollama zou active (running) moeten weergeven. Als dit niet het geval is, geeft journalctl -e -u ollama de reden aan.

Het model moet tool-calling ondersteunen, omdat een agent op deze manier werkt. Het leest een bestand, schrijft een patch, voert de test uit, leest vervolgens de foutmelding en probeert het opnieuw. Een model dat geen tool-call kan genereren, zal de bewerking in proza beschrijven in plaats van deze uit te voeren, waardoor de agent in een lus terechtkomt of stopt. Zoek naar het label tools op de pagina van het model op ollama.com voordat u het ophaalt. qwen3-coder:30b beschikt hierover, en per augustus 2026 is die tag een download van 19 GB met een contextvenster van 256K. Als uw systeem alleen over een CPU beschikt of weinig RAM heeft, laat de geheugenberekening voor de Qwen 27B-tag op een VPS zien wat er daadwerkelijk in 8 tot 64 GB past voordat u de download start. Zodra u het model ophaalt, komen die gigabytes op de root-schijf van de server terecht; dit is het onderdeel van een VPS met de minste vrije ruimte, dus waar Ollama zijn modelbestanden bewaart en hoe u deze naar een andere locatie verplaatst is het lezen waard voordat de schijf vol raakt.

Bevestig nu welke namen de server daadwerkelijk serveert:

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

De strings in dat antwoord zijn wat uw agentconfiguratie moet bevatten, teken voor teken. Dit vooraf controleren lost de meeste 'model-not-found'-fouten op. Als Ollama nog niet is geïnstalleerd, vindt u de uitgebreidere handleiding in een LLM zelf hosten met Ollama op een VPS.

OpenCode koppelen aan Ollama

Bewerk ~/.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"
        }
      }
    }
  }
}

De sleutel onder models is de modelnaam die naar Ollama wordt verzonden; deze moet dus exact overeenkomen met ollama ls. Het veld name is enkel het label in de modelkiezer. Start opencode, schakel over naar de Ollama-provider en monitor journalctl -e -u ollama om te bevestigen dat het verzoek bij uw server is aangekomen en niet ergens anders. Het instellen van de agent zelf wordt behandeld in OpenCode draaien op een VPS.

Claude Code koppelen aan 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 is bewust op een lege string ingesteld. Als u een echte sleutel in de omgeving laat staan, worden uw verzoeken naar de gehoste API gestuurd; u ontvangt dan een factuur en maakt geen gebruik van lokale inferentie. ollama launch claude stelt dit alles voor u in.

Wees u bewust van wat de compatibiliteitslaag weglaat. Deze implementeert geen tool_choice of prompt caching, en er is geen endpoint voor het tellen van tokens. De getoonde aantallen tokens zijn daarom benaderingen van de eigen tokenizer van het model. Claude Code verstuurt ook een uitgebreide systeemprompt en een grote set tools, waardoor er meer context nodig is dan bij een chatclient. De bredere vraag over wat wel en niet wordt ondersteund, wordt behandeld in of u Claude zelf kunt hosten.

Aider koppelen aan Ollama

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

De documentatie van Aider adviseert het gebruik van het ollama_chat/-voorvoegsel boven ollama/. Het stelt u tevens in staat om het contextvenster per model vast te leggen in .aider.model.settings.yml. Dit is nuttig wanneer een model een ander venster vereist dan de standaardinstelling van de server:

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

Waarom een werkende configuratie toch onzin produceert

Dit is de sectie die ertoe doet. Ollama kiest een standaard contextlengte op basis van het VRAM (videogeheugen op de GPU) dat het kan detecteren, en deze standaardwaarden zijn gepubliceerd:

[
  {
    "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"
  }
]

De meeste VPS-abonnementen, en elke server die alleen op CPU draait, vallen in de eerste rij: 4,096 tokens. Alleen een grote GPU krijgt de 262,144 tokens in de laatste rij.

Een agent verbruikt 4096 tokens voordat deze ook maar enig werk verricht. De systeemprompt, de tooldefinities, de repository-lijst en het eerste bestand dat wordt geopend, zijn al groter dan dat. Wat er daarna gebeurt, vormt het hele probleem: er treden geen fouten op. De documentatie van Aider stelt dat Ollama stilletjes context verwijdert die het venster overschrijdt. De oudste tokens vallen weg, waardoor het model zelfverzekerd antwoordt over een bestand dat het niet meer kan zien, of een instructie vergeet die u twee stappen eerder gaf. Dat mechanisme is de oorzaak van de meeste meldingen dat een lokaal model te dom is om code te schrijven. Het kiezen van het getal zelf is een eigen afweging, en wat num_ctx kost aan KV-cachegeheugen bij elke grootte is het lezen waard voordat u een keuze maakt.

De documentatie van Ollama stelt dat taken zoals agents en coderingstools op ten minste 64000 tokens moeten worden ingesteld. Stel dit in op de server:

sudo systemctl edit ollama.service

Voeg deze regels toe in het override-bestand:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Herlaad en herstart vervolgens:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps is de controle. Het print een CONTEXT-kolom, en dat getal is wat het model daadwerkelijk heeft ontvangen. Uw ID en SIZE zullen verschillen:

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

Stel dit in op de server in plaats van in de agent, om twee redenen. Het OpenAI chat completions-schema heeft geen veld voor contextlengte, dus een OpenAI-compatibele client kan er niet om vragen. Bovendien is de instelling per server, dus elke agent die u naar de server wijst, neemt deze over. De output-zijde heeft zijn eigen limiet, en in tegenstelling tot de contextlengte wordt deze wel via het compatibiliteitseindpunt verzonden, dus num_predict en het max_tokens-veld dat hierop aansluit zijn de zaken waar u naar moet kijken wanneer een antwoord halverwege een patch stopt. Als een model een ander venster nodig heeft, verwerk dit dan in een kopie met een Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Context is niet gratis. Een langer venster kost meer geheugen, dus houd de PROCESSOR-kolom in de gaten. 100% GPU is wat u wilt bereiken. Zodra een deel van het model naar de CPU uitwijkt, daalt de tokensnelheid zo ver dat een agent-loop onbruikbaar wordt, en het meten van tokens per seconde op een lokale LLM is de manier om de werkelijke limiet voor uw machine te vinden. Het dimensioneren van de machine voordat u deze aanschaft, wordt behandeld in hoeveel RAM en CPU een VPS voor een coding agent nodig heeft.

Houd het model geladen tussen verzoeken

Standaard ontlaadt Ollama een model 5 minuten na het laatste verzoek. Dit is correct voor een chatvenster, maar ongeschikt voor agent-taken. U pauzeert om een diff te lezen, de timer loopt af en het volgende verzoek herlaadt tientallen gigabytes aan gewichten vanaf de schijf voordat het eerste token verschijnt. Dit wordt ervaren als een vastloper.

OLLAMA_KEEP_ALIVE accepteert een tijdsduur-string zoals 10m of 24h, een getal in seconden, -1 om het model voor onbepaalde tijd geladen te houden, of 0 om het onmiddellijk te ontladen. Stel dit in naast de contextlengte:

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

Het keep_alive verzoekveld bestaat alleen op de eigen /api/generate en /api/chat endpoints van Ollama, niet op de compatibiliteits-endpoints, waardoor een agent dit niet per verzoek kan instellen. De omgevingsvariabele is de enige methode die u heeft. Wanneer u het geheugen weer vrij wilt maken, ontlaadt ollama stop qwen3-coder:30b het model zonder de server te stoppen. Als u wilt dat de instelling een herstart overleeft, of als u de afweging wilt maken tussen het de hele dag in het geheugen houden van de gewichten en het vrijmaken van dat geheugen, behandelt het geladen houden van een Ollama-model in het geheugen beide scenario's.

Ollama uitvoeren op een aparte server

Ollama bindt standaard aan localhost. Om de service vanaf een andere machine te bereiken, stelt u OLLAMA_HOST=0.0.0.0:11434 in via dezelfde systemd-override en herstart u de service.

Doe dit uitsluitend binnen een privénetwerk. De documentatie van Ollama vermeldt dat er geen authenticatie vereist is voor de lokale API. Als poort 11434 openstaat naar het internet, kan iedereen uw hardware gebruiken en alles lezen wat uw agent verstuurt. Er zijn twee veilige opties. Behoud de binding op localhost en stuur de poort door via SSH vanaf uw laptop:

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

Uw agent blijft verwijzen naar http://localhost:11434/v1 en merkt geen verschil. De andere optie is een VPN, waarbij Ollama gebonden is aan het VPN-adres in plaats van aan 0.0.0.0. Als meerdere personen of meerdere agents één server delen, is de scheduler van Ollama niet berekend op die belasting, en de vergelijking tussen Ollama en vLLM laat zien waar het verschil in doorvoersnelheid merkbaar wordt.

Waar een lokaal programmeermodel wint, en waar niet

Een agent die wordt aangestuurd door een model dat u zelf host, vervangt niet bij elke taak een frontier API. Het wint duidelijk op vier soorten werk.

• Mechanische bulkbewerkingen, waarbij elke wijziging klein is en u deze kunt controleren. Hernoemen in een repository, type hints toevoegen, docstrings schrijven, commentaar vertalen. Het model draait urenlang zonder dat de kosten oplopen.
• Werk dat uw hardware niet mag verlaten. Clientcode onder een geheimhoudingsverklaring, of een interne repository die u niet naar een derde partij mag sturen.
• Offline en air-gapped machines, waar helemaal geen gehoste API beschikbaar is om aan te roepen.
• Voorspelbare kosten. Zodra de server is betaald, kost een agent die in een lus tokens verbruikt niets extra, wat het tegenovergestelde is van een API met verbruiksafhankelijke kosten. Waar een GPU VPS rendabel wordt ten opzichte van API-tokens bevat de berekening.

Het verliest bij lange taken met meerdere stappen. "Zoek uit waarom deze test faalt, los de oorzaak op, update de aanroepers" vereist veel correcte tool-aanroepen achter elkaar, waarbij de volledige geschiedenis in de context moet blijven. Een model in het bereik van 8B tot 14B op een bescheiden server zal een onjuiste tool-aanroep produceren, of het plan na enkele stappen verliezen, waardoor u meer tijd kwijt bent aan het bijsturen dan de taak zelf zou hebben gekost. Dat is geen probleem met de prompt dat u kunt oplossen door beter te formuleren. Het is een kwestie van capaciteit.

Het verliest ook wanneer ongelijk hebben duur is en u niet elke regel zult lezen. Geef het lokale model specifieke taken waarvan u de output verifieert, en houd een gehost model aan voor het werk dat u niet stap voor stap zou controleren.

Foutmodi en de meldingen die u zult zien

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. De server draait niet, of de agent is geconfigureerd voor een andere host. Voer systemctl status ollama uit en vervolgens journalctl -e -u ollama.

De agent meldt dat het model niet bestaat. De naam in uw configuratie komt niet overeen met een naam die de server aanbiedt. Vergelijk deze met curl http://localhost:11434/v1/models en kopieer de string daarvandaan. De tag is onderdeel van de naam; een configuratie die verwijst naar een tag die u nooit heeft binnengehaald, zal falen, zelfs als er een vergelijkbaar model is geïnstalleerd.

De agent antwoordt in proza en bewerkt geen bestanden. Ofwel het model ondersteunt geen tools, of het verzoek inclusief de tooldefinities vult de context window al volledig. Controleer het label tools op de modelpagina en bekijk vervolgens de kolom CONTEXT in ollama ps.

Een lange stilte voor het eerste token, daarna normale snelheid. De keep-alive is verlopen en de gewichten worden opnieuw vanaf de schijf ingelezen. Stel OLLAMA_KEEP_ALIVE in.

Het model spreekt een bestand tegen dat het zojuist heeft gelezen. Context-truncatie. ollama ps toont meestal een CONTEXT-waarde die lager is dan u denkt te hebben ingesteld, omdat de omgevingsvariabele naar uw shell is gegaan in plaats van naar de systemd-unit.

Alles werkt, maar traag, en PROCESSOR is niet 100% GPU. Het model plus de context past niet in het VRAM. Verlaag de contextlengte of stap over op een kleiner model of een lagere kwantisatie. Voordat u opnieuw downloadt, leest u in wat q4_K_M, q8_0 en fp16 elk aan geheugen kosten en waar de kwaliteit daadwerkelijk afneemt hoeveel ruimte een stap omlaag oplevert en wat u daarvoor inlevert.

FAQ

Kan ik Claude Code koppelen aan Ollama?

Ja, maar niet met een OpenAI-compatibele URL. Claude Code gebruikt de Anthropic Messages API en Ollama biedt deze interface aan op /v1/messages via dezelfde poort 11434. Exporteer ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama en een lege ANTHROPIC_API_KEY, en start het vervolgens met claude --model qwen3-coder:30b. ollama launch claude schrijft dezelfde instellingen voor u weg. De compatibiliteitslaag implementeert geen tool_choice of prompt-caching, en beschikt niet over een endpoint voor het tellen van tokens, waardoor de gerapporteerde aantallen tokens schattingen zijn.

Waarom geeft mijn lokale model antwoord over code die het niet kan zien?

Omdat het verzoek niet meer in het contextvenster past en het oudste deel ervan zonder foutmelding is verwijderd. Ollama bepaalt de standaardcontext op basis van het gevonden VRAM. Onder de 24 GiB is die standaardwaarde 4,096 tokens, wat de systeem-prompt en tooldefinities van een agent al overschrijden. Stel OLLAMA_CONTEXT_LENGTH=64000 in de systemd-unit in, herstart Ollama en controleer of de kolom CONTEXT in ollama ps de nieuwe waarde toont.

Welk model moet ik gebruiken voor een codeer-agent op een VPS?

Kies het grootste model met een tools-label dat nog in het geheugen past met een contextvenster van 64k, en geef de voorkeur aan een model dat is getraind voor code. qwen3-coder:30b is het gangbare antwoord op een GPU-server met voldoende VRAM. Als die tag te groot is voor uw server, zijn de RAM-cijfers en CPU-only snelheden voor Nemotron 3.5 Lightning een nuttige vergelijking voordat u overgaat tot een download. Onder de ongeveer 14B parameters kan een model nog steeds goed vragen over code beantwoorden, maar faalt het vaak bij bewerkingen in meerdere stappen, omdat agent-werk kleine opmaakfouten in tool-aanroepen afstraft. Test met een echte taak uit uw eigen repository in plaats van met een voorbeeld-prompt.

Heb ik een GPU nodig om een codeer-agent op mijn eigen model te draaien?

In de praktijk wel. Inference op alleen de CPU werkt en is prima voor losse vragen, maar een agent verstuurt veel verzoeken per taak en elk verzoek leest een lange geschiedenis opnieuw in. Een lage token-snelheid verandert een taak van twee minuten daarom in een uur. Controleer de kolom PROCESSOR in ollama ps: elke waarde anders dan 100% GPU betekent dat een deel van het model op de CPU draait, waardoor de token-snelheid scherp daalt.