Ollama

Lokale en LAN Ollama-hosts hebben geen echte bearer-token nodig. OpenClaw gebruikt de lokale ollama-local-markering alleen voor loopback, private-network-, .local- en kale hostnaam-Ollama-base-URL's.

Externe openbare hosts en Ollama Cloud (https://ollama.com) vereisen een echte credential via OLLAMA_API_KEY, een auth-profiel of de apiKey van de provider.

Aangepaste provider-id's die api: "ollama" instellen, volgen dezelfde regels. Bijvoorbeeld: een ollama-remote-provider die naar een private LAN Ollama-host wijst, kan apiKey: "ollama-local" gebruiken en sub-agents zullen die markering via de Ollama-providerhook oplossen in plaats van deze als een ontbrekende credential te behandelen. Geheugenzoekopdrachten kunnen ook agents.defaults.memorySearch.provider instellen op die aangepaste provider-id, zodat embeddings het overeenkomende Ollama-endpoint gebruiken.

auth-profiles.json slaat de credential voor een provider-id op. Plaats endpointinstellingen (baseUrl, api, model-id's, headers, timeouts) in models.providers.<id>. Oudere platte auth-profielbestanden zoals { "ollama-windows": { "apiKey": "ollama-local" } } zijn geen runtime-indeling; voer openclaw doctor --fix uit om ze te herschrijven naar het canonieke ollama-windows:default API-key-profiel met een back-up. baseUrl in dat bestand is compatibiliteitsruis en moet naar providerconfiguratie worden verplaatst.

Wanneer Ollama wordt gebruikt voor geheugenembeddings, is bearer-auth beperkt tot de host waar deze is gedeclareerd:

• Een sleutel op providerniveau wordt alleen naar de Ollama-host van die provider verzonden.
• agents.*.memorySearch.remote.apiKey wordt alleen naar de externe embeddinghost ervan verzonden.
• Een pure OLLAMA_API_KEY-omgevingswaarde wordt behandeld als de Ollama Cloud-conventie en wordt standaard niet naar lokale of zelfgehoste hosts verzonden.

Gebruik dit wanneer Ollama op dezelfde machine draait als de Gateway en je wilt dat OpenClaw de geïnstalleerde modellen automatisch ontdekt.

ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

Dit pad houdt de configuratie minimaal. Voeg geen models.providers.ollama-blok toe tenzij je modellen handmatig wilt definiëren.

Gebruik native Ollama-URL's voor LAN-hosts. Voeg geen /v1 toe.

{
  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 het contextbudget aan de OpenClaw-kant. params.num_ctx wordt voor het verzoek naar Ollama gestuurd. Houd ze op elkaar afgestemd wanneer je hardware de volledige geadverteerde context van het model niet kan draaien.

Gebruik dit wanneer je geen lokale daemon draait en gehoste Ollama-modellen rechtstreeks wilt gebruiken.

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" },
    },
  },
}

Gebruik dit wanneer een lokale of LAN-Ollama-daemon is aangemeld met ollama signin en zowel lokale modellen als :cloud-modellen moet bedienen.

ollama signin
ollama pull gemma4

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        models: [
          { id: "gemma4", name: "gemma4", input: ["text"] },
          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/gemma4",
        fallbacks: ["ollama/kimi-k2.5:cloud"],
      },
    },
  },
}

Gebruik aangepaste provider-ID's wanneer je meer dan één Ollama-server hebt. Elke provider krijgt zijn eigen host, modellen, authenticatie, timeout en modelrefs.

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

Wanneer OpenClaw het verzoek verstuurt, wordt het actieve providerprefix verwijderd zodat ollama-large/qwen3.5:27b Ollama bereikt als qwen3.5:27b.

Sommige lokale modellen kunnen eenvoudige prompts beantwoorden, maar hebben moeite met het volledige agenttooloppervlak. Begin met het beperken van tools en context voordat je globale runtime-instellingen wijzigt.

