OpenCode CLI nella pratica: flussi di lavoro, automazione e insidie

L’interfaccia a riga di comando di OpenCode è progettata per la scripting, le pipeline CI e le esecuzioni non monitorate di agenti. Questo articolo è una guida pratica per utilizzarlo nel lavoro quotidiano.

Dietro la CLI si cela un sistema di modelli, strumenti, permessi, agenti, abilità, comandi, sessioni, server MCP e un’architettura client/server. L’agente può leggere e modificare i file del progetto, cercare nei repository, eseguire comandi shell, chiamare strumenti esterni e delegare il lavoro a subagenti. Lo stesso ambiente funziona in modo interattivo nella TUI o in modo non interattivo da script.

Per i piccoli compiti, puoi installarlo, collegare un modello e iniziare a fare domande in pochi minuti. Per un lavoro serio, la qualità dell’esperienza dipende fortemente dalla selezione del modello, dalle istruzioni del repository, dai limiti di autorizzazione, dalla gestione del contesto e da quanto aggressivamente consenti all’agente di operare. Questo articolo si concentra su questa seconda fase, dalla riga di comando: quali casi d’uso rendono, quali workflow di automazione reggono nell’uso quotidiano e quali problemi emergono dopo che la novità di un terminale basato su IA è svanita. Fa parte della sezione AI Developer Tools di questo sito.

Le osservazioni qui riportate sono state verificate con OpenCode 1.18.9 e la documentazione corrente nell’agosto 2026. OpenCode cambia rapidamente, quindi gli esempi di configurazione meritano una rapida verifica della documentazione prima di essere copiati in una configurazione di team a lungo termine. Se non hai ancora installato OpenCode, la guida rapida di OpenCode copre l’installazione, la verifica e la connessione del provider.

Cosa è realmente OpenCode: Un ambiente di agenti, non una chat box

OpenCode è un agente di coding open-source progettato attorno al terminale. Una visione semplificata di ciò che mette insieme è la seguente:

La parte importante è il livello di permessi tra l’intenzione di un modello e le azioni che OpenCode può eseguire. Un modello eccellente con permessi scadenti può essere pericoloso. Un modello debole con permessi perfetti è semplicemente lento e fastidioso. L’uso produttivo di OpenCode richiede di ottenere entrambi gli aspetti ragionevolmente corretti.

Lo stesso ambiente serve entrambe le interfacce: la TUI interattiva e la riga di comando non interattiva. È ciò che rende OpenCode scriptabile in un modo in cui una pura interfaccia di chat non lo è. Se vuoi una presa deliberatamente minima sulla stessa idea di agente per terminale — quattro strumenti predefiniti, nessun sandbox integrato, tutto il resto tramite estensioni — la recensione di Pi Coding Agent è un utile contrasto.

Setup: Installazione, Connessione e perché l’Indipendenza dal Provider Conta

OpenCode si installa in una riga — script di installazione ufficiale, npm o Homebrew — e si avvia con opencode da una directory del repository. La guida rapida di OpenCode copre la matrice di installazione completa (Arch, Windows, Docker), la verifica e la connessione del provider (/connect e /models), quindi questo articolo non la ripete.

Puoi usare i servizi di modello di OpenCode stesso o collegare provider esterni supportati. OpenCode attualmente costruisce gran parte del suo catalogo di provider utilizzando Models.dev e supporta un’ampia gamma di configurazioni di modelli commerciali e locali.

L’indipendenza dal provider è una delle decisioni architetturali più utili di OpenCode. Il tuo flusso di lavoro di coding non deve essere permanentemente accoppiato a un unico vendor di modelli: puoi usare un modello per lavori di architettura difficili, un altro per compiti di implementazione economici e un modello locale per codice che non dovrebbe lasciare il tuo ambiente.

Quella flessibilità è reale, ma crea un’altra variabile da gestire. Quando OpenCode si comporta male, il problema potrebbe essere l’harness, il prompt, il contesto disponibile, il modello selezionato o l’interazione tra tutti e quattro.

Inizializza il Repository con AGENTS.md Prima di Richiedere Codice

Uno dei primi comandi che vale la pena eseguire in un nuovo repository è:

/init

OpenCode analizza il progetto e crea un file AGENTS.md. Committa quel file.

AGENTS.md è il luogo in cui i vincoli specifici del repository possono diventare un contesto durevole per ogni conversazione — interattiva o scriptata — invece di essere ripetuta a mano. Un file utile è abbastanza breve da rimanere rilevante ma abbastanza concreto da prevenire errori prevedibili. Ad esempio:

# Istruzioni del Repository

## Architettura

- I handler API si trovano sotto src/api.
- La logica di business appartiene sotto src/services.
- L'accesso al database appartiene sotto src/repositories.
- Non chiamare i client del database direttamente dagli handler HTTP.

