Ollama

Ollama-URLs mit Loopback-Adressen, privaten Netzwerken, .local und einfachen Hostnamen benötigen kein echtes Bearer-Token. OpenClaw verwendet dafür die Markierung ollama-local.

Öffentliche Remote-Hosts und https://ollama.com erfordern echte Anmeldedaten: OLLAMA_API_KEY, ein Authentifizierungsprofil oder 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 Provider ollama-remote, der auf einen privaten LAN-Host verweist, apiKey: "ollama-local" verwenden; Sub-Agenten lösen diese Markierung über den Ollama-Provider-Hook auf, statt sie als fehlende Anmeldedaten zu behandeln. agents.defaults.memorySearch.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; legen Sie Endpunkteinstellungen (baseUrl, api, Modelle, Header, Zeitüberschreitungen) unter models.providers.<id> ab. Ä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 baseUrl-Wert in dieser Legacy-Datei ist überflüssig 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.
• agents.*.memorySearch.remote.apiKey wird nur an den zugehörigen Remote-Host für Einbettungen gesendet.
• Ein ausschließlich über die Umgebungsvariable OLLAMA_API_KEY festgelegter Wert 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 Werte aufeinander abgestimmt, wenn die Hardware nicht den vollständigen angegebenen Kontext des Modells verarbeiten 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 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, 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 das Präfix des aktiven Providers (mit Rückgriff auf ein einfaches Präfix ollama/), bevor Ollama aufgerufen wird. Daher erreicht ollama-large/qwen3.5:27b Ollama als qwen3.5:27b.

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 – dies tauscht Agentenfunktionen gegen Stabilität. localModelLean entfernt umfangreiche Browser-, Cron-, Nachrichten-, Mediengenerierungs-, Sprach- und PDF-Tools aus dem direkten Agentenumfang, sofern sie nicht ausdrücklich erforderlich sind, und verschiebt größere Kataloge hinter die Tool-Suche. Die Laufzeitkontext- oder Denkmodus-Einstellungen von Ollama werden dadurch nicht geändert. Kombinieren Sie dies bei kleinen Qwen-artigen Denkmodellen, die Schleifen erzeugen oder ihr Budget für verborgenes Schlussfolgern aufwenden, mit params.num_ctx und params.thinking: false.

Legen Sie api: "openai-completions" für einen Proxy hinter /v1/chat/completions ausdrücklich 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 müssen Sie für das Modell params: { streaming: false } festlegen.

OpenClaw fügt in diesem Modus standardmäßig options.num_ctx ein, damit Ollama nicht stillschweigend auf einen Kontext mit 4096 Token zurückfällt. Wenn Ihr Proxy unbekannte options-Felder 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 greift es auf das standardmäßige Ollama-Kontextfenster von OpenClaw zurück.

contextWindow, contextTokens und maxTokens auf Provider-Ebene legen Standardwerte für jedes Modell dieses Providers fest und können pro Modell überschrieben werden. contextWindow ist das eigene Prompt-/Compaction-Budget von OpenClaw. Native /api/chat-Anfragen lassen options.num_ctx unverändert, sofern Sie params.num_ctx nicht ausdrücklich festlegen. Daher verwendet Ollama den eigenen Modellstandard, OLLAMA_CONTEXT_LENGTH oder einen VRAM-basierten Standardwert. Ungültige, nullwertige, negative oder nicht endliche Werte für params.num_ctx werden ignoriert. Wenn eine ältere Konfiguration nur 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 vorgeschaltete 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 Anfragenfelder 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,            },          }        ]      }    }  }}

agents.defaults.models["ollama/<model>"].params.num_ctx pro Modell funktioniert ebenfalls. Der ausdrückliche Modell-Eintrag des Providers hat Vorrang, wenn beide Werte festgelegt sind.

OpenClaw leitet den Denkmodus so weiter, wie Ollama ihn erwartet: als think auf oberster Ebene, nicht als 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 Denkmodus stellen nur /think off bereit.

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

