OpenCode + Ollama : ein Code-Agent in Ihrem terminal

#OpenCode mit Ollama: Wer macht was

OpenCode ist ein Open-Source-Code-Agent, der im Terminal ausgeführt wird: Er liest Ihr Projekt, ändert Dateien und führt Befehle aus. Er stellt selbst kein Modell bereit. Ollama hingegen lädt Modelle herunter, führt sie auf Ihrem Rechner aus und stellt eine lokale API bereit. Die beiden ergänzen sich: OpenCode sendet seine Anfragen an Ollama, das mit einem lokalen Modell antwortet. Die Frage „OpenCode oder Ollama“ stellt sich daher nicht – man verwendet beide.

Der Nutzen des lokalen Betriebs ist nicht ideologisch begründet. Ein Code-Agent sieht alles: die Verzeichnisstruktur, die Konfigurationsdateien und die Geschäftslogik. Mit einem lokalen Modell bleibt dieser Kontext auf dem Rechner, ohne Abrechnung pro Token und ohne Abhängigkeit vom Netzwerk. Der Preis dafür sind die begrenzten Fähigkeiten: Ein lokales Modell mit einigen Dutzend Milliarden Parametern kommt nicht an die größten gehosteten Modelle heran, und lange Aufgaben laufen langsamer ab.

#Voraussetzungen: Rechner, Terminal und Ollama

Ollama im Betrieb

Prüfen Sie, ob ein Modell antwortet, bevor Sie irgendetwas konfigurieren: ollama list, dann ollama run mit einem Code-Modell. Wenn das funktioniert, bleibt nur noch die Konfiguration von OpenCode.

Ein modernes Terminal

Die Dokumentation von OpenCode nennt WezTerm, Alacritty, Ghostty und Kitty. Unter Windows empfiehlt sie die Verwendung von WSL für bessere Leistung und vollständige Kompatibilität.

Speicher für den Kontext

Ein Agent liest Dateien und baut einen Verlauf auf. Laut Ollama benötigt OpenCode eine Kontextlänge von mindestens 64.000 Tokens. Dadurch wird zusätzlich zum Speicher für die Modellgewichte weiterer Speicher benötigt.

Ein Git-Repository

Nicht zwingend erforderlich, aber empfohlen: Mit git diff oder git restore lässt sich eine fehlgeschlagene Sitzung sauber rückgängig machen.

#OpenCode installieren und mit Ollama verbinden

OpenCode wird über ein Skript oder über Paketmanager installiert. Die Dokumentation listet das offizielle Skript, npm, bun, pnpm, yarn, Homebrew, Arch, Chocolatey, Scoop, Mise und Docker auf. Für macOS und Linux mit Homebrew empfiehlt sie den offiziellen tap anstelle der Standardformel, die seltener aktualisiert wird.

curl -fsSL https://opencode.ai/install | bash

npm install -g opencode-ai

brew install anomalyco/tap/opencode

choco install opencode
scoop install opencode

#Schnelle Methode: ollama launch opencode

Ollama kann OpenCode mit einem ausgewählten Modell starten. Der Befehl ollama launch opencode startet OpenCode mit einer inline übergebenen Konfiguration, ohne Ihre Datei ~/.config/opencode/opencode.json zu überschreiben; Ihre bestehenden OpenCode-Einstellungen gelten weiterhin. Mit der Option --config konfiguriert Ollama OpenCode, ohne eine interaktive Sitzung zu öffnen. Modelle, die nur in opencode.json definiert sind, erscheinen nicht in der Modellauswahl von ollama launch.

ollama launch opencode

#Manuelle Methode: Ollama als Anbieter deklarieren

Wenn Sie lieber die Kontrolle behalten möchten, fügen Sie einen Anbieter in opencode.json hinzu, entweder global (~/.config/opencode/opencode.json) oder im Stammverzeichnis des Projekts. Der OpenAI-kompatible Endpunkt von Ollama lautet http://localhost:11434/v1. Jeder Schlüssel unter models muss exakt dem Modellnamen entsprechen, den ollama list anzeigt.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3-coder:30b": { "name": "Qwen3-Coder 30B" },
        "devstral-small-2:24b": { "name": "Devstral Small 2" }
      }
    }
  }
}

