Ollama

Loopback-, privénetwerk-, .local- en Ollama-URL's met alleen een hostnaam hebben geen echt bearer-token nodig. OpenClaw gebruikt hiervoor de markering ollama-local.

Openbare externe hosts en https://ollama.com vereisen echte aanmeldgegevens: OLLAMA_API_KEY, een authenticatieprofiel of de apiKey van de provider. Geef voor rechtstreeks gehost gebruik de voorkeur aan de provider ollama-cloud.

Voor een aangepaste provider met api: "ollama" gelden dezelfde regels. Een ollama-remote-provider die bijvoorbeeld naar een privéhost op het LAN verwijst, kan apiKey: "ollama-local" gebruiken; subagents verwerken die markering via de providerhook van Ollama in plaats van deze als ontbrekende aanmeldgegevens te behandelen. memory.search.provider kan ook naar een aangepaste provider-id verwijzen, zodat embeddings dat Ollama-eindpunt gebruiken.

auth-profiles.json bewaart de aanmeldgegevens voor een provider-id; plaats eindpuntinstellingen (baseUrl, api, modellen, headers en time-outs) in models.providers.<id>. Oudere platte bestanden zoals { "ollama-windows": { "apiKey": "ollama-local" } } zijn geen runtime-indeling; openclaw doctor --fix herschrijft ze met een back-up naar een canoniek API-sleutelprofiel van ollama-windows:default. Een waarde voor baseUrl in dat verouderde bestand is ruis en moet naar de providerconfiguratie worden verplaatst.

Bearer-authenticatie voor Ollama-geheugenembeddings is beperkt tot de host waarvoor deze is opgegeven:

• Een sleutel op providerniveau wordt alleen naar de host van die provider verzonden.
• memory.search.remote.apiKey en overrides per agent worden alleen naar hun externe embeddinghost verzonden.
• Een zuivere OLLAMA_API_KEY-omgevingsvariabele wordt behandeld als de conventie van Ollama Cloud en wordt standaard niet naar lokale/zelfgehoste hosts verzonden.

Ollama op dezelfde machine als de Gateway, automatisch gedetecteerd:

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

Voeg geen models.providers.ollama-blok toe, tenzij je handmatige modellen nodig hebt.

