OpenCode mit Ollama: Verbindungs- und Werkzeugfehler beheben

Wenn OpenCode mit Ollama nicht mehr funktioniert, prüfen Sie zunächst den Server-Endpunkt und die exakte Modell-ID, bevor Sie das Modell wechseln. Wenn beide Prüfungen erfolgreich sind, testen Sie eine kleine Dateiänderung, um ein Tool-Call-Problem von einem Verbindungsproblem zu unterscheiden. Ein Modell, das auf eine Chat-Anfrage antwortet, hat damit nur den ersten Teil eines Coding-Agent-Workflows bestanden.

Dieser Leitfaden setzt voraus, dass Ollama und OpenCode bereits installiert sind. Für Installation und Provider-Setup verwenden Sie den Ollama mit OpenCode Setup-Leitfaden. Die hier beschriebene Vorgehensweise grenzt Fehler ein, ohne Ihre funktionierende Konfiguration wiederholt zu ändern.

Ermitteln, welche Anfrage fehlschlägt

Ein OpenCode-Fehler kann vor der Inferenz, während der Generierung oder bei der Ausführung eines Tools auftreten. Prüfen Sie diese Phasen getrennt. Eine verweigerte Verbindung deutet auf ein anderes Problem hin als ein Modell, das einen JSON-ähnlichen Absatz zurückgibt. Notieren Sie den Endpunkt, das ausgewählte Modell und die Fehlermeldung, bevor Sie eine Einstellung ändern – so erkennen Sie, ob die Änderung geholfen hat.

Beobachtung	Nächste Prüfung	Was das Ergebnis belegt
Verbindung verweigert	Anfrage an /api/version auf dem konfigurierten Host und Port	Ob dieser Ollama-Endpunkt erreichbar ist
Modell nicht gefunden	/v1/models lesen und die exakte ID vergleichen	Ob das angefragte Modell auf diesem Server existiert
Chat funktioniert, Dateien bleiben unverändert	Tool-Aufrufe und Berechtigungsergebnisse prüfen	Ob OpenCode eine Aktion versucht und abgeschlossen hat
Kleine Änderungen funktionieren, große Aufgaben scheitern	Zugewiesenen Kontext und Laufzeit-Logs prüfen	Ob die größere Aufgabe auf ein messbares Limit stößt
Lokal funktioniert, Cloud hängt	Beide Routen getrennt testen	Ob der Fehler spezifisch für den Cloud-Pfad ist

Notieren Sie die Versionen, bevor Sie einen Fehler reproduzieren:

opencode --version
ollama --version

Die lokalen Prüfungen für diesen Artikel verwendeten OpenCode 1.19.4 und Ollama 0.32.9 auf einem Apple M3 Ultra mit 96 GB Unified Memory. Diese Hardware kann unser gewähltes 31B-Modell betreiben; es handelt sich nicht um eine Speicherempfehlung für einen kleineren Laptop. Für die Modellauswahl auf anderer Hardware lesen Sie den Ollama Coding-Modell-Leitfaden.

Den Endpunkt prüfen, bevor das Modell gewechselt wird

Senden Sie eine Anfrage an denselben Host und Port, den OpenCode verwendet. Ein lokaler Server unter 127.0.0.1:11434 und ein Server unter 127.0.0.1:11435 sind unterschiedliche Endpunkte. Wenn die Anfrage fehlschlägt, beheben Sie zuerst das Problem mit dem Server oder der Adresse. Ein Modellwechsel kann eine abgelehnte Netzwerkverbindung nicht beheben.

curl --fail-with-body --max-time 5 \
  http://127.0.0.1:11434/api/version

curl --fail-with-body --max-time 5 \
  http://127.0.0.1:11434/v1/models

Eine Versionsantwort bestätigt, dass Ollama erreichbar ist und antwortet. Eine Modelllisten-Antwort zeigt, welche Modell-IDs dieser Server bereitstellt. Eine leere Liste bedeutet, dass der Server erreichbar ist, aber keine Modelle aufgeführt sind – das ist etwas anderes als ein Verbindungsfehler.

Wenn Ollama gestoppt ist, starten Sie die Anwendung oder führen Sie den Server in einem Terminal aus:

ollama serve

Wenn der Port bereits belegt ist, prüfen Sie, welcher Server läuft, statt eine weitere Kopie zu starten. Eine Remote-Ollama-Installation erfordert die Adresse des Remote-Servers; 127.0.0.1 verweist immer auf die Maschine, die den Client ausführt.

Die OpenCode-Integrationsdokumentation von Ollama verwendet eine OpenAI-kompatible Base-URL, die auf /v1 endet. Dieses Suffix muss in der Provider-Konfiguration von OpenCode erhalten bleiben. Native Diagnose-Routen wie /api/version liegen außerhalb dieser Basis-URL.

Das konfigurierte Modell mit der exakten Server-ID abgleichen

Verwenden Sie die vom Server zurückgegebene Modell-ID einschließlich ihres Tags. Ein auf einem Ollama-Server heruntergeladenes Modell ist auf einem anderen Server nicht verfügbar, es sei denn, dort ist dasselbe Modell vorhanden. Prüfen Sie den ausgewählten Provider, seine Base-URL und die Modelldeklaration zusammen, bevor Sie die Anfrage erneut senden.

