Salta ai contenuti
OpenCode
app.header.homeapp.header.docs

Risoluzione dei problemi

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 (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:

{
  "$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. 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
  1. 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). 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

    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

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

  2. Se il problema persiste, prova a cancellare la configurazione salvata:

    Terminal window
    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:

    Terminal window
    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:

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

Per sistemi Wayland:

Terminal window
apt install -y wl-clipboard

Per ambienti headless:

Terminal window
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.