opencode/packages/web/src/content/docs/it/troubleshooting.mdx

---
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`.