Ollama koppelen aan uw coding agent: zo stelt u het in

Wat u verbindt

U kunt Ollama gebruiken met uw coding 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 bedient twee verzoekstructuren tegelijkertijd. /v1/chat/completions is de OpenAI-compatibele structuur, waarbij de documentatie van Ollama aangeeft dat de key vereist is maar wordt genegeerd. /v1/messages is de Anthropic-compatibele structuur, de taal die Claude Code spreekt. Uw agent spreekt al een van deze twee, dus er verandert verder niets aan de configuratie.

Dat onderdeel kost vijf minuten. Of het resultaat bruikbaar is, hangt af van twee instellingen die bijna niemand wijzigt: 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. Dat dekt het merendeel van wat men in augustus 2026 verstaat onder een coding agent. Ze hanteren niet allemaal hetzelfde formaat, en in dat verschil schuilt de oorzaak van mislukte configuraties.

• 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 hiervoor moet ANTHROPIC_BASE_URL worden ingesteld op http://localhost:11434, waarbij Ollama /v1/messages aanbiedt.
• Codex gebruikt de OpenAI Responses API. Ollama biedt ook /v1/responses aan, 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.

Ollama installeren en een model ophalen 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 tool calling de werking van een agent bepaalt. De agent 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, toont de geheugenberekening voor de Qwen 27B-tag op een VPS wat er daadwerkelijk in 8 tot 64 GB past voordat u de download start.

Bevestig nu welke namen de server daadwerkelijk aanbiedt:

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

De strings in dat antwoord zijn wat uw agent-configuratie 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 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 op uw server is aangekomen en niet elders. 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 verzonden; dit resulteert in een factuur in plaats 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 bevat geen endpoint voor het tellen van tokens. De getoonde aantallen tokens zijn daarom benaderingen van de eigen tokenizer van het model. Claude Code verstuurt daarnaast 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 ollama_chat/-voorvoegsel boven ollama/. Het stelt u ook in staat 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 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 die 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 zonder GPU, vallen in de eerste rij: 4,096 tokens. Alleen een krachtige GPU krijgt de 262,144 tokens in de laatste rij.

Een agent verbruikt 4096 tokens voordat deze ook maar iets uitvoert. De systeemprompt, de tooldefinities, de lijst met bestanden in de repository en het eerste bestand dat wordt geopend, zijn al groter dan dat. Wat 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.

De documentatie van Ollama stelt dat taken zoals agents en coderingstools moeten worden ingesteld op ten minste 64000 tokens. 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"

Herlaad en herstart vervolgens:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps is de controle. Het toont 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 hier niet om vragen. Bovendien is de instelling per server, dus elke agent die u naar de server wijst, neemt deze over. 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 groter 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 wordt verplaatst, 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 van uw machine te vinden. Het bepalen van de juiste machinegrootte voordat u deze aanschaft, wordt behandeld in hoeveel RAM en CPU een VPS voor een codeer-agent nodig heeft.

Het model geladen houden tussen verzoeken

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

OLLAMA_KEEP_ALIVE accepteert een tijdsduur-string zoals 10m of 24h, een simpel aantal 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 het enige middel waarover u beschikt. Wanneer u het geheugen weer vrij wilt maken, ontlaadt ollama stop qwen3-coder:30b het model zonder de server te stoppen.

Ollama uitvoeren op een aparte server

Ollama bindt aan localhost. Om het 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 alleen binnen een privénetwerk. De documentatie van Ollama stelt 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. Houd de binding op localhost en forward de poort 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 het verschil niet. De andere optie is een VPN, waarbij Ollama gebonden is aan het VPN-adres in plaats van 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 problematisch wordt.

Waar een lokaal programmeermodel wint, en waar niet

Een agent die wordt aangestuurd door een model dat u zelf host, vervangt niet voor 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 tokens in een lus verbruikt niets extra, wat het tegenovergestelde is van een API met verbruiksafhankelijke kosten. Waar een GPU VPS rendabel is 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 behouden blijft. Een model in het bereik van 8B tot 14B op een bescheiden server zal een onjuist geformatteerde 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 prompt-probleem dat u kunt oplossen door de instructies aan te passen. Het is een kwestie van capaciteit.

Het verliest ook wanneer onjuistheden kostbaar zijn en u niet elke regel zult lezen. Geef het lokale model afgebakende taken waarvan u de uitvoer 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 verwijst naar 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 een tag benoemt die u nooit heeft binnengehaald, zal falen, zelfs als er een vergelijkbaar model is geïnstalleerd.

De agent antwoordt in proza en bewerkt nooit een bestand. Of het model heeft geen ondersteuning voor 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 gelezen. 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 naar een kleiner model of een kleinere kwantisatie.

FAQ

Kan ik Claude Code koppelen aan Ollama?

Ja, maar niet met een OpenAI-compatibele URL. Claude Code communiceert via 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 slechts 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 stelt de standaardcontext in op basis van het beschikbare VRAM. Onder de 24 GiB is die standaardwaarde 4,096 tokens, wat al wordt overschreden door de systeemprompt en de tooldefinities van een agent. Stel OLLAMA_CONTEXT_LENGTH=64000 in de systemd-unit in, herstart Ollama en controleer of de kolom CONTEXT in ollama ps de nieuwe waarde weergeeft.

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 voor een GPU-server met voldoende VRAM. Bij minder dan 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 zwaar afstraft. Test met een echte taak uit uw eigen repository in plaats van met een voorbeeldprompt.

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 leest bij elk verzoek een lange geschiedenis opnieuw in. Een lage tokensnelheid verandert een taak van twee minuten daardoor in een uur werk. 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 tokensnelheid scherp daalt.