## Validazione

Dopo modifiche a TypeScript eseguire:

```bash
npm run typecheck
npm test
```

Dopo modifiche al frontend eseguire anche:

```bash
npm run lint
```

## Vincoli

- Non modificare i file generati.
- Non modificare i contratti dell'API pubblica senza chiedere prima.
- Non creare migrazioni del database se non esplicitamente richiesto.
- Non eseguire mai comandi di deployment.

Questo è meno entusiasmante che installare un altro server MCP, ma di solito fornisce più valore. Gli agenti di coding falliscono sorprendentemente spesso perché non sanno quali vincoli sono importanti. Un breve contratto del repository rimuove parte di quell’ambiguità prima della prima chiamata allo strumento.

Lavora dalla Riga di Comando con opencode run

L’interfaccia interattiva riceve la maggior parte dell’attenzione, ma la modalità non interattiva di OpenCode cambia considerevolmente la gamma di workflow utili:

opencode run "Spiega la strategia di gestione degli errori in questo pacchetto"

Puoi usare OpenCode da script shell, job CI, Makefile, task runner o automazione locale senza inserire manualmente la TUI ogni volta. Ad esempio, una revisione di un diff come comando one-shot:

opencode run \
  "Rivedi il diff git corrente per correttezza e test mancanti. Non modificare i file."

O incanalare il contesto direttamente in un run:

git diff --name-only HEAD~1 |
  opencode run "Ispeziona i file modificati e identifica i cambiamenti comportamentali rischiosi."

In un Makefile, la stessa chiamata diventa un target:

.PHONY: review
review:
	opencode run "Rivedi il diff git corrente per correttezza e test mancanti. Non modificare i file."

Poiché un run scriptato non ha un umano al prompt, la politica di permessi che configuri è l’unico guardrail che sta tra il modello e il tuo ambiente. È per questo che la sezione sui permessi qui sotto è più importante per l’automazione che per l’uso interattivo.

La direzione interessante qui non è sostituire gli script deterministici con un LLM. È inserire il ragionamento del modello in luoghi dove la logica shell tradizionale diventa goffo, mantenendo la validazione deterministica attorno ad esso.

I Migliori Casi d’Uso della CLI di OpenCode

OpenCode può tentare quasi qualsiasi compito di programmazione, ma ciò non significa che ogni compito debba essere delegato allo stesso modo. I workflow di maggior valore tendono ad avere tre proprietà: il risultato desiderato è testabile, il contesto rilevante del repository può essere scoperto e i cambiamenti errati sono economici da ispezionare o annullare. Ogni prompt qui sotto funziona nella TUI o come argomento per opencode run.

1. Esplorazione del repository

OpenCode è eccellente nel rispondere a domande che altrimenti richiederebbero una sequenza di comandi grep, ricerche nell’editor, salti tra file e git log. Ad esempio:

Spiega come funziona l'autenticazione in questo repository.

Traccia una richiesta dal middleware HTTP attraverso la validazione del token,
il caricamento dell'utente, l'autorizzazione e l'handler finale.

Non modificare nulla.

Un buon agente cercherà punti di ingresso, seguirà i riferimenti, ispezionerà i test e restituirà qualcosa di più vicino a una passeggiata architettonica che a una semplice ricerca testuale. Questo è uno dei modi più sicuri per introdurre OpenCode in una codebase esistente perché l’agente può fornire valore senza scrivere codice.

2. Piccole correzioni ben delimitate

Un bug a scope ristretto è vicino al compito ideale per un agente di coding. Ad esempio:

La CLI esce con stato 0 quando la validazione della configurazione fallisce.

Trova il percorso di codice responsabile, aggiungi un test di regressione, implementa
la correzione minima ed esegui i test rilevanti.

Non rifattorizzare codice non correlato.

La frase chiave non è “correggi il bug”. Sono i vincoli che circondano il compito. OpenCode funziona meglio quando il successo può essere dimostrato con un test, un compilatore o un comando osservabile. Requisiti vaghi danno al modello spazio per creare codice plausibile piuttosto che codice dimostrabilmente corretto.

3. Generazione di test dopo l’implementazione

I test sono un lavoro utile per gli agenti perché l’implementazione esistente dà a OpenCode qualcosa di concreto su cui ragionare. Un prompt produttivo potrebbe essere:

Rivedi src/parser.ts e i suoi test esistenti.

Identifica i casi limite importanti che attualmente non sono coperti.
Aggiungi solo test. Non modificare l'implementazione.

Esegui la suite di test del parser quando hai finito.

Separare la generazione dei test dall’implementazione è importante. Se lo stesso agente scrive sia la funzionalità che i test in un’unica passata non vincolata, può accidentalmente creare test che validano la sua interpretazione piuttosto che il comportamento previsto.

4. Rifattorizzazione meccanica

