Prime Agent Ollama 2026: Fehler schnell beheben

Zuletzt aktualisiert am 11.08.2026; die Angaben wurden gegen die aktuelle Prime-Agent-Dokumentation sowie die offiziellen Ollama-API- und Troubleshooting-Dokumente geprüft.

Symptom: Prime Agent zeigt Ollama nicht, verbindet sich nicht oder bleibt bei einer Programmieraufgabe stehen.
Schnellste Lösung: Installieren Sie nicht sofort neu. Isolieren Sie den Fehler in fünf Schichten: Ollama-Dienst, Netzwerkadresse, models.json, API-Kompatibilität und Modellfähigkeit.

Dieser Beitrag richtet sich an Sie, wenn Sie Prime Agent bereits eingerichtet haben und ein lokales Modell nutzen möchten. Er hilft bei fehlenden Modellen, abgelehnten Requests, fehlenden Werkzeugaktionen, abgebrochenen Streams und langen Aufgaben in einer lokalen oder entfernten Umgebung.

Ein typischer Fall sieht zunächst nach einem Verbindungsproblem aus: Das Modell erscheint in Prime Agent, eine kurze Frage wird beantwortet, aber beim Lesen und Ändern einer Datei endet die Aufgabe mit einer Fehlermeldung oder ohne verwertbaren Fortschritt. Genau hier müssen Sie die Modellfähigkeit von der eigentlichen Verbindung trennen.

Die fünf Fehlergrenzen vor dem ersten Neustart

Prime Agent kann benutzerdefinierte Provider und Modelle über ~/.prime/agent/models.json einlesen. Für Ollama wird in der aktuellen Dokumentation ein OpenAI-kompatibler Provider mit api: "openai-completions" und einer baseUrl unter /v1 gezeigt. Die Datei wird beim erneuten Öffnen von /model geladen; ein kompletter Neustart ist für eine reine Konfigurationsänderung daher nicht immer erforderlich. (Prime-Agent-Dokumentation zu benutzerdefinierten Modellen)

Diese Trennung verhindert drei typische Fehlentscheidungen:

• Sie verwechseln ein nicht installiertes Modell mit einer fehlerhaften Prime-Agent-Konfiguration.
• Sie testen eine Adresse aus Ihrer lokalen Shell, obwohl Prime Agent in einem Container oder auf einem anderen Rechner läuft.
• Sie interpretieren eine sprachlich gute Antwort als Beweis dafür, dass das Modell auch zuverlässige Dateiänderungen, Werkzeugaufrufe und längere Abläufe beherrscht.

Die offiziellen Prime-Agent-Dokumente weisen außerdem darauf hin, dass der Agent modellgenerierten Python-Code und Projektbefehle mit Ihren Benutzerrechten ausführt. Eine funktionierende Verbindung ist deshalb kein ausreichender Sicherheitsnachweis. Arbeiten Sie mit einem sauberen Arbeitsbaum, einer temporären Kopie und einem kontrollierten Repository.

Zeitlinie für die Diagnose

Bearbeiten Sie die fünf Schichten in dieser Reihenfolge. Jede Stufe muss einen eigenen überprüfbaren Erfolg liefern, bevor Sie weitergehen.

Verändern Sie nach Möglichkeit nur einen Parameter pro Test. Wenn Sie gleichzeitig baseUrl, Modell-ID und Kompatibilitätsfelder ändern, ist der nächste grüne Test nicht mehr aussagekräftig.

Modellbestand und Dienstzugriff

Beginnen Sie nicht in Prime Agent, sondern direkt bei Ollama. Die native API wird standardmäßig unter http://localhost:11434/api bereitgestellt; für die OpenAI-kompatible Schnittstelle verwendet Ollama /v1. (Ollama-API-Einführung)

Prüfen Sie auf dem Rechner, auf dem Ollama laufen soll:

ollama list

Suchen Sie danach die Modellliste über die native Schnittstelle ab:

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

Für Prime Agent ist zusätzlich der OpenAI-kompatible Endpunkt relevant:

curl -sS http://localhost:11434/v1/models

Der erwartete Erfolg ist kein leerer HTTP-Response, sondern gültiges JSON mit der exakten Modell-ID. Achten Sie auf Tags wie :7b, :8b oder eine eigene Variante. qwen2.5-coder und qwen2.5-coder:7b sind für die Konfiguration nicht automatisch identisch.

