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
| File | Cosa configura | Dove sta |
|---|---|---|
cli.json |
Solo il terminale: tema, keybind, input, tab, diff, avvisi, Mini, plugin TUI. | ~/.config/opencode/cli.json |
opencode.jsonopencode.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
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.