Questa guida è il seguito naturale di OpenRouter in 15 minuti: la chiave che hai creato lì, con il suo tetto di spesa, diventa il motore di un agente che lavora nei tuoi file. Fine del percorso: un compito vero completato da OpenCode sotto i tuoi occhi.

Passo 1 · Installa

Due strade equivalenti, dalla documentazione ufficiale: lo script (curl -fsSL https://opencode.ai/install | bash) o, se hai Node, npm install -g opencode-ai. Verifica con opencode --version: se risponde con un numero, ci sei.

Passo 2 · Collega il modello

Crea una cartella di lavoro dedicata e lancia opencode lì dentro. Al primo avvio usa il comando /connect: cerca OpenRouter nell’elenco dei provider, incolla la chiave. Poi scegli il modello: per il primo giro un modello medio va benissimo, e se vuoi spendere zero c’è la variante :free di diversi modelli aperti (col limite di richieste al minuto documentato nella scheda OpenRouter).

Passo 3 · Recinta il campo

Un agente che legge, scrive ed esegue va trattato come un collaboratore nuovo: perimetro chiaro prima del primo compito. La regola pratica: lavora sempre in una cartella dedicata che contiene solo il materiale del compito, mai nella home o in cartelle con documenti che non c’entrano. Dentro quel recinto l’agente può fare danni ridotti e recuperabili; la logica è la stessa della lezione sui confini da dare agli strumenti.

Passo 4 · Il primo compito vero

Metti nella cartella un file su cui l’agente possa lavorare (un CSV da analizzare, una manciata di note da riorganizzare, uno script da commentare) e descrivi il compito come lo daresti a una persona: cosa c’è, cosa vuoi, come riconosci un buon risultato. Poi guardalo lavorare: OpenCode mostra i passi e le modifiche, e tu supervisioni. Il momento formativo è proprio questo: vedere il ciclo leggere-agire-verificare succedere nei tuoi file, coi tuoi contenuti.

Gli errori tipici

Il compito vago. «Sistemami questi file» produce risultati vaghi con qualunque agente. Obiettivo, materiale, criterio di riuscita: le tre cose che dai a un collega le dai anche qui.

Il recinto saltato. La tentazione di lanciarlo «solo un attimo» nella cartella dei documenti veri. Il costo di copiare tre file in una cartella pulita è trenta secondi; l’alternativa è supervisionare col fiato sospeso.

Il modello sbagliato per il compito. Se i risultati deludono, prima di condannare l’agente prova un modello più capace: con OpenCode il cambio è un comando, ed è esattamente il tipo di esperimento per cui l’accoppiata con un gateway esiste.

Stato del collaudo: installazione e versione verificate davvero il 19/07/2026 (v1.18.3, via npm). Il giro completo del passo 4 è stato eseguito alla stessa data, con chiave e modello reali, dal workflow di collaudo del sito: OpenCode ha letto il CSV dei materiali del corso dentro un recinto dedicato, ha prodotto l’analisi con il totale e le 4 anomalie che il materiale contiene apposta, e non ha toccato il file originale. Esattamente il ciclo leggere-agire-verificare descritto sopra.