Risposta rapida
Considera OpenCode V2 una migrazione pianificata, non un aggiornamento alla cieca
Prova V2 quando le sue funzionalità attuali da riga di comando o desktop si adattano al tuo lavoro e puoi dedicare tempo alla verifica. Mantieni V1 disponibile finché non hai controllato modelli, credenziali, agenti, permessi, server MCP, plugin, client per editor e attività reali. Una configurazione personale semplice può partire da un progetto di prova; un team o un repository con plugin personalizzati dovrebbe procedere per fasi.
La guida ufficiale dice che le configurazioni V1 supportate e le definizioni basate su file sono pensate per continuare a funzionare, e che resta il comando opencode. Ci sono però tre cambiamenti da verificare: i plugin V1 non funzionano con V2, il contratto dell’API server e dei relativi client è cambiato e le preferenze del terminale passano a un file globale cli.json. Anche se non converti la configurazione principale, testa la compatibilità effettiva.
Questa pagina raccoglie i canali ufficiali d’installazione, un confronto pratico e una lista di controllo reversibile. La documentazione di migrazione principale non garantisce la conversione completa dei vecchi database delle sessioni. Per modelli, chiavi API e prezzi, consulta le pagine dedicate a modelli, provider e piani.
OpenCode V1 vs V2: cambiamenti che incidono sul lavoro reale
Il numero di versione non basta a stimare la migrazione. Controlla le parti che usi davvero: client terminale, plugin, API server e configurazione. I file di progetto supportati sono diversi dal codice eseguibile di un plugin o da un client API.
| Area | V1 | V2 e conseguenze |
|---|---|---|
| Comando CLI | opencode | Il nome rimane. Di norma le versioni gestite da pacchetto non sono installate in parallelo. |
| Configurazione e file supportati | Configurazione V1 e file in .opencode/ | I campi e le definizioni supportati sono destinati a restare utilizzabili; verifica provider e permessi. |
| Plugin | API e punti d’ingresso per plugin V1 | La nuova API richiede di portare ogni plugin V1 prima di eseguirlo. |
| API server e client | Contratto V1 e client generati | I contratti cambiano; le integrazioni richiedono client compatibili e test V2. |
| Preferenze del terminale | File stratificati tui.json o tui.jsonc | Le impostazioni supportate passano al cli.json globale; controlla il risultato. |
| Installazione | Pacchetto o installer V1 | Usa un canale ufficiale V2; potrebbe essere necessario rimuovere prima il pacchetto V1. |
La tabella aiuta a delimitare i controlli, ma non promette il supporto di ogni vecchio campo. La guida distingue valori supportati, accettati ma non supportati e non ammessi. Consulta la documentazione aggiornata prima di cambiare impostazioni di sicurezza, accesso ai provider o automazione e leggi gli avvisi all’avvio.
Conviene aggiornare OpenCode a V2 adesso?
Decidi in base a compatibilità e reversibilità, non solo al numero principale. Una configurazione personale basata sulle funzioni integrate ha un costo diverso da un repository con plugin propri e integrazione con l’editor.
Una prova di V2 è ragionevole se
- Il tuo flusso usa soprattutto configurazione supportata, provider, comandi integrati, agenti, skill e MCP che puoi verificare in un progetto di prova.
- Vuoi l’esperienza CLI o desktop di V2 e puoi conservare una copia funzionante dell’ambiente attuale.
- I tuoi plugin o client server hanno già una versione V2 oppure c’è una persona incaricata di portarli e testarli.
È meglio mantenere V1 per ora se
- Un plugin V1, endpoint server, client IDE o processo automatico essenziale non è ancora stato testato con il contratto V2.
- Non riesci a ripristinare il pacchetto, la configurazione o i dati delle sessioni in caso di errore.
- Lo strumento è condiviso nel team ma manca un piano per aggiornare ambienti, documentazione e assistenza.
Se non sei sicuro, prova con un progetto temporaneo e annota comando, gestore di pacchetti, versione OpenCode e risultato atteso. Per esempio, chi usa solo agenti e provider può controllare una copia del repository, mentre un collega mantiene V1 per un plugin server. La scelta diventa così una lista di verifiche concrete, non l’idea generica che una nuova versione sia sempre migliore.
Come installare OpenCode V2 da un canale ufficiale
L’introduzione ufficiale di V2 elenca alcuni canali da terminale. Scegli il gestore che usi già e segui le istruzioni aggiornate, compresa la compatibilità della tua piattaforma. Non riutilizzare un vecchio comando di installazione V1 senza verificarne il ruolo nella migrazione.
| Canale | Comando indicato dai documenti V2 | Verifica |
|---|---|---|
| Installer ufficiale | curl -fsSL https://opencode.ai/v2/install | bash | Verifica che installer e sistema operativo corrispondano alle istruzioni V2. |
| Homebrew | brew install anomalyco/tap/opencode-v2 | Controlla che tap e nome del pacchetto siano ancora aggiornati. |
| npm | npm install -g @opencode/cli | Il tag npm @latest puntava a 2.0.22 il 3 ottobre 2026; controlla la versione corrente. |
La documentazione V2 presenta anche Bun, pnpm e altri metodi. Il supporto varia per piattaforma; su Windows consulta i binari indicati invece di presumere che ogni gestore sia adatto. Per Yarn, Vite+ o AUR segui la sintassi ufficiale corrente ed evita collegamenti a siti terzi per scaricare gli installer.
Prima di installare, individua come hai ottenuto V1. Secondo la guida ufficiale, a volte il pacchetto V1 va rimosso perché entrambe le versioni usano il comando opencode. L’installer curl di V2 sostituisce il binario V1. Rimuovere il pacchetto non deve cancellare configurazione o dati condivisi: fanne una copia separata e controlla che cosa elimina il gestore.
Migrare da OpenCode V1 a V2 mantenendo il controllo
Rendi reversibile il primo passaggio. L’obiettivo iniziale è verificare che V2 si avvii e che il progetto funzioni, non riscrivere tutti i file di configurazione il primo giorno. Segui le istruzioni ufficiali per il tuo sistema operativo e pacchetto.
- Registra l’installazione V1. Segna gestore o installer, versione, variabili e percorsi di configurazione. Conserva il pacchetto precedente o un modo affidabile per reinstallarlo.
- Crea un backup datato. Salva configurazione, definizioni del progetto e dati da ripristinare. Verifica che il backup sia leggibile e non sia solo in una cartella temporanea.
- Fai l’inventario delle dipendenze eseguibili. Elenca plugin, client API, comandi CI e integrazioni dell’editor. Per ognuno indica se è verificato con V2, da portare o non più necessario.
- Installa con il canale adatto. Rimuovi il pacchetto V1 solo se le istruzioni lo richiedono. Un normale aggiornamento V1 non installa la versione V2.
- Controlla la configurazione. Avvia V2 in un progetto di prova. Esamina gli avvisi sui vecchi campi, modelli, credenziali, permessi e connessioni MCP prima di un’attività importante.
- Adatta codice e client. Porta i plugin alla nuova API e aggiorna i client server. Testa anche errori e autorizzazioni.
- Converti le preferenze in seguito. Le preferenze terminale supportate migrano in un
cli.jsonglobale. Convertire la configurazione al formato nativo V2 è facoltativo e può aspettare la verifica del flusso iniziale.
Durante il primo giro di prove lascia intatta la configurazione V1 supportata. La guida afferma che V2 può normalizzare in memoria le impostazioni supportate senza riscrivere il file sorgente. Separare installazione, migrazione dei plugin e conversione aiuta a capire la causa di una regressione e a ripristinare il sistema.
Cosa viene mantenuto e cosa va controllato manualmente
Considera compatibile solo il comportamento dichiarato esplicitamente nella guida V2 corrente. Questa distinzione chiarisce le domande sulla compatibilità senza implicare che ogni campo o estensione precedente continui a funzionare.
| Elemento | Aspettativa prudente | Verifica pratica |
|---|---|---|
| Configurazione e file di progetto supportati | Dovrebbero restare utilizzabili, ma alcuni campi potrebbero essere ignorati o non supportati. | Leggi gli avvisi e testa provider, permessi e attività reali. |
| Agenti, comandi e skill basati su file | La guida prevede che continuino se il comportamento utilizzato è supportato. | Richiama ogni elemento in un progetto di prova e confronta il risultato atteso. |
| Plugin | Le implementazioni V1 non funzionano come plugin V2. | Adatta il punto d’ingresso e verifica caricamento, permessi ed errori. |
| API e client server | Il contratto cambia; non dare per compatibili i client V1. | Migra il client e convalida richieste, eventi e autenticazione. |
| Sessioni precedenti | La guida principale non promette la conversione di massa dei database storici. | Fai un backup e controlla le sessioni necessarie prima del cambio quotidiano. |
La documentazione ufficiale classifica alcuni vecchi valori come accettati ma non supportati e avverte che possono produrre messaggi. Se un’opzione riguarda permessi sui file, limiti degli strumenti o accesso ai provider, non basta che l’applicazione si avvii: controlla i log ed esegui un test che dimostri il comportamento di sicurezza previsto.
Verifica OpenCode V2 prima di rimuovere il ripiego V1
Esegui un breve collaudo in un progetto di prova e conserva il risultato con le note di aggiornamento. Un team può riutilizzare l’elenco su altri computer; una persona può usarlo per decidere con dati concreti se continuare con V2 o tornare a V1.
- Il comando risolto è quello previsto e mostra una versione V2.
- Provider, credenziali e modello funzionano senza esporre chiavi nei log.
- Agenti, comandi e skill necessari producono il comportamento atteso.
- I permessi di lettura e scrittura rispettano le regole del progetto.
- I server MCP si collegano e un errore non provoca azioni inattese.
- Plugin e client indispensabili dispongono di versioni compatibili con V2.
- Le sessioni importanti sono accessibili oppure coperte da un backup verificato.
- Un’attività reale termina correttamente e il risultato può essere controllato.
Se fallisce una verifica essenziale, sospendi V2 per quel flusso e torna al pacchetto o all’installazione V1 conservata. Non far leggere a V1 configurazione riservata a V2. Il ripristino dipende dal gestore di pacchetti: tieni disponibile il pacchetto e separa i dati utente dal software. Cancella il backup solo dopo aver completato un normale ciclo di lavoro.
Per gli aggiornamenti ordinari dopo l’installazione di V2, la CLI V2 documenta opencode upgrade e l’alias update. Questo comando riguarda una V2 già installata; il passaggio dalla versione principale V1 ha istruzioni distinte per pacchetto e installazione.
Domande frequenti sulla migrazione a OpenCode V2
OpenCode V2 è un normale aggiornamento da V1?
No. È una migrazione a una versione principale. Entrambe usano il comando opencode e le installazioni gestite da pacchetti non sono affiancate per impostazione predefinita. Identifica come hai installato V1 e segui la guida ufficiale.
Devo riscrivere la configurazione OpenCode per V2?
Non necessariamente. La guida ufficiale dice che V2 legge e normalizza le configurazioni V1 supportate senza riscrivere il file sorgente. Controlla gli avvisi e testa provider, permessi e MCP.
I plugin OpenCode V1 funzionano con V2?
Non direttamente. Le implementazioni V1 non vengono eseguite come plugin V2. Porta il punto d’ingresso e il comportamento seguendo la guida ufficiale e prova il pacchetto installato.
Come si installa OpenCode V2 con npm?
La documentazione V2 attuale indica npm install -g @opencode/cli. Consulta la guida e la pagina del pacchetto per confermare versione e requisiti della piattaforma.
Quale comando aggiorna OpenCode V2?
Per un’installazione già V2, la CLI documenta opencode upgrade e l’alias update. La migrazione da V1 richiede di gestire separatamente pacchetto precedente e canale d’installazione.
Il passaggio a V2 migra tutta la cronologia delle sessioni?
La guida principale non garantisce la conversione completa dei database storici. Fai un backup dei dati importanti e verifica le sessioni necessarie prima di modificare il flusso quotidiano.
Riferimenti ufficiali OpenCode
Comandi e informazioni di compatibilità sono stati controllati sulle fonti ufficiali il 3 ottobre 2026. Pacchetti e istruzioni possono cambiare: ricontrollali prima di una migrazione principale.