Configurazione

Usare il file JSON di configurazione di OpenCode.

Puoi configurare OpenCode tramite un file di configurazione JSON.

Formato

OpenCode supporta sia JSON sia JSONC (JSON con commenti).

{
  "$schema": "https://opencode.ai/config.json",
  // Theme configuration
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
}

Posizione

Puoi posizionare il file di configurazione in vari percorsi con diverso ordine di precedenza.

Le impostazioni di tutte le sorgenti vengono fuse. I file caricati più tardi sovrascrivono solo le chiavi in conflitto; le altre restano invariate.

Ad esempio, se la config globale imposta theme: "opencode" e autoupdate: true e la config del progetto imposta model: "anthropic/claude-sonnet-4-5", la config finale conterrà tutti e tre i valori.

Ordine di precedenza

Le sorgenti di configurazione vengono caricate in questo ordine (le successive sovrascrivono le precedenti):

Config remota (.well-known/opencode) – default dell’organizzazione
Config globale (~/.config/opencode/opencode.json) – preferenze utente
Config personalizzata (variabile d’ambiente OPENCODE_CONFIG)
Config di progetto (opencode.json nella root del progetto)
Directory .opencode – agents, commands, plugin
Config inline (OPENCODE_CONFIG_CONTENT)

In questo modo la config di progetto può sovrascrivere quella globale e la globale può sovrascrivere quella remota.

Remota

Le organizzazioni possono pubblicare una configurazione predefinita tramite l’endpoint .well-known/opencode. Viene recuperata automaticamente quando ti autentichi con un provider che la supporta.

La config remota costituisce il layer di base; le altre sorgenti (globale e progetto) possono sovrascriverla.

Esempio di MCP disabilitato di default:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

E come abilitarlo localmente:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Globale

La config globale di OpenCode va in ~/.config/opencode/opencode.json. Qui ha senso mettere preferenze a livello utente: temi, provider, scorciatoie da tastiera, ecc.

La config globale sovrascrive i default remoti dell’organizzazione.

Per progetto

Aggiungi un file opencode.json nella root del progetto. La config di progetto ha la priorità più alta tra i file standard: sovrascrive sia la globale sia la remota.

All’avvio OpenCode cerca un file di config nella directory corrente e risale fino al root Git più vicino.

Questo file può essere committato in sicurezza e usa lo stesso schema della config globale.

Percorso personalizzato

Con la variabile d’ambiente OPENCODE_CONFIG puoi indicare un percorso alternativo:

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Questa config viene caricata tra quella globale e quella di progetto.

Directory personalizzata

Con OPENCODE_CONFIG_DIR puoi specificare una directory di configurazione alternativa. Viene trattata come una directory .opencode: al suo interno si cercano agents, commands, modes e plugin.

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

La directory personalizzata viene caricata dopo la config globale e le directory .opencode, quindi può sovrascriverne le impostazioni.

Schema

Lo schema del file di configurazione è definito in opencode.ai/config.json.

L’editor può usarlo per validare e offrire completamento automatico.

TUI

Le impostazioni specifiche del TUI si definiscono sotto la chiave tui:

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Opzioni disponibili:

scroll_acceleration.enabled – abilita l’accelerazione dello scroll in stile macOS. Ha priorità su scroll_speed.
scroll_speed – moltiplicatore di velocità di scroll (default 1, minimo 1), ignorato se scroll_acceleration.enabled è true.
diff_style – stile di visualizzazione diff: "auto" si adatta alla larghezza del terminale, "stacked" forza una singola colonna.

Ulteriori dettagli sul TUI.

Server

Le impostazioni del server per opencode serve e opencode web si configurano tramite server:

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["http://localhost:5173"]
  }
}

Opzioni:

port – porta di ascolto
hostname – hostname; se mdns è abilitato e non viene impostato, si usa 0.0.0.0
mdns – abilita il service discovery mDNS
cors – origini aggiuntive per il CORS (schema + host + porta opzionale), ad es. https://app.example.com

Ulteriori dettagli sul server.

Tools

Con l’opzione tools puoi controllare quali strumenti può usare il modello:

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Ulteriori dettagli sugli strumenti.

Modelli

I provider e i modelli si configurano tramite provider, model e small_model:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

small_model definisce un modello più leggero per compiti semplici (es. generazione di titoli). Per impostazione predefinita OpenCode prova a usare un modello più economico dello stesso provider; in mancanza, ricade sul modello principale.

Le opzioni del provider possono includere timeout e setCacheKey:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

timeout – timeout in millisecondi (default 300000). Imposta false per disabilitarlo.
setCacheKey – garantisce che venga sempre impostata una cache key per quel provider.

Puoi anche configurare modelli locali. Ulteriori dettagli sui modelli.

Opzioni specifiche del provider

Alcuni provider supportano opzioni aggiuntive.

Amazon Bedrock

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}