Oder legen Sie einen Modellstandard fest:

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

Pro Modell können params.think/params.thinking 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 Standardwert off verwendet; ein Laufzeitbefehl mit einem anderen Wert als „off“, beispielsweise /think medium, überschreibt sie weiterhin. Eine aktivierte Denkanforderung wird niemals an ein Modell gesendet, das ausdrücklich mit reasoning: false gekennzeichnet ist; eine Anforderung mit think: false wird unabhängig davon immer gesendet.

Modelle mit den Namen 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. Es 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.

Wenn proxy.enabled=true gilt, verwenden Embedding-Anforderungen an den exakten hostlokalen Loopback-Ursprung, der aus der konfigurierten baseUrl abgeleitet wird, den geschützten 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 und öffentlichen Netzwerk verbleiben immer auf dem verwalteten Proxy-Pfad, und Weiterleitungen zu einem anderen Host/Port übernehmen diese Vertrauensstellung nicht. proxy.loopbackMode: "proxy" leitet Loopback-Datenverkehr trotzdem durch den Proxy; proxy.loopbackMode: "block" verweigert ihn vor dem Verbindungsaufbau – siehe Verwalteter Proxy.

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

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

Beschränken Sie bei einem Remote-Embedding-Host die Authentifizierung auf diesen Host:

{  agents: {    defaults: {      memorySearch: {        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 gleichzeitig 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 auf oberster Ebene think: false, sofern nicht ausdrücklich params.think/params.thinking konfiguriert ist; /think low|medium|high sendet die entsprechende Aufwandszeichenfolge; /think max wird Ollamas höchstem Aufwand zugeordnet: think: "high".

Unter WSL2 mit NVIDIA/CUDA erstellt das offizielle Ollama-Linux-Installationsprogramm eine systemd-Einheit namens ollama.service 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 dauerhaft belegen; die Hyper-V-Speicherrückgewinnung kann diese Seiten nicht immer freigeben. Dadurch kann Windows die WSL2-VM beenden, systemd startet Ollama neu und die Schleife wiederholt sich.

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

OpenClaw protokolliert beim Start eine Warnung, wenn WSL2, eine aktivierte ollama.service mit Restart=always und sichtbare CUDA-Markierungen erkannt werden.

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

Oder verkürzen Sie die Keep-Alive-Zeit beziehungsweise starten Sie Ollama nur bei Bedarf manuell:

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 ausdrücklich definiert ist:

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

Rufen Sie das Modell lokal ab oder definieren Sie es ausdrücklich 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 Computer und in derselben Laufzeitumgebung, in der auch der Gateway ausgeführt wird:

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

Häufige Ursachen:

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

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

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

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

Gehostete Kimi-/GLM-Antworten, die aus langen, nicht sprachlichen Symbolfolgen bestehen, werden als fehlgeschlagener Provider-Aufruf statt als erfolgreiche Antwort behandelt. Dadurch übernimmt die normale Wiederholungs-/Fallback-/Fehlerbehandlung, anstatt beschädigten Text in der Sitzung zu speichern.

Wenn das Problem erneut auftritt, erfassen Sie den Modellnamen, die aktuelle Sitzungsdatei und ob für den Lauf Cloud + Local oder Cloud only verwendet wurde. 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. Beschränken Sie das Zeitlimit auf den Ollama-Provider und halten Sie das Modell optional zwischen Durchläufen 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 auch das geschützte Verbindungszeitlimit für diesen Provider.

Viele Modelle geben Kontextgrößen an, die Ihre Hardware nicht problemlos verarbeiten kann. 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 erzielen:

{  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 zu viel Prompt sendet. Verringern Sie params.num_ctx, wenn der Ollama-Laufzeitkontext für den Computer zu groß ist. Verringern Sie maxTokens, wenn die Generierung zu lange dauert.