Configurazione

Guida

Configurazione

OpenCode usa due configurazioni separate: una per il terminale e una per server e progetto. Confonderle è l'errore più comune.

Due file, due scopi

FileCosa configuraDove sta
cli.json Solo il terminale: tema, keybind, input, tab, diff, avvisi, Mini, plugin TUI. ~/.config/opencode/cli.json
opencode.json
opencode.jsonc
Server e progetto: modello, agenti, comandi, plugin, provider, MCP, permessi, skill, istruzioni. ~/.config/opencode/ oppure .opencode/ nel progetto

Su Windows, ~ corrisponde alla cartella del profilo (%USERPROFILE%), quindi i percorsi globali diventano:

%USERPROFILE%\.config\opencode\cli.json
%USERPROFILE%\.config\opencode\opencode.json
%USERPROFILE%\.config\opencode\opencode.jsonc
Attenzione: tema e keybind non vanno in opencode.json. Se li metti lì, vengono ignorati. cli.json non ha una variante di progetto: è sempre globale.

cli.json

Esempio con le impostazioni più utili:

{
  "keybinds": {
    "leader": "ctrl+x",
    "agent.cycle": "alt+p",
    "command.palette.show": "ctrl+p"
  },
  "leader": {
    "timeout": 1500
  }
}

Keybind

Un tasto singolo:

{
  "keybinds": {
    "command.palette.show": "ctrl+k"
  }
}

Più alternative, separate da virgola:

{
  "keybinds": {
    "app.exit": "ctrl+c,ctrl+d"
  }
}

Disattivare un binding:

{
  "keybinds": {
    "app.debug": "none",
    "help.show": false
  }
}

Forma a oggetto, quando serve controllare il comportamento dell'evento:

{
  "keybinds": {
    "prompt.paste": {
      "key": "ctrl+v",
      "preventDefault": false
    }
  }
}

Il leader predefinito è Ctrl+X. Dentro gli altri binding, <leader> si riferisce a quel tasto:

{
  "keybinds": {
    "leader": "ctrl+space",
    "model.list": "<leader>m"
  },
  "leader": {
    "timeout": 2000
  }
}

Gli ID di comando sconosciuti vengono ignorati. L'elenco completo è nella pagina Scorciatoie da tastiera.

Tema e altre preferenze

Tema, modalità chiara/scura, comportamento dell'input, tab e diff vivono tutti in cli.json. Puoi anche cambiarli dalla TUI con Ctrl+P → Open settings.

In alternativa, puoi fondere JSON inline sopra la configurazione globale con la variabile d'ambiente OPENCODE_CLI_CONFIG_CONTENT.

opencode.json

Includi sempre lo schema, così l'editor valida i campi e offre l'autocompletamento:

{
  "$schema": "https://opencode.ai/config.json"
}

Esempio completo

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/big-pickle",
  "default_agent": "build",
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" }
  ],
  "agents": {
    "plan": { "mode": "primary" },
    "reviewer": {
      "description": "Revisiona le modifiche",
      "mode": "subagent",
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" }
      ]
    }
  },
  "plugins": ["%USERPROFILE%\\.config\\opencode\\node_modules\\superpowers"],
  "providers": {
    "github-copilot": {
      "models": {
        "gpt-5.5": { "name": "GPT-5.5" }
      }
    }
  },
  "mcp": {
    "servers": {}
  }
}

Dove viene cercato

La configurazione globale vale per ogni progetto. Quella di progetto può stare in qualsiasi directory come opencode.json(c) o .opencode/opencode.json(c), anche in package annidati di un monorepo.

Durante la scoperta normale, OpenCode cerca nella directory corrente e in tutti i suoi antenati fino alla radice del filesystem. I file più vicini hanno la precedenza; i file dentro .opencode/ hanno la precedenza su quelli diretti.

Ricarica

Le modifiche vengono applicate senza riavviare: OpenCode osserva i file di configurazione e ricarica agenti, comandi, skill, server MCP e plugin dopo il salvataggio. La TUI fa lo stesso per cli.json.

Per forzare una ricarica completa:

opencode reload

Oppure, dalla TUI, il comando /reload.

Plugin

opencode plugin list
opencode plugin add @esempio/opencode-tui
opencode plugin check
opencode plugin update
opencode plugin remove @esempio/opencode-tui

In configurazione, il campo V2 è plugins. Il vecchio plugin (singolare) è ancora accettato per compatibilità, ma è deprecato: usa plugins nei file nuovi.

Server MCP

opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp list
opencode mcp auth sentry
opencode mcp logout sentry

I server si configurano sotto mcp.servers. I server remoti usano OAuth per impostazione predefinita: se mcp list segnala che serve l'autenticazione, apri /mcps nella TUI, scegli il server e accedi.

Permessi

I permessi sono regole ordinate. Vince l'ultima regola che corrisponde, quindi metti le regole generiche prima delle eccezioni.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status", "effect": "allow" }
  ]
}

Azioni comuni: shell, edit, subagent, read, glob, grep, webfetch, websearch, skill. Effetti: allow, ask, deny.