OpenCode è molto bravo nelle trasformazioni ripetitive dove lo stato finale desiderato è chiaro. Gli esempi includono:

• sostituire un’API deprecata in tutto un repository;
• convertire codice ripetuto in un helper condiviso;
• rinominare un campo di configurazione;
• migrare i test da un pattern di asserzione a un altro;
• aggiornare gli import dopo aver spostato un pacchetto;
• sostituire un’astrazione di logging obsoleta.

Il compilatore e i test del repository diventano il loop di feedback dell’agente. Un pattern utile è:

Sostituisci gli usi di LegacyResult<T> con Result<T, AppError> solo in
packages/api.

Preserva il comportamento runtime.

Lavora in piccoli lotti. Dopo ogni lotto esegui il typecheck del pacchetto.
Alla fine esegui la suite di test del pacchetto e mostrami il riepilogo
finale del diff git.

Questo è spesso più affidabile che richiedere l’intera migrazione in un unico enorme passo.

5. Revisione del codice

OpenCode diventa molto più utile quando la revisione è trattata come un ruolo di agente separato piuttosto che un altro prompt inviato allo stesso contesto di editing. Puoi creare un agente orientato alla revisione che non può modificare i file. Poi dagli istruzioni come:

Rivedi il diff git corrente.

Concentrati su:
- correttezza;
- sicurezza;
- concorrenza;
- test mancanti;
- gestione degli errori;
- cambiamenti accidentali all'API.

Non riassumere file che non sono cambiati.
Classifica i risultati per gravità.

Un revisore read-only è utile anche se un altro agente di coding ha prodotto i cambiamenti. La separazione è preziosa perché l’implementazione e la critica sono compiti diversi: un agente che ha appena speso diverse migliaia di token difendendo un approccio è spesso meno scettico verso quell’approccio di un revisore fresco.

Usa le Modalità Plan e Build come Diverse Mentalità

OpenCode fornisce agenti primari e subagenti, con workflow integrati che includono comportamento orientato alla pianificazione e all’implementazione. Anche quando la configurazione esatta dell’agente cambia nel tempo, la separazione concettuale rimane utile.

La pianificazione dovrebbe rispondere a domande come:

• Quali file sono importanti?
• Quali pattern esistenti dovrebbero essere seguiti?
• Cosa potrebbe rompersi?
• Come verificheremo il cambiamento?
• Il cambiamento richiesto è realmente locale?

L’implementazione dovrebbe avvenire solo dopo che a quelle domande sono state date risposte ragionevoli. Per compiti sostanziali, preferisco una sequenza di prompt come questa:

Prima indaga la richiesta.

Non modificare i file ancora.

Restituisci:
1. i file rilevanti;
2. il comportamento attuale;
3. il cambiamento proposto;
4. i rischi;
5. i comandi di verifica esatti.

La stessa sequenza funziona come comando one-shot:

opencode run "Prima indaga la richiesta. Non modificare i file ancora. Restituisci: i file rilevanti; il comportamento attuale; il cambiamento proposto; i rischi; i comandi di verifica esatti."

Poi ispeziona il piano prima di consentire le modifiche. Questo sembra più lento che dire immediatamente a un agente di “implementarlo”, ma i fallimenti costosi nel coding agentico di solito derivano da assunzioni errate fatte prima della prima modifica.

