Fehlerbehebung

Häufige Probleme und wie Sie diese beheben können.

Um Probleme mit OpenCode zu debuggen, überprüfen Sie zunächst die Logs und die lokalen Daten, die auf der Festplatte gespeichert sind.

Logs

Logdateien werden geschrieben nach:

macOS/Linux: ~/.local/share/opencode/log/
Windows: Drücken Sie WIN+R und fügen Sie %USERPROFILE%\.local\share\opencode\log ein

Logdateien sind mit Zeitstempeln benannt (z.B. 2025-01-09T123456.log) und die letzten 10 Logdateien werden aufbewahrt.

Sie können das Log-Level mit der --log-level Kommandozeilenoption setzen, um detailliertere Debug-Informationen zu erhalten. Zum Beispiel: opencode --log-level DEBUG.

Speicher

opencode speichert Sitzungsdaten und andere Anwendungsdaten auf der Festplatte unter:

macOS/Linux: ~/.local/share/opencode/
Windows: Drücken Sie WIN+R und fügen Sie %USERPROFILE%\.local\share\opencode ein

Dieses Verzeichnis enthält:

auth.json - Authentifizierungsdaten wie API-Schlüssel, OAuth-Tokens
log/ - Anwendungslogs
project/ - Projektspezifische Daten wie Sitzungs- und Nachrichtendaten
- Wenn das Projekt in einem Git-Repo ist, wird es in ./<project-slug>/storage/ gespeichert
- Wenn es kein Git-Repo ist, wird es in ./global/storage/ gespeichert

Desktop-App

OpenCode Desktop führt einen lokalen OpenCode-Server (den opencode-cli Sidecar) im Hintergrund aus. Die meisten Probleme werden durch ein fehlerhaftes Plugin, einen beschädigten Cache oder eine falsche Servereinstellung verursacht.

Schnelle Überprüfungen

Beenden Sie die App vollständig und starten Sie sie neu.
Wenn die App einen Fehlerbildschirm zeigt, klicken Sie auf Neustart und kopieren Sie die Fehlerdetails.
Nur macOS: OpenCode Menü -> Webview neu laden (hilft, wenn die UI leer/eingefroren ist).

Plugins deaktivieren

Wenn die Desktop-App beim Start abstürzt, hängt oder sich seltsam verhält, deaktivieren Sie zunächst die Plugins.

Globale Konfiguration überprüfen

Öffnen Sie Ihre globale Konfigurationsdatei und suchen Sie nach einem plugin Schlüssel.

macOS/Linux: ~/.config/opencode/opencode.jsonc (oder ~/.config/opencode/opencode.json)
macOS/Linux (ältere Installationen): ~/.local/share/opencode/opencode.jsonc
Windows: Drücken Sie WIN+R und fügen Sie %USERPROFILE%\.config\opencode\opencode.jsonc ein

Wenn Sie Plugins konfiguriert haben, deaktivieren Sie diese vorübergehend, indem Sie den Schlüssel entfernen oder auf ein leeres Array setzen:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": []
}

Plugin-Verzeichnisse überprüfen

OpenCode kann auch lokale Plugins von der Festplatte laden. Verschieben Sie diese vorübergehend (oder benennen Sie den Ordner um) und starten Sie die Desktop-App neu:

Globale Plugins
- macOS/Linux: ~/.config/opencode/plugins/
- Windows: Drücken Sie WIN+R und fügen Sie %USERPROFILE%\.config\opencode\plugins ein
Projekt-Plugins (nur wenn Sie projektspezifische Konfiguration verwenden)
- <your-project>/.opencode/plugins/

Wenn die App wieder funktioniert, aktivieren Sie die Plugins einzeln wieder, um herauszufinden, welches das Problem verursacht.

Cache leeren

Wenn das Deaktivieren von Plugins nicht hilft (oder eine Plugin-Installation hängt), leeren Sie den Cache, damit OpenCode ihn neu aufbauen kann.

Beenden Sie OpenCode Desktop vollständig.
Löschen Sie das Cache-Verzeichnis:

