Fehlerbehebung

Häufige Probleme und wie Sie sie beheben.

Um Probleme mit OpenCode zu debuggen, beginnen Sie damit, die Logs und die lokalen Daten zu überprüfen, die es auf der Festplatte speichert.

Logs

Log-Dateien werden hier geschrieben:

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

Log-Dateien werden mit Zeitstempeln benannt (z. B. 2025-01-09T123456.log) und die zehn neuesten Log-Dateien werden aufbewahrt.

Sie können die Log-Stufe mit der Befehlszeilenoption --log-level festlegen, 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-Token
log/ - Anwendungslogs
project/ - projektspezifische Daten wie Sitzungs- und Nachrichtendaten
- Wenn sich das Projekt in einem Git-Repository befindet, wird es in ./<project-slug>/storage/ gespeichert
- Wenn es kein Git-Repository ist, wird es in ./global/storage/ gespeichert

Desktop-App

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

Schnellprüfungen

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

Plugins deaktivieren

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

Globale Konfiguration prü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 sie vorübergehend, indem Sie den Schlüssel entfernen oder ihn auf ein leeres Array setzen:

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

Plugin-Verzeichnisse prüfen

OpenCode kann auch lokale Plugins von der Festplatte laden. Verschieben Sie diese vorübergehend aus dem Weg (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 eine 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 -> ~/.cache/opencode einfügen
Linux : ~/.cache/opencode löschen (oder rm -rf ~/.cache/opencode ausführen)
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 einen eigenen lokalen Server starten (Standard) oder sich mit einer von Ihnen konfigurierten Server-URL verbinden.

Wenn Sie einen „Connection Failed"-Dialog sehen (oder die App nie über den Startbildschirm hinauskommt), suchen Sie nach einer benutzerdefinierten Server-URL.

Die Desktop-Standard-Server-URL löschen

Klicken Sie auf dem Startbildschirm auf den Servernamen (mit dem Statuspunkt), um die Serverauswahl zu öffnen. Klicken Sie im Abschnitt Default server auf Clear.

`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 prüfen

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

Heben Sie die Einstellung von OPENCODE_PORT auf (oder wählen Sie einen freien Port) und starten Sie neu.

Linux: Wayland / X11-Probleme

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

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

Windows: WebView2-Runtime

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

Windows: Allgemeine Leistungsprobleme

Wenn Sie unter Windows langsame Leistung, Dateizugriffsprobleme oder Terminalprobleme haben, versuchen Sie, WSL (Windows Subsystem for Linux) zu verwenden. WSL stellt eine Linux-Umgebung bereit, 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 innerhalb der UI löschen können, setzen Sie den gespeicherten Zustand der Desktop-App zurück.

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

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

So finden Sie das Verzeichnis schnell:

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

Hilfe erhalten

Wenn Sie Probleme mit OpenCode haben:

Probleme auf GitHub melden Der beste Weg, Fehler zu melden oder Funktionen 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-Diskussionen 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 sie beheben.

OpenCode startet nicht

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

Authentifizierungsprobleme

Versuchen Sie eine erneute Authentifizierung mit dem Befehl /connect in der TUI
Prüfen Sie, ob Ihre API-Schlüssel gültig sind
Stellen Sie sicher, dass Ihr Netzwerk Verbindungen zur API des Anbieters zulässt

Modell nicht verfügbar

Prüfen Sie, ob Sie sich beim Anbieter authentifiziert haben
Stellen Sie sicher, dass der Modellname in Ihrer Konfiguration korrekt ist
Einige Modelle erfordern möglicherweise spezifischen Zugriff oder Abonnements

Wenn Sie auf ProviderModelNotFoundError stoßen, referenzieren Sie höchstwahrscheinlich irgendwo ein Modell 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 auf einen ProviderInitError stoßen, haben Sie wahrscheinlich eine ungültige oder beschädigte Konfiguration.

So beheben Sie dies:

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

AI_APICallError und Probleme mit Anbieter-Paketen

Wenn Sie auf API-Aufruffehler stoßen, kann dies auf veraltete Anbieter-Pakete zurückzuführen sein. opencode installiert Anbieter-Pakete (OpenAI, Anthropic, Google usw.) dynamisch nach Bedarf und speichert sie lokal im Cache.

So beheben Sie Probleme mit Anbieter-Paketen:

Leeren Sie den Cache der Anbieter-Pakete:
```
rm -rf ~/.cache/opencode
```
Drücken Sie unter Windows WIN+R und löschen Sie: %USERPROFILE%\.cache\opencode
Starten Sie opencode neu, um die neuesten Anbieter-Pakete neu zu installieren

Dadurch wird opencode gezwungen, die aktuellsten Versionen der Anbieter-Pakete herunterzuladen, was häufig Kompatibilitätsprobleme mit Modellparametern und API-Änderungen behebt.

Kopieren/Einfügen funktioniert unter Linux nicht

Linux-Benutzer müssen eines der folgenden Zwischenablage-Dienstprogramme installiert haben, damit die Kopier-/Einfügefunktion funktioniert:

Für X11-Systeme:

apt install -y xclip
# or
apt install -y xsel

Für Wayland-Systeme:

apt install -y wl-clipboard

Für Headless-Umgebungen:

apt install -y xvfb
# and run:
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-Tools in folgender Reihenfolge zu finden: xclip und xsel.

Enterprise Windows (WSL)