Wenn ollama list das Modell nicht zeigt, liegt das Problem noch nicht bei Prime Agent. Laden Sie das gewünschte Modell nach der offiziellen Ollama-Anleitung und testen Sie anschließend erneut. Prüfen Sie außerdem mit:

ollama ps

Damit sehen Sie, welche Modelle aktuell geladen sind und welche Speicheraufteilung Ollama meldet. Die offizielle Ollama-FAQ nennt ollama ps als Prüfpunkt für geladenes Modell und Prozessorverwendung. (Ollama-FAQ zu Modellen und Ressourcen)

Hinweis: Ein erfolgreicher Aufruf von /v1/models beweist nur, dass der Server Modelle auflistet. Er beweist noch nicht, dass das konkrete Modell einen Prime-Agent-Request mit Rollen, Streaming, Reasoning-Parametern und Werkzeugdefinitionen verarbeiten kann.

Konfigurationspfad und models.json

Wenn Ollama direkt funktioniert, prüfen Sie den Pfad und die Datei. Die aktuelle Prime-Agent-Dokumentation verwendet:

~/.prime/agent/models.json

Validieren Sie zuerst die Syntax:

jq empty ~/.prime/agent/models.json
echo $?

Ein Rückgabewert 0 zeigt, dass die JSON-Datei syntaktisch gültig ist. Danach kontrollieren Sie, ob der Provider und die Modell-ID zur laufenden Installation passen. Ein minimales Beispiel sieht so aus:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

Bei lokalen Modellen ist apiKey laut Dokumentation weiterhin als Feld vorgesehen, auch wenn Ollama den Wert ignoriert. Verwenden Sie keinen echten geheimen Schlüssel in einer lokalen Testdatei.

Prüfen Sie jetzt drei Dinge getrennt:

1. Modell installiert: Die ID erscheint in ollama list.
2. Konfiguration geladen: Die ID erscheint nach dem erneuten Öffnen von /model.
3. ID identisch: Groß-/Kleinschreibung, Tags und Sonderzeichen stimmen exakt überein.

Wenn das Modell in models.json steht, aber in Prime Agent fehlt, verwenden Sie nicht sofort eine neue Provider-Struktur. Öffnen Sie zuerst erneut /model. Die Dokumentation beschreibt, dass die Datei bei dieser Aktion neu geladen wird. Erst wenn die Auswahl weiterhin leer bleibt, untersuchen Sie Dateiberechtigungen, den Benutzerkontext und den tatsächlichen Home-Pfad des laufenden Prozesses.

Achten Sie auch auf die Ebene der Einstellungen. compat kann beim Provider oder beim einzelnen Modell stehen. Provider-Einstellungen gelten grundsätzlich für die darunterliegenden Modelle; eine Model-Einstellung kann sie überschreiben. Das ist wichtig, wenn ein Ollama-Modell andere Einschränkungen hat als ein zweites Modell am gleichen Endpunkt.

Hostnamen, Container und entfernte Rechner

Die häufigste Ursache bei einer entfernten Installation ist ein falsches Verständnis von localhost.

• Läuft Prime Agent und Ollama auf demselben Host, kann http://localhost:11434/v1 korrekt sein.
• Läuft Prime Agent in einem Container, zeigt localhost meist auf den Container selbst.
• Läuft Ollama auf einem zweiten Rechner, zeigt localhost auf den Prime-Agent-Rechner und nicht auf den Ollama-Host.
• Läuft Prime Agent über SSH auf einer entfernten Maschine, müssen Sie die Route aus genau dieser Sitzung testen.

Starten Sie den Test daher auf dem Rechner oder im Container, in dem Prime Agent tatsächlich ausgeführt wird:

curl -i http://<ollama-host>:11434/v1/models

Erwarten Sie eine HTTP-Antwort und ein JSON-Dokument. Ein Timeout weist eher auf Route, Firewall oder Bind-Adresse hin. Ein HTTP-Fehler mit JSON-Body zeigt dagegen, dass der Host grundsätzlich erreicht wurde und Sie danach den Pfad oder Request prüfen sollten.

Ollama bindet standardmäßig an 127.0.0.1:11434. Für einen kontrollierten Fernzugriff kann die Bind-Adresse über OLLAMA_HOST geändert werden. Die offizielle FAQ beschreibt dafür unterschiedliche Vorgehensweisen unter macOS, Linux und Windows. Öffnen Sie den Port nicht ungeschützt im Internet; verwenden Sie ein privates Netzwerk, VPN oder einen abgesicherten Proxy mit Zugriffskontrolle.

