Ollama

Lokale und LAN-Ollama-Hosts benötigen kein echtes Bearer-Token. OpenClaw verwendet die lokale Markierung ollama-local nur für loopback, private Netzwerke, .local und Ollama-Basis-URLs mit bloßem Hostnamen.

Remote-öffentliche Hosts und Ollama Cloud (https://ollama.com) benötigen echte Anmeldedaten über OLLAMA_API_KEY, ein Authentifizierungsprofil oder apiKey des Providers. Für die direkte gehostete Nutzung bevorzugen Sie den Provider ollama-cloud.

Benutzerdefinierte Provider-IDs, die api: "ollama" setzen, folgen denselben Regeln. Ein Provider ollama-remote, der auf einen privaten LAN-Ollama-Host zeigt, kann zum Beispiel apiKey: "ollama-local" verwenden, und Sub-Agents lösen diese Markierung über den Ollama-Provider-Hook auf, statt sie als fehlende Anmeldedaten zu behandeln. Die Memory-Suche kann außerdem agents.defaults.memorySearch.provider auf diese benutzerdefinierte Provider-ID setzen, damit Embeddings denselben Ollama-Endpunkt verwenden.

auth-profiles.json speichert die Anmeldedaten für eine Provider-ID. Legen Sie Endpunkteinstellungen (baseUrl, api, Modell-IDs, Header, Timeouts) in models.providers.<id> ab. Ältere flache Authentifizierungsprofildateien wie { "ollama-windows": { "apiKey": "ollama-local" } } sind kein Laufzeitformat; führen Sie openclaw doctor --fix aus, um sie mit Backup in das kanonische API-Key-Profil ollama-windows:default umzuschreiben. baseUrl in dieser Datei ist Kompatibilitätsrauschen und sollte in die Provider-Konfiguration verschoben werden.

Wenn Ollama für Memory-Embeddings verwendet wird, ist die Bearer-Authentifizierung auf den Host beschränkt, auf dem sie deklariert wurde:

• Ein Schlüssel auf Provider-Ebene wird nur an den Ollama-Host dieses Providers gesendet.
• agents.*.memorySearch.remote.apiKey wird nur an seinen Remote-Embedding-Host gesendet.
• Ein reiner Umgebungswert OLLAMA_API_KEY wird als Ollama-Cloud-Konvention behandelt und standardmäßig nicht an lokale oder selbst gehostete Hosts gesendet.

Verwenden Sie dies, wenn Ollama auf derselben Maschine wie der Gateway läuft und OpenClaw die installierten Modelle automatisch erkennen soll.

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

Dieser Pfad hält die Konfiguration minimal. Fügen Sie keinen models.providers.ollama-Block hinzu, es sei denn, Sie möchten Modelle manuell definieren.

Verwenden Sie native Ollama-URLs für LAN-Hosts. Fügen Sie kein /v1 hinzu.

{  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 OpenClaw-seitige Kontextbudget. params.num_ctx wird für die Anfrage an Ollama gesendet. Halten Sie beide Werte aufeinander abgestimmt, wenn Ihre Hardware nicht den vollständig beworbenen Kontext des Modells ausführen kann.

Verwenden Sie dies, wenn Sie keinen lokalen Daemon ausführen und gehostete Ollama-Modelle direkt verwenden möchten.

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

Verwenden Sie dies, wenn ein lokaler oder LAN-Ollama-Daemon mit ollama signin angemeldet ist und sowohl lokale Modelle als auch :cloud-Modelle bereitstellen soll.

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

Verwenden Sie benutzerdefinierte Provider-IDs, wenn Sie mehr als einen Ollama-Server haben. Jeder Provider erhält seinen eigenen Host, eigene Modelle, Authentifizierung, Timeout und Modellreferenzen.

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

Wenn OpenClaw die Anfrage sendet, wird das aktive Provider-Präfix entfernt, sodass ollama-large/qwen3.5:27b Ollama als qwen3.5:27b erreicht.

Einige lokale Modelle können einfache Prompts beantworten, haben aber Schwierigkeiten mit der vollständigen Agent-Tool-Oberfläche. Beginnen Sie damit, Tools und Kontext zu begrenzen, bevor Sie globale Runtime-Einstellungen ä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 Agent-Fähigkeiten gegen Stabilität. localModelLean entfernt Browser-, Cron- und Nachrichten-Tools von der direkten Agent-Oberfläche und platziert größere Kataloge standardmäßig hinter strukturierten Tool Search-Steuerelementen, außer wenn ein Lauf direkte Nachrichtenübermittlungssemantik beibehalten muss. Es ändert jedoch nicht Ollamas Runtime-Kontext oder Thinking-Modus. Kombinieren Sie es mit explizitem params.num_ctx und params.thinking: false für kleine Qwen-artige Thinking-Modelle, die in Schleifen geraten oder ihr Antwortbudget für verborgenes Reasoning verbrauchen.

Wenn Sie stattdessen den OpenAI-kompatiblen Endpunkt verwenden müssen (zum Beispiel hinter einem Proxy, der nur das OpenAI-Format unterstützt), setzen Sie api: "openai-completions" explizit:

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

Dieser Modus unterstützt Streaming und Tool Calling möglicherweise nicht gleichzeitig. Sie müssen Streaming eventuell mit params: { streaming: false } in der Modellkonfiguration deaktivieren.

Wenn api: "openai-completions" mit Ollama verwendet wird, injiziert OpenClaw standardmäßig options.num_ctx, damit Ollama nicht stillschweigend auf ein Kontextfenster von 4096 zurückfällt. Wenn Ihr Proxy/Upstream unbekannte options-Felder ablehnt, deaktivieren Sie dieses Verhalten:

{  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 Ollama gemeldete Kontextfenster, sofern verfügbar, einschließlich größerer PARAMETER num_ctx-Werte aus benutzerdefinierten Modelfiles. Andernfalls fällt es auf das von OpenClaw verwendete standardmäßige Ollama-Kontextfenster zurück.

Sie können Standardwerte auf Provider-Ebene für contextWindow, contextTokens und maxTokens für jedes Modell unter diesem Ollama-Provider festlegen und sie bei Bedarf pro Modell überschreiben. contextWindow ist das Prompt- und Compaction-Budget von OpenClaw. Native Ollama-Anfragen lassen options.num_ctx ungesetzt, sofern Sie nicht ausdrücklich params.num_ctx konfigurieren, sodass Ollama seinen eigenen modell-, OLLAMA_CONTEXT_LENGTH- oder VRAM-basierten Standard anwenden kann. Um den Laufzeitkontext von Ollama pro Anfrage zu begrenzen oder zu erzwingen, ohne eine Modelfile neu zu bauen, setzen Sie params.num_ctx; ungültige, nullwertige, negative und nicht endliche Werte werden ignoriert. Wenn Sie eine ältere Konfiguration aktualisiert haben, die nur contextWindow oder maxTokens verwendet hat, um einen nativen Ollama-Anfragekontext zu erzwingen, führen Sie openclaw doctor --fix aus, um diese expliziten Provider- oder Modell-Budgets nach params.num_ctx zu kopieren. Der OpenAI-kompatible Ollama-Adapter fügt weiterhin standardmäßig options.num_ctx aus dem konfigurierten params.num_ctx oder contextWindow ein; deaktivieren Sie dies mit injectNumCtxForOpenAICompat: false, wenn Ihr Upstream options ablehnt.

Native Ollama-Modelleinträge akzeptieren außerdem die üblichen Ollama-Laufzeitoptionen unter params, darunter temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread und use_mmap. OpenClaw leitet nur Ollama-Anfrageschlüssel weiter, sodass OpenClaw-Laufzeitparameter wie streaming nicht an Ollama weitergegeben werden. Verwenden Sie params.think oder params.thinking, um think auf oberster Ollama-Ebene zu senden; false deaktiviert API-level Thinking für Qwen-artige Thinking-Modelle.

{  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 auch agents.defaults.models["ollama/<model>"].params.num_ctx. Wenn beides konfiguriert ist, gewinnt der explizite Provider-Modelleintrag vor dem Agent-Standard.

Für native Ollama-Modelle leitet OpenClaw die Thinking-Steuerung so weiter, wie Ollama sie erwartet: think auf oberster Ebene, nicht options.think. Automatisch erkannte Modelle, deren /api/show-Antwort die Fähigkeit thinking enthält, stellen /think low, /think medium, /think high und /think max bereit; Modelle ohne Thinking stellen nur /think off bereit.

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

Sie können auch einen Modellstandard festlegen:

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

Pro Modell kann params.think oder params.thinking Ollama-API-Thinking für ein bestimmtes konfiguriertes Modell deaktivieren oder erzwingen. OpenClaw behält diese expliziten Modellparameter bei, wenn der aktive Lauf nur den impliziten Standard off hat; Laufzeitbefehle ungleich off wie /think medium überschreiben den aktiven Lauf weiterhin.

OpenClaw behandelt Modelle mit Namen wie deepseek-r1, reasoning oder think standardmäßig als reasoning-fähig.

ollama pull deepseek-r1:32b

Es ist keine zusätzliche Konfiguration erforderlich. OpenClaw markiert sie automatisch.

Ollama ist kostenlos und läuft lokal, daher werden alle Modellkosten auf $0 gesetzt. Dies gilt sowohl für automatisch erkannte als auch für manuell definierte Modelle.

Das gebündelte Ollama-Plugin registriert einen Memory-Embedding-Provider für Memory-Suche. Es verwendet die konfigurierte Ollama-Basis-URL und den API-Schlüssel, ruft Ollamas aktuellen /api/embed-Endpunkt auf und bündelt nach Möglichkeit mehrere Memory-Chunks in einer input-Anfrage.

Wenn proxy.enabled=true ist, verwenden Ollama-Memory-Embedding-Anfragen an den exakten vom konfigurierten baseUrl abgeleiteten Host-local-loopback-Ursprung den geschützten direkten Pfad von OpenClaw statt des verwalteten Forward-Proxys. Der konfigurierte Hostname muss selbst localhost oder ein Loopback-IP-Literal sein; DNS-Namen, die lediglich zu Loopback auflösen, verwenden weiterhin den verwalteten Proxy-Pfad. LAN-, Tailnet-, private Netzwerk- und öffentliche Ollama-Hosts bleiben ebenfalls auf dem verwalteten Proxy-Pfad. Weiterleitungen zu einem anderen Host oder Port erben kein Vertrauen. Betreiber können weiterhin die globale Einstellung proxy.loopbackMode: "proxy" setzen, um Loopback-Datenverkehr durch den Proxy zu senden, oder proxy.loopbackMode: "block", um Loopback-Verbindungen abzulehnen, bevor eine Verbindung geöffnet wird; siehe Verwalteter Proxy für die prozessweite Wirkung dieser Einstellung.

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

So wählen Sie Ollama als Embedding-Provider für die Memory-Suche aus:

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

Für einen Remote-Embedding-Host beschränken Sie 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,        },      },    },  },}