{
  agents: {
    defaults: {
      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 betrouwbaar faalt op toolschema's. Het ruilt agentcapaciteit in voor stabiliteit. localModelLean verwijdert de browser-, cron- en berichttools uit het agentoppervlak, maar verandert de runtimecontext of denkmodus van Ollama niet. Combineer het met expliciete params.num_ctx en params.thinking: false voor kleine Qwen-achtige denkmodellen die in een lus terechtkomen of hun responsbudget besteden aan verborgen redenering.

Als je in plaats daarvan het OpenAI-compatibele endpoint moet gebruiken (bijvoorbeeld achter een proxy die alleen de OpenAI-indeling ondersteunt), stel api: "openai-completions" dan expliciet in:

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

Deze modus ondersteunt streaming en toolaanroepen mogelijk niet tegelijk. Mogelijk moet je streaming uitschakelen met params: { streaming: false } in de modelconfiguratie.

Wanneer api: "openai-completions" met Ollama wordt gebruikt, injecteert OpenClaw standaard options.num_ctx, zodat Ollama niet stil terugvalt op een contextvenster van 4096. Als je proxy/upstream onbekende options-velden weigert, schakel dit gedrag 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 door Ollama wordt gerapporteerd wanneer beschikbaar, inclusief grotere PARAMETER num_ctx-waarden uit aangepaste Modelfiles. Anders valt het terug op het standaard Ollama-contextvenster dat door OpenClaw wordt gebruikt.

Je kunt standaardwaarden op providerniveau instellen voor contextWindow, contextTokens en maxTokens voor elk model onder die Ollama-provider, en ze daarna per model overschrijven wanneer nodig. contextWindow is het prompt- en Compaction-budget van OpenClaw. Native Ollama-requests laten options.num_ctx leeg tenzij je expliciet params.num_ctx configureert, zodat Ollama zijn eigen model, OLLAMA_CONTEXT_LENGTH of op VRAM gebaseerde standaard kan toepassen. Stel params.num_ctx in om Ollama's runtimecontext per request te begrenzen of af te dwingen zonder een Modelfile opnieuw te bouwen; ongeldige, nul-, negatieve en niet-eindige waarden worden genegeerd. De OpenAI-compatibele Ollama-adapter injecteert nog steeds standaard options.num_ctx vanuit de geconfigureerde params.num_ctx of contextWindow; schakel dat uit met injectNumCtxForOpenAICompat: false als je upstream options weigert.

Native Ollama-modelvermeldingen accepteren ook de algemene Ollama-runtimeopties onder params, waaronder temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread en use_mmap. OpenClaw stuurt alleen Ollama-requestsleutels door, zodat OpenClaw-runtimeparams zoals streaming niet naar Ollama lekken. Gebruik params.think of params.thinking om top-level Ollama think te versturen; 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,
            },
          }
        ]
      }
    }
  }
}

Per-model agents.defaults.models["ollama/<model>"].params.num_ctx werkt ook. Als beide zijn geconfigureerd, wint de expliciete providermodelvermelding van de agentstandaard.

Voor native Ollama-modellen stuurt OpenClaw denkcontrole door zoals Ollama die verwacht: top-level think, niet options.think. Automatisch ontdekte modellen waarvan de /api/show-respons de thinking-capaciteit bevat, bieden /think low, /think medium, /think high en /think max; niet-denkende modellen bieden alleen /think off.

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

Je kunt ook een modelstandaard instellen:

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

Per-model params.think of params.thinking kan Ollama-API-denken uitschakelen of afdwingen voor een specifiek geconfigureerd model. OpenClaw behoudt die expliciete modelparams wanneer de actieve run alleen de impliciete standaard off heeft; niet-off runtimecommando's zoals /think medium overschrijven de actieve run nog steeds.

OpenClaw behandelt modellen met namen zoals deepseek-r1, reasoning of think standaard als redeneercapabel.

ollama pull deepseek-r1:32b

Er is geen aanvullende configuratie nodig. OpenClaw markeert ze automatisch.

Ollama is gratis en draait lokaal, dus alle modelkosten zijn ingesteld op $0. Dit geldt voor zowel automatisch ontdekte als handmatig gedefinieerde modellen.

De gebundelde Ollama-Plugin registreert een provider voor geheugen-embeddings voor geheugenzoekopdrachten. Deze gebruikt de geconfigureerde Ollama-basis-URL en API-sleutel, roept Ollama's huidige /api/embed-endpoint aan en bundelt meerdere geheugenfragmenten waar mogelijk in één input-request.

Embeddings tijdens query's gebruiken retrievalprefixen voor modellen die ze vereisen of aanbevelen, waaronder nomic-embed-text, qwen3-embedding en mxbai-embed-large. Geheugendocumentbatches blijven onbewerkt, zodat bestaande indexen geen formaatmigratie nodig hebben.

Om Ollama te selecteren als embeddingprovider voor geheugenzoekopdrachten:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        remote: {
          // Default for Ollama. Raise on larger hosts if reindexing is too slow.
          nonBatchConcurrency: 1,
        },
      },
    },
  },
}

Houd voor een externe embeddinghost de auth beperkt tot die host:

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

OpenClaw's Ollama-integratie gebruikt standaard de native Ollama-API (/api/chat), die streaming en toolaanroepen tegelijk volledig ondersteunt. Er is geen speciale configuratie nodig.