Questa è una versione leggera, per singolo compito, della stessa istintività che sta dietro lo sviluppo guidato da specifiche: concordare il piano prima che l’agente inizi a modificare. Per lavori che attraversano più file, sessioni o contributori, una specifica scritta giustifica i suoi sovraccarichi in un modo che un singolo prompt di indagine preliminare non può; il [confronto tra GitHub Spec Kit, Kiro e Claude Code](https://www.glukhov.org/it/ai-devtools/ai-coding-assistants/spec-kit-vs-kiro-vs-claude-code/ “Confronta i workflow SDD di GitHub Spec Kit, AWS Kiro e Claude Code per portabilità, attrito di setup, gate di revisione e lock-in – poi scegli la configurazione giusta per il tuo team.”} copre workflow SDD strutturati che vanno oltre un singolo prompt.

I Subagenti Sono Utili, ma la Delega Non è Gratuita

OpenCode può invocare subagenti specializzati automaticamente o tramite menzioni esplicite. Ad esempio:

@general trova dove è implementato il comportamento di retry

Puoi anche definire subagenti dedicati per lavori come la revisione della sicurezza, l’analisi delle dipendenze, i test frontend o la documentazione. Lo stesso pattern funziona in altri harness; la guida ai subagenti di Claude Code copre il design analogo sul lato Anthropic.

Questo è potente perché il lavoro dei subagenti può rimanere al di fuori del percorso di ragionamento immediato della conversazione primaria. Un agente primario può delegare l’esplorazione del repository e consumare il risultato invece di riempire il proprio contesto con ogni ricerca intermedia. Ma i subagenti creano tre costi meno ovvi:

1. Consumano token. Un albero di agenti che rilegge il repository può diventare sorprendentemente costoso — il mio report di esperienza con Oh My Opencode documenta cosa succede quando quel sovraccarico è portato all’estremo.
2. Creano complessità di policy. I permessi devono essere considerati per l’agente delegato, non solo per il genitore.
3. La delega può nascondere il ragionamento. Quando l’agente primario dice “il subagente ha trovato X”, potresti dover ispezionare la sessione del figlio per capire quanto sia affidabile quella conclusione.

Per la maggior parte dei compiti di coding, due o tre agenti intenzionali sono più utili di un’elaborata società di software fittizia che vive nel tuo terminale.

Se il compito ha realmente bisogno di un orchestratore completo che delega a un elenco fisso di specialisti — esecuzione in background parallela, fasi di pianificazione e ricerca, routing dei modelli per ruolo — è un prodotto diverso costruito sopra queste primitive, non un prompt più grande. La [guida rapida di Oh My Opencode](https://www.glukhov.org/it/ai-devtools/opencode/oh-my-opencode/ “Oh My Opencode QuickStart per OpenCode: Installazione, Configurazione, Esecuzione”}) copre quell’harness.

Usa Agenti Custom come Limiti di Permesso

Gli agenti di OpenCode possono avere prompt, modelli e permessi separati. Questo rende gli agenti utili come confini di sicurezza e flusso di lavoro, non semplicemente come personalità diverse. Ad esempio, un agente di revisione locale al progetto può essere definito come file Markdown:

---
description: Rivede il codice senza modificare il repository
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
    "git status *": allow
    "git log *": allow
  webfetch: deny
---

Rivedi il codice per correttezza, sicurezza, manutenibilità,
cambiamenti comportamentali inaspettati e test mancanti.

Non modificare i file.

Questo è molto meglio che scrivere “per favore non modificare nulla” in prosa. Le istruzioni influenzano il modello. I permessi vincolano lo strumento. Non sono controlli equivalenti.

Configura i Permessi di OpenCode dal Primo Giorno

Una delle caratteristiche pratiche più importanti di OpenCode è che i suoi valori predefiniti normali sono permissivi. Questo è comodo durante una demo e non è necessariamente ciò che voglio su una workstation contenente chiavi SSH, credenziali di produzione, token di pubblicazione pacchetti, contesti Kubernetes e accesso a diversi account cloud. Per i job opencode run non monitorati, le posta in gioco sono ancora più alte: nulla ferma un run tranne la policy che configuri.

Il modello di permessi corrente di OpenCode supporta:

allow
ask
deny

Le regole possono essere applicate all’accesso ai file, alle modifiche, ai comandi shell, alle operazioni web, ai subagenti, alle abilità, alle directory esterne e ad altre categorie di strumenti. Un punto di partenza conservativo potrebbe sembrare così:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git diff *": "allow",
      "git log *": "allow",
      "git push *": "deny",
      "rm *": "deny"
    }
  }
}

Le regole esatte dovrebbero corrispondere al tuo ambiente. Ciò che conta è rendere la policy intenzionale piuttosto che scoprire il valore predefinito dopo che l’agente ha già eseguito qualcosa di sorprendente.

Non confondere i prompt di approvazione con il sandboxing

Le regole di permesso sono utili, ma non sono la stessa cosa dell’isolamento del sistema operativo. Se OpenCode ha il permesso di eseguire un comando shell consentito, quel processo viene eseguito con l’accesso disponibile al tuo ambiente. Un agente di coding può potenzialmente interagire con file, servizi di rete, variabili d’ambiente, credenziali, socket, gestori di pacchetti e altri strumenti di sviluppo.

Per repository sensibili o run non monitorati, un isolamento più forte vale la pena di essere considerato:

Git è rollback. I permessi sono policy. Un container o una VM è isolamento. Sono tre livelli diversi.

Trasforma i Prompt Ripetitivi in Comandi Custom

Se digiti ripetutamente le stesse istruzioni, dovrebbero probabilmente smettere di essere cronologia di chat e diventare configurazione. OpenCode supporta comandi slash custom di progetto e globali per l’interfaccia interattiva. Ad esempio, crea:

.opencode/commands/review.md

con:

---
description: Rivedi i cambiamenti correnti
agent: plan
---

Rivedi il diff git corrente.

Cerca:
- bug;
- problemi di sicurezza;
- gestione degli errori incompleta;
- test mancanti;
- cambiamenti accidentali all'API.

Non modificare i file.

Poi usa:

/review

Questa è una piccola funzionalità con un valore sproporzionato. I workflow di coding-agent affidabili emergono quando i buoni prompt diventano infrastruttura di progetto condivisa piuttosto che frammenti personali della clipboard. Altri comandi di progetto utili potrebbero includere:

