Troubleshooting

Typowe problemy i sposoby ich rozwiązywania.

Aby debugować problemy z opencode, zacznij od sprawdzenia dzienników i danych lokalnych przechowywanych na dysku.

Logs

Log files are written to:

macOS/Linux: ~/.local/share/opencode/log/
Windows: Naciśnij WIN+R i wklej %USERPROFILE%\.local\share\opencode\log

Nazwy plików dziennika zawierają znaczniki czasu (np. 2025-01-09T123456.log) i przechowywanych jest 10 ostatnich plików dziennika.

Możesz ustawić poziom dziennika za pomocą opcji wiersza poleceń --log-level, aby uzyskać bardziej szczegółowe informacje debugowania. Na przykład opencode --log-level DEBUG.

Storage

opencode przechowuje dane sesji i inne dane aplikacji na dysku pod adresem:

macOS/Linux: ~/.local/share/opencode/
Windows: Naciśnij WIN+R i wklej %USERPROFILE%\.local\share\opencode

Ten katalog zawiera:

auth.json - Authentication data like API keys, OAuth tokens
log/ - Application logs
project/ — Dane specyficzne dla projektu, takie jak dane sesji i komunikatów
- Jeśli projekt znajduje się w repozytorium Git, jest on przechowywany w ./<project-slug>/storage/
- If it is not a Git repo, it is stored in ./global/storage/

opencode Desktop uruchamia w tle lokalny serwer opencode (sidecar opencode-cli). Większość problemów jest spowodowana nieprawidłowo działającą wtyczką, uszkodzoną pamięcią podręczną lub złymi ustawieniami serwera.

Quick checks

Całkowicie zakończ i uruchom ponownie aplikację.
Jeśli aplikacja wyświetli ekran błędu, kliknij Uruchom ponownie i skopiuj szczegóły błędu.
Tylko macOS: menu OpenCode -> Załaduj ponownie przeglądarkę internetową (pomaga, jeśli interfejs użytkownika jest pusty/zawieszony).

Disable plugins

Jeśli aplikacja komputerowa ulega awarii podczas uruchamiania, zawiesza się lub zachowuje się dziwnie, zacznij od wyłączenia wtyczek.

Sprawdź konfigurację globalną

Otwórz globalny plik konfiguracyjny i poszukaj klucza plugin.

macOS/Linux: ~/.config/opencode/opencode.jsonc (or ~/.config/opencode/opencode.json)
macOS/Linux (older installs): ~/.local/share/opencode/opencode.jsonc
Windows: Naciśnij WIN+R i wklej %USERPROFILE%\.config\opencode\opencode.jsonc

Jeśli masz skonfigurowane wtyczki, tymczasowo je wyłącz, usuwając klucz lub ustawiając go na pustą tablicę:

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

Check plugin directories

opencode może także ładować lokalne wtyczki z dysku. Tymczasowo usuń je (lub zmień nazwę folderu) i uruchom ponownie aplikację komputerową:

Global plugins
- macOS/Linux: ~/.config/opencode/plugins/
- Windows: Naciśnij WIN+R i wklej %USERPROFILE%\.config\opencode\plugins
Wtyczki projektowe (tylko jeśli używasz konfiguracji dla poszczególnych projektów)
- <your-project>/.opencode/plugins/

Jeśli aplikacja ponownie zacznie działać, włączaj ponownie wtyczki pojedynczo, aby dowiedzieć się, która powoduje problem.

Wyczyść pamięć podręczną

Jeśli wyłączenie wtyczek nie pomoże (lub instalacja wtyczki utknęła), wyczyść pamięć podręczną, aby opencode mógł ją odbudować.

Quit opencode Desktop completely.
Usuń katalog pamięci podręcznej:

macOS: Finder -> Cmd+Shift+G -> paste ~/.cache/opencode
Linux: usuń ~/.cache/opencode (lub uruchom rm -rf ~/.cache/opencode)
Windows: Naciśnij WIN+R i wklej %USERPROFILE%\.cache\opencode

Restart opencode Desktop.

Napraw problemy z połączeniem z serwerem

opencode Desktop może uruchomić własny serwer lokalny (domyślnie) lub połączyć się ze skonfigurowanym adresem URL serwera.

Jeśli zobaczysz okno dialogowe „Połączenie nie powiodło się” (lub aplikacja nigdy nie wychodzi poza ekran powitalny), sprawdź, czy jest niestandardowy adres URL serwera.

Wyczyść domyślny adres URL serwera na komputerze

Na ekranie głównym kliknij nazwę serwera (z kropką stanu), aby otworzyć selektor serwerów. W sekcji Serwer domyślny kliknij Wyczyść.

Usuń `server.port` / `server.hostname` ze swojej konfiguracji

Jeśli Twój opencode.json(c) zawiera sekcję server, tymczasowo usuń ją i uruchom ponownie aplikację komputerową.

Check environment variables

Jeśli w swoim środowisku masz ustawiony OPENCODE_PORT, aplikacja komputerowa spróbuje użyć tego portu dla serwera lokalnego.

Rozbierz OPENCODE_PORT (lub wybierz wolny port) i uruchom ponownie.

Linux: Wayland / X11 issues

On Linux, some Wayland setups can cause blank windows or compositor errors.

Jeśli korzystasz z Wayland, a aplikacja jest pusta/ ulega awarii, spróbuj uruchomić ją za pomocą OC_ALLOW_WAYLAND=1.
Jeśli to pogorszy sprawę, usuń go i zamiast tego spróbuj uruchomić w sesji X11.