So sieht die Provider-Konfiguration aus, die wir für unsere Tests mit OpenCode 1.19.4 verwendet haben:

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:11434/v1"
      },
      "models": {
        "gemma4:31b": {
          "name": "Gemma 4 31B",
          "limit": {
            "context": 65536,
            "output": 2048
          }
        }
      }
    }
  }
}

Ersetzen Sie gemma4:31b durch eine ID, die Ihr Server tatsächlich auflistet. Das Beispiel lädt dieses Modell nicht herunter. Der vollständige Selektor von OpenCode kombiniert Provider-Name und Modell-ID:

opencode run -m ollama/gemma4:31b "Reply with one short sentence."

Wir haben absichtlich ein nicht vorhandenes Modell über den kompatiblen Endpunkt von Ollama angefragt und HTTP 404 mit einem not_found_error erhalten. Dieses Ergebnis belegt einen Modellauswahlfehler. Es deutet nicht auf Speichermangel oder einen defekten Tool-Parser hin.

Konfigurationen können aus mehreren Quellen stammen. Die OpenCode-Konfigurationsdokumentation beschreibt, wie Einstellungen zusammengeführt werden. Prüfen Sie die aufgelöste Konfiguration lokal, wenn ein Wert ignoriert zu werden scheint:

opencode debug config

Die aufgelöste Konfiguration kann Zugangsdaten enthalten. Extrahieren Sie die relevanten Provider-Einstellungen, bevor Sie einen Diagnosebericht teilen, und entfernen Sie Schlüssel oder unbeteiligte Kontodetails.

Eine Aktion mit einer temporären Coding-Fixture verifizieren

Prüfen Sie die geänderte Datei und führen Sie den Test selbst aus. Geben Sie OpenCode eine kleine Datei mit einem bekannten Bug, lassen Sie OpenCode die Datei reparieren und führen Sie anschließend eine unabhängige Prüfung durch. Damit werden Dateizugriff, Bearbeitung und Ausführung getestet, während die Diagnose klein genug zum Nachvollziehen bleibt.

Erstellen Sie ein neues Verzeichnis und wechseln Sie hinein:

mkdir opencode-ollama-check
cd opencode-ollama-check

cat > add.mjs <<'JS'
export function add(a, b) {
  return a - b;
}
JS

cat > check.mjs <<'JS'
import { add } from './add.mjs';
if (add(2, 3) !== 5) throw new Error('Expected add(2, 3) to return 5');
console.log('PASS');
JS

node check.mjs

Die erste Prüfung sollte fehlschlagen. Kopieren Sie Ihre getestete Provider-Konfiguration in dieses temporäre Verzeichnis und führen Sie dann aus:

opencode run -m ollama/gemma4:31b \
  "Read add.mjs. Fix add so it adds its arguments. Run node check.mjs."

node check.mjs

Prüfen Sie add.mjs selbst. Eine Erfolgsmeldung des Modells reicht nicht aus, wenn die Datei weiterhin subtrahiert oder die unabhängige Prüfung fehlschlägt. Lassen Sie Berechtigungsabfragen sichtbar, damit Sie eine verweigerte Bearbeitung von einem fehlenden Tool-Aufruf unterscheiden können. Während unserer Prüfungen löste macOS die Fixture unter /private/tmp auf, ein Tool forderte jedoch den /tmp-Alias an. OpenCode behandelte den Alias-Pfad als extern und lehnte ihn in einem nicht-interaktiven Lauf ab. Die Verwendung des aufgelösten Verzeichnisses und relativer Dateipfade ermöglichte die Ausführung der Fixture mit eng gefassten Berechtigungen.

Für eine tiefere Untersuchung unterstützt die OpenCode-CLI JSON-Ausgabe:

opencode run --format json -m ollama/gemma4:31b \
  "Read add.mjs and explain the implementation."

Suchen Sie nach einem ausgeführten Tool und seinem Ergebnis. Text, der einen Funktionsnamen oder ein JSON-Objekt enthält, belegt für sich allein nicht, dass OpenCode etwas ausgeführt hat. Nach der Korrektur des Endpunkts und der Fixture-Berechtigungen las OpenCode im Reparaturdurchlauf die Fixture ein, änderte die Subtraktion in eine Addition und bestand eine unabhängige Node-Prüfung. Ein zweiter Durchlauf bestand dieselbe Prüfung, nachdem die absichtlich fehlende Modell-ID ersetzt wurde. In unserem separaten Direct-API-Test gab Gemma 4 31B einen strukturierten read_file-Aufruf bei 65.536 Kontext zurück. Dieses einzelne Ergebnis validiert das Antwortformat des Tests, nicht die Zuverlässigkeit bei Coding-Aufgaben im Allgemeinen.

Den tatsächlich zugewiesenen Ollama-Kontext prüfen