Starten Sie OpenCode neu: Die Modellauswahl bietet die unter dem Anbieter Ollama deklarierten Modelle an.

#Die Falle Nummer eins: die Kontextlänge

Viele erste Versuche scheitern, weil der Kontext zu kurz ist: Der Agent verliert den Anfang der Aufgabe aus dem Blick, liest Dateien wiederholt oder erzeugt inkonsistente Änderungen. Ollama legt keine einheitliche Kontextgröße fest: Die Dokumentation nennt 4.000 Tokens bei weniger als 24 GB VRAM, 32.000 zwischen 24 und 48 GB und 256.000 ab 48 GB. Sie stellt klar, dass für Aufgaben, die einen großen Kontext benötigen, etwa Agenten und Programmierwerkzeuge, eine Kontextgröße von mindestens 64.000 Tokens eingestellt werden muss.

Um den Wert zu ändern, gibt es zwei Möglichkeiten. In der Ollama-Anwendung legen Sie die Kontextgröße mit einem Schieberegler in den Einstellungen fest. Auf der Kommandozeile wird die Variable OLLAMA_CONTEXT_LENGTH beim Start des Servers wirksam. Ein größerer Kontext verbraucht mehr Speicher: Prüfen Sie mit ollama ps, ob das Modell vollständig auf die GPU passt, denn ein Modell, das teilweise auf die CPU ausgelagert wird, wird sehr langsam.

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

#Welches lokale Modell für einen Code-Agenten?

Ein Agent muss Tools zuverlässig aufrufen können: lesen, schreiben, ausführen. Wählen Sie ein Modell, bei dem in der Ollama-Bibliothek die Fähigkeit „tools“ angegeben ist. Hier sind einige Kandidaten, deren Tags und Größen auf ollama.com erfasst wurden.

Diese Größen beziehen sich auf die Dateien; rechnen Sie den Kontext-Cache hinzu, der mit den angeforderten 64.000 Tokens wächst. Das 15 GB große Modell (Devstral Small 2) lässt sich auf einem Rechner mit 24 GB am ehesten nutzen; das 19 GB große Modell (Qwen3-Coder 30B) benötigt mehr Speicherreserve. Auf einem weniger leistungsfähigen Rechner erledigt ein kleineres Modell einfache, gezielte Aufgaben, stößt aber bei einem Refactoring über mehrere Dateien hinweg schneller an seine Grenzen.

#Ein realer Workflow: Eine Route und den zugehörigen Test hinzufügen

Konkretes Beispiel: Einer kleinen Express-API eine GET-Route /health hinzufügen und sie mit einem Test abdecken. Die OpenCode-Dokumentation empfiehlt, mit /init zu beginnen. Dieser Befehl analysiert das Projekt und erstellt im Projektstamm eine Datei AGENTS.md, die in Git committet werden soll, damit der Agent die Struktur besser versteht.

1. 01
   Projekt öffnen

   Wechseln Sie in das Stammverzeichnis des Repositorys, starten Sie opencode und führen Sie beim ersten Mal anschließend /init aus. Prüfen Sie unten, ob das ausgewählte Modell tatsächlich ein Ollama-Modell ist.
2. 02
   In den Plan-Modus wechseln

   Mit der Tab-Taste wechseln Sie zwischen den Modi Plan und Build. Der Modus Plan deaktiviert Änderungen: Der Agent schlägt lediglich vor, wie er vorgehen würde. Bitten Sie ihn vor jeder Änderung um einen Plan.
3. 03
   Die Aufgabe beschreiben

   Geben Sie den Kontext so an, wie Sie es gegenüber einem Junior-Entwickler tun würden: „Füge in src/server.js eine GET-Route /health hinzu, die status ok zurückgibt, und anschließend einen Test in test/health.test.js.“ Das Zeichen @ ermöglicht die Suche nach einer Datei im Projekt.