{  models: {    providers: {      ollama: {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 300,        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            reasoning: true,            input: ["text"],            params: {              num_ctx: 32768,              thinking: false,              keep_alive: "15m",            },          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/qwen3.5:9b" },    },  },}

contextWindow is OpenClaws contextbudget; params.num_ctx wordt naar Ollama verzonden. Houd ze op elkaar afgestemd wanneer de hardware niet de volledige geadverteerde context van het model kan uitvoeren.

Geen lokale daemon, rechtstreeks gehoste modellen:

export OLLAMA_API_KEY="your-ollama-api-key"

{  models: {    providers: {      ollama: {        baseUrl: "https://ollama.com",        apiKey: "OLLAMA_API_KEY",        api: "ollama",        models: [          {            id: "kimi-k2.5:cloud",            name: "kimi-k2.5:cloud",            reasoning: false,            input: ["text", "image"],            contextWindow: 128000,            maxTokens: 8192,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/kimi-k2.5:cloud" },    },  },}

Zie Ollama Cloud voor de specifieke provider-id ollama-cloud in plaats van deze structuur.

Aangepaste provider-id's bij het uitvoeren van meer dan één Ollama-server; elke server krijgt een eigen host, modellen, authenticatie en time-out.

{  models: {    providers: {      "ollama-fast": {        baseUrl: "http://mini.local:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],      },      "ollama-large": {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 420,        contextWindow: 131072,        maxTokens: 16384,        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],      },    },  },  agents: {    defaults: {      model: {        primary: "ollama-fast/gemma4",        fallbacks: ["ollama-large/qwen3.5:27b"],      },    },  },}

OpenClaw verwijdert het actieve providerprefix (met een kaal ollama/-prefix als terugvaloptie) voordat Ollama wordt aangeroepen, zodat ollama-large/qwen3.5:27b Ollama bereikt als qwen3.5:27b.

Sommige lokale modellen kunnen eenvoudige prompts verwerken, maar hebben moeite met de volledige toolset van de agent. Beperk tools en context voordat je algemene runtime-instellingen wijzigt:

{  agents: {    list: [      {        id: "local",        experimental: {          localModelLean: true,        },        model: { primary: "ollama/gemma4" },      },    ],  },  models: {    providers: {      ollama: {        baseUrl: "http://127.0.0.1:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [          {            id: "gemma4",            name: "gemma4",            input: ["text"],            params: { num_ctx: 32768 },            compat: { supportsTools: false },          },        ],      },    },  },}

Gebruik compat.supportsTools: false alleen wanneer het model of de server herhaaldelijk faalt op toolschema's — dit verruilt agentmogelijkheden voor stabiliteit. localModelLean verwijdert zware browser-, cron-, bericht-, mediageneratie-, spraak- en PDF-tools van het directe agentoppervlak, tenzij ze expliciet vereist zijn, en plaatst grotere catalogi achter Tool Search. Het verandert de runtimecontext of denkmodus van Ollama niet. Combineer het met params.num_ctx en params.thinking: false voor kleine Qwen-achtige denkmodellen die in een lus raken of hun budget aan verborgen redeneringen besteden.

Stel api: "openai-completions" expliciet in voor een proxy achter /v1/chat/completions:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // standaard: true        apiKey: "ollama-local",        models: [...]      }    }  }}

Deze modus ondersteunt mogelijk niet tegelijkertijd streaming en toolaanroepen; mogelijk is params: { streaming: false } op het model nodig.

OpenClaw injecteert in deze modus standaard options.num_ctx, zodat Ollama niet stilzwijgend terugvalt op een context van 4096 tokens. Als je proxy onbekende options-velden weigert, schakel dit dan uit:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: false,        apiKey: "ollama-local",        models: [...]      }    }  }}

Voor automatisch ontdekte modellen gebruikt OpenClaw het contextvenster dat /api/show rapporteert, inclusief grotere PARAMETER num_ctx-waarden uit aangepaste Modelfiles; anders valt het terug op het standaard Ollama-contextvenster van OpenClaw.

contextWindow, contextTokens en maxTokens op providerniveau stellen standaardwaarden in voor elk model onder die provider en kunnen per model worden overschreven. contextWindow is het eigen prompt-/Compaction-budget van OpenClaw. Native /api/chat-aanvragen laten options.num_ctx oningesteld, tenzij je params.num_ctx expliciet instelt, zodat Ollama zijn eigen standaardwaarde op basis van het model, OLLAMA_CONTEXT_LENGTH of VRAM toepast; ongeldige, nul-, negatieve of niet-eindige params.num_ctx-waarden worden genegeerd. Als een oudere configuratie alleen contextWindow/maxTokens gebruikte om de context van native aanvragen af te dwingen, voer dan openclaw doctor --fix uit om deze waarden naar params.num_ctx te kopiëren. De OpenAI-compatibele adapter injecteert nog steeds standaard options.num_ctx vanuit de geconfigureerde params.num_ctx of contextWindow; schakel dit uit met injectNumCtxForOpenAICompat: false als de upstream options weigert.

Native modelvermeldingen accepteren ook algemene Ollama-runtimeopties onder params, die worden doorgestuurd als native /api/chat options: num_keep, seed, num_predict, top_k, top_p, min_p, typical_p, repeat_last_n, temperature, repeat_penalty, presence_penalty, frequency_penalty, stop, num_batch, num_gpu, main_gpu, use_mmap en num_thread. Enkele sleutels (format, keep_alive, truncate, shift) worden als aanvraagvelden op het hoogste niveau doorgestuurd in plaats van genest onder options. OpenClaw stuurt alleen deze Ollama-aanvraagsleutels door, zodat uitsluitend voor de runtime bestemde parameters zoals streaming nooit naar Ollama worden verzonden. Gebruik params.think (of params.thinking) om think op het hoogste niveau in te stellen; false schakelt denken op API-niveau uit voor Qwen-achtige denkmodellen.

{  models: {    providers: {      ollama: {        contextWindow: 32768,        models: [          {            id: "llama3.3",            contextWindow: 131072,            maxTokens: 65536,            params: {              num_ctx: 32768,              temperature: 0.7,              top_p: 0.9,              thinking: false,            },          }        ]      }    }  }}

agents.defaults.models["ollama/<model>"].params.num_ctx per model werkt ook; de expliciete modelvermelding van de provider heeft voorrang als beide zijn ingesteld.

OpenClaw stuurt denken door zoals Ollama het verwacht: think op het hoogste niveau, niet options.think. Automatisch ontdekte modellen waarvan /api/show een thinking-mogelijkheid rapporteert, bieden /think low, /think medium, /think high en /think max; modellen zonder denkfunctie bieden alleen /think off.

openclaw agent --model ollama/gemma4 --thinking offopenclaw agent --model ollama/gemma4 --thinking low

Of stel een standaardwaarde voor een model in:

{  agents: {    defaults: {      models: {        "ollama/gemma4": {          thinking: "low",        },      },    },  },}

params.think/params.thinking per model kan API-denken voor een specifiek model uitschakelen of afdwingen. OpenClaw behoudt die expliciete configuratie wanneer de actieve uitvoering alleen de impliciete standaardwaarde off heeft; een runtimeopdracht die niet op uit staat, zoals /think medium, overschrijft deze nog steeds. Een ingeschakeld denkverzoek wordt nooit verzonden naar een model dat expliciet is gemarkeerd als reasoning: false; een think: false-verzoek wordt altijd verzonden.

Modellen met de naam deepseek-r1, reasoning, reason of think worden standaard behandeld als modellen met redeneervermogen — er is geen extra configuratie nodig:

ollama pull deepseek-r1:32b

Ollama wordt lokaal uitgevoerd en is gratis, dus alle modelkosten zijn 0 voor zowel automatisch ontdekte als handmatig gedefinieerde modellen.

De meegeleverde Ollama-plugin registreert een provider voor geheugen-embeddings voor zoeken in het geheugen. Deze gebruikt de geconfigureerde basis-URL en API-sleutel van Ollama, roept /api/embed aan en bundelt waar mogelijk meerdere geheugenfragmenten in één input-verzoek.

Wanneer proxy.enabled=true gebruiken embeddingverzoeken naar de exacte hostlokale loopback-oorsprong die is afgeleid van de geconfigureerde baseUrl het beveiligde directe pad van OpenClaw in plaats van de beheerde forwardproxy. De geconfigureerde hostnaam moet zelf localhost of een letterlijk loopback-IP-adres zijn — DNS-namen die alleen naar loopback worden omgezet, gebruiken nog steeds het beheerde proxypad. Ollama-hosts op het LAN, tailnet, privénetwerk en openbare netwerk blijven altijd het beheerde proxypad gebruiken, en omleidingen naar een andere host/poort nemen het vertrouwen niet over. proxy.loopbackMode: "proxy" leidt loopback-verkeer toch via de proxy; proxy.loopbackMode: "block" weigert het voordat verbinding wordt gemaakt — zie Beheerde proxy.

Embeddings tijdens zoekopdrachten gebruiken voorvoegsels voor ophalen bij modellen die deze vereisen of aanbevelen: nomic-embed-text, qwen3-embedding en mxbai-embed-large. Documentbatches blijven ongewijzigd, zodat bestaande indexen geen formaatmigratie nodig hebben.

{  memory: {    search: {      provider: "ollama",      remote: {        // Standaard voor Ollama. Verhoog dit op grotere hosts als opnieuw indexeren te langzaam gaat.        nonBatchConcurrency: 1,      },    },  },}

Beperk voor een externe embeddinghost de authenticatie tot die host:

{  memory: {    search: {      provider: "ollama",      model: "nomic-embed-text",      remote: {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        nonBatchConcurrency: 2,      },    },  },}

Ollama gebruikt standaard de native API (/api/chat), die streaming en toolaanroepen tegelijk ondersteunt — er is geen speciale configuratie nodig.

Voor native verzoeken wordt de denkcontrole rechtstreeks doorgestuurd: /think off en openclaw agent --thinking off verzenden think: false op het hoogste niveau, tenzij expliciet params.think/params.thinking is geconfigureerd; /think low|medium|high verzendt de bijbehorende inspanningswaarde; /think max wordt gekoppeld aan Ollama's hoogste inspanningsniveau, think: "high".

In WSL2 met NVIDIA/CUDA maakt het officiële Ollama-installatieprogramma voor Linux een ollama.service-systemd-eenheid met Restart=always. Als die service automatisch start en tijdens het opstarten van WSL2 een GPU-model laadt, kan Ollama tijdens het laden hostgeheugen vastzetten; Hyper-V-geheugenterugwinning kan die pagina's niet altijd terugwinnen, waardoor Windows de WSL2-VM kan beëindigen, systemd Ollama opnieuw start en de lus zich herhaalt.

Aanwijzingen: herhaaldelijk opnieuw opstarten/beëindigen van WSL2, hoog CPU-gebruik in app.slice of ollama.service direct na het starten van WSL2 en SIGTERM van systemd in plaats van de Linux OOM-killer.

OpenClaw registreert bij het opstarten een waarschuwing wanneer het WSL2 detecteert, ollama.service ingeschakeld is met Restart=always en CUDA-markeringen zichtbaar zijn.

Mitigatie:

sudo systemctl disable ollama

Voeg aan de Windows-kant het volgende toe aan %USERPROFILE%\.wslconfig en voer daarna wsl --shutdown uit:

[experimental]autoMemoryReclaim=disabled

Of verkort keep-alive/start Ollama alleen handmatig wanneer dat nodig is:

export OLLAMA_KEEP_ALIVE=5mollama serve

Zie ollama/ollama#11317.

Controleer of Ollama actief is, OLLAMA_API_KEY (of een authenticatieprofiel) is ingesteld en models.providers.ollama niet expliciet is gedefinieerd:

ollama servecurl http://localhost:11434/api/tags

Haal het model lokaal op of definieer het expliciet in models.providers.ollama:

ollama list  # Bekijk wat er is geïnstalleerdollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Of een ander model

Controleer dit vanaf dezelfde machine en runtime waarop de Gateway wordt uitgevoerd:

openclaw gateway status --deepcurl http://ollama-host:11434/api/tags

Veelvoorkomende oorzaken:

• baseUrl verwijst naar localhost, maar de Gateway wordt uitgevoerd in Docker of op een andere host.
• De URL gebruikt /v1, waardoor OpenAI-compatibel gedrag wordt geselecteerd in plaats van native Ollama.
• Voor de externe host moeten de firewall of LAN-binding worden aangepast.
• Het model staat op de daemon van je laptop, maar niet op de externe daemon.

Meestal bevindt de provider zich in de OpenAI-compatibele modus of kan het model geen toolschema's verwerken. Geef de voorkeur aan de native modus:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434",        api: "ollama",      },    },  },}

Als een klein lokaal model nog steeds niet met toolschema's overweg kan, stel dan compat.supportsTools: false in voor die modelvermelding en test opnieuw.

Gehoste Kimi/GLM-antwoorden die bestaan uit lange reeksen niet-talige symbolen worden behandeld als een mislukte provideraanroep en niet als een geslaagd antwoord, zodat de normale afhandeling voor opnieuw proberen, fallback en fouten het overneemt in plaats van beschadigde tekst in de sessie op te slaan.

Als dit opnieuw gebeurt, leg dan de modelnaam en het huidige sessiebestand vast, evenals of de uitvoering Cloud + Local of Cloud only gebruikte, en probeer vervolgens een nieuwe sessie en een fallbackmodel:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Antwoord exact met: ok" --jsonopenclaw models set ollama/gemma4

Grote lokale modellen kunnen de eerste keer veel tijd nodig hebben om te laden. Beperk de time-out tot de Ollama-provider en houd het model eventueel tussen beurten geladen:

{  models: {    providers: {      ollama: {        timeoutSeconds: 300,        models: [          {            id: "gemma4:26b",            name: "gemma4:26b",            params: { keep_alive: "15m" },          },        ],      },    },  },}

Als de host zelf langzaam verbindingen accepteert, verlengt timeoutSeconds ook de beveiligde verbindingstime-out voor deze provider.

Veel modellen adverteren contexten die groter zijn dan je hardware comfortabel kan uitvoeren. Native Ollama gebruikt zijn eigen standaardwaarde voor de runtime, tenzij params.num_ctx is ingesteld. Beperk zowel het budget van OpenClaw als de aanvraagcontext van Ollama voor een voorspelbare latentie tot het eerste token:

{  models: {    providers: {      ollama: {        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            params: { num_ctx: 32768, thinking: false },          },        ],      },    },  },}

Verlaag contextWindow als OpenClaw te veel prompttekst verzendt. Verlaag params.num_ctx als de runtimecontext van Ollama te groot is voor de machine. Verlaag maxTokens als het genereren te lang duurt.