/test-changes
/review
/prepare-pr
/check-migration
/update-docs
/release-check

Usa le Abilità per Workflow Riutilizzabili

OpenCode supporta anche file SKILL.md. Le abilità sono utili quando un workflow ha bisogno di più di un singolo prompt. Un’abilità può contenere dettagli operative guida e file di supporto rimanendo non caricata finché l’agente non ne ha realmente bisogno. Candidati utili includono:

• procedure di migrazione del database;
• workflow di rilascio;
• indagine degli incidenti;
• revisioni di compatibilità API;
• pubblicazione di pacchetti;
• validazione dell’infrastruttura;
• convenzioni di architettura interne.

Ad esempio:

.opencode/skills/database-migration/SKILL.md

Una descrizione di abilità potrebbe dire a OpenCode quando la procedura si applica, mentre il corpo spiega come ispezionare gli schemi, creare migrazioni, validare il comportamento di rollback ed eseguire test di integrazione. Se già usi il concetto equivalente in un altro harness, la [guida alle Abilità di Claude per sviluppatori](https://www.glukhov.org/it/ai-devtools/claude-code/claude-skills-for-developers/ “Spiegate le Abilità di Claude: struttura SKILL.md, layout delle cartelle, best practice, test e troubleshooting.”} mappa le stesse decisioni di design.

Il vantaggio è la disciplina del contesto. Scaricare ogni regola organizzativa in AGENTS.md alla fine crea un enorme system prompt che è costoso e sempre più facile per il modello di ignorare. Le abilità permettono alle istruzioni specializzate di entrare nel contesto solo quando necessario.

MCP: Utile Fino a Quando il Catalogo Strumenti Diventa il Problema

OpenCode supporta server MCP locali e remoti. Ciò può esporre tracker di problemi, sistemi di documentazione, browser, piattaforme di osservabilità, database, API e altri strumenti all’agente di coding. Una configurazione tipica potrebbe fornire un server di documentazione:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

MCP è una di quelle funzionalità che è facile abusare. Ogni strumento che l’agente deve comprendere consuma attenzione e frequentemente token di contesto. Una configurazione con quindici server MCP può sembrare potente in uno screenshot della configurazione rendendo al tempo stesso il comportamento reale del modello più lento, più costoso e meno prevedibile.

La mia regola è semplice: se uno strumento non è utile in una settimana normale di lavoro, probabilmente non dovrebbe essere abilitato globalmente. Carica gli strumenti perché un workflow li richiede, non perché l’integrazione esiste.

Modelli Locali in OpenCode: Un’Opzione Reale, Non una Soluzione Magica

Uno dei casi d’uso più forti di OpenCode è la sua capacità di lavorare con endpoint di modelli OpenAI-compatibili locali o self-hosted. Questo è attraente quando:

• il codice sorgente deve rimanere locale;
• i costi API sono significativi;
• già operi infrastruttura GPU;
• vuoi sperimentare con modelli aperti;
• la connettività Internet è inaffidabile;
• il routing dei modelli fa parte della tua piattaforma.

Un provider custom può puntare OpenCode a un endpoint locale come LM Studio, llama.cpp tramite llama-server, vLLM, infrastruttura compatibile con Ollama o un altro server OpenAI-compatibile.

Qui è dove le aspettative contano. Un buon harness di coding non può compensare completamente un modello debole nell’uso di strumenti, nella pianificazione a lungo orizzonte, nel ragionamento sul codice o nel mantenimento delle istruzioni. Le discussioni della comunità attorno alle configurazioni locali di OpenCode convergono ripetutamente sulla stessa osservazione: i modelli locali possono essere eccellenti per compiti delimitati, ma quelli più piccoli spesso hanno bisogno di più supervisione. Per numeri misurati su come i modelli specifici si comportano realmente dentro OpenCode, vedi il mio confronto pratico di LLM per OpenCode.

La soluzione pratica è il routing dei modelli per complessità del compito. Usa un modello più economico o locale per:

• ricerca nel repository;
• documentazione;
• test semplici;
• modifiche ripetitive;
• cambiamenti di formattazione;
• correzioni di bug dirette.

Usa un modello più forte per:

• cambiamenti architetturali;
• bug ambigui;
• rifattorizzazioni tra pacchetti;
• concorrenza;
• codice sensibile alla sicurezza;
• migrazioni difficili.

L’indipendenza dal provider rende questa strategia possibile. Non rende la qualità del modello irrilevante.

Un Workflow Quotidiano Pratico con OpenCode

Il mio workflow preferito è deliberatamente conservativo. Funziona allo stesso modo nella TUI o tramite opencode run; dove un passo è un prompt, la variante a riga di comando è mostrata accanto.

Passo 1: Partire da uno stato Git pulito

git status

Committa i cambiamenti esistenti o registra deliberatamente cosa è già modificato. Un agente di coding IA che opera dentro un albero di lavoro sporco rende la revisione molto più difficile perché i cambiamenti umani e quelli dell’agente si mescolano insieme.

Passo 2: Richiedere prima l’indagine

Indaga il problema #482.

Non modificare i file.

Spiega:
- il comportamento attuale;
- la probabile causa radice;
- i file rilevanti;
- i test esistenti;
- la correzione proposta;
- i comandi di verifica.

Lo stesso prompt come comando one-shot:

opencode run "Indaga il problema #482. Non modificare i file. Spiega il comportamento attuale, la probabile causa radice, i file rilevanti, i test esistenti, la correzione proposta e i comandi di verifica."

Se l’indagine è sbagliata, correggerla è economico.

Passo 3: Ristrettire l’implementazione

Implementa solo la correzione proposta.

Non rifattorizzare codice non correlato.
Aggiungi prima il test di regressione.
Esegui la suite di test più piccola rilevante dopo il cambiamento.

O non interattivamente:

opencode run "Implementa solo la correzione proposta. Non rifattorizzare codice non correlato. Aggiungi prima il test di regressione. Esegui la suite di test più piccola rilevante dopo il cambiamento."

L’agente ora ha uno spazio di decisione più piccolo.

Passo 4: Ispezionare il diff da solo

git diff --stat
git diff

Non esternalizzare completamente questo passo a un altro modello. Stai controllando non solo se il codice sembra plausibile, ma se l’agente ha modificato file che non aveva bisogno di toccare.

Passo 5: Eseguire la verifica deterministica

npm run typecheck
npm test
npm run lint

Usa i comandi reali del progetto. “OpenCode dice che i test passano” non è una prova più forte del tuo terminale che mostra un processo di test riuscito.

Passo 6: Eseguire una revisione indipendente

Chiedi a un agente read-only:

Rivedi il diff non committo come se fosse una pull request scritta
da un altro ingegnere.

Cerca motivi per cui questa implementazione è sbagliata.

Non modificare i file.

La variante a riga di comando:

opencode run "Rivedi il diff non committo come se fosse una pull request scritta da un altro ingegnere. Cerca motivi per cui questa implementazione è sbagliata. Non modificare i file."

La frase “cerca motivi per cui questo è sbagliato” è intenzionale. I modelli sono molto bravi a confermare educatamente lavoro plausibile. I prompt di revisione dovrebbero incoraggiare la falsificazione piuttosto che gli applausi.

Passo 7: Commitare solo dopo che il diff ha senso

git add -p
git commit

Preferisco ancora lo staging interattivo dopo i cambiamenti generati dall’agente. Forza un ultimo passaggio umano attraverso ogni hunk che diventa parte della storia del repository.

Dove OpenCode Diventa Frustrante: Errori Comuni

I limiti interessanti non sono di solito “l’IA ha fatto un errore di sintassi”. I compilatori sono bravi a catturarli. I problemi difficili derivano dall’autonomia, dal contesto, dalle assunzioni nascoste e dalla configurazione.

Sfida 1: La qualità del modello domina l’esperienza

Lo stesso workflow di OpenCode può sembrare eccellente con un modello e quasi inutilizzabile con un altro. Questo rende difficili le recensioni dei prodotti perché gli utenti spesso attribuiscono il comportamento del modello all’harness dell’agente.

Se OpenCode ripetutamente:

• ignora le istruzioni;
• riscrive troppo codice;
• chiama gli strumenti in modo errato;
• entra in loop sulla stessa azione fallita;
• perde il filo dei vincoli;
• inventa API;

prova un altro modello prima di ridisegnare l’intera configurazione di OpenCode. Il terminale non è diventato improvvisamente più intelligente. È stato il modello.

Sfida 2: Le sessioni lunghe accumulano contesto scadente

Le sessioni di coding-agent diventano meno affidabili man mano che le assunzioni errate si accumulano. Un errore iniziale come “questo servizio è stateless” può influenzare decine di decisioni successive anche dopo che i file rilevanti sono cambiati.

OpenCode supporta la compattazione per gestire i limiti di contesto, ma la compressione crea i suoi compromessi. Un riassunto decide necessariamente quali dettagli sopravvivono. Per transizioni di compito importanti, iniziare una sessione fresca è spesso più pulito che continuare una conversazione eroica da 80.000 token. Con i run scriptati la risposta è ancora più semplice: un nuovo opencode run inizia con un contesto pulito ogni volta, quindi lo stato a lungo termine appartiene a file come AGENTS.md, non a una conversazione.

Il contesto non è memoria gratuita. È stato di lavoro, e lo stato di lavoro diventa obsoleto.

Sfida 3: I permessi possono diventare ingannevolmente complicati

Le regole semplici sono facili:

read -> allow
edit -> ask
git push -> deny

Le gerarchie di agenti complesse sono più difficili. Una volta che gli agenti primari possono invocare subagenti, strumenti custom, server MCP e comandi shell, devi ragionare sulle capacità effettive dell’intero workflow piuttosto che su una sola riga di configurazione.

Ci sono state anche discussioni reali della comunità e di GitHub sul comportamento dei permessi dei subagenti e sull’ereditarietà dei permessi. La lezione è più ampia di qualsiasi singolo bug: testa le assunzioni di sicurezza con un repository di scarto reale — ad esempio, git init /tmp/opencode-perm-test e prova a far eseguire all’agente un comando che gli hai negato lì. Se un’azione non deve assolutamente avvenire, non fare affidamento solo su istruzioni in prosa.

Sfida 4: OpenCode cambia rapidamente

OpenCode è stato rilasciato a un ritmo notevole. Questo è buono per le funzionalità e meno gradevole per la longevità della documentazione. Una trappola particolarmente facile nel 2026 è trovare esempi di configurazione da una generazione diversa di OpenCode. La documentazione corrente contiene anche materiale V2 separato il cui schema di configurazione differisce dalla sintassi 1.x consolidata. Ad esempio, i concetti di permesso potrebbero apparire sotto nomi di campo diversi nella documentazione V2.

Non combinare casualmente esempi da:

/docs/

e:

/v2/docs/

senza verificare quale runtime stai effettivamente usando. Quando stai facendo troubleshooting di una configurazione copiata da un post di blog, controlla la sua data di pubblicazione prima di assumere che OpenCode sia rotto.

Sfida 5: La TUI può nascondere la scala

Un’interfaccia conversazionale fa sembrare un cambiamento di dieci file più piccolo di quanto sia realmente. L’agente potrebbe riportare:

Ho implementato la nuova validazione e aggiornato i test rilevanti.

Quella frase potrebbe rappresentare tre righe o 600 righe. Tieni vicini strumenti shell indipendenti:

git status --short
git diff --stat
git diff --name-only
git diff

L’agente di coding non dovrebbe essere l’unico interfaccia attraverso cui osservi l’agente di coding.

Sfida 6: MCP può distruggere l’efficienza del contesto

Meno integrazioni non producono automaticamente un agente di coding migliore. I grandi server MCP possono esporre molti schemi di strumenti, ognuno dei quali consuma contesto del modello e aumenta la complessità della selezione degli strumenti. Se OpenCode si sente stranamente indeciso dopo che hai installato metà dell’ecosistema MCP, disabilita la maggior parte di esso e confronta. Una superficie di strumenti più piccola spesso produce un comportamento dell’agente migliore.

Sfida 7: La privacy locale richiede di verificare l’intero percorso

Eseguire un modello locale non garantisce automaticamente che ogni parte di una toolchain sia locale. Le discussioni della comunità nei primi mesi del 2026 hanno sollevato domande sulla privacy riguardo al comportamento del modello ausiliario di OpenCode e all’architettura dell’interfaccia web. Alcuni di quei riferimenti si riferivano a versioni più vecchie, alcuni erano contestati e alcuni percorsi di codice sono cambiati da allora.

La lezione duratura non è “OpenCode invia tutto da qualche parte”. La lezione duratura è: se il funzionamento solo locale è un requisito rigido, verificalo. Usa l’ispezione di rete, leggi la configurazione corrente, capisci quale interfaccia stai usando, disabilita le integrazioni remote non necessarie e testa la versione esatta che intendi distribuire. I requisiti di sicurezza dovrebbero essere validati, non inferiti da una categoria di prodotto.

OpenCode vs Claude Code e Codex CLI

Il differenziatore più forte di OpenCode non è necessariamente la qualità del coding. Il modello sottostante contribuisce ancora fortemente alla qualità del coding. Il suo differenziatore è il controllo sull’harness.

OpenCode è convincente quando valorizzi:

• un’implementazione open-source;
• flessibilità dei provider;
• workflow terminal-first;
• agenti configurabili;
• permessi granulari;
• supporto per modelli locali;
• MCP;
• comandi e abilità riutilizzabili;
• architettura client/server.

Claude Code è convincente quando vuoi un’esperienza Anthropic strettamente integrata con un forte comportamento del modello first-party e workflow di agenti integrati sempre più rifiniti. Codex CLI è convincente quando i tuoi modelli e workflow preferiti sono già centrati sullo stack di coding di OpenAI.

Non li sceglierei contando le funzionalità. Scegli in base a quale strato vuoi possedere. Se vuoi che un vendor prenda la maggior parte delle decisioni di workflow, un agente di coding first-party può essere attraente. Se vuoi che l’harness rimanga sostituibile mentre sperimenti con provider e configurazioni di agenti, OpenCode fa un argomento più forte.

Cosa Reddit e Hacker News Dicono Giusto su OpenCode

Le discussioni della comunità attorno a OpenCode sono insolitamente polarizzate. Alcuni sviluppatori lo descrivono come il loro harness di coding preferito, specialmente quando combinato con modelli Codex, modelli locali o configurazioni di agenti custom. Altri si concentrano sull’uso delle risorse, sul comportamento dei permessi, sulle domande sulla privacy, sui cambiamenti di autenticazione del provider o sulla complessità che appare una volta che un’applicazione per terminale apparentemente semplice diventa infrastruttura. Entrambe le prospettive sono ragionevoli.

OpenCode non è difficile perché la riga di comando è difficile. È difficile perché un ambiente di coding autonomo espone domande che gli sviluppatori non dovevano rispondere esplicitamente prima:

• Quale modello dovrebbe prendere questa decisione?
• Quali file può leggere?
• Quali comandi può eseguire?
• Quali credenziali può vedere il processo?
• Quali compiti dovrebbero diventare subagenti?
• Quanto contesto dovrebbe sopravvivere?
• Quali strumenti meritano contesto permanente?
• Quale risultato deve essere verificato da un umano?

Un prodotto chiuso rifinito può prendere molte di quelle decisioni per te. OpenCode ne rende molte di più tue. È precisamente per questo che gli utenti avanzati lo amano.

Una Configurazione Iniziale che Raccomanderei

Resisterei a costruire un setup elaborato immediatamente. Inizia con:

1. un modello predefinito forte;
2. un AGENTS.md;
3. permessi conservativi per shell ed editing;
4. un agente di revisione read-only;
5. due o tre comandi custom;
6. nessun server MCP fino a quando non appare un bisogno reale.

Un ambiente semplice è più facile da debuggare. Una volta che un workflow diventa ripetitivo, promuovalo in un comando, abilità o agente. Una volta che una capacità diventa rischiosa, limitala con i permessi. Una volta che il contesto diventa gonfio, suddividi il workflow invece di acquistare semplicemente una finestra di contesto più grande. Questo approccio incrementale è meno impressionante negli screenshot e considerevolmente più gradevole da mantenere.

Chi Dovrebbe Usare OpenCode

OpenCode è una scelta particolarmente buona per gli sviluppatori che già vivono nei terminali e vogliono che il loro agente di coding si comporti come un altro strumento di sviluppo programmabile. Lo considererei fortemente se:

• lavori con più provider LLM;
• vuoi supporto per modelli locali;
• non ti piace essere bloccato a un unico vendor di IA;
• hai bisogno di agenti specifici per il progetto;
• automatizzi compiti di sviluppo da script shell;
• vuoi ispezionare o modificare l’harness di coding;
• comprendi già Git e il tooling CLI normale.

È meno convincente se vuoi principalmente un livello di IA invisibile dentro un IDE. OpenCode si aspetta anche più giudizio operativo di un tradizionale strumento di autocompletamento. Se rivedere i diff, comprendere i comandi shell e gestire i rami Git ti fanno già sentire a disagio, dare a un processo autonomo accesso a quegli strumenti non farà scomparire la complessità sottostante.

Verdetto Finale

OpenCode è uno degli esempi più convincenti di uno strumento di coding IA che diventa infrastruttura per sviluppatori piuttosto che semplicemente un’interfaccia di chat. Le sue migliori funzionalità non sono appariscenti. L’indipendenza dal provider, i permessi espliciti, gli agenti riutilizzabili, l’esecuzione non interattiva, le istruzioni del repository, i comandi, le abilità e gli strumenti componibili lo rendono possibile modellare l’agente attorno a un flusso di lavoro di ingegneria reale.

Il punto debole è l’immagine speculare di quella forza. OpenCode ti dà abbastanza controllo per creare un ambiente di coding disciplinato, ma ti dà anche abbastanza controllo per creare uno sciame complicato, costoso, scarsamente isolato di agenti con venti server MCP e nessun confine di verifica chiaro.

Non ottimizzerei OpenCode per l’autonomia massima. Lo ottimizzerei per loop di feedback brevi. Dagli un problema delimitato, abbastanza contesto per comprendere il problema, il permesso di eseguire solo le azioni necessarie e comandi deterministici che possono provare se il risultato funziona. Questo è meno magico che chiedere a un agente di costruire un’intera applicazione mentre dormi. È anche molto più vicino a come OpenCode diventa genuinamente utile.

Riferimenti

• Documentazione di OpenCode: https://opencode.ai/docs/
• Changelog di OpenCode: https://opencode.ai/changelog
• Repository GitHub di OpenCode: https://github.com/anomalyco/opencode
• Catalogo provider di Models.dev: https://models.dev