4. 04
   In den Build-Modus wechseln

   Wenn der Plan Ihnen zusagt, drücken Sie erneut Tab und bitten Sie darum, die Änderungen anzuwenden.
5. 05
   Ausführen und iterieren

   Der Agent kann npm test ausführen, die Ausgabe lesen und Fehler korrigieren. Diese Schleife aus Ausführen, Beobachten und Korrigieren bildet den Kern der Arbeitsweise von KI-Agenten.
6. 06
   Prüfen und committen

   Prüfen Sie git diff vor dem Commit noch einmal. Wenn die Sitzung aus dem Ruder gelaufen ist, stellt git restore den vorherigen Zustand der Dateien wieder her.

Mit einem lokalen Modell ist jeder Schritt langsamer als mit einem gehosteten Modell, und eine mehrdeutige Anweisung muss manchmal umformuliert werden. Der Vorteil liegt in der Kontrolle: Der Code und der Kontext bleiben auf Ihrem Rechner, und Sie wählen das Modell, seine Quantisierung und seine Kontextgröße passend zu Ihrer Hardware.

#Berechtigungen: Was der Agent tun kann, ohne Sie zu fragen

Eine verbreitete Annahme ist, dass der Agent ohne Ihre Zustimmung nichts verändert. Das entspricht nicht dem Standardverhalten. Laut der Dokumentation von OpenCode sind ohne Konfiguration die meisten Berechtigungen auf allow gesetzt, das heißt, die entsprechenden Aktionen werden ohne Rückfrage ausgeführt; nur einige wenige, etwa external_directory und doom_loop, sind auf ask gesetzt. Der Lesezugriff auf .env-Dateien wird standardmäßig verweigert, mit Ausnahme von .env.example.

Für einen Agenten, der ein weniger zuverlässiges lokales Modell steuert, sind strengere Einstellungen ratsam. Die Datei opencode.json unterstützt einen Abschnitt permission, in dem für jede Aktion allow, ask oder deny festgelegt wird; auch eine globale Regel mit * auf ask ist möglich.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": { "*": "ask" }
}

#OpenCode, Cline oder Aider: Welches wählen?

Alle drei nutzen die API von Ollama; die beiden auszuprobieren, die Ihren Gewohnheiten am nächsten kommen, dauert eine Stunde und bringt mehr als ein Vergleich. Wenn Sie Inline-Autovervollständigung statt eines Agenten möchten, sehen Sie sich Tabby an.

#Fehlerbehebung

Das Modell erscheint nicht

Der Name in opencode.json stimmt nicht mit dem Ergebnis von ollama list überein. Kopieren Sie den genauen Namen einschließlich Tags. Mit ollama launch erscheint ein Modell, das nur in opencode.json definiert ist, nicht im Auswahlmenü.

Der Agent vergisst, was er gerade gelesen hat

Der Kontext ist zu kurz: Wechseln Sie auf 64.000 Tokens (OLLAMA_CONTEXT_LENGTH) und überprüfen Sie mit ollama ps.

Verbindung abgelehnt

Der Ollama-Server läuft nicht oder lauscht nicht auf dem Standardport 11434. Testen Sie ollama list und anschließend die in baseURL angegebene URL.

Fehlschlagende Tool-Aufrufe

Das Modell beherrscht Tools nicht gut. Wählen Sie ein Modell mit der Kennzeichnung „tools“ in der Ollama-Bibliothek.

Sehr langsame Antworten

Das Modell und sein Kontext überschreiten die VRAM-Kapazität, sodass ein Teil auf dem Prozessor ausgeführt wird. Reduzieren Sie den Kontext, die Modellgröße oder die Quantisierung.

#Weiterführende Informationen

• Cline + Ollama in VS Code
• Aider + Ollama im Terminal
• Tabby: lokale Code-Autocompletion
• Quantisierung wählen
• Das Kontextfenster verstehen
• Ollama in 5 Minuten installieren

• Quelle: Ollama, Integration von OpenCode
• Quelle: Ollama, Kontextlänge
• Quelle: OpenCode-Dokumentation
• Quelle: OpenCode-Berechtigungen