Die Ollama-Integration von OpenClaw verwendet standardmäßig die native Ollama-API (/api/chat), die Streaming und Tool-Calling gleichzeitig vollständig unterstützt. Es ist keine spezielle Konfiguration erforderlich.

Für native /api/chat-Anfragen leitet OpenClaw die Thinking-Steuerung außerdem direkt an Ollama weiter: /think off und openclaw agent --thinking off senden think: false auf oberster Ebene, sofern kein expliziter Modellwert params.think/params.thinking konfiguriert ist, während /think low|medium|high den passenden Aufwand-String für think auf oberster Ebene senden. /think max wird Ollamas höchstem nativen Aufwand zugeordnet, think: "high".

Unter WSL2 mit NVIDIA/CUDA erstellt der offizielle Ollama-Linux-Installer eine systemd-Einheit 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 Host-Speicher belegen, während das Modell geladen wird. Die Hyper-V-Speicherrückgewinnung kann diese belegten Seiten nicht immer zurückgewinnen, sodass Windows die WSL2-VM beenden kann, systemd Ollama erneut startet und sich die Schleife wiederholt.

Häufige Hinweise:

• wiederholte WSL2-Neustarts oder Beendigungen von der Windows-Seite
• hohe CPU-Last in app.slice oder ollama.service kurz nach dem WSL2-Start
• SIGTERM von systemd statt eines Linux-OOM-Killer-Ereignisses

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