Windows: WebView2 runtime

W systemie Windows opencode Desktop wymaga Microsoft Edge WebView2 Runtime. Jeśli aplikacja otwiera się w pustym oknie lub nie uruchamia się, zainstaluj/zaktualizuj WebView2 i spróbuj ponownie.

Windows: General performance issues

Jeśli doświadczasz niskiej wydajności, problemów z dostępem do plików lub problemów z terminalem w systemie Windows, spróbuj użyć [WSL (podsystem Windows dla systemu Linux) (./windows-wsl). WSL zapewnia środowisko Linux, które płynniej współpracuje z funkcjami opencode.

Notifications not showing

opencode Desktop only shows system notifications when:

powiadomienia są włączone dla opencode w ustawieniach systemu operacyjnego, oraz
okno aplikacji nie jest aktywne.

Reset desktop app storage (last resort)

Jeśli aplikacja nie uruchamia się i nie możesz wyczyścić ustawień w interfejsie użytkownika, zresetuj zapisany stan aplikacji komputerowej.

Quit opencode Desktop.
Znajdź i usuń te pliki (znajdują się w katalogu danych aplikacji opencode Desktop):

opencode.settings.dat (domyślny adres URL serwera na komputerze stacjonarnym)
opencode.global.dat i opencode.workspace.*.dat (stan interfejsu użytkownika, taki jak najnowsze serwery/projekty)

Aby szybko znaleźć katalog:

macOS: Finder -> Cmd+Shift+G -> ~/Library/Application Support (następnie wyszukaj nazwy plików powyżej)
Linux: wyszukaj powyższe nazwy plików pod ~/.local/share
Windows: Naciśnij WIN+R -> %APPDATA% (następnie wyszukaj nazwy plików powyżej)

Getting help

Jeśli masz problemy z opencode:

Report issues on GitHub

Najlepszym sposobem zgłaszania błędów lub zgłaszania żądań funkcji jest skorzystanie z naszego repozytorium GitHub:

github.com/anomalyco/opencode/issues

Przed utworzeniem nowego problemu przeszukaj istniejące i sprawdź, czy Twój problem nie został już zgłoszony.
Join our Discord

Aby uzyskać pomoc w czasie rzeczywistym i dyskusję społeczności, dołącz do naszego serwera Discord:

opencode.ai/discord

Common issues

Oto kilka typowych problemów i sposobów ich rozwiązania.

opencode nie uruchamia się

Sprawdź dzienniki pod kątem komunikatów o błędach
Spróbuj uruchomić z --print-logs, aby zobaczyć dane wyjściowe w terminalu
Upewnij się, że masz najnowszą wersję z opencode upgrade

Authentication issues

Spróbuj ponownie uwierzytelnić się za pomocą polecenia /connect w TUI
Sprawdź, czy klucze API są ważne
Upewnij się, że Twoja sieć umożliwia połączenia z interfejsem API dostawcy

Model niedostępny

Sprawdź, czy dokonałeś uwierzytelnienia u dostawcy
Sprawdź, czy nazwa modelu w konfiguracji jest poprawna
Some models may require specific access or subscriptions

Jeśli napotkasz ProviderModelNotFoundError, najprawdopodobniej się mylisz odwołując się gdzieś do modelu. Models should be referenced like so: <providerId>/<modelId>

Examples:

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

Aby dowiedzieć się, do jakich modeli masz dostęp, uruchom opencode models

ProviderInitError

Jeśli napotkasz błąd ProviderInitError, prawdopodobnie masz nieprawidłową lub uszkodzoną konfigurację.

Aby rozwiązać ten problem:

Najpierw sprawdź, czy Twój dostawca jest prawidłowo skonfigurowany, postępując zgodnie z przewodnikiem dostawców
Jeśli problem będzie się powtarzał, spróbuj wyczyścić zapisaną konfigurację:
Okno terminala
```
rm -rf ~/.local/share/opencode
```
W systemie Windows naciśnij WIN+R i usuń: %USERPROFILE%\.local\share\opencode
Ponownie uwierzytelnij się u swojego dostawcy za pomocą polecenia /connect w TUI.

Problemy z AI_APICallError i pakietem dostawcy

Jeśli napotkasz błędy wywołań API, może to wynikać z nieaktualnych pakietów dostawców. opencode dynamicznie instaluje pakiety dostawców (OpenAI, Anthropic, Google itp.) w razie potrzeby i przechowuje je lokalnie w pamięci podręcznej.

Aby rozwiązać problemy z pakietem dostawcy:

Wyczyść pamięć podręczną pakietu dostawcy:
Okno terminala
```
rm -rf ~/.cache/opencode
```
W systemie Windows naciśnij WIN+R i usuń: %USERPROFILE%\.cache\opencode
Uruchom ponownie kod opencode, aby ponownie zainstalować najnowsze pakiety dostawców

Zmusi to opencode do pobrania najnowszych wersji pakietów dostawców, co często rozwiązuje problemy ze zgodnością z parametrami modelu i zmianami API.

Copy/paste not working on Linux

Aby funkcja kopiowania/wklejania działała, użytkownicy systemu Linux muszą mieć zainstalowane jedno z następujących narzędzi schowka:

Dla systemów X11:

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

Dla systemów Wayland:

apt install -y wl-clipboard

Dla środowisk headless:

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

opencode wykryje, czy używasz Waylanda i wolisz wl-clipboard, w przeciwnym razie spróbuje znaleźć narzędzia schowka w kolejności: xclip i xsel.