Ollama

Ollama-URLs für Loopback, private Netzwerke, .local und einfache Hostnamen benötigen kein echtes Bearer-Token. OpenClaw verwendet für diese die Markierung ollama-local.

Öffentliche Remote-Hosts und https://ollama.com erfordern echte Anmeldedaten: OLLAMA_API_KEY, ein Authentifizierungsprofil oder den Wert apiKey des Providers. Bevorzugen Sie für die direkte gehostete Nutzung den Provider ollama-cloud.

Für einen benutzerdefinierten Provider mit api: "ollama" gelten dieselben Regeln. Beispielsweise kann ein auf einen privaten LAN-Host verweisender ollama-remote-Provider apiKey: "ollama-local" verwenden; Sub-Agenten lösen diese Markierung über den Ollama-Provider-Hook auf, anstatt sie als fehlende Anmeldedaten zu behandeln. memory.search.provider kann ebenfalls auf eine benutzerdefinierte Provider-ID verweisen, damit Einbettungen diesen Ollama-Endpunkt verwenden.

auth-profiles.json speichert die Anmeldedaten für eine Provider-ID; speichern Sie Endpunkteinstellungen (baseUrl, api, Modelle, Header, Zeitüberschreitungen) in models.providers.<id>. Ältere flache Dateien wie { "ollama-windows": { "apiKey": "ollama-local" } } sind kein Laufzeitformat; openclaw doctor --fix schreibt sie mit einer Sicherung in ein kanonisches API-Schlüsselprofil ollama-windows:default um. Ein Wert baseUrl in dieser Legacy-Datei ist irrelevant und sollte in die Provider-Konfiguration verschoben werden.

Die Bearer-Authentifizierung für Ollama-Speicher-Einbettungen ist auf den Host beschränkt, für den sie deklariert wurde:

• Ein Schlüssel auf Provider-Ebene wird nur an den Host dieses Providers gesendet.
• memory.search.remote.apiKey und agentenspezifische Überschreibungen werden nur an ihren Remote-Einbettungshost gesendet.
• Ein reiner Umgebungswert OLLAMA_API_KEY wird als Ollama-Cloud-Konvention behandelt und standardmäßig nicht an lokale oder selbst gehostete Hosts gesendet.

Ollama auf demselben Rechner wie das Gateway, automatisch erkannt:

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

Fügen Sie keinen models.providers.ollama-Block hinzu, sofern Sie keine manuellen Modelle benötigen.