Unter macOS kann die Umgebung beispielsweise über launchctl gesetzt werden:

launchctl setenv OLLAMA_HOST "0.0.0.0:11434"

Danach muss die Ollama-Anwendung neu gestartet werden. Unter Linux mit einem Systemdienst erfolgt die Konfiguration anders. Übernehmen Sie deshalb nicht blind einen macOS-Befehl auf einem Linux-Host.

Für DSGVO-relevante Projekte sollten Sie zusätzlich dokumentieren, ob Prompts, Quellcode und Protokolle den lokalen Rechner verlassen. Eine lokale Ollama-Instanz kann Daten lokal halten, aber Netzwerkfreigaben, Reverse Proxies, Backups und Sitzungsdateien bleiben eigenständige Datenschutzgrenzen. Die Datenschutzinformationen von Kvmkit sollten Sie in die interne Betriebsdokumentation aufnehmen, wenn Sie eine entfernte Mac-Umgebung oder gemietete Infrastruktur einsetzen.

API-Parameter und compat-Einstellungen

Erreicht Prime Agent den Server, aber Ollama lehnt den Request ab, lesen Sie zuerst Statuscode und Fehlermeldung. „Modell inkompatibel“ ist keine ausreichende Diagnose.

Die Prime-Agent-Dokumentation führt mehrere Kompatibilitätsfelder für OpenAI-ähnliche Schnittstellen auf, darunter:

• supportsDeveloperRole
• supportsReasoningEffort
• supportsUsageInStreaming
• maxTokensField
• supportsStrictMode
• requiresToolResultName

Für Ollama ist besonders relevant, ob das Backend eine developer-Rolle, reasoning_effort oder Streaming-Nutzungsdaten akzeptiert. Die Dokumentation nennt ausdrücklich die Möglichkeit, supportsDeveloperRole und supportsReasoningEffort auf false zu setzen, wenn der Server diese Felder nicht unterstützt.

Ein vorsichtiges Beispiel:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "qwen2.5-coder:7b",
          "reasoning": false
        }
      ]
    }
  }
}

Ändern Sie nicht gleichzeitig Provider- und Model-Einstellungen. Beginnen Sie mit einem einzigen Feld, öffnen Sie /model erneut und senden Sie danach denselben Minimalauftrag. Bleibt der Fehler bestehen, nehmen Sie die Änderung zurück und prüfen Sie das nächste Feld.

Ein direkter Test gegen Ollamas OpenAI-kompatible Schnittstelle kann so aussehen:

curl -sS http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "<MODELL_ID>",
    "messages": [
      {"role": "user", "content": "Antworten Sie mit OK."}
    ],
    "stream": false
  }'

Ollama dokumentiert für diesen Endpunkt unter anderem Chat-Vervollständigungen, Streaming, JSON-Modus, Vision und Werkzeuge. Das bedeutet jedoch nicht, dass jede Kombination aus Modell, Werkzeugdefinition und Prime-Agent-Kompatibilitätsoption in Ihrer konkreten Version identisch funktioniert. (Ollama-Dokumentation zur OpenAI-Kompatibilität)

Coding-Fähigkeit statt Chat-Demo

Wenn „Antworten Sie mit OK“ funktioniert, wechseln Sie zu einer kleinen, kontrollierten Aufgabenfolge:

1. Lassen Sie Prime Agent eine bekannte Textdatei lesen.
2. Lassen Sie eine einzelne, klar beschriebene Zeile ändern.
3. Prüfen Sie den Diff manuell.
4. Lassen Sie einen ungefährlichen Test- oder Formatierungsbefehl ausführen.
5. Bitten Sie den Agenten, den Testausgang zu lesen und nur bei Erfolg weiterzumachen.

Diese Reihenfolge trennt Berechtigungen, Werkzeugnutzung, Instruktionsbefolgung und Modellqualität. Ein Modell kann überzeugend erklären, wie eine Datei zu ändern wäre, ohne den richtigen Werkzeugaufruf zu erzeugen. Es kann auch eine Änderung vorschlagen, aber den anschließenden Test falsch interpretieren.