Abhilfe:

sudo systemctl disable ollama

Fügen Sie dies auf der Windows-Seite zu %USERPROFILE%\.wslconfig hinzu und führen Sie dann wsl --shutdown aus:

[experimental]autoMemoryReclaim=disabled

Legen Sie in der Ollama-Dienstumgebung eine kürzere Keep-alive-Zeit fest oder starten Sie Ollama nur bei Bedarf manuell:

export OLLAMA_KEEP_ALIVE=5mollama serve

Siehe ollama/ollama#11317.

Stellen Sie sicher, dass Ollama läuft, dass Sie OLLAMA_API_KEY (oder ein Authentifizierungsprofil) gesetzt haben und dass Sie keinen expliziten Eintrag models.providers.ollama definiert haben:

ollama serve

Prüfen Sie, ob die API erreichbar ist:

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

Wenn Ihr Modell nicht aufgeführt ist, rufen Sie das Modell entweder lokal ab oder definieren Sie es explizit in models.providers.ollama.

ollama list  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

Prüfen Sie, ob Ollama auf dem richtigen Port läuft:

# Check if Ollama is runningps aux | grep ollama # Or restart Ollamaollama serve

Prüfen Sie dies von derselben Maschine und Laufzeit aus, auf der der Gateway läuft:

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