{  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 ist das Kontextbudget von OpenClaw; params.num_ctx wird an Ollama gesendet. Halten Sie beide aufeinander abgestimmt, wenn die Hardware nicht den gesamten angekündigten Kontext des Modells ausführen kann.

Kein lokaler Daemon, direkt gehostete Modelle:

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

Informationen zur Verwendung der dedizierten Provider-ID ollama-cloud anstelle dieser Struktur finden Sie unter Ollama Cloud.

Benutzerdefinierte Provider-IDs beim Betrieb mehrerer Ollama-Server; jeder erhält einen eigenen Host, eigene Modelle, eine eigene Authentifizierung und ein eigenes Zeitlimit.

{  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 entfernt vor dem Aufruf von Ollama das Präfix des aktiven Providers (mit Rückgriff auf ein einfaches Präfix ollama/), sodass ollama-large/qwen3.5:27b Ollama als qwen3.5:27b erreicht.

Einige lokale Modelle verarbeiten einfache Prompts, haben jedoch Schwierigkeiten mit dem vollständigen Tool-Umfang des Agenten. Begrenzen Sie Tools und Kontext, bevor Sie globale Laufzeiteinstellungen ändern:

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

Verwenden Sie compat.supportsTools: false nur, wenn das Modell oder der Server bei Tool-Schemas zuverlässig fehlschlägt — dabei wird Agentenfunktionalität zugunsten der Stabilität aufgegeben. localModelLean entfernt ressourcenintensive Browser-, Cron-, Nachrichten-, Mediengenerierungs-, Sprach- und PDF-Tools aus dem direkten Agentenumfang, sofern sie nicht ausdrücklich erforderlich sind, und stellt größere Kataloge über die Tool-Suche bereit. Dies ändert weder den Laufzeitkontext noch den Denkmodus von Ollama. Kombinieren Sie es mit params.num_ctx und params.thinking: false für kleine Qwen-artige Denkmodelle, die Schleifen bilden oder ihr Budget für verborgenes Schlussfolgern aufwenden.

Legen Sie api: "openai-completions" ausdrücklich für einen Proxy hinter /v1/chat/completions fest:

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

Dieser Modus unterstützt möglicherweise nicht gleichzeitig Streaming und Tool-Aufrufe; eventuell benötigen Sie params: { streaming: false } für das Modell.

OpenClaw fügt in diesem Modus standardmäßig options.num_ctx ein, damit Ollama nicht unbemerkt auf einen Kontext mit 4096 Token zurückfällt. Wenn Ihr Proxy unbekannte Felder vom Typ options ablehnt, deaktivieren Sie dies:

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

Bei automatisch erkannten Modellen verwendet OpenClaw das von /api/show gemeldete Kontextfenster, einschließlich größerer PARAMETER num_ctx-Werte aus benutzerdefinierten Modelfiles; andernfalls wird auf das standardmäßige Ollama-Kontextfenster von OpenClaw zurückgegriffen.

contextWindow, contextTokens und maxTokens auf Provider-Ebene legen Standardwerte für jedes Modell unter diesem Provider fest und können pro Modell überschrieben werden. contextWindow ist OpenClaws eigenes Prompt-/Compaction-Budget. Native /api/chat-Anfragen lassen options.num_ctx ungesetzt, sofern Sie params.num_ctx nicht ausdrücklich festlegen; dadurch verwendet Ollama seinen eigenen modell-, OLLAMA_CONTEXT_LENGTH- oder VRAM-basierten Standardwert. Ungültige, nullwertige, negative oder nicht endliche params.num_ctx-Werte werden ignoriert. Wenn eine ältere Konfiguration ausschließlich contextWindow/maxTokens verwendete, um den Kontext nativer Anfragen zu erzwingen, führen Sie openclaw doctor --fix aus, um diese Werte nach params.num_ctx zu kopieren. Der OpenAI-kompatible Adapter fügt options.num_ctx weiterhin standardmäßig aus dem konfigurierten params.num_ctx oder contextWindow ein; deaktivieren Sie dies mit injectNumCtxForOpenAICompat: false, wenn das Upstream-System options ablehnt.

Native Modelleinträge akzeptieren unter params außerdem gängige Ollama-Laufzeitoptionen, die als native /api/chat-options weitergeleitet werden: 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 und num_thread. Einige Schlüssel (format, keep_alive, truncate, shift) werden als Anfragefelder auf oberster Ebene statt als verschachtelte options weitergeleitet. OpenClaw leitet nur diese Ollama-Anfrageschlüssel weiter, sodass reine Laufzeitparameter wie streaming niemals an Ollama gesendet werden. Verwenden Sie params.think (oder params.thinking), um think auf oberster Ebene festzulegen; false deaktiviert das Denken auf API-Ebene für Qwen-artige Denkmodelle.

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

Pro Modell funktioniert agents.defaults.models["ollama/<model>"].params.num_ctx ebenfalls; der explizite Provider-Modelleintrag hat Vorrang, wenn beide festgelegt sind.

OpenClaw leitet das Denken so weiter, wie Ollama es erwartet: think auf oberster Ebene, nicht options.think. Automatisch erkannte Modelle, deren /api/show eine thinking-Fähigkeit meldet, stellen /think low, /think medium, /think high und /think max bereit; Modelle ohne Denkfunktion stellen nur /think off bereit.

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

Alternativ können Sie einen Modellstandard festlegen:

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

Mit params.think/params.thinking pro Modell lässt sich das API-Denken für ein bestimmtes Modell deaktivieren oder erzwingen. OpenClaw behält diese explizite Konfiguration bei, wenn der aktive Lauf nur den impliziten Standard off verwendet; ein Laufzeitbefehl, der nicht „off“ entspricht, wie /think medium, setzt sie dennoch außer Kraft. Eine aktivierte Denkanforderung wird niemals an ein Modell gesendet, das explizit mit reasoning: false gekennzeichnet ist; eine think: false-Anforderung wird unabhängig davon immer gesendet.

Modelle namens deepseek-r1, reasoning, reason oder think werden standardmäßig als Reasoning-fähig behandelt — es ist keine zusätzliche Konfiguration erforderlich:

ollama pull deepseek-r1:32b

Ollama wird lokal ausgeführt und ist kostenlos, daher betragen sämtliche Modellkosten sowohl für automatisch erkannte als auch für manuell definierte Modelle 0.

Das mitgelieferte Ollama-Plugin registriert einen Provider für Speicher-Embeddings für die Speichersuche. Er verwendet die konfigurierte Ollama-Basis-URL und den API-Schlüssel, ruft /api/embed auf und fasst nach Möglichkeit mehrere Speicherabschnitte in einer input-Anforderung zusammen.

Bei proxy.enabled=true verwenden Embedding-Anforderungen an den exakten hostlokalen Loopback-Ursprung, der aus dem konfigurierten baseUrl abgeleitet wird, den abgesicherten direkten Pfad von OpenClaw anstelle des verwalteten Forward-Proxys. Der konfigurierte Hostname muss selbst localhost oder ein Loopback-IP-Literal sein — DNS-Namen, die lediglich zu Loopback aufgelöst werden, verwenden weiterhin den verwalteten Proxy-Pfad. Ollama-Hosts im LAN, Tailnet, privaten Netzwerk oder öffentlichen Netzwerk verbleiben stets auf dem verwalteten Proxy-Pfad, und Weiterleitungen zu einem anderen Host/Port übernehmen das Vertrauen nicht. proxy.loopbackMode: "proxy" leitet Loopback-Datenverkehr trotzdem durch den Proxy; proxy.loopbackMode: "block" lehnt ihn vor dem Verbindungsaufbau ab — siehe Verwalteter Proxy.

Embeddings zur Abfragezeit verwenden für Modelle, die diese erfordern oder empfehlen, Abrufpräfixe: nomic-embed-text, qwen3-embedding und mxbai-embed-large. Dokument-Batches bleiben unverändert, sodass vorhandene Indizes keine Formatmigration benötigen.

{  memory: {    search: {      provider: "ollama",      remote: {        // Standard für Ollama. Auf größeren Hosts erhöhen, wenn die Neuindizierung zu langsam ist.        nonBatchConcurrency: 1,      },    },  },}

Begrenzen Sie bei einem entfernten Embedding-Host die Authentifizierung auf diesen Host:

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

Ollama verwendet standardmäßig die native API (/api/chat), die Streaming und Tool-Aufrufe gemeinsam unterstützt — es ist keine besondere Konfiguration erforderlich.

Bei nativen Anforderungen wird die Steuerung des Denkens direkt weitergeleitet: /think off und openclaw agent --thinking off senden think: false auf oberster Ebene, sofern kein explizites params.think/params.thinking konfiguriert ist; /think low|medium|high senden die entsprechende Aufwandszeichenfolge; /think max wird Ollamas höchstem Aufwand think: "high" zugeordnet.

Unter WSL2 mit NVIDIA/CUDA erstellt das offizielle Ollama-Linux-Installationsprogramm eine ollama.service-systemd-Unit mit Restart=always. Wenn dieser Dienst automatisch startet und während des WSL2-Starts ein GPU-gestütztes Modell lädt, kann Ollama beim Laden Hostspeicher fest belegen; die Hyper-V-Speicherrückgewinnung kann diese Seiten nicht immer zurückgewinnen, sodass Windows die WSL2-VM beenden kann, systemd Ollama neu startet und sich die Schleife wiederholt.

Hinweise: wiederholte WSL2-Neustarts/-Beendigungen, hohe CPU-Auslastung in app.slice oder ollama.service direkt nach dem WSL2-Start und SIGTERM von systemd statt durch den Linux-OOM-Killer.

OpenClaw protokolliert beim Start eine Warnung, wenn es WSL2, aktiviertes ollama.service mit Restart=always und sichtbare CUDA-Markierungen erkennt.

Abhilfe:

sudo systemctl disable ollama

Fügen Sie auf der Windows-Seite Folgendes zu %USERPROFILE%\.wslconfig hinzu und führen Sie anschließend wsl --shutdown aus:

[experimental]autoMemoryReclaim=disabled

Alternativ können Sie die Keep-Alive-Zeit verkürzen bzw. Ollama nur bei Bedarf manuell starten:

export OLLAMA_KEEP_ALIVE=5mollama serve

Siehe ollama/ollama#11317.

Vergewissern Sie sich, dass Ollama ausgeführt wird, OLLAMA_API_KEY (oder ein Authentifizierungsprofil) festgelegt ist und models.providers.ollama nicht explizit definiert ist:

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

Rufen Sie das Modell lokal ab oder definieren Sie es explizit in models.providers.ollama:

ollama list  # Anzeigen, was installiert istollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Oder ein anderes Modell

Überprüfen Sie dies auf demselben Rechner und in derselben Laufzeitumgebung, in der das Gateway ausgeführt wird:

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

Häufige Ursachen:

• baseUrl verweist auf localhost, aber das Gateway wird in Docker oder auf einem anderen Host ausgeführt.
• Die URL verwendet /v1, wodurch OpenAI-kompatibles Verhalten anstelle des nativen Ollama-Verhaltens ausgewählt wird.
• Der entfernte Host erfordert Änderungen an der Firewall oder LAN-Bindung.
• Das Modell befindet sich im Daemon Ihres Laptops, jedoch nicht im entfernten Daemon.

Üblicherweise befindet sich der Provider im OpenAI-kompatiblen Modus oder das Modell kann Tool-Schemas nicht verarbeiten. Bevorzugen Sie den nativen Modus:

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

Wenn ein kleines lokales Modell bei Tool-Schemas weiterhin fehlschlägt, legen Sie compat.supportsTools: false für diesen Modelleintrag fest und testen Sie erneut.

Gehostete Kimi-/GLM-Antworten, die aus langen Folgen nichtsprachlicher Symbole bestehen, werden als fehlgeschlagener Provider-Aufruf und nicht als erfolgreiche Antwort behandelt, sodass die normale Wiederholungs-/Fallback-/Fehlerbehandlung übernimmt, statt beschädigten Text dauerhaft in der Sitzung zu speichern.

Wenn das Problem erneut auftritt, erfassen Sie den Modellnamen, die aktuelle Sitzungsdatei und ob der Lauf Cloud + Local oder Cloud only verwendet hat. Versuchen Sie anschließend eine neue Sitzung und ein Fallback-Modell:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Antworten Sie exakt mit: ok" --jsonopenclaw models set ollama/gemma4

Große lokale Modelle können beim ersten Laden viel Zeit benötigen. Begrenzen Sie die Zeitüberschreitung auf den Ollama-Provider und lassen Sie das Modell optional zwischen Interaktionen geladen:

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

Wenn der Host selbst Verbindungen nur langsam annimmt, verlängert timeoutSeconds außerdem die abgesicherte Verbindungszeitüberschreitung für diesen Provider.

Viele Modelle geben Kontextgrößen an, die auf Ihrer Hardware nicht problemlos ausgeführt werden können. Das native Ollama verwendet seinen eigenen Laufzeitstandard, sofern params.num_ctx nicht festgelegt ist. Begrenzen Sie sowohl das Budget von OpenClaw als auch den Anforderungskontext von Ollama, um eine vorhersagbare Latenz bis zum ersten Token zu erreichen:

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

Verringern Sie contextWindow, wenn OpenClaw einen zu großen Prompt sendet. Verringern Sie params.num_ctx, wenn der Laufzeitkontext von Ollama für den Rechner zu groß ist. Verringern Sie maxTokens, wenn die Generierung zu lange dauert.