OpenCode CLI in pratica: workflow, automazione e insidie

L’interfaccia a riga di comando di OpenCode è progettata per la scripting, le pipeline CI e l’esecuzione non supervisionata di agenti. Questo articolo è una guida pratica al suo utilizzo nel lavoro quotidiano.

Dietro la CLI si nasconde un sistema di modelli, strumenti, autorizzazioni, agenti, skill, comandi, sessioni, server MCP e un’architettura client/server. L’agente può leggere e modificare file di progetto, cercare nei repository, eseguire comandi shell, richiamare 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 compiti piccoli, puoi installarlo, connettere 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 confini delle autorizzazioni, dalla gestione del contesto e da quanto permetti all’agente di operare in modo aggressivo. Questo articolo si concentra su quella seconda fase, dalla riga di comando: quali casi d’uso si rivelano profittevoli, quali flussi di automazione reggono nell’uso quotidiano e quali problemi emergono dopo che la novità di un terminale basato su IA si è esaurita. Fa parte della sezione Strumenti per sviluppatori AI di questo sito.

Le osservazioni qui riportate sono state verificate rispetto a OpenCode 1.18.9 e alla documentazione attuale ad agosto 2026. OpenCode cambia rapidamente, quindi gli esempi di configurazione meritano una rapida verifica della documentazione prima di essere copiati in un setup di team a lunga durata. Se non hai ancora installato OpenCode, il Quickstart di OpenCode copre l’installazione, la verifica e la connessione del provider.

Cos’è davvero OpenCode: un ambiente di agenti, non una chat box

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

La parte importante è il livello di autorizzazioni tra l’intento di un modello e le azioni che OpenCode può eseguire. Un ottimo modello con autorizzazioni errate può essere pericoloso. Un modello debole con autorizzazioni perfette è semplicemente lento e fastidioso. L’uso produttivo di OpenCode richiede di ottenere entrambi gli aspetti ragionevolmente giusti.

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

Setup: Installa, Connetti e Perché l’Indipendenza dal Provider Conta

OpenCode si installa in una riga — script di installazione ufficiale, npm o Homebrew — e inizia con opencode da una directory del repository. Il Quickstart 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 lo ripete.

Puoi usare i servizi modello di OpenCode stesso o connettere 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 ha bisogno di essere permanentemente accoppiato a un singolo venditore di modelli: puoi usare un modello per il lavoro di architettura difficile, 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 performa male, il problema può essere l’arnese, il prompt, il contesto disponibile, il modello selezionato o l’interazione tra tutti e quattro.

Inizializza il Repository con AGENTS.md Prima di Chiederci 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 posto in cui i vincoli specifici del repository possono diventare un contesto durevole per ogni conversazione — interattiva o scripted — invece di essere ripetuti a mano. Un file utile è abbastanza corto da rimanere rilevante ma abbastanza concreto da prevenire errori prevedibili. Per esempio:

# Repository Instructions

## Architecture

- API handlers live under src/api.
- Business logic belongs under src/services.
- Database access belongs under src/repositories.
- Do not call database clients directly from HTTP handlers.

## Validation

After TypeScript changes run:

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

After frontend changes also run:

```bash
npm run lint
```

## Constraints

- Do not modify generated files.
- Do not change public API contracts without asking first.
- Do not create database migrations unless explicitly requested.
- Never run deployment commands.

Questo è meno entusiasmante dell’installazione di 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 contratto di repository breve 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 notevolmente la gamma di flussi di lavoro utili:

opencode run "Explain the error handling strategy in this package"

Puoi usare OpenCode da script shell, job CI, Makefile, task runner o automazione locale senza entrare manualmente nella TUI ogni volta. Per esempio, una revisione diff come comando one-shot:

opencode run \
  "Review the current git diff for correctness and missing tests. Do not edit files."

Oppure incanalare il contesto direttamente in un run:

git diff --name-only HEAD~1 |
  opencode run "Inspect the changed files and identify risky behavior changes."

In un Makefile, la stessa chiamata diventa un target:

.PHONY: review
review:
	opencode run "Review the current git diff for correctness and missing tests. Do not edit files."

Poiché un run scripted non ha un umano nel prompt, la politica di autorizzazioni che configuri è l’unico guardrail che sta tra il modello e il tuo ambiente. Ecco perché la sezione sulle autorizzazioni qui sotto conta più 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 in cui la logica shell tradizionale diventa ingombrante, mantenendo la validazione deterministica intorno ad esso.