macOS: Finder -> Cmd+Shift+G -> fügen Sie ~/.cache/opencode ein
Linux: löschen Sie ~/.cache/opencode (oder führen Sie rm -rf ~/.cache/opencode aus)
Windows: Drücken Sie WIN+R und fügen Sie %USERPROFILE%\.cache\opencode ein

Starten Sie OpenCode Desktop neu.

Serververbindungsprobleme beheben

OpenCode Desktop kann entweder seinen eigenen lokalen Server starten (Standard) oder sich mit einer von Ihnen konfigurierten Server-URL verbinden.

Wenn Sie einen Verbindung fehlgeschlagen Dialog sehen (oder die App nie über den Splash-Screen hinauskommt), überprüfen Sie eine benutzerdefinierte Server-URL.

Desktop-Standard-Server-URL löschen

Klicken Sie vom Startbildschirm aus auf den Servernamen (mit dem Statuspunkt), um den Server-Picker zu öffnen. Im Abschnitt Standardserver klicken Sie auf Löschen.

`server.port` / `server.hostname` aus Ihrer Konfiguration entfernen

Wenn Ihre opencode.json(c) einen server Abschnitt enthält, entfernen Sie ihn vorübergehend und starten Sie die Desktop-App neu.

Umgebungsvariablen überprüfen

Wenn Sie OPENCODE_PORT in Ihrer Umgebung gesetzt haben, wird die Desktop-App versuchen, diesen Port für den lokalen Server zu verwenden.

Setzen Sie OPENCODE_PORT zurück (oder wählen Sie einen freien Port) und starten Sie neu.

Linux: Wayland / X11 Probleme

Unter Linux können einige Wayland-Setups leere Fenster oder Compositor-Fehler verursachen.

Wenn Sie Wayland verwenden und die App leer ist/abstürzt, versuchen Sie den Start mit OC_ALLOW_WAYLAND=1.
Wenn das die Dinge verschlimmert, entfernen Sie es und versuchen Sie stattdessen den Start unter einer X11-Sitzung.

Windows: WebView2 Runtime

Unter Windows benötigt OpenCode Desktop die Microsoft Edge WebView2 Runtime. Wenn die App mit einem leeren Fenster öffnet oder nicht startet, installieren/aktualisieren Sie WebView2 und versuchen Sie es erneut.

Windows: Allgemeine Leistungsprobleme

Wenn Sie unter Windows langsame Leistung, Dateizugriffsprobleme oder Terminal-Probleme erleben, versuchen Sie WSL (Windows Subsystem for Linux) zu verwenden. WSL bietet eine Linux-Umgebung, die nahtloser mit den Funktionen von OpenCode zusammenarbeitet.

Benachrichtigungen werden nicht angezeigt

OpenCode Desktop zeigt Systembenachrichtigungen nur an, wenn:

Benachrichtigungen für OpenCode in Ihren OS-Einstellungen aktiviert sind, und
das App-Fenster nicht fokussiert ist.

Desktop-App-Speicher zurücksetzen (letzter Ausweg)

Wenn die App nicht startet und Sie die Einstellungen nicht von der UI aus löschen können, setzen Sie den gespeicherten Zustand der Desktop-App zurück.

Beenden Sie OpenCode Desktop.
Finden und löschen Sie diese Dateien (sie befinden sich im OpenCode Desktop App-Datenverzeichnis):

opencode.settings.dat (Desktop-Standard-Server-URL)
opencode.global.dat und opencode.workspace.*.dat (UI-Zustand wie kürzliche Server/Projekte)

Um das Verzeichnis schnell zu finden:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (dann nach den obigen Dateinamen suchen)
Linux: suchen Sie unter ~/.local/share nach den obigen Dateinamen
Windows: Drücken Sie WIN+R -> %APPDATA% (dann nach den obigen Dateinamen suchen)

Hilfe bekommen

Wenn Sie Probleme mit OpenCode haben:

Probleme auf GitHub melden

Der beste Weg, Bugs zu melden oder Features anzufordern, ist über unser GitHub-Repository:

github.com/anomalyco/opencode/issues (opens in a new tab)

