SSD Nodes Learn Hosting plans →
Gidsen Matt ConnorDoor Matt Connor

Ollama koppelen aan uw coding agent: handleiding

Verbind uw coding agent met Ollama via de OpenAI of Anthropic API. Leer hoe u de base URL instelt, een dummy API key gebruikt en de juiste contextlimieten configureert.

Wat u verbindt

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

Ollama luistert op poort 11434 en biedt gelijktijdig drie API-interfaces aan. /api is de native API van Ollama. /v1 is de OpenAI-compatibele laag, die zelf verschillende vormen ondersteunt: /v1/chat/completions, /v1/responses, /v1/completions, /v1/models en /v1/embeddings. De documentatie van Ollama beschrijft de key daar als verplicht maar genegeerd. De derde interface is Anthropic-compatibel: de client gebruikt http://localhost:11434 als base URL en voegt daar /v1/messages aan toe, wat de taal is die Claude Code spreekt. De meeste agents gebruiken /v1/chat/completions, Codex gebruikt /v1/responses en Claude Code gebruikt /v1/messages. Uw agent spreekt al een van deze talen, dus er hoeft verder niets aan de configuratie te worden gewijzigd.

Dat onderdeel kost vijf minuten. Of het resultaat bruikbaar is, hangt af van twee instellingen die bijna niemand aanpast: de context length en de keep-alive, en van het toewijzen van taken waar het model goed in is. 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 IDE's en VS Code. Aider documenteert zijn eigen Ollama-ondersteuning afzonderlijk. Dit dekt het merendeel van wat men in oktober 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 gebruikt de Anthropic Messages API, dus hiervoor moet ANTHROPIC_BASE_URL worden ingesteld 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. Als de agent een aangepaste URL accepteert maar een ander API-formaat vereist, plaats dan een vertaallaag zoals een self-hosted LiteLLM gateway en bied uw model opnieuw aan 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-aanroepen 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-aanroep 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 oktober 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 heeft opgehaald, 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 ingesteld op een lege tekenreeks. De base URL bepaalt waar verzoeken naartoe worden gestuurd; door de sleutel te wissen, blijven gehoste inloggegevens buiten deze lokale configuratie. 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 op basis van de eigen tokenizer van het model. Claude Code verzendt 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 overgenomen, 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/. Standaard vraagt Aider voldoende context aan voor elk verzoek, plus 8k tokens voor het antwoord. Het is ook mogelijk om het contextvenster per model vast te pinnen 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 onzinnige resultaten oplevert

