OpenClaw mit Ollama: ein Modell anschließen lokal
Dieser Guide zeigt, wie Sie OpenClaw mit Ollama verbinden, um den Assistenten auf einem lokalen Modell zu betreiben: Anbieterdefinition, Serveradresse, vorzusehendes Kontextfenster und Auswahl eines Modells, das Tools aufrufen kann. Die Hälfte der Arbeit besteht darin, Fehler zu vermeiden, die keine Fehlermeldung anzeigen: abgeschnittener Kontext, nie aufgerufene Tools, in der Liste fehlendes Modell. Die Befehle orientieren sich an der Dokumentation von Ollama und der von OpenClaw. Lesen Sie sie vor dem Einfügen erneut durch, da sich beide schnell weiterentwickeln; diese Seite enthält weder eigene Tests noch Geschwindigkeitsmessungen oder ein Modellranking.
#OpenClaw und Ollama: Wer macht was?
OpenClaw ist ein Gateway: ein Prozess, der Ihre Nachrichten aus einem Messaging-Dienst empfängt, sie an ein Sprachmodell weiterleitet und die von diesem Modell angeforderten Aktionen ausführt. Ollama ist ein Modellserver: Er lädt ein Modell in den Speicher und antwortet am Port 11434 der Maschine standardmäßig unter der Adresse http://localhost:11434. Die beiden miteinander zu verbinden bedeutet, Ollama als Anbieter in OpenClaw zu deklarieren und anschließend ein lokales Modell als Hauptmodell des Agenten festzulegen.
Laut der Dokumentation von OpenClaw läuft diese Verbindung über die native API von Ollama (den Endpunkt /api/chat), die Streaming-Antworten und Tool-Aufrufe unterstützt. Dieses Detail ist wichtiger, als es scheint: Wir werden sehen, dass eine falsch geschriebene Adresse genügt, um das Gateway in einen anderen Modus zu versetzen, in dem die Tools nicht mehr funktionieren.
- Ollama
- Lädt das Modell, weist ihm ein Kontextfenster zu und generiert den Text. Es entscheidet, wie viel Speicher verbraucht wird.
- OpenClaw
- Sendet bei jedem Durchlauf die Systemanweisung, die Beschreibung der verfügbaren Tools und den Gesprächsverlauf und führt anschließend die vom Modell angeforderten Tools aus.
- Das Modell
- Muss eine lange Anweisung im Gedächtnis behalten und ein Tool im erwarteten Format anfordern können. Nicht alle lokalen Modelle sind dazu fähig.
- Das, was sich nicht ändert
- Nachrichten, der Speicher des Assistenten, das Token und die Sicherheit des Gateways bleiben unabhängig vom Modellanbieter auf der Seite von OpenClaw konfiguriert.
Diese Anbindung ist anspruchsvoller als die einer Chat-Oberfläche. Ein Chat sendet dem Modell einige Zeilen; ein Agent sendet ihm von Anfang an mehrere tausend Tokens an Anweisungen und Tool-Definitionen, noch bevor Sie Ihre erste Nachricht schreiben. Die Standardeinstellungen von Ollama sind für den ersten Fall gedacht, nicht für den zweiten.
#Voraussetzungen
Agenten, die auf Ihrem Rechner handeln: agentisches Cline, MCP, n8n + Ollama und lokale Automatisierungen.
- Lebenslanger Online-Zugang
- PDF + Dateien
- Lebenslange Updates
- OpenClaw installiert
- Ein Gateway, das startet und dessen Diagnose erfolgreich ist. Die Installation wird hier nicht behandelt: Siehe unseren Leitfaden „OpenClaw mit Docker installieren“.
- Ollama installiert und aktuell
- Der weiter unten verwendete Befehl ollama launch ist nur in neueren Versionen verfügbar. Die Installation wird in unserem Leitfaden „Ollama installieren“ behandelt.
- Speicher für das Modell und seinen Kontext
- Orientierungswerte in Q4_K_M nur für die Gewichte: etwa 5 GB für ein Modell mit 7 Milliarden Parametern, 9 GB für 14 Milliarden, 19 GB für 32 Milliarden. Das von einem Agenten angeforderte Kontextfenster kommt zu diesem Wert hinzu.
- Zugriff auf das Terminal
- Auf dem Rechner, der das Gateway hostet, und auf dem Rechner, der Ollama hostet, falls es nicht derselbe ist.
Der letzte Befehl muss die Liste der installierten Modelle im JSON-Format ausgeben. Eine verweigerte Verbindung bedeutet, dass Ollama nicht gestartet ist: Starten Sie die Anwendung oder ollama serve in einem Terminal. Gehen Sie nicht weiter, solange diese Antwort nicht erscheint.
#Schritt 1: 64 000 Kontexttokens einplanen
Dies ist die Einstellung, an der die meisten Installationen scheitern; sie wird auf der Seite von Ollama vorgenommen, nicht auf der OpenClaw-Seite. Die Seite, die Ollama OpenClaw widmet, weist darauf hin, dass der Assistent ein großes Kontextfenster benötigt, und empfiehlt bei einem lokalen Modell mindestens 64 000 Tokens. Die Seite zur Kontextlänge nennt denselben Wert für Agenten, Websuche und Code-Tools.
Allerdings wählt Ollama sein Standardfenster abhängig vom verfügbaren Videospeicher: Laut derselben Dokumentation sind es etwa 4.000 Tokens bei weniger als 24 GiB VRAM, 32.000 zwischen 24 und 48 GiB und 256.000 ab 48 GiB. Auf einer Karte mit 12 oder 16 GB startet der Server daher mit einem sechzehnmal kleineren Fenster als empfohlen. Nichts weist darauf hin: Ollama schneidet alles Überstehende ohne Fehlermeldung ab.
Wenn Ollama bereits als Anwendung (macOS, Windows) läuft, führen Sie diesen Befehl nicht aus: Ein zweiter Server würde mit dem Port 11434 in Konflikt geraten. Stellen Sie die Kontextlänge in den Anwendungseinstellungen ein. Unter Linux wird die Variable in dem Dienst selbst deklariert, wenn Ollama als systemd-Dienst installiert wurde.
#Schritt 2: Ein Modell auswählen, das Tools aufrufen kann
Ein Agent handelt nur über seine Werkzeuge: eine Datei lesen, einen Befehl ausführen, im Web suchen. Ein Modell, das keine Werkzeuganfrage formulieren kann, wird höflich auf Ihre Nachrichten antworten, aber niemals etwas tun. Diese Seite ordnet die Modelle nicht ein; sie nennt die Kriterien, die Sie prüfen sollten, bevor Sie eines anschließen.
- Die „tools“-Fähigkeit
- Der Befehl ollama show affiche enthält einen Abschnitt „Capabilities“. Dieser muss tools enthalten. In der Bibliothek von Ollama befindet sich der entsprechende Filter unter https://ollama.com/search?c=tools.
- Ein ausreichend großes natives Kontextfenster
- Derselbe Befehl zeigt die maximale Kontextlänge des Modells an. Ein Modell, das für 8 000 oder 32 000 Tokens ausgelegt ist, kann der Empfehlung von 64 000 unabhängig von der Servereinstellung nicht folgen.
- Ein realistisches Speicherbudget
- Gewichte und Kontext müssen gemeinsam in den VRAM oder in den Unified Memory eines Mac passen. Bei einer 12-GB-Karte (RTX 3060, RTX 4070) führt dies zu deutlich kleineren Modellen als denen, die die Karte in einem einfachen Dialog akzeptiert; 16 GB (RTX 4080) und 24 GB (RTX 4090) lassen mehr Spielraum.
- Die Ausdauer im laufenden Betrieb
- Ein Agent führt pro Anfrage mehrere Tool-Aufrufe hintereinander aus. Bei sehr kleinen Modellen treten Format- oder Toolfehler häufiger auf. Kein Datenblatt ersetzt einen Test mit Ihren eigenen Anfragen, zunächst mit geringem Risiko.
Der Name gpt-oss:20b dient im weiteren Verlauf dieses Leitfadens als Beispiel: Ersetzen Sie ihn durch das von Ihnen ausgewählte Modell. Die Integrationsseite von Ollama führt eine aktuelle Liste der für OpenClaw empfohlenen Modelle, die sich mit neuen Veröffentlichungen ändert; Sie sollten sich daher besser daran orientieren, als hier auf eine feste Liste zu vertrauen.
#Schritt 3: Anbieter Ollama in OpenClaw konfigurieren
Es gibt zwei Wege. Der erste ist ein Ollama-Befehl, der die Konfiguration für Sie schreibt. Der zweite besteht darin, den Anbieter selbst in der OpenClaw-Konfiguration zu deklarieren; das ist unverzichtbar, sobald das Gateway in Docker läuft oder sich Ollama auf einem anderen Rechner befindet.
#Schneller Weg: ollama launch openclaw
Laut der Dokumentation von Ollama sorgt dieser Befehl dafür, dass ein Modell ausgewählt, OpenClaw für die Verwendung von Ollama konfiguriert und das Gateway gestartet wird; falls es bereits läuft, lädt es die neue Konfiguration selbstständig neu. Der alte Projektname wird weiterhin akzeptiert: ollama launch clawdbot ist ein Alias. Der Befehl richtet sich an ein direkt auf der Maschine installiertes OpenClaw, wobei der Befehl openclaw im Terminal verfügbar ist. Er macht Schritt 1 nicht überflüssig: Auf derselben Seite wird verlangt, den Kontext des Servers zu erfassen.
#Manueller Weg: den Anbieter selbst deklarieren
Die OpenClaw-Dokumentation beschreibt zunächst einen Modus zur automatischen Erkennung. Wir geben einen Dummy-Schlüssel an, da Ollama keinen benötigt, und OpenClaw fragt die lokale Instanz unter http://127.0.0.1:11434 ab, um die installierten Modelle zu finden.
Ein Modell wird in der Form ollama/ gefolgt vom exakten, einschließlich des Labels angezeigten Namen aus ollama list angegeben. Wenn das Gateway als Dienst läuft, tragen Sie es vorzugsweise in die Konfiguration ein, statt die Umgebungsvariable zu verwenden: Eine in Ihrem Terminal exportierte Variable wird nicht an einen vom System gestarteten Prozess weitergegeben. Bei einer Docker-Installation wird jedem Befehl openclaw der Präfix docker compose run --rm openclaw-cli vorangestellt.
Der zweite Modus ist die explizite Deklaration in der Datei ~/.openclaw/openclaw.json, die in JSON5 geschrieben ist. Er wird verwendet, wenn Ollama auf einer anderen Maschine als der Gateway-Maschine läuft, wenn ein Modell nicht in der Liste erscheint oder wenn Sie das dem Agenten angekündigte Fenster selbst festlegen möchten.
- baseUrl
- Die Adresse des Servers Ollama einschließlich des Ports, ohne irgendetwas danach. Dies ist die einzige Zeile, die Sie ändern müssen, wenn Ollama auf einem anderen Rechner läuft.
- api: "ollama"
- Fordern Sie ausdrücklich die native API von Ollama an, die den Tool-Aufruf unterstützt.
- apiKey
- Ein Platzhalterwert. Er dient lediglich dazu, den Anbieter zu aktivieren.
- contextWindow
- Das für OpenClaw angekündigte Fenster, das zur Verwaltung der Verlaufslänge dient. Es muss dem entsprechen, was Ollama tatsächlich lädt, nicht dem, was das Modell theoretisch akzeptieren würde.
- maxTokens
- Die maximale Länge einer Antwort.
- cost
- Nullkosten: Ein lokales Modell wird nicht pro Token abgerechnet.
- agents.defaults.model.primary
- Das vom Agenten standardmäßig verwendete Modell in der Form ollama/Name-des-Modells.
Dieses Beispiel übernimmt die von der OpenClaw-Dokumentation vorgegebene Struktur; die Werte von contextWindow und maxTokens stammen von uns und müssen an Ihr Modell angepasst werden. Zwei Dinge sind wichtig. Setzen Sie reasoning zunächst auf true, wenn Sie ein Reasoning-Modell verwenden. Außerdem ist laut derselben Dokumentation die automatische Erkennung deaktiviert, sobald ein expliziter Eintrag models.providers.ollama vorhanden ist: Jedes Modell, das Sie verwenden möchten, muss dann in der Liste models aufgeführt sein.
#Gateway in Docker oder Ollama auf einer anderen Maschine
In einem Container bezeichnet localhost den Container selbst. Ein mit Docker gestartetes OpenClaw-Gateway sieht daher den Ollama des Hostcomputers unter der Adresse http://localhost:11434 nicht: Die Verbindung wird abgelehnt, obwohl alles von Ihrem Terminal aus funktioniert. Die Lösung hängt davon ab, wo Ollama läuft.
- Docker Desktop (macOS, Windows)
- Der Name host.docker.internal bezeichnet aus dem Container heraus die Hostmaschine. Geben Sie http://host.docker.internal:11434 in der expliziten Deklaration als baseUrl an.
- Docker Engine unter Linux
- Dieser Name existiert standardmäßig nicht: Sie müssen ihn mit extra_hosts zum Dienst hinzufügen, wie unten gezeigt. Ollama muss außerdem auf einer Schnittstelle lauschen, die der Container erreichen kann; das ist bei der ursprünglichen Einstellung nicht der Fall, da sie auf die Loopback-Schnittstelle beschränkt ist.
- Ollama auf einem anderen Gerät
- Tragen Sie die Adresse dieses Rechners in Ihrem lokalen Netzwerk oder VPN in baseUrl ein und stellen Sie die Überwachung von Ollama auf diesem Rechner entsprechend ein.
Die Compose-Datei ist ein Beispiel von uns und kein Auszug aus der OpenClaw-Dokumentation: Vergleichen Sie den Namen des Dienstes mit der docker-compose.yml Ihrer Version. Die Variable OLLAMA_HOST wird dagegen in der FAQ zu Ollama beschrieben. Machen Sie sich klar, was sie bedeutet: Mit 0.0.0.0 lauscht der Server auf allen Schnittstellen des Rechners, und die API von Ollama verlangt keinerlei Authentifizierung. Eine Firewall muss den Port 11434 auf das Docker-Netzwerk oder das lokale Netzwerk beschränken, und dieser Port darf niemals aus dem Internet erreichbar sein. Unser Leitfaden zur Absicherung eines Ollama-Servers erläutert diese Regeln ausführlich.
#Schritt 4: Die Verbindung von Ende zu Ende überprüfen
Ein Agent, der „Hallo“ antwortet, beweist nichts: Diese Antwort benötigt weder ein Tool noch Kontext. Die sinnvolle Überprüfung arbeitet sich Schicht für Schicht vor, vom Modellserver bis zum Nachrichtendienst.
- 01Tool-Aufrufe nur mit Ollama testenSenden Sie dem Server mit dem folgenden Befehl eine Frage zusammen mit einem erfundenen Tool. Die Antwort muss ein Feld tool_calls enthalten, das das Tool nennt und ihm ein Argument übergibt. Wenn das Modell mit einem Satz antwortet, eignet es sich nicht als Agent.
- 02Kontrollieren, was OpenClaw siehtDer Befehl openclaw models list muss Ihr Modell in der Form ollama/nom-du-modèle anzeigen, und openclaw doctor darf keinen Anbieterfehler melden.
- 03Eine Aktion anfordern, keine AntwortSenden Sie über die Kontrolloberfläche oder Ihr Nachrichtenprogramm eine Anfrage, die den Agenten zwingt, ein Tool zu verwenden, zum Beispiel die Dateien seines Arbeitsbereichs aufzulisten. Er muss dies tatsächlich tun und darf nicht beschreiben, was er tun würde.
- 04Sehen, was Ollama geladen hatFühren Sie direkt nach diesem Austausch ollama ps auf der Servermaschine aus und lesen Sie die Spalten CONTEXT und PROCESSOR.
In der Ausgabe von ollama ps gibt die Spalte CONTEXT das Fenster an, das dem geladenen Modell tatsächlich zugewiesen wurde. Wenn dort 4096 steht, obwohl Sie 64 000 anvisiert haben, wurde die Einstellung aus Schritt 1 nicht übernommen, unabhängig davon, was die Konfiguration von OpenClaw angibt. Die Spalte PROCESSOR zeigt die Verteilung zwischen Grafikkarte und Prozessor: Die Angabe 100% GPU ist das gewünschte Ergebnis; eine gemischte Verteilung weist darauf hin, dass Modell und Kontext den Videospeicher überschreiten.
#Stille Ausfälle: Symptome und ihre Ursachen
Eindeutige Fehler (Verbindung abgelehnt, Modell nicht gefunden) sind in den Protokollen zu erkennen. Die folgenden Ausfälle sind kostspieliger, weil der Assistent weiterhin antwortet: Er antwortet lediglich falsch.
- Der Assistent ignoriert seine Anweisungen oder antwortet am Thema vorbei
- Wahrscheinlichste Ursache: Der Kontext wurde abgeschnitten. Die Systemanweisung und die Tooldefinitionen überschreiten das von Ollama geladene Fenster, das einen Teil davon ohne Hinweis abschneidet. Prüfen Sie die Spalte CONTEXT von ollama ps und wiederholen Sie Schritt 1.
- Statt der Aktion wird JSON angezeigt
- Das Modell hat einen Tool-Aufruf korrekt formuliert, aber das Gateway hat ihn als Text erhalten. Das deutet auf eine Adresse unter /v1 oder auf einen im OpenAI-kompatiblen Modus eingerichteten Anbieter hin. Kehren Sie zur nativen Adresse und zu api: "ollama" zurück.
- Es beschreibt, was es tun würde, ohne etwas zu tun
- Das Modell weist die tools-Fähigkeit nicht aus oder ist zu eingeschränkt, um sie mitten in einer langen Anweisung zu verwenden. Wiederholen Sie den in Schritt 4 beschriebenen direkten Test mit Ollama; falls er fehlschlägt, wechseln Sie das Modell.
- Das Modell erscheint nicht in openclaw models list
- Drei Möglichkeiten. Der Anbieter ist nicht aktiviert (der Dummy-Schlüssel fehlt oder die Variable wurde nicht an den Dienst übergeben). Es gibt einen expliziten Eintrag models.providers.ollama, der dieses Modell nicht auflistet. Oder das Modell deklariert keine Tool-Aufrufe: Nach der uns bekannten Dokumentation berücksichtigt die automatische Erkennung nur Modelle, die dies deklarieren – ein Verhalten, das sich je nach Version geändert haben kann.
- Die Kontexteinstellung bleibt wirkungslos
- Die Variable OLLAMA_CONTEXT_LENGTH wurde in einem Terminal exportiert, während Ollama als Dienst oder Anwendung läuft: Der Server hat sie nie gesehen. Definieren Sie sie im Dienst oder in den Anwendungseinstellungen und starten Sie anschließend Ollama neu.
- Die Antworten brauchen sehr lange oder kommen gar nicht
- Entweder läuft das Modell über den Prozessor hinaus (Spalte PROCESSOR von ollama ps), oder es wurde nach einer Inaktivitätsphase entladen und wird bei jeder Nachricht neu geladen: Standardmäßig hält Ollama ein Modell fünf Minuten lang im Speicher. Die Variable OLLAMA_KEEP_ALIVE verlängert diese Frist.
- Im Terminal funktioniert alles, über das Gateway nichts
- Das Gateway läuft in einem Container und sucht Ollama auf seinem eigenen Localhost. Siehe den Abschnitt zu Docker.
- „Model context window too small“
- Diese ist nicht stumm, aber sie führt in die Irre: Die uns bekannten OpenClaw-Versionen lehnen ein Modell ab, dessen angekündigtes Kontextfenster zu klein ist. Setzen Sie contextWindow in der ausdrücklichen Deklaration entsprechend, ebenso den Kontext von Ollama.
Eine Einschränkung, die Sie nach dem Herstellen der Verbindung im Hinterkopf behalten sollten: Ein korrekt angebundenes lokales Modell verhält sich bei langen oder mehrdeutigen Aufgaben nicht unbedingt wie ein großes Online-Modell. Wir veröffentlichen hier keinerlei Vergleich und keinerlei Durchsatz. Beginnen Sie mit einfachen, unkritischen Anfragen, beobachten Sie, wann das Modell ins Stocken gerät, und behalten Sie einen Online-Anbieter als Ausweichlösung, wenn der Assistent täglich zum Einsatz kommt.
#Offizielle Quellen zum Nachschlagen
Dieser Leitfaden beruht auf keinerlei eigenen Tests: Er enthält weder Dauer noch Durchsatz noch Punktzahl. Die Befehle und Feldnamen entsprechen der Dokumentation der beiden Projekte, die sich von Version zu Version ändert: Optionen von ollama launch, Verhalten der automatischen Erkennung, Standardwerte. Bei Abweichungen zwischen dieser Seite und der Dokumentation ist die Dokumentation maßgeblich.
#Weiterführende Informationen
Die Anbindung beruht auf drei Konzepten, die an anderer Stelle auf der Website ausführlich behandelt werden: dem Server Ollama, dem Kontextfenster und dem Tool-Aufruf.
- Ollama installieren
- Die Installation des Modellservers, seine Grundeinstellungen und was die Maschine verlassen kann. https://quelllm.fr/guide/installer-ollama
- Das Kontextfenster verstehen
- Was ein Token misst, warum der Kontext Speicher verbraucht und wie er dimensioniert wird. https://quelllm.fr/guide/comprendre-fenetre-contexte
- Tool-Aufrufe mit Ollama
- Das Format von Tool-Anfragen und die Art, sie unabhängig von einem Agenten zu testen. https://quelllm.fr/guide/appel-outil-ollama-tutoriel
- Hermes Agent mit Ollama
- Ein weiterer selbst gehosteter Agent, der mit einem lokalen Modell verbunden ist, um die Ansätze zu vergleichen. https://quelllm.fr/guide/hermes-agent-ollama-guide
- OpenClaw mit Docker installieren
- Die Installation des Gateways, seine Aktualisierung und die Regeln für die Bereitstellung auf einem VPS. https://quelllm.fr/guide/installer-openclaw-docker
Haben Sie Feedback, einen Fehler entdeckt oder möchten Sie etwas präzisieren? Geben Sie uns Bescheid – so wird der Guide für alle besser.