Wenn der Fehler an derselben Stelle reproduzierbar ist, behandeln Sie ihn zunächst als Fähigkeits- oder Kompatibilitätsgrenze, nicht als bestätigten Prime-Agent- oder Ollama-Bug. Testen Sie ein anderes lokales Modell mit derselben baseUrl und demselben Auftrag. Wenn nur ein Modell scheitert, liegt die Ursache wahrscheinlich in Modellverhalten, Template-Unterstützung oder Tool-Fähigkeit. Wenn alle Modelle scheitern, gehen Sie zurück zu API, Rollen und Streaming.

Reduzieren Sie außerdem die Aufgabe. Ein langes Repository-Refactoring ist kein sinnvoller Ersttest. Teilen Sie es in Analyse, kleine Änderung und Prüfung. Bewahren Sie jeden Diff und jeden Testausgang auf. So können Sie später nachweisen, an welcher Stufe der Ablauf abgebrochen ist.

Streaming, Kontext und Ressourcen

Bei langen Aufgaben sind mehrere Ursachen gleichzeitig möglich:

• Das Modell wird erst beim ersten Request geladen.
• Der Gesprächs- und Dateikontext wächst weiter.
• Mehrere Agenten oder Requests konkurrieren um Speicher.
• Das Modell wird teilweise in den Systemspeicher ausgelagert.
• Ollama nimmt Anfragen an, kann sie aber wegen Überlastung nicht zeitnah bedienen.
• Die Terminalverbindung endet, obwohl der Agent im Hintergrund weiterlaufen könnte oder sollte.

Ollama dokumentiert, dass ein 503-Fehler auf einen überlasteten Server hindeuten kann. Die FAQ beschreibt außerdem Modell-Ladezeiten, keep_alive, parallele Requests und die Auswirkungen von Kontextlänge und Parallelität auf den Speicherbedarf.

Prüfen Sie während eines hängenden Auftrags:

ollama ps

und parallel die Logs. Auf macOS nennt die offizielle Troubleshooting-Dokumentation:

cat ~/.ollama/logs/server.log

Unter Linux mit systemd:

journalctl -u ollama --no-pager --follow --pager-end

In einem Container:

docker logs <container-name>

(Ollama-Troubleshooting-Dokumentation)

Für Coding- und Agent-Aufgaben kann eine zu kleine Kontextgröße dazu führen, dass Dateien, Plan, Werkzeuginformationen und Testergebnisse nicht gemeinsam im aktiven Kontext bleiben. Ollama weist darauf hin, dass größere Kontexte mehr Arbeitsspeicher benötigen; die empfohlene Größe hängt daher von Modell, Hardware und Parallelität ab. Erhöhen Sie die Kontextgröße nicht blind. Wenn der Speicher knapp ist, kann ein kleinerer Kontext mit klaren Teilaufgaben stabiler sein als ein großer Kontext, der das System in Auslagerung oder Überlastung bringt.

Bei entfernten Sitzungen sollten Sie zusätzlich prüfen, ob Prime Agent daemonbasiert weiterläuft und später wieder verbunden werden kann. Die Prime-Agent-Dokumentation beschreibt Status-, Attach- und Resume-Befehle für Hintergrundsitzungen. (Prime-Agent-Quickstart und Sitzungsverwaltung)

Abnahme und Standortentscheidung

Beenden Sie die Diagnose erst, wenn Sie die folgende Kette erfolgreich dokumentiert haben:

• Das Modell erscheint in ollama list.
• /api/tags und /v1/models antworten vom tatsächlichen Prime-Agent-Host.
• models.json ist syntaktisch gültig und wird unter /model geladen.
• Ein einfacher Chat-Request funktioniert.
• Eine Datei kann gelesen und kontrolliert geändert werden.
• Ein Testbefehl wird ausgeführt und korrekt ausgewertet.
• Ein längerer Auftrag kann nach einer Unterbrechung wieder aufgenommen werden.
• Logs, Modell-ID, Prime-Agent-Version, Ollama-Version und Konfigurationszusammenfassung sind gespeichert.

Notieren Sie dabei keine API-Schlüssel und keine vertraulichen Quellcodedaten. Speichern Sie stattdessen Hashes, Platzhalter und den Zeitpunkt des Tests.

Wenn die ersten vier Stufen stabil sind, aber die letzten drei wiederholt scheitern, ist eine reine Konfigurationsänderung wahrscheinlich nicht mehr der wirtschaftlichste Weg. Eine lokale Umgebung hat dann oft drei reale Nachteile: begrenzter Arbeitsspeicher, schwankende Verfügbarkeit durch Arbeitsplatz- oder Energiesparzustände und eine schwer reproduzierbare Netz- beziehungsweise Sitzungssituation. Ein eigener Rechner bleibt sinnvoll, wenn Sie dauerhaft hohe Last, lokale Dateien und physische Schnittstellen benötigen. Für zeitlich begrenzte Tests oder Teamsitzungen ist eine unabhängige, dauerhaft erreichbare Mac-Umgebung jedoch leichter zu standardisieren.