Dit is het belangrijkste onderdeel. Ollama kiest een standaardcontextlengte op basis van het totale VRAM (videogeheugen van de GPU's) dat het kan zien. Daarbij trekt het voor elke gedetecteerde GPU OLLAMA_GPU_OVERHEAD af. De implementatie gebruikt deze drempelwaarden:

GrafiekOllama default context length by aggregate VRAM, checked 2026-10-26
De gegevens achter deze grafiek
[
  {
    "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"
  }
]

De meeste VPS-abonnementen, en elke server zonder GPU, vallen in de eerste rij: 4,096 tokens. Meerdere kleinere GPU's kunnen samen de drempel van 47 GiB bereiken voor de 262,144 tokens in de laatste rij.

Een agent stuurt 4096 tokens voordat hij enig werk uitvoert. De systeemprompt, de tooldefinities, de repositorylijst en het eerste bestand dat hij opent, zijn samen al groter dan dat. Daarna ontstaat het eigenlijke probleem: er verschijnt geen foutmelding. In de documentatie van Aider staat dat Ollama context die het venster overschrijdt stilzwijgend verwijdert. De oudste tokens vallen weg. Daardoor antwoordt het model vol vertrouwen over een bestand dat het niet meer kan zien, of vergeet het een instructie die u twee stappen eerder hebt gegeven. Dit mechanisme ligt aan de basis van de meeste meldingen dat een lokaal model te weinig kan om code te schrijven. Het kiezen van de waarde zelf is een afzonderlijke beslissing. Lees daarom wat num_ctx bij elke grootte kost aan KV-cachegeheugen voordat u een waarde vastlegt.

In de documentatie van Ollama staat dat taken zoals agents en programmeertools op minstens 64000 tokens moeten worden ingesteld. Stel dit in op de server:

sudo systemctl edit ollama.service

Voeg deze regels toe aan het override-bestand:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Laad daarna de configuratie opnieuw en start de service opnieuw:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

Stuur na de herstart een verzoek vanuit uw agent. Voer daarna opnieuw ollama ps uit, zodat er een geladen model is om te inspecteren. ollama ps is de controle. De uitvoer bevat een kolom CONTEXT. Dat getal geeft aan wat het model daadwerkelijk heeft ontvangen. Uw ID en SIZE zullen verschillen:

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

Stel dit in op de server en niet in de agent, om twee redenen. Het OpenAI-schema voor chat completions heeft geen veld voor de contextlengte. Een OpenAI-compatibele client kan er dus geen waarde voor opvragen. Bovendien geldt de standaardwaarde van de server voor elke agent, tenzij een model of verzoek deze overschrijft. De uitvoer heeft een eigen limiet. In tegenstelling tot de contextlengte wordt die wel via het compatibiliteitseindpunt doorgegeven. Gebruik daarom num_predict en het veld max_tokens dat daarop wordt afgebeeld wanneer een antwoord halverwege een patch stopt. Als één model een ander venster nodig heeft, legt u dit vast 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. Houd daarom de kolom PROCESSOR in de gaten. 100% GPU is de waarde die u nodig hebt. Zodra een deel van het model naar de CPU wordt verplaatst, daalt de tokensnelheid zo sterk dat een agentlus onbruikbaar wordt. Met tokens per seconde meten op een lokale LLM bepaalt u de werkelijke bovengrens voor uw systeem. In hoeveel RAM en CPU een coding-agent-VPS nodig heeft staat beschreven hoe u de machine dimensioneert voordat u deze aanschaft.

Houd het model geladen tussen verzoeken

Standaard ontlaadt Ollama een model 5 minuten na het laatste verzoek. Dit is correct voor een chatvenster, maar onjuist 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 simpel getal in seconden, -1 om het model voor onbepaalde tijd geladen te houden, of 0 om direct te ontladen. Stel dit in naast de contextlengte:

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

Het keep_alive verzoekveld bestaat op de native /api/generate en /api/chat endpoints van Ollama en als een Ollama-extensie op /v1/chat/completions. Een agent die extra verzoekvelden blootstelt, kan dit daarheen sturen; gebruik anders de omgevingsvariabele. Wanneer u het geheugen wilt vrijmaken, 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 terugwinnen van dat geheugen, werkt een Ollama-model in het geheugen geladen houden voor beide scenario's.

Ollama draaien op een aparte server

Ollama luistert standaard op localhost. Om de service vanaf een andere machine te bereiken, stelt u OLLAMA_HOST=0.0.0.0:11434 in via hetzelfde systemd-overridebestand 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. Er zijn twee veilige opties. Laat de binding op localhost staan 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 hier niets van. De andere optie is een VPN, waarbij Ollama luistert op het VPN-adres in plaats van op 0.0.0.0. Als meerdere personen of meerdere agents één server delen, ondersteunt Ollama gelijktijdige verzoeken voor zover het geheugen dit toelaat, 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.

Storingsmodi en de meldingen die u ziet

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. De server draait niet of de agent verwijst naar een andere host. Voer systemctl status ollama uit en daarna 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 tekenreeks daaruit. De tag maakt deel uit van de naam. Een configuratie met een tag die u nooit hebt opgehaald, werkt dus niet, ook al is een vergelijkbaar model geïnstalleerd.

De agent antwoordt in proza en bewerkt nooit een bestand. Het model ondersteunt mogelijk geen tools, of de aanvraag plus de tooldefinities nemen het volledige contextvenster al in beslag. Controleer het label tools op de modelpagina en controleer daarna de kolom CONTEXT in ollama ps.

Een lange stilte vóór het eerste token, daarna normale snelheid. De keep-alive is verlopen en de gewichten worden opnieuw van schijf gelezen. Stel OLLAMA_KEEP_ALIVE in.

Het model spreekt een bestand tegen dat het zojuist heeft gelezen. Dit wijst op afkapping van de context. ollama ps toont meestal een CONTEXT-waarde die kleiner is dan u hebt ingesteld, omdat de omgevingsvariabele naar uw shell is gegaan in plaats van naar de systemd-unit.

Alles werkt, maar langzaam, en PROCESSOR toont 100% CPU of een CPU/GPU-verdeling. Meestal passen het model en de context niet volledig in het VRAM. Als PROCESSOR op een machine met een GPU 100% CPU leest, sluit u eerst de andere oorzaak uit: Ollama heeft de GPU mogelijk helemaal niet gevonden. In de documentatie van Ollama staat dat het op Linux na een suspend/resume-cyclus soms geen NVIDIA-GPU detecteert en terugvalt op de CPU. Het opnieuw laden van het stuurprogramma met sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm omzeilt dit probleem. Als de GPU wel wordt gevonden en de verdeling blijft bestaan, verlaagt u de contextlengte of schakelt u over naar een kleiner model of een kleinere quantisatie. Voordat u het model opnieuw ophaalt, legt wat q4_K_M, q8_0 en fp16 elk aan geheugen kosten en waar de kwaliteit daadwerkelijk afneemt uit hoeveel ruimte een stap omlaag oplevert en wat u daarvoor inlevert. Unknown is ook een mogelijke PROCESSOR-waarde; dit bewijst niet dat CPU-offloading wordt gebruikt.

FAQ

Kan ik Claude Code naar Ollama laten verwijzen?

Ja, maar niet met een OpenAI-compatibele URL. Claude Code gebruikt de Anthropic Messages API en Ollama biedt die structuur aan op /v1/messages op dezelfde poort 11434. Exporteer ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama en een lege ANTHROPIC_API_KEY en start de applicatie met claude --model qwen3-coder:30b. Met ollama launch claude worden dezelfde instellingen automatisch voor u geschreven. De compatibiliteitslaag implementeert tool_choice en promptcaching niet en heeft geen endpoint voor het tellen van tokens. De gerapporteerde aantallen tokens zijn daarom benaderingen.

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 zonder foutmelding is verwijderd. Ollama bepaalt de standaardcontext op basis van het gedetecteerde VRAM-totaal, na aftrek van de geconfigureerde overhead per GPU: onder 23 GiB is de standaard 4,096 tokens, van 23 tot minder dan 47 GiB is dit 32,768 tokens en bij 47 GiB of meer is dit 262,144 tokens. Stel OLLAMA_CONTEXT_LENGTH=64000 in de systemd-unit in, start Ollama opnieuw en controleer of de kolom CONTEXT in ollama ps de nieuwe waarde toont.

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

Kies het grootste model met het label tools dat met een contextvenster van 64k in het geheugen past. Geef de voorkeur aan een model dat voor code is geoptimaliseerd. qwen3-coder:30b is het gebruikelijke 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 een download start. Onder ongeveer 14B parameters kan een model nog steeds goed antwoorden op vragen over code, maar toch mislukken bij bewerkingen in meerdere stappen. Agentwerk is namelijk gevoelig voor kleine opmaakfouten in toolaanroepen. Test het model met één echte taak uit uw eigen repository in plaats van met een voorbeeldprompt.

Heb ik een GPU nodig om een coding-agent met mijn eigen model uit te voeren?

In de praktijk wel. Inference die alleen de CPU gebruikt werkt en is geschikt voor afzonderlijke vragen, maar een agent verstuurt per taak veel verzoeken en leest daarbij telkens een lange geschiedenis opnieuw. Daardoor kan een lage tokensnelheid een taak van twee minuten in een uur veranderen. Controleer de kolom PROCESSOR in ollama ps: 100% CPU of een CPU/GPU-splitsing wijst op CPU-gebruik, wat inference vertraagt. Unknown bewijst niet dat CPU-offloading plaatsvindt.

Was dit artikel nuttig?

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