Guida opencode.jsonc: 7 controlli prima del commit

La risposta utile non è solo dove mettere il file. Usa opencode.jsonc per impostazioni OpenCode non segrete e revisionabili, tieni le credenziali fuori dal repository, capisci come si fondono configurazione globale e di progetto, poi valida provider, modelli, permessi e rollback.

La documentazione ufficiale indica supporto JSON e JSONC. I commenti devono spiegare perché esiste una scelta, chi la possiede e quale comando la verifica.

Non salvare segreti nel file. Modelli, shell, strumenti, permessi e percorsi di progetto possono stare nella configurazione; API key, token, URL private e proxy restano fuori dal repository.

OpenCode unisce i file di configurazione invece di sostituirli interamente. Preferenze globali e regole di progetto possono quindi combinarsi se non usano la stessa chiave.

La configurazione globale è adatta alle abitudini personali. Quella di progetto è adatta a regole revisionabili dal team: modello, percorsi ignorati, comandi, MCP e permessi.

Copia gli ID modello dai docs attuali o dal pannello del provider. Un JSON valido può fallire se il nome è solo marketing.

Usa modello principale e piccolo solo con una ragione chiara: costo, latenza, contesto, disponibilità locale o compliance. Se la ragione cambia, rivedi il file.

I permessi sono la parte più delicata. Lascia edit e comandi su ask finché non provi quali azioni sono ripetute, reversibili e a basso rischio.

Installazioni, cancellazioni, migrazioni, deploy, push, segreti e cartelle esterne restano deny o revisione esplicita. Eccezioni agent o MCP devono stare vicino al ruolo.

Aggiungi l'URL dello schema ufficiale per validazione e autocomplete. Non sostituisce la review, ma intercetta chiavi sbagliate e forme obsolete.

Poi controlla ogni chiave: non segreta, utile al progetto, commentata e corretta per la versione attuale.

Prima del commit, prova in un repository a basso rischio. Avvia OpenCode, elenca i modelli, leggi un file, fai una piccola modifica, esegui un comando previsto e verifica un deny.

Registra sistema, shell, provider, modello, comando e rollback. Così il file diventa una base riproducibile.

Controlla anche cartelle generate, note locali storiche e più punti di ingresso del repository. Una configurazione che funziona in un esempio minimo può toccare percorsi diversi in un progetto reale. Una modifica innocua alla documentazione è spesso il test migliore per verificare modello, permessi e shell insieme.

1. Crea file minimoInizia con schema, modello e postura permessi revisionata.
2. Valida sintassiUsa schema editor o strumenti JSONC.
3. Risolvi livelliControlla se vince globale, progetto, percorso custom o gestito.
4. Esegui task piccoloLeggi un file, fai modifica innocua ed esegui comando noto.
5. Testa denyProva un'azione bloccata e conferma che non parta.
6. Registra rollbackDocumenta come togliere la regola o avviare senza il file.

Se qualcosa si rompe, isola i livelli: sintassi JSONC, directory corrente, radice Git, override globali, override di progetto, variabili, provider e permessi.

Su Windows, percorso del file e shell sono separati. Una configurazione valida fallisce se il terminale non vede le variabili o la shell manca.

Aggiungi una revisione periodica quando cambiano provider, ID dei modelli, policy di permesso o requisiti di sicurezza. In questo modo opencode.jsonc resta un riferimento di team verificabile, non una vecchia eccezione locale.