Wenn Sie dafür eine alternative Infrastruktur prüfen, finden Sie bei Kvmkit beispielsweise Mac-mini-Mietoptionen für die USA-Ostküste. Für eine erste Einordnung der verfügbaren Wege können Sie außerdem die deutsche Startseite von Kvmkit verwenden. Entscheidend ist nicht, lokale Modelle um jeden Preis auf einem einzelnen Rechner zu halten, sondern eine Umgebung zu wählen, in der Ollama, Prime Agent, Netzwerk, Sitzung und Ressourcen gemeinsam reproduzierbar bleiben.

Für temporäre Rechenleistung, einen abgeschotteten Testarbeitsplatz oder einen langen Agent-Lauf kann das Mieten einer Mac-Umgebung deshalb sinnvoller sein als wiederholtes Ändern von models.json. Für dauerhaft konstante Schwerlast oder Anforderungen an lokale Hardware bleibt der Kauf eines eigenen Systems die ehrlichere Entscheidung. Prüfen Sie vor dem Wechsel zuerst die fünf Fehlergrenzen und nehmen Sie erst danach die Infrastrukturentscheidung vor.

Häufige Fragen

Warum erscheint mein Ollama-Modell nicht in Prime Agent?

Prüfen Sie zuerst, ob Ollama läuft und das Modell mit ollama list sowie einem direkten API-Aufruf erreichbar ist. Danach kontrollieren Sie den tatsächlichen Pfad ~/.prime/agent/models.json, die JSON-Syntax, den Provider-Namen und die exakte Modell-ID. Öffnen Sie anschließend in Prime Agent die Modellansicht erneut, da die Datei laut Dokumentation beim Aufruf von /model neu geladen wird.

Welche baseUrl benötigt Prime Agent für Ollama?

Bei der OpenAI-kompatiblen Schnittstelle verwenden Sie normalerweise die Adresse des Ollama-Servers mit dem Pfad /v1, zum Beispiel http://localhost:11434/v1. Die native Ollama-API liegt dagegen unter /api. Entscheidend ist, dass localhost aus Sicht des Prime-Agent-Prozesses auf den Rechner zeigt, auf dem Ollama tatsächlich lauscht. In Containern oder auf entfernten Hosts ist localhost daher oft falsch.

Ollama antwortet, aber Prime Agent erledigt keine Programmieraufgabe. Was ist zu tun?

Trennen Sie API-Erreichbarkeit von Modellfähigkeit. Testen Sie zuerst das Lesen einer Datei, danach eine kleine Änderung und anschließend einen ungefährlichen Testbefehl. Wenn einfache Antworten funktionieren, aber Werkzeugaufrufe, Änderungen oder mehrstufige Prüfungen wiederholt scheitern, ist das kein sicherer Beweis für einen Prime-Agent- oder Ollama-Fehler. Wechseln Sie dann das Modell oder verkleinern Sie die Aufgabe.

Warum friert Prime Agent mit einem lokalen Modell ein oder verliert den Stream?

Häufige Ursachen sind das erstmalige Laden des Modells, ein wachsender Kontext, parallele Anfragen oder fehlender Arbeitsspeicher. Prüfen Sie Prime-Agent-Status, Ollama-Protokoll und Systemressourcen in derselben Zeitachse. Mit ollama ps sehen Sie, ob das Modell geladen ist und welcher Speicher verwendet wird. Ein 503-Fehler deutet laut offizieller Dokumentation außerdem auf Überlastung hin.

Wie erreicht ein entfernter Prime Agent einen Ollama-Dienst?

Verwenden Sie nicht automatisch localhost, sondern die erreichbare Adresse des Ollama-Hosts und prüfen Sie die Route zunächst mit curl vom selben Rechner oder Container wie Prime Agent. Ollama bindet standardmäßig an 127.0.0.1:11434. Für entfernte Zugriffe muss die Bind-Adresse bewusst geändert und durch Firewall, VPN oder einen abgesicherten Proxy geschützt werden. Offene Internetfreigaben ohne Authentifizierung sind keine belastbare Produktionslösung.

FAQ