I Migliori Casi d’Uso della CLI di OpenCode

OpenCode può provare quasi qualsiasi compito di programmazione, ma ciò non significa che ogni compito debba essere delegato nello stesso modo. I flussi di lavoro a maggior valore tendono ad avere tre proprietà: il risultato desiderato è testabile, il contesto del repository rilevante può essere scoperto e le modifiche errate sono economiche da ispezionare o revertire. 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 comandi git log. Per esempio:

Explain how authentication works in this repository.

Trace a request from the HTTP middleware through token validation,
user loading, authorization, and the final handler.

Do not modify anything.

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

2. Piccole correzioni ben delimitate

Un bug di ambito ristretto è vicino al compito ideale per un agente di coding. Per esempio:

The CLI exits with status 0 when config validation fails.

Find the code path responsible, add a regression test, implement
the smallest fix, and run the relevant tests.

Do not refactor unrelated code.

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 lo spazio per creare codice plausibile anziché codice dimostrabilmente corretto.

3. Generazione di test dopo l’implementazione

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

Review src/parser.ts and its existing tests.

Identify important edge cases that are currently uncovered.
Add tests only. Do not modify the implementation.

Run the parser test suite when finished.

Separare la generazione dei test dall’implementazione è importante. Se lo stesso agente scrive sia la funzione sia i test in un unico passaggio senza vincoli, può accidentalmente creare test che validano la sua stessa interpretazione anziché il comportamento previsto.

4. Refactoring meccanico

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

• sostituire un API deprecata in tutto il 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 package;
• sostituire un’astrazione di logging obsoleta.

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

Replace uses of LegacyResult<T> with Result<T, AppError> in
packages/api only.

Preserve runtime behavior.

Work in small batches. After each batch run the package typecheck.
At the end run the package test suite and show me the final git diff
summary.

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

5. Revisione del codice

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

Review the current git diff.

Focus on:
- correctness;
- security;
- concurrency;
- missing tests;
- error handling;
- accidental API changes.

Do not summarize files that are unchanged.
Rank findings by severity.

Un revisore read-only è utile anche se un altro agente di coding ha prodotto le modifiche. La separazione ha valore perché l’implementazione e la critica sono compiti diversi: un agente che ha appena speso 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 flussi di lavoro integrati che includono comportamenti orientati alla pianificazione e all’implementazione. Anche quando la configurazione esatta degli agenti 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 è davvero locale?

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

First investigate the request.

Do not edit files yet.

Return:
1. the relevant files;
2. the current behavior;
3. the proposed change;
4. risks;
5. the exact verification commands.

La stessa sequenza funziona come comando one-shot:

opencode run "First investigate the request. Do not edit files yet. Return: the relevant files; the current behavior; the proposed change; risks; the exact verification commands."

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

Questa è una versione leggera, per-task, dello stesso istinto dietro lo sviluppo guidato da specifica: raggiungere un accordo sul piano prima che l’agente inizi a modificare. Per lavori che attraversano più file, sessioni o collaboratori, una specifica scritta giustifica il suo overhead in un modo che un singolo prompt investigate-first 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 flussi SDD di GitHub Spec Kit, AWS Kiro e Claude Code in termini di portabilità, frizione di setup, gate di revisione e lock-in — poi scegli il setup giusto per il tuo team.”}) copre i flussi 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. Per esempio:

