--- title: Risoluzione dei problemi description: Problemi comuni e come risolverli. --- Per diagnosticare problemi con OpenCode, inizia controllando i log e i dati locali che salva su disco. --- ## Log I file di log vengono scritti in: - **macOS/Linux**: `~/.local/share/opencode/log/` - **Windows**: premi `WIN+R` e incolla `%USERPROFILE%\.local\share\opencode\log` I file di log hanno nomi con timestamp (ad es. `2025-01-09T123456.log`) e vengono conservati i 10 file di log piu recenti. Puoi impostare il livello di log con l'opzione a riga di comando `--log-level` per ottenere informazioni di debug piu dettagliate. Per esempio: `opencode --log-level DEBUG`. --- ## Archiviazione opencode salva i dati delle sessioni e altri dati dell'applicazione su disco in: - **macOS/Linux**: `~/.local/share/opencode/` - **Windows**: premi `WIN+R` e incolla `%USERPROFILE%\.local\share\opencode` Questa directory contiene: - `auth.json` - dati di autenticazione come chiavi API, token OAuth - `log/` - log dell'applicazione - `project/` - dati specifici del progetto come dati di sessione e messaggi - Se il progetto e dentro un repository Git, viene salvato in `.//storage/` - Se non e un repository Git, viene salvato in `./global/storage/` --- ## App desktop OpenCode Desktop esegue in background un server locale di OpenCode (il sidecar `opencode-cli`). La maggior parte dei problemi e causata da un plugin che si comporta male, da una cache corrotta o da un'impostazione del server errata. ### Controlli rapidi - Chiudi completamente l'app e riaprila. - Se l'app mostra una schermata di errore, fai clic su **Restart** e copia i dettagli dell'errore. - Solo macOS: menu `OpenCode` -> **Reload Webview** (utile se l'interfaccia e vuota o bloccata). --- ### Disabilita i plugin Se l'app desktop va in crash all'avvio, si blocca o si comporta in modo strano, inizia disabilitando i plugin. #### Controlla la configurazione globale Apri il tuo file di configurazione globale e cerca la chiave `plugin`. - **macOS/Linux**: `~/.config/opencode/opencode.jsonc` (or `~/.config/opencode/opencode.json`) - **macOS/Linux** (older installs): `~/.local/share/opencode/opencode.jsonc` - **Windows**: premi `WIN+R` e incolla `%USERPROFILE%\.config\opencode\opencode.jsonc` Se hai plugin configurati, disabilitali temporaneamente rimuovendo la chiave o impostandola a un array vuoto: ```jsonc { "$schema": "https://opencode.ai/config.json", "plugin": [], } ``` #### Controlla le directory dei plugin OpenCode puo anche caricare plugin locali dal disco. Spostali temporaneamente altrove (o rinomina la cartella) e riavvia l'app desktop: - **Plugin globali** - **macOS/Linux**: `~/.config/opencode/plugins/` - **Windows**: premi `WIN+R` e incolla `%USERPROFILE%\.config\opencode\plugins` - **Plugin del progetto** (solo se usi una configurazione per progetto) - `/.opencode/plugins/` Se l'app ricomincia a funzionare, riabilita i plugin uno alla volta per capire quale stia causando il problema. --- ### Svuota la cache Se disabilitare i plugin non aiuta (o l'installazione di un plugin e bloccata), svuota la cache in modo che OpenCode possa ricostruirla. 1. Quit OpenCode Desktop completely. 2. Elimina la directory della cache: - **macOS**: Finder -> `Cmd+Shift+G` -> paste `~/.cache/opencode` - **Linux**: elimina `~/.cache/opencode` (oppure esegui `rm -rf ~/.cache/opencode`) - **Windows**: premi `WIN+R` e incolla `%USERPROFILE%\.cache\opencode` 3. Restart OpenCode Desktop. --- ### Risolvi problemi di connessione al server OpenCode Desktop puo avviare il proprio server locale (predefinito) oppure connettersi a un URL server che hai configurato. Se vedi una finestra **"Connection Failed"** (o l'app non supera mai la schermata di avvio), controlla se hai impostato un URL server personalizzato. #### Cancella l'URL del server predefinito dell'app desktop Dalla schermata Home, fai clic sul nome del server (con il pallino di stato) per aprire il selettore dei server. Nella sezione **Default server**, fai clic su **Clear**. #### Rimuovi `server.port` / `server.hostname` dalla tua configurazione Se il tuo `opencode.json(c)` contiene una sezione `server`, rimuovila temporaneamente e riavvia l'app desktop. #### Controlla le variabili d'ambiente Se hai `OPENCODE_PORT` impostato nell'ambiente, l'app desktop provera a usare quella porta per il server locale. - Rimuovi `OPENCODE_PORT` (o scegli una porta libera) e riavvia. --- ### Linux: problemi Wayland / X11 Su Linux, alcune configurazioni Wayland possono causare finestre vuote o errori del compositor. - Se sei su Wayland e l'app e vuota o va in crash, prova ad avviarla con `OC_ALLOW_WAYLAND=1`. - Se peggiora la situazione, rimuovilo e prova invece ad avviare sotto una sessione X11. --- ### Windows: runtime WebView2 Su Windows, OpenCode Desktop richiede **WebView2 Runtime** di Microsoft Edge. Se l'app si apre su una finestra vuota o non parte, installa/aggiorna WebView2 e riprova. --- ### Windows: problemi generali di prestazioni Se riscontri prestazioni lente, problemi di accesso ai file o problemi del terminale su Windows, prova a usare [WSL (Windows Subsystem for Linux)](/docs/windows-wsl). WSL fornisce un ambiente Linux che funziona in modo piu fluido con le funzionalita di OpenCode. --- ### Notifiche non visualizzate OpenCode Desktop mostra le notifiche di sistema solo quando: - le notifiche sono abilitate per OpenCode nelle impostazioni del sistema operativo, e - la finestra dell'app non e in primo piano. --- ### Reimposta lo stato dell'app desktop (ultima risorsa) Se l'app non si avvia e non riesci a ripulire le impostazioni dall'interfaccia, reimposta lo stato salvato dell'app desktop. 1. Quit OpenCode Desktop. 2. Trova ed elimina questi file (si trovano nella directory dati dell'app OpenCode Desktop): - `opencode.settings.dat` (desktop default server URL) - `opencode.global.dat` e `opencode.workspace.*.dat` (stato dell'interfaccia come server/progetti recenti) Per trovare rapidamente la directory: - **macOS**: Finder -> `Cmd+Shift+G` -> `~/Library/Application Support` (poi cerca i nomi file qui sopra) - **Linux**: cerca sotto `~/.local/share` i nomi file qui sopra - **Windows**: premi `WIN+R` -> `%APPDATA%` (poi cerca i nomi file qui sopra) --- ## Ottenere aiuto Se riscontri problemi con OpenCode: 1. **Segnala i problemi su GitHub** Il modo migliore per segnalare bug o richiedere funzionalita e tramite il nostro repository GitHub: [**github.com/anomalyco/opencode/issues**](https://github.com/anomalyco/opencode/issues) Prima di creare una nuova issue, cerca tra quelle esistenti per vedere se il problema e gia stato segnalato. 2. **Unisciti al nostro Discord** Per supporto in tempo reale e discussioni con la community, unisciti al nostro server Discord: [**opencode.ai/discord**](https://opencode.ai/discord) --- ## Problemi comuni Ecco alcuni problemi comuni e come risolverli. --- ### OpenCode non si avvia 1. Controlla i log per eventuali messaggi di errore 2. Prova a eseguire con `--print-logs` per vedere l'output nel terminale 3. Assicurati di avere l'ultima versione con `opencode upgrade` --- ### Problemi di autenticazione 1. Prova a riautenticarti con il comando `/connect` nella TUI 2. Controlla che le chiavi API siano valide 3. Assicurati che la rete permetta connessioni all'API del provider --- ### Modello non disponibile 1. Controlla di esserti autenticato con il provider 2. Verifica che il nome del modello nella configurazione sia corretto 3. Alcuni modelli potrebbero richiedere accessi o abbonamenti specifici Se incontri `ProviderModelNotFoundError`, probabilmente stai facendo riferimento a un modello in modo errato da qualche parte. I modelli vanno indicati in questo formato: `/` Esempi: - `openai/gpt-4.1` - `openrouter/google/gemini-2.5-flash` - `opencode/kimi-k2` Per capire a quali modelli hai accesso, esegui `opencode models` --- ### ProviderInitError Se incontri un ProviderInitError, probabilmente la tua configurazione e invalida o corrotta. Per risolvere: 1. Per prima cosa, verifica che il provider sia configurato correttamente seguendo la [guida ai provider](/docs/providers) 2. Se il problema persiste, prova a cancellare la configurazione salvata: ```bash rm -rf ~/.local/share/opencode ``` Su Windows, premi `WIN+R` ed elimina: `%USERPROFILE%\.local\share\opencode` 3. Riautenticati con il provider usando il comando `/connect` nella TUI. --- ### AI_APICallError e problemi dei pacchetti provider Se incontri errori nelle chiamate API, potrebbe dipendere da pacchetti provider non aggiornati. opencode installa dinamicamente i pacchetti provider (OpenAI, Anthropic, Google, ecc.) quando servono e li mette in cache localmente. Per risolvere problemi coi pacchetti provider: 1. Svuota la cache dei pacchetti provider: ```bash rm -rf ~/.cache/opencode ``` Su Windows, premi `WIN+R` ed elimina: `%USERPROFILE%\.cache\opencode` 2. Riavvia opencode per reinstallare i pacchetti provider piu recenti Questo forzera opencode a scaricare le versioni piu recenti dei pacchetti provider, cosa che spesso risolve problemi di compatibilita con parametri dei modelli e cambiamenti delle API. --- ### Copia/incolla non funziona su Linux Su Linux e necessario avere installata una delle seguenti utility per gli appunti affinche copia/incolla funzioni: **Per sistemi X11:** ```bash apt install -y xclip # or apt install -y xsel ``` **Per sistemi Wayland:** ```bash apt install -y wl-clipboard ``` **Per ambienti headless:** ```bash apt install -y xvfb # and run: Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 & export DISPLAY=:99.0 ``` opencode rilevera se stai usando Wayland e preferira `wl-clipboard`; altrimenti provera a trovare gli strumenti per gli appunti nell'ordine: `xclip` e `xsel`.