Voor native /api/chat-verzoeken stuurt OpenClaw denkbesturing ook rechtstreeks door naar Ollama: /think off en openclaw agent --thinking off sturen top-level think: false, tenzij een expliciete modelwaarde params.think/params.thinking is geconfigureerd, terwijl /think low|medium|high de overeenkomende top-level think-inspanningstekenreeks sturen. /think max wordt gekoppeld aan Ollama's hoogste native inspanning, think: "high".

Op WSL2 met NVIDIA/CUDA maakt de officiële Ollama Linux-installer een ollama.service systemd-unit met Restart=always. Als die service automatisch start en een GPU-ondersteund model laadt tijdens het opstarten van WSL2, kan Ollama hostgeheugen vastzetten terwijl het model wordt geladen. Hyper-V-geheugenterugwinning kan die vastgezette pagina's niet altijd terugwinnen, waardoor Windows de WSL2-VM kan beëindigen, systemd Ollama opnieuw start en de lus zich herhaalt.

Veelvoorkomend bewijs:

• herhaalde WSL2-herstarts of beëindigingen vanaf de Windows-kant
• hoge CPU in app.slice of ollama.service kort na het opstarten van WSL2
• SIGTERM van systemd in plaats van een Linux OOM-killer-gebeurtenis

OpenClaw logt een opstartwaarschuwing wanneer het WSL2 detecteert, ollama.service ingeschakeld is met Restart=always en zichtbare CUDA-markeringen aanwezig zijn.

Beperking:

sudo systemctl disable ollama

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

[experimental]
autoMemoryReclaim=disabled

Stel een kortere keep-alive in de Ollama-serviceomgeving in, of start Ollama alleen handmatig wanneer je het nodig hebt:

export OLLAMA_KEEP_ALIVE=5m
ollama serve

Zie ollama/ollama#11317.

Zorg dat Ollama draait en dat je OLLAMA_API_KEY (of een auth-profiel) hebt ingesteld, en dat je geen expliciete models.providers.ollama-vermelding hebt gedefinieerd:

ollama serve

Controleer of de API toegankelijk is:

curl http://localhost:11434/api/tags

Als je model niet wordt vermeld, haal het model dan lokaal op of definieer het expliciet in models.providers.ollama.

ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model

Controleer of Ollama op de juiste poort draait:

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

Controleer dit vanaf dezelfde machine en runtime waarop de Gateway draait:

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

Veelvoorkomende oorzaken:

• baseUrl verwijst naar localhost, maar de Gateway draait in Docker of op een andere host.
• De URL gebruikt /v1, waardoor OpenAI-compatibel gedrag wordt geselecteerd in plaats van native Ollama.
• De externe host heeft firewall- of LAN-bindingswijzigingen nodig aan de Ollama-kant.
• Het model is aanwezig op de daemon van je laptop, maar niet op de externe daemon.

Dit betekent meestal dat de provider de OpenAI-compatibele modus gebruikt of dat het model geen toolschema's aankan.

Geef de voorkeur aan native Ollama-modus:

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

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

Gehoste Kimi/GLM-antwoorden die bestaan uit lange, niet-linguïstische reeksen symbolen worden behandeld als mislukte provideruitvoer in plaats van als een geslaagd assistentantwoord. Daardoor kunnen normale retries, fallback of foutafhandeling het overnemen zonder de beschadigde tekst in de sessie op te slaan.

Als dit herhaaldelijk gebeurt, leg dan de ruwe modelnaam, het huidige sessiebestand en of de run Cloud + Local of Cloud only gebruikte vast, en probeer daarna een nieuwe sessie en een fallbackmodel:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --json
openclaw models set ollama/gemma4

Grote lokale modellen kunnen een lange eerste laadactie nodig hebben voordat streaming begint. Houd de time-out beperkt tot de Ollama-provider en vraag Ollama eventueel om het model tussen beurten geladen te houden:

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

Als de host zelf traag verbindingen accepteert, verlengt timeoutSeconds ook de bewaakte Undici-verbindingstime-out voor deze provider.

Veel Ollama-modellen adverteren contexten die groter zijn dan je hardware comfortabel kan uitvoeren. Native Ollama gebruikt Ollama's eigen standaard runtimecontext, tenzij je params.num_ctx instelt. Beperk zowel het budget van OpenClaw als de aanvraagcontext van Ollama wanneer je voorspelbare first-token-latentie wilt:

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

Verlaag eerst contextWindow als OpenClaw te veel prompt verstuurt. Verlaag params.num_ctx als Ollama een runtimecontext laadt die te groot is voor de machine. Verlaag maxTokens als generatie te lang duurt.