@neurocode-ai/web 1.18.8

package/src/content/docs/it/troubleshooting.mdx

@@ -0,0 +1,299 @@
+---
+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 `./<project-slug>/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` (o `~/.config/opencode/opencode.json`)
+- **macOS/Linux** (installazioni vecchie): `~/.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)
+  - `<your-project>/.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. Chiudi completamente OpenCode Desktop.
+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. Riavvia 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. Chiudi 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: `<providerId>/<modelId>`
+
+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`.