Bevor Sie ein neues Issue erstellen, durchsuchen Sie bestehende Issues, um zu sehen, ob Ihr Problem bereits gemeldet wurde.
Treten Sie unserem Discord bei

Für Echtzeit-Hilfe und Community-Diskussion treten Sie unserem Discord-Server bei:

opencode.ai/discord (opens in a new tab)

Häufige Probleme

Hier sind einige häufige Probleme und wie Sie diese beheben können.

OpenCode startet nicht

Überprüfen Sie die Logs auf Fehlermeldungen
Versuchen Sie mit --print-logs zu starten, um die Ausgabe im Terminal zu sehen
Stellen Sie sicher, dass Sie die neueste Version haben mit opencode upgrade

Authentifizierungsprobleme

Versuchen Sie sich mit dem /connect Befehl in der TUI neu zu authentifizieren
Überprüfen Sie, ob Ihre API-Schlüssel gültig sind
Stellen Sie sicher, dass Ihr Netzwerk Verbindungen zur API des Anbieters erlaubt

Modell nicht verfügbar

Überprüfen Sie, ob Sie sich beim Anbieter authentifiziert haben
Verifizieren Sie, dass der Modellname in Ihrer Konfiguration korrekt ist
Einige Modelle erfordern möglicherweise speziellen Zugang oder Abonnements

Wenn Sie ProviderModelNotFoundError erhalten, referenzieren Sie höchstwahrscheinlich ein Modell irgendwo falsch. Modelle sollten so referenziert werden: <providerId>/<modelId>

Beispiele:

openai/gpt-4.1
openrouter/google/gemini-2.5-flash
opencode/kimi-k2

Um herauszufinden, auf welche Modelle Sie Zugriff haben, führen Sie opencode models aus

ProviderInitError

Wenn Sie einen ProviderInitError erhalten, haben Sie wahrscheinlich eine ungültige oder beschädigte Konfiguration.

Um dies zu beheben:

Überprüfen Sie zunächst, ob Ihr Anbieter korrekt eingerichtet ist, indem Sie dem Anbieter-Leitfaden folgen
Wenn das Problem weiterhin besteht, versuchen Sie Ihre gespeicherte Konfiguration zu löschen:
```
rm -rf ~/.local/share/opencode
```
Unter Windows drücken Sie WIN+R und löschen Sie: %USERPROFILE%\.local\share\opencode
Authentifizieren Sie sich erneut bei Ihrem Anbieter mit dem /connect Befehl in der TUI.

AI_APICallError und Anbieterpaket-Probleme

Wenn Sie API-Aufruffehler erhalten, kann dies an veralteten Anbieterpaketen liegen. opencode installiert Anbieterpakete (OpenAI, Anthropic, Google, etc.) dynamisch nach Bedarf und cached sie lokal.

Um Anbieterpaket-Probleme zu beheben:

Leeren Sie den Anbieterpaket-Cache:
```
rm -rf ~/.cache/opencode
```
Unter Windows drücken Sie WIN+R und löschen Sie: %USERPROFILE%\.cache\opencode
Starten Sie opencode neu, um die neuesten Anbieterpakete neu zu installieren

Dies zwingt opencode, die neuesten Versionen der Anbieterpakete herunterzuladen, was oft Kompatibilitätsprobleme mit Modellparametern und API-Änderungen behebt.

Kopieren/Einfügen funktioniert nicht unter Linux

Linux-Benutzer müssen eines der folgenden Zwischenablage-Werkzeuge installiert haben, damit die Kopieren/Einfügen-Funktionalität funktioniert:

Für X11-Systeme:

apt install -y xclip
# oder
apt install -y xsel

Für Wayland-Systeme:

apt install -y wl-clipboard

Für Headless-Umgebungen:

apt install -y xvfb
# und ausführen:
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
export DISPLAY=:99.0

opencode erkennt, ob Sie Wayland verwenden und bevorzugt wl-clipboard, andernfalls versucht es Zwischenablage-Werkzeuge in dieser Reihenfolge zu finden: xclip und xsel.

Enterprise Windows (WSL)