region – regione AWS (default AWS_REGION o us-east-1)
profile – profilo nominato da ~/.aws/credentials (default AWS_PROFILE)
endpoint – URL endpoint personalizzato (alias di baseURL; se entrambi sono presenti, prevale endpoint).

Ulteriori dettagli sulla configurazione di Amazon Bedrock.

Temi

Il tema dell’interfaccia si imposta con la chiave theme:

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

Ulteriori dettagli sui temi.

Agents

Puoi definire agent specializzati per compiti specifici con l’opzione agent:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

Gli agent possono anche essere definiti come file Markdown in ~/.config/opencode/agent/ o .opencode/agent/. Ulteriori dettagli.

Agent predefinito

L’agent predefinito si imposta con default_agent e viene usato quando non ne specifichi uno esplicitamente:

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

Deve essere un agent primario (non un sub‑agent). Può essere integrato ("build", "plan") o un agent personalizzato. Se l’agent non esiste o è un sub‑agent, OpenCode torna a "build" e mostra un avviso.

Vale per tutte le interfacce: TUI, CLI (opencode run), app desktop e GitHub Action.

Condivisione

La funzionalità di condivisione delle sessioni si controlla con la chiave share:

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

Valori possibili:

"manual" – condividere solo manualmente tramite comandi (default)
"auto" – condividere automaticamente le nuove conversazioni
"disabled" – disabilitare del tutto la condivisione

Per impostazione predefinita è "manual", quindi devi eseguire /share esplicitamente.

Comandi

Le attività ripetitive possono essere incapsulate come comandi personalizzati tramite command:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component",
    },
  },
}

Anche i comandi possono essere definiti come file Markdown sotto ~/.config/opencode/command/ o .opencode/command/. Ulteriori dettagli.

Scorciatoie da tastiera

Le scorciatoie si configurano con la chiave keybinds:

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

Ulteriori dettagli sui keybinds.

Aggiornamenti automatici

OpenCode scarica automaticamente le nuove versioni all’avvio. Puoi disattivare questo comportamento con autoupdate:

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

Se non vuoi aggiornamenti automatici ma desideri ricevere notifiche, imposta autoupdate su "notify".

Formatter

I formatter di codice si configurano tramite la chiave formatter:

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Ulteriori dettagli sui formatter.

Permessi

Per impostazione predefinita OpenCode consente tutte le operazioni senza chiedere conferma. Puoi renderlo più restrittivo con l’opzione permission, ad esempio per richiedere conferma per edit e bash:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Ulteriori dettagli sui permessi.

Compattazione

Il comportamento di compattazione del contesto si controlla con compaction:

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}

auto – compatta automaticamente la sessione quando il contesto è pieno (default true).
prune – rimuove vecchi output degli strumenti per risparmiare token (default true).

Watcher

I pattern di esclusione per il file watcher si impostano tramite watcher:

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

I pattern usano la sintassi glob.

Server MCP

I server MCP si configurano tramite la chiave mcp:

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

Ulteriori dettagli.

Plugin

I plugin estendono OpenCode con tools, hook e integrazioni personalizzate.

Posiziona i file di plugin in .opencode/plugin/ o ~/.config/opencode/plugin/. Puoi anche caricare plugin da npm tramite la chiave plugin:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Ulteriori dettagli sui plugin.

Istruzioni

Puoi indicare file di istruzioni per il modello con l’opzione instructions:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Accetta un array di percorsi e pattern glob. Ulteriori dettagli sulle regole.

Provider disabilitati

Con disabled_providers puoi disabilitare completamente alcuni provider, anche se hanno credenziali configurate:

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

Quando un provider è disabilitato:

non viene caricato anche se esistono variabili d’ambiente;
le chiavi impostate tramite /connect vengono ignorate;
i suoi modelli non compaiono nella lista dei modelli.

Provider abilitati

Con enabled_providers definiisci una allow‑list di provider. Se impostata, solo quei provider vengono abilitati, tutti gli altri vengono ignorati:

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

È utile quando vuoi limitare OpenCode a un set ristretto di provider.

Se un provider appare in entrambe le liste, prevale disabled_providers.

Experimental

La chiave experimental raccoglie opzioni in fase di sviluppo attivo:

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

Variabili

Nei file di configurazione puoi usare la sostituzione di variabili per referenziare variabili d’ambiente e contenuti di file.

Variabili d’ambiente

Usa {env:NOME_VARIABILE} per inserire una variabile d’ambiente:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Se la variabile non è definita, viene sostituita con una stringa vuota.

File

Usa {file:percorso/al/file} per inserire il contenuto di un file:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

I percorsi possono essere:

relativi alla directory del file di configurazione;
oppure assoluti che iniziano con / o ~.

Questo è utile per:

tenere i secret (API key, ecc.) in file separati;
includere grandi file di istruzioni senza appesantire la config;
riutilizzare snippet di configurazione tra più progetti.