Häufige Ursachen:

• baseUrl zeigt auf localhost, aber der Gateway läuft in Docker oder auf einem anderen Host.
• Die URL verwendet /v1, wodurch OpenAI-kompatibles Verhalten statt nativer Ollama-Nutzung ausgewählt wird.
• Der Remote-Host benötigt Firewall- oder LAN-Binding-Änderungen auf der Ollama-Seite.
• Das Modell ist im Daemon Ihres Laptops vorhanden, aber nicht im Remote-Daemon.

Dies bedeutet üblicherweise, dass der Provider den OpenAI-kompatiblen Modus verwendet oder das Modell Tool-Schemas nicht verarbeiten kann.

Bevorzugen Sie den nativen Ollama-Modus:

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

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

Gehostete Kimi/GLM-Antworten, die aus langen, nichtsprachlichen Symbolfolgen bestehen, werden als fehlgeschlagene Provider-Ausgabe behandelt statt als erfolgreiche Assistant-Antwort. Dadurch können normale Wiederholungs-, Fallback- oder Fehlerbehandlung übernehmen, ohne den beschädigten Text in der Sitzung zu speichern.

Wenn dies wiederholt passiert, erfassen Sie den rohen Modellnamen, die aktuelle Sitzungsdatei und ob der Lauf Cloud + Local oder Cloud only verwendet hat, und versuchen Sie dann eine neue Sitzung sowie ein Fallback-Modell:

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

Große lokale Modelle können vor Beginn des Streamings einen langen ersten Ladevorgang benötigen. Beschränken Sie das Timeout auf den Ollama-Provider und bitten Sie Ollama optional, das Modell zwischen Turns geladen zu halten:

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

Wenn der Host selbst Verbindungen nur langsam annimmt, erweitert timeoutSeconds auch das geschützte Undici-Verbindungs-Timeout für diesen Provider.

Viele Ollama-Modelle geben Kontexte an, die größer sind, als Ihre Hardware bequem ausführen kann. Natives Ollama verwendet Ollamas eigene Standardvorgabe für den Laufzeitkontext, sofern Sie nicht params.num_ctx setzen. Begrenzen Sie sowohl das Budget von OpenClaw als auch den Anfragekontext von Ollama, wenn Sie eine vorhersehbare Latenz bis zum ersten Token wünschen:

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

Senken Sie zuerst contextWindow, wenn OpenClaw zu viel Prompt sendet. Senken Sie params.num_ctx, wenn Ollama einen Laufzeitkontext lädt, der für die Maschine zu groß ist. Senken Sie maxTokens, wenn die Generierung zu lange dauert.