Das angegebene Modelllimit von OpenCode und die Laufzeitzuweisung von Ollama müssen übereinstimmen. Eine Zahl in der Client-Konfiguration zu erhöhen, beweist nicht, dass der Server mehr Kontext zugewiesen hat. Prüfen Sie das laufende Modell während einer Anfrage und vergleichen Sie dann den tatsächlichen Kontext mit dem Prompt und der Tool-Historie der Aufgabe.

Die Ollama-Kontextdokumentation empfiehlt mindestens 64.000 Tokens für Coding-Tools und Agenten. Sie erklärt auch, dass größere Zuweisungen mehr Speicher verbrauchen. Ein manuell gestarteter Server kann eine explizite Kontextgröße festlegen:

OLLAMA_CONTEXT_LENGTH=65536 ollama serve

Setzen Sie diese Variable für den Prozess, der Ollama ausführt. Die Variable nur im Terminal zu exportieren, in dem OpenCode läuft, ändert nichts an einer bereits laufenden Ollama-Instanz. Verwenden Sie die Kontexteinstellung der Anwendung, wenn die Anwendung Ihren Server verwaltet.

Während das Modell geladen ist, prüfen Sie es:

ollama ps

Prüfen Sie die Spalten CONTEXT und PROCESSOR. Wenn Ollama einen benutzerdefinierten Host oder Port verwendet, richten Sie die CLI ebenfalls auf diesen Server. Speicherdruck, CPU-Offloading, Trunkierung und Tool-Format-Fehler erfordern jeweils separate Belege; eine langsame Antwort allein lässt nicht erkennen, welche Ursache vorliegt.

Wenn Ihre Hardware den erforderlichen Kontext nicht bewältigen kann, wählen Sie ein kleineres Modell, das Tools unterstützt, und wiederholen Sie dieselbe Fixture. Vermeiden Sie es, zwei Modelle mit unterschiedlichen Aufgaben zu vergleichen und den Unterschied dann der Modellqualität zuzuschreiben.

Einen nützlichen Fehlerbericht erstellen

Ein nützlicher Bericht ermöglicht es einem anderen Entwickler, dieselbe Anfrage zu reproduzieren. Fügen Sie die Versionen, die bereinigte Provider-Konfiguration, das exakte Modell-Tag, den zugewiesenen Kontext und die kleinste Fixture, die noch fehlschlägt, hinzu. Notieren Sie, ob eine direkte Anfrage erfolgreich ist und ob OpenCode den Modellserver erreicht. Diese Details helfen Maintainern, den Fehler zu lokalisieren.

Der OpenCode-Troubleshooting-Leitfaden erklärt, wie Sie Logs finden. In der getesteten Version identifiziert dieser Befehl die konfigurierten Daten- und Log-Pfade:

opencode debug paths

Behandeln Sie lokale und Cloud-Ergebnisse getrennt. Ein lokaler Coding-Test kann die Ollama-Cloud-Authentifizierung oder -Verfügbarkeit nicht validieren, und ein Cloud-Ausfall belegt keine lokale Tool-Use-Regression. Ebenso beweist ein älteres Issue, das dasselbe Symptom beschreibt, nicht, dass der dort vorgeschlagene Fix auf Ihre installierte Version zutrifft.

Wenn die Fixture erfolgreich ist, aber Ihre Repository-Aufgabe fehlschlägt, bewahren Sie die funktionierende Fixture auf und erhöhen Sie die Komplexität schrittweise: eine weitere Datei, eine größere Eingabe oder eine längere Tool-Sequenz. Die erste Änderung, die den Fehler reproduziert, ist nützlicher als beide Anwendungen ohne Vergleich neu zu installieren.

Nach Abschluss der lokalen Diagnose behandelt der OpenCode-Custom-Provider-Leitfaden das Haimaker-Setup für eine separate Provider-Konfiguration. Halten Sie private lokale Tests lokal; der Wechsel des Providers ist ein optionaler nächster Schritt, wenn es die Arbeitslast erlaubt.

Häufig gestellte Fragen

Bedeutet eine erfolgreiche Ollama-Chat-Antwort, dass OpenCode-Tools funktionieren?

Nein. Eine Chat-Antwort zeigt nur, dass das Modell Text generieren kann. OpenCode benötigt zusätzlich strukturierte Tool-Aufrufe, die Berechtigung zur Ausführung und ausreichend Kontext für die Aufgabe. Überprüfen Sie eine tatsächliche Dateiänderung und deren Testergebnis.

Weist eine Erhöhung des OpenCode-Kontextlimits mehr Ollama-Speicher zu?

Ein beworbenes Kontextlimit in OpenCode beweist nicht, dass Ollama diesen Kontext zugewiesen hat. Konfigurieren Sie den Ollama-Server und prüfen Sie das laufende Modell mit ollama ps. Ein größerer Kontext erhöht auch die Speicheranforderungen.

Sollte ich alles neu installieren, wenn ein Ollama-Modell aus OpenCode verschwindet?

Vergleichen Sie zunächst die von Ollama zurückgegebenen Modell-IDs mit dem in Ihrer OpenCode-Konfiguration deklarierten Modell. Prüfen Sie den Endpunkt und den ausgewählten Provider, bevor Sie eine der beiden Anwendungen neu installieren.