@general find where retry behavior is implemented

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 arnesi; la [guida sui subagenti di Claude Code](https://www.glukhov.org/it/ai-devtools/claude-code/claude-code-subagents/ “Subagenti di Claude Code spiegati: quando usarli, matematica di contesto e costi, definizioni di subagenti personalizzate e un esempio pratico di revisione del codice.”}) copre il design analogo sul lato Anthropic.

Questo è potente perché il lavoro dei subagenti può rimanere fuori dal 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 rileggono il repository può diventare sorprendentemente costoso — il mio report di esperienza su Oh My Opencode documenta cosa succede quando quel sovraccarico è portato all’estremo.
2. Creano complessità di policy. Le autorizzazioni devono essere considerate 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 aver bisogno di ispezionare la sessione figlia per capire quanto sia affidabile quella conclusione in realtà.

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

Se il compito ha davvero bisogno di un orchestratore completo che delega a un roster fisso di specialisti — esecuzione in background parallela, fasi di pianificazione e ricerca, instradamento del modello per ruolo — quello è un prodotto diverso costruito sopra a queste primitive, non un prompt più grande. Il [Quickstart di Oh My Opencode](https://www.glukhov.org/it/ai-devtools/opencode/oh-my-opencode/ “Oh My Opencode QuickStart per OpenCode: Installa, Configura, Esegui”}) copre quell’arnese.

Usa Agenti Personalizzati come Confini di Autorizzazione

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

---
description: Reviews code without modifying the repository
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
    "git status *": allow
    "git log *": allow
  webfetch: deny
---

Review code for correctness, security, maintainability,
unexpected behavior changes, and missing tests.

Do not modify files.

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

Configura le Autorizzazioni 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 publishing dei package, contesti Kubernetes e accesso a diversi account cloud. Per i job non supervisionati di opencode run, le poste in gioco sono ancora più alte: nulla ferma un run tranne la policy che configuri.

Il modello di autorizzazioni attuale 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 skill, alle directory esterne e ad altre categorie di strumenti. Un punto di partenza conservativo potrebbe essere 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 autorizzazione sono utili, ma non sono la stessa cosa dell’isolamento del sistema operativo. Se OpenCode ha l’autorizzazione per eseguire un comando shell consentito, quel processo si esegue 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 package e altri strumenti di sviluppo. Il [Quickstart di OpenHands CLI](https://www.glukhov.org/it/ai-devtools/openhands/ “Installa OpenHands CLI 1.16.0, puntala a un modello locale o hostato, ed esegui task headless o ACP. Le nuove installazioni sono indirizzate ad Agent Canvas.”}) è l’equivalente sandboxed: uno spazio di lavoro Docker, una modalità headless che approva sempre, e il handoff di Agent Canvas che il progetto OpenHands documenta ora.

Per repository sensibili o run non supervisionati, un isolamento più forte vale la pena considerarlo:

Git è rollback. Le autorizzazioni sono policy. Un container o VM è isolamento. Questi sono tre livelli diversi.

Trasforma i Prompt Ripetitivi in Comandi Personalizzati

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

.opencode/commands/review.md

con:

---
description: Review the current changes
agent: plan
---

Review the current git diff.

Look for:
- bugs;
- security issues;
- incomplete error handling;
- missing tests;
- accidental API changes.

Do not modify files.

Poi usa:

/review

Questa è una piccola funzionalità con valore sproporzionato. I flussi di lavoro affidabili degli agenti di coding 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 Skill per Flussi di Lavoro Riutilizzabili

OpenCode supporta anche file SKILL.md. Le skill sono utili quando un flusso di lavoro ha bisogno di più di un singolo prompt. Una skill può contenere guida operativa dettagliata e file di supporto rimanendo non caricata finché l’agente non ne ha effettivamente bisogno. Candidati utili includono:

• procedure di migrazione del database;
• flussi di lavoro di rilascio;
• indagine sugli incidenti;
• revisioni di compatibilità API;
• publishing dei package;
• validazione dell’infrastruttura;
• convenzioni architetturali interne.

Per esempio:

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

Una descrizione di skill 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 i test di integrazione. Se già usi il concetto equivalente in un altro arnese, la [guida per sviluppatori su Claude Skills](https://www.glukhov.org/it/ai-devtools/claude-code/claude-skills-for-developers/ “Claude Skills spiegate: struttura di SKILL.md, layout delle cartelle, best practices, test e troubleshooting.”}) mappa le stesse decisioni di design.

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

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

OpenCode supporta server MCP locali e remoti. Questo può esporre tracker di issue, 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 sovradimensionare. Ogni strumento che l’agente deve capire consuma attenzione e spesso token di contesto. Un setup con quindici server MCP può sembrare potente in uno screenshot di configurazione mentre rende 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 flusso di lavoro li richiede, non perché l’integrazione esiste.

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

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 un’infrastruttura GPU;
• vuoi sperimentare con modelli aperti;
• la connettività internet è inaffidabile;
• l’instradamento dei modelli è parte della tua piattaforma.

Un provider personalizzato può puntare OpenCode a un endpoint locale come LM Studio, [llama.cpp](https://www.glukhov.org/it/llm-hosting/llama-cpp/ “Installa llama.cpp, esegui modelli GGUF con llama-cli e fornisci API OpenAI-compatibili usando llama-server.”}) tramite llama-server, vLLM, infrastruttura compatibile con Ollama, o un altro server OpenAI-compatibile.

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

La soluzione pratica è l’instradamento 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 straightforward.

Usa un modello più forte per:

• cambiamenti architetturali;
• bug ambigui;
• refactoring tra package;
• concorrenza;
• codice sensibile alla sicurezza;
• migrazioni difficili.

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

Un Flusso di Lavoro Quotidiano Pratico con OpenCode

Il mio flusso di lavoro 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: Parti da uno stato Git pulito

git status

O committa i cambiamenti esistenti o registra deliberatamente cosa è già modificato. Un agente di coding AI che opera dentro un working tree sporco rende la revisione molto più difficile perché i cambiamenti umani e quelli dell’agente si mescolano.

Passo 2: Chiedi prima l’indagine

Investigate issue #482.

Do not modify files.

Explain:
- the current behavior;
- likely root cause;
- relevant files;
- existing tests;
- proposed fix;
- verification commands.

Lo stesso prompt come comando one-shot:

opencode run "Investigate issue #482. Do not modify files. Explain the current behavior, likely root cause, relevant files, existing tests, proposed fix, and verification commands."

Se l’indagine è sbagliata, correggerla è economico.

Passo 3: Restringi l’implementazione

Implement the proposed fix only.

Do not refactor unrelated code.
Add the regression test first.
Run the smallest relevant test suite after the change.

Oppure in modo non interattivo:

opencode run "Implement the proposed fix only. Do not refactor unrelated code. Add the regression test first. Run the smallest relevant test suite after the change."

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

Passo 4: Ispeziona il diff da solo

git diff --stat
git diff

Non externalizzare questo passo completamente 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: Esegui la validazione deterministica

npm run typecheck
npm test
npm run lint

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

Passo 6: Esegui una revisione indipendente

Chiedi a un agente read-only:

Review the uncommitted diff as if it were a pull request written
by another engineer.

Try to find reasons this implementation is wrong.

Do not edit files.

La variante a riga di comando:

opencode run "Review the uncommitted diff as if it were a pull request written by another engineer. Try to find reasons this implementation is wrong. Do not edit files."

La frase “prova a trovare motivi per cui questa è sbagliata” è intenzionale. I modelli sono molto bravi a confermare cortesemente il lavoro plausibile. I prompt di revisione dovrebbero incoraggiare la falsificazione piuttosto che l’applauso.

Passo 7: Committa 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 dello storico del repository.

Dove OpenCode Diventa Fastidioso: Trappole Comuni

I limiti interessanti non sono di solito “l’IA ha fatto un errore di sintassi”. I compilatori sono bravi a catturare quelli. 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 flusso di lavoro di OpenCode può sembrare eccellente con un modello e quasi inutilizzabile con un altro. Questo rende le recensioni di prodotto difficili perché gli utenti spesso attribuiscono il comportamento del modello all’arnese 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 track 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 Cattivo

Le sessioni degli agenti di coding 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 il suo stesso tradeoff. Un riassunto necessariamente decide quali dettagli sopravvivono. Per transizioni di task importanti, iniziare una nuova sessione è spesso più pulito che continuare una conversazione eroica di 80.000 token. Con i run scripted la risposta è ancora più semplice: un nuovo opencode run inizia con un contesto pulito ogni volta, quindi lo stato a lunga durata appartiene a file come AGENTS.md, non a una conversazione.

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

Sfida 3: Le Autorizzazioni Possono Diventare Ingannosamente Complesse

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 personalizzati, server MCP e comandi shell, devi ragionare sulle capacità effettive dell’intero flusso di lavoro piuttosto che su una riga di configurazione.

Ci sono state anche discussioni reali di comunità e GitHub sul comportamento delle autorizzazioni dei subagenti e sull’ereditarietà delle autorizzazioni. La lezione è più ampia di qualsiasi bug: testare le assunzioni di sicurezza con un repository effettivo e usa e getta — per esempio, git init /tmp/opencode-perm-test e provare a far eseguire all’agente un comando che ci hai negato. Se un’azione non deve assolutamente accadere, non fare affidamento solo su istruzioni in prosa.

Sfida 4: OpenCode Cambia Rapidamente

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

Non combinare casualmente esempi da:

/docs/

e:

/v2/docs/

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

Sfida 5: La TUI Può Nascondere la Scala

Un’interfaccia conversazionale fa sentire un cambiamento di dieci file più piccolo di un cambiamento di dieci file. L’agente può riportare:

Implemented the new validation and updated the relevant tests.

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

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

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

Sfida 6: MCP Può Distruggere l’Efficienza del Contesto

Più integrazioni non producono automaticamente un agente di coding migliore. Grandi server MCP possono esporre molti schemi di strumenti, ognuno che consuma il contesto del modello e aumenta la complessità della selezione degli strumenti. Se OpenCode sembra 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’Inter Percorso

Eseguire un modello locale non garantisce automaticamente che ogni parte della toolchain sia locale. Le discussioni di comunità all’inizio del 2026 hanno sollevato domande di privacy attorno al comportamento del modello ausiliario di OpenCode e all’architettura dell’interfaccia web. Alcune di quelle affermazioni si riferivano a versioni più vecchie, alcune sono state contestate, 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 attuale, capisci quale interfaccia stai usando, disabilita le integrazioni remote non necessarie e testa la versione esatta che intendi di 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 molto alla qualità del coding. Il suo differenziatore è il controllo sull’arnese.

OpenCode è convincente quando valuti:

• un’implementazione open-source;
• flessibilità del provider;
• flussi di lavoro terminal-first;
• agenti configurabili;
• autorizzazioni granulari;
• supporto per modelli locali;
• MCP;
• comandi e skill riutilizzabili;
• architettura client/server.

[Claude Code](https://www.glukhov.org/it/ai-devtools/claude-code/ “Una guida pratica a Claude Code: installa, comandi quickstart, settings.json, autorizzazioni, prezzi ed esecuzione di backend completamente locali tramite Ollama o llama.cpp.”}) è convincente quando vuoi un’esperienza Anthropic strettamente integrata con un forte comportamento di modello first-party e flussi di lavoro degli agenti integrati sempre più rifiniti. Codex CLI è convincente quando i tuoi modelli e flusso di lavoro preferiti sono già centrati sullo stack di coding di OpenAI.

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

Cosa Reddit e Hacker News Fanno Giusto Su OpenCode

Le discussioni di comunità attorno a OpenCode sono insolitamente polarizzate. Alcuni sviluppatori lo descrivono come il loro arnesi di coding preferito, soprattutto quando combinato con modelli Codex, modelli locali o setup di agenti personalizzati. Altri si concentrano sull’uso delle risorse, sul comportamento delle autorizzazioni, sulle domande di privacy, sui cambiamenti dell’autenticazione del provider o sulla complessità che emerge una volta che un’applicazione 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 avevano bisogno di 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 un contesto permanente?
• Quale risultato un umano deve verificare?

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

Una Configurazione Iniziale Che Riconsiglierei

Resisterei a costruire un setup elaborato immediatamente. Inizia con:

1. un modello predefinito forte;
2. un AGENTS.md;
3. autorizzazioni conservative per shell e editing;
4. un agente di revisione read-only;
5. due o tre comandi personalizzati;
6. nessun server MCP finché non appare un bisogno reale.

Un ambiente semplice è più facile da debuggare. Una volta che un flusso di lavoro diventa ripetitivo, promuovilo in un comando, skill o agente. Una volta che una capacità diventa rischiosa, restrigila con le autorizzazioni. Una volta che il contesto diventa gonfio, dividilo invece di acquistare semplicemente una finestra di contesto più grande. Questo approccio incrementale è meno impressionante negli screenshot e considerevolmente più piacevole da mantenere.

Chi Dovrebbe Usare OpenCode

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

• lavori attraverso più provider LLM;
• vuoi il supporto per modelli locali;
• non ti piace essere bloccato a un vendor AI;
• hai bisogno di agenti specifici per progetto;
• automatizzi task di sviluppo da script shell;
• vuoi ispezionare o modificare l’arnese di coding;
• già capisci Git e gli strumenti CLI normali.

È meno convincente se vuoi principalmente un layer AI invisibile dentro un IDE. OpenCode si aspetta anche più giudizio operativo di uno strumento di autocomplete tradizionale. Se la revisione dei diff, la comprensione dei comandi shell e la gestione dei 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 AI che diventa infrastruttura per sviluppatori piuttosto che semplicemente un’interfaccia di chat. Le sue migliori funzionalità non sono appariscenti. L’indipendenza dal provider, le autorizzazioni esplicite, gli agenti riutilizzabili, l’esecuzione non interattiva, le istruzioni del repository, i comandi, le skill e gli strumenti componibili lo rendono possibile per modellare l’agente attorno a un flusso di lavoro ingegneristico reale.

La debolezza è 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 e 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 corti. Dagli un problema delimitato, abbastanza contesto per capire il problema, l’autorizzazione per 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