Installa facilmente OpenCode su Mac e Windows

L'installazione di OpenCode può talvolta risultare confusa quando errori di configurazione interrompono il processo o lo strumento non funziona come previsto. Dai comandi mancanti ai problemi di compatibilità con Node.js, gli utenti incontrano spesso difficoltà durante l'installazione iniziale. Questa guida all'installazione di OpenCode offre una soluzione completa per correggere gli errori più comuni e configurare correttamente OpenCode su Mac e Windows, sia che tu utilizzi Desktop sia CLI/TUI, così potrai iniziare a programmare senza ritardi.

OpenCode è un agente di programmazione IA open source progettato per aiutare gli sviluppatori a scrivere, modificare, eseguire il debug e gestire il codice direttamente dall'ambiente che preferiscono, che si tratti di un terminale, di un IDE o di un'applicazione desktop. A differenza degli assistenti di programmazione IA tradizionali, che si concentrano soprattutto sui suggerimenti per il codice, OpenCode è in grado di comprendere un'intera codebase, modificare file, eseguire comandi e automatizzare i flussi di lavoro di sviluppo. Supporta inoltre più modelli IA e modelli locali, offrendo agli sviluppatori maggiore flessibilità e controllo sul modo in cui realizzano il software.

Prima di installare OpenCode, assicurati che il tuo sistema soddisfi i requisiti di base. I prerequisiti esatti dipendono dal fatto che intendi usare l'applicazione desktop o l'interfaccia basata sul terminale, ma una configurazione adeguata contribuirà a garantire un processo di installazione senza intoppi.

Sistema operativo: macOS / Windows / Linux

OpenCode offre applicazioni desktop per i principali sistemi operativi, consentendo agli sviluppatori di installare e utilizzare lo strumento nell'ambiente che preferiscono. Assicurati che il tuo sistema utilizzi un sistema operativo compatibile, come macOS (Apple Silicon o Intel), Windows (x64) o Linux (.deb, .rpm).

Autorizzazione a installare app: potresti aver bisogno di autorizzazioni di amministratore o a livello di sistema per scaricare e installare software sul tuo dispositivo. Questo aspetto è particolarmente importante in ambienti di lavoro o IT gestiti, dove i diritti di installazione potrebbero essere limitati.

Connessione Internet stabile: è necessaria una connessione Internet stabile per scaricare OpenCode, installare gli aggiornamenti e collegarsi ai modelli e ai servizi IA supportati durante la configurazione e l'utilizzo.

Accesso al terminale: OpenCode può essere installato e utilizzato direttamente dalla riga di comando. Assicurati di avere accesso a un'applicazione terminale, come Terminal su macOS, Prompt dei comandi o PowerShell su Windows, oppure una shell Linux.

Un metodo di installazione: OpenCode supporta diversi metodi di installazione per adattarsi ai vari sistemi operativi e alle preferenze degli sviluppatori. Scegli il gestore di pacchetti o lo strumento di installazione più adatto al tuo ambiente, ad esempio npm, curl, brew, Scoop, Chocolatey o WSL.

Conoscenze di base della riga di comando: la familiarità con i comandi comuni del terminale può rendere molto più semplici l'installazione e l'uso quotidiano. Sebbene non sia richiesta un'esperienza avanzata, è consigliabile comprendere le operazioni di navigazione e l'esecuzione dei comandi di base.

L'installazione di OpenCode Desktop è un processo semplice che richiede solo pochi passaggi per rendere operativa l'applicazione. Ecco i passaggi da seguire.

Passaggio 1: scarica OpenCode Desktop

Vai alla pagina di download ufficiale di OpenCode e seleziona la versione dell'applicazione per Windows o macOS. Il programma di installazione verrà scaricato automaticamente sul tuo sistema. Per sicurezza e autenticità, assicurati di scaricarlo dalla fonte ufficiale.

Passaggio 2: esegui il programma di installazione

Individua il file del programma di installazione scaricato e fai doppio clic per avviare l'installazione. Segui le istruzioni sullo schermo per completare la configurazione.

Passaggio 3: completa l'installazione

Segui le schermate di configurazione man mano che vengono visualizzate e, quando richiesto, seleziona la directory di installazione desiderata. Quindi attendi che il programma di installazione completi la configurazione sul sistema.

Passaggio 4: avvia OpenCode Desktop

Al termine dell'installazione, apri OpenCode Desktop dal menu Start o dal collegamento sul desktop. Quindi avvia un nuovo progetto oppure apri una cartella esistente per iniziare a lavorare. Una volta caricato l'ambiente di lavoro, puoi interagire con l'assistente IA per generare codice, risolvere problemi di debug o sviluppare funzionalità direttamente nel progetto.

OpenCode Terminal (TUI) su Mac può essere installato direttamente tramite gestori di pacchetti ufficiali o con un comando di installazione su una sola riga. È pensato per gli sviluppatori che preferiscono lavorare nel terminale anziché con un'interfaccia grafica. Segui questi passaggi per installare OpenCode TUI su Mac.

Passaggio 1: scegli un metodo di installazione per OpenCode Terminal

Visita la pagina di download ufficiale di OpenCode e vai alla sezione OpenCode Terminal. Qui troverai diverse opzioni di installazione, tra cui curl, Homebrew, npm e bun. Seleziona il metodo più adatto al tuo ambiente di sviluppo e copia il comando di installazione corrispondente.

Passaggio 2: apri l'app Terminale su Mac

Avvia l'app Terminale sul Mac. Puoi aprirla da Applicazioni > Utility > Terminale oppure trovarla rapidamente usando la ricerca Spotlight. Qui eseguirai il comando di installazione di OpenCode.

Passaggio 3: installa OpenCode Terminal

Incolla il seguente comando di installazione nel Terminale e premi Invio:

Attendi il completamento dell'installazione. OpenCode scaricherà i file necessari e configurerà automaticamente la CLI.

Passaggio 4: avvia l'interfaccia terminale di OpenCode

Al termine dell'installazione, esegui il comando OpenCode nel Terminale per avviare l'interfaccia utente del terminale (TUI). L'interfaccia interattiva si aprirà direttamente nella finestra del terminale e ti consentirà di connetterti a un provider di IA, configurare le impostazioni e iniziare a lavorare con OpenCode.

OpenCode supporta diversi metodi di installazione su Windows, tra cui WSL, npm e bun. Per la migliore compatibilità ed esperienza d'uso, la documentazione ufficiale consiglia Windows Subsystem for Linux (WSL). I passaggi seguenti utilizzano il metodo di installazione WSL. Se hai già installato WSL, puoi saltare il primo passaggio.

Passaggio 1: installa WSL (consigliato)

Apri PowerShell come amministratore, quindi esegui il seguente comando:

Questo comando abilita Windows Subsystem for Linux (WSL) e installa Ubuntu per impostazione predefinita. Al termine dell'installazione, riavvia il computer. La prima volta che aprirai Ubuntu, Windows completerà automaticamente la configurazione dell'ambiente Linux.

Passaggio 2: apri WSL e installa OpenCode

Avvia il terminale WSL, ad esempio Ubuntu, dal menu Start di Windows. Se lo apri per la prima volta, completa la configurazione iniziale. Quindi esegui il seguente comando per installare OpenCode:

Attendi il completamento dell'installazione prima di proseguire.

Passaggio 3: verifica l'installazione

Al termine dell'installazione, esegui il seguente comando:

Se OpenCode Terminal/TUI si avvia correttamente, l'installazione è completata e puoi iniziare a usare OpenCode per programmare con l'assistenza dell'IA.

Uno dei principali vantaggi di OpenCode è la possibilità di connettersi a provider esterni di modelli IA tramite integrazioni API. Aggiungendo la tua chiave API, puoi accedere a diversi modelli linguistici e scegliere quello più adatto al tuo flusso di lavoro di programmazione.

Di seguito sono riportati i passaggi per integrare API esterne in OpenCode:imi

Passaggio 1: crea un account e genera una chiave API

Per prima cosa, crea un account presso il provider di IA che preferisci, ad esempio Kimi o un altro servizio supportato. Dopo aver configurato l'account, vai alla pagina di gestione delle chiavi API del provider e genera una nuova chiave API. Conserva questa chiave in modo sicuro, poiché sarà necessaria per collegare il provider a OpenCode.

Passaggio 2: apri il menu di connessione del provider

Avvia OpenCode e apri il tuo spazio di lavoro. Nell'interfaccia a riga di comando, esegui il comando seguente:

Questo comando apre il menu di connessione del provider, in cui puoi aggiungere e gestire servizi di IA esterni.

Passaggio 3: aggiungi la chiave API

Seleziona dall'elenco delle opzioni disponibili il provider che desideri utilizzare. Quando richiesto, incolla la chiave API generata in precedenza e conferma la connessione. OpenCode memorizzerà la chiave in modo sicuro e la utilizzerà per autenticare le richieste al provider selezionato.

Passaggio 4: visualizza i modelli disponibili

Dopo aver collegato il provider, esegui il comando seguente per visualizzare tutti i modelli disponibili tramite quell'API:

OpenCode mostrerà un elenco dei modelli supportati, con i relativi nomi e opzioni di configurazione.

Passaggio 5: seleziona un modello e inizia a usarlo

Scegli dall'elenco disponibile il modello con cui desideri lavorare. Una volta selezionato, OpenCode indirizzerà le tue richieste attraverso quel modello, consentendoti di generare codice, eseguire il debug delle applicazioni e svolgere altre attività di sviluppo tramite l'API collegata. Potrai cambiare modello in seguito se cambiano le tue esigenze.

OpenCode supporta più provider di IA, consentendo agli sviluppatori di collegare modelli esterni tramite chiavi API per una maggiore flessibilità. Una delle opzioni più efficaci è Kimi API.

Kimi API, fornita da Moonshot AI Open Platform, offre accesso ai modelli linguistici avanzati di Kimi tramite un'interfaccia compatibile con OpenAI. Può essere integrata facilmente in strumenti di programmazione, applicazioni e flussi di lavoro basati sull'IA tramite una chiave API sicura. La piattaforma include una gamma di modelli Kimi ottimizzati per attività di programmazione, ragionamento e comprensione di contesti lunghi.

Segui questi passaggi per integrare le API Kimi in OpenCode.

Passaggio 1: crea un account Moonshot AI e genera una chiave API

1. Visita Kimi AI Open Platform e accedi al tuo account.

2. Dalla dashboard, vai a Chiavi API e fai clic su Crea chiave API.

3. Dopo aver generato la chiave (inizia con sk-), copiala subito e conservala in modo sicuro. La chiave viene visualizzata una sola volta e viene utilizzata per autenticare le richieste tra OpenCode e Moonshot AI.

Passaggio 2: collega Moonshot AI a OpenCode

Apri il tuo spazio di lavoro OpenCode ed esegui:

Verrà visualizzato il menu di connessione del provider. Cerca Moonshot AI (o Kimi) nell'elenco dei provider integrati e selezionalo. OpenCode ti chiederà di inserire la chiave API.

Quando richiesto, incolla la chiave API generata nella console Moonshot AI e premi Invio:

Dopo la verifica, OpenCode salverà in modo sicuro le credenziali in ~/.local/share/opencode/auth.json e le assocerà alla configurazione del provider Moonshot AI.

Nota: per motivi di sicurezza, OpenCode memorizza le chiavi API separatamente dal file di configurazione principale. Il comando /connect gestisce l'archiviazione delle credenziali, mentre il comportamento del provider viene configurato in opencode.json.

Passaggio 3: configura il provider in opencode.json (se necessario)

Se dopo la connessione riscontri l'errore No endpoints found oppure devi personalizzare la configurazione del provider, aggiungi la configurazione Moonshot AI al file opencode.json:

Salva il file e riavvia OpenCode per applicare le modifiche.

Passaggio 4: visualizza i modelli Kimi disponibili

Dopo aver collegato il provider, esegui:

OpenCode visualizzerà tutti i modelli disponibili tramite il tuo account Moonshot AI, inclusi:

Passaggio 5: seleziona un modello Kimi e inizia a programmare

Seleziona moonshotai/kimi-k3 e impostalo come modello attivo. Una volta selezionato, OpenCode utilizzerà il modello Kimi scelto per la generazione di codice, il debug, il refactoring e altre attività di sviluppo assistite dall'IA.

Puoi passare a un modello diverso in qualsiasi momento tramite lo stesso menu di selezione del modello.

Suggerimento: se riscontri problemi con la modalità Agent/Tool (ad esempio errori di convalida dello schema JSON), si tratta di un problema di compatibilità noto tra i requisiti rigorosi degli schemi di Moonshot AI e il formato dei parametri degli strumenti di OpenCode. Per una maggiore stabilità, valuta l'uso della modalità Chat oppure installa il plugin opencode-moonshot-compatibility per gestire automaticamente la compatibilità della temperatura.

Kimi API è progettata per supportare i moderni flussi di lavoro di sviluppo, aiutando i team a passare dalle idee all'implementazione in modo più efficiente. Oltre a generare codice, è in grado di comprendere diversi tipi di input, adattarsi ai requisiti del progetto e automatizzare le attività ingegneristiche di routine. Ecco alcuni dei principali vantaggi:

• Trasformare input multimodali in implementazioni funzionanti

Kimi API è in grado di interpretare informazioni provenienti da più formati, inclusi mockup di design, diagrammi architetturali, diagrammi di flusso e video. Utilizza questo contesto per comprendere i requisiti del progetto e convertirli in specifiche tecniche o codice funzionale. Di conseguenza, i team possono passare dal concetto all'implementazione con meno passaggi di traduzione manuale.

• Gestire attività di coding a lungo termine e complesse attività ingegneristiche

Kimi API aiuta OpenCode a gestire attività di coding più ampie, che richiedono pianificazione, coerenza e perfezionamento. È utile per sviluppare funzionalità, effettuare il refactoring del codice e risolvere problemi ingegneristici complessi.

• Affrontare i problemi con chiamate di strumenti in più passaggi

Kimi API può ragionare su attività articolate in più passaggi e richiamare strumenti quando necessario. Questo è utile per il debugging, l'analisi del codice e i flussi di lavoro che non possono essere completati in un'unica risposta.

L'installazione di OpenCode è generalmente semplice, ma possono verificarsi errori comuni di configurazione dovuti a incompatibilità dell'ambiente, dipendenze o problemi di configurazione. Di seguito trovi una guida chiara e pratica per risolvere rapidamente ed efficacemente i problemi di installazione più frequenti.

• Comando non trovato: opencode

Se viene visualizzato questo errore, significa che il sistema non riesce a individuare l'eseguibile di OpenCode nel PATH. In genere accade quando l'installazione è incompleta o le variabili d'ambiente non sono configurate correttamente.

Per risolvere il problema, verifica prima l'installazione e assicurati che la directory dei binari sia stata aggiunta al PATH di sistema. Se hai eseguito l'installazione tramite npm, controlla il percorso globale dei binari npm e aggiorna di conseguenza la configurazione della shell. Dopo le correzioni, spesso è sufficiente riavviare il terminale per risolvere il problema.

• Versione di Node.js troppo vecchia

Solo il metodo di installazione tramite npm richiede un ambiente Node.js: lo script di installazione e i gestori di pacchetti (Homebrew, Scoop, Chocolatey) installano un binario autonomo che non richiede Node.js.

Se hai eseguito l'installazione tramite npm e riscontri errori di versione, controlla la versione attuale con node --version e aggiorna Node.js usando un gestore di versioni come nvm. Dopo l'aggiornamento, reinstalla OpenCode per garantire la compatibilità con l'ambiente di runtime aggiornato.

• Errori di autorizzazione npm

Gli errori di autorizzazione si verificano in genere quando npm tenta di installare pacchetti globali senza disporre dei necessari permessi di scrittura.

Anziché usare sudo, configura una directory globale npm dedicata nella cartella home e aggiorna le impostazioni del PATH. Questo garantisce installazioni più sicure e stabili. Dopo aver corretto le autorizzazioni, esegui nuovamente il comando di installazione per completare la configurazione correttamente.

• Problemi di rete/firewall

In reti soggette a restrizioni o ambienti aziendali, l'installazione di OpenCode potrebbe non riuscire a causa dell'accesso bloccato al registro npm o di download lenti.

Per risolvere il problema, passa a un registro npm alternativo oppure usa un metodo di installazione diretto, come curl o il download del binario. Assicurati inoltre che il firewall consenta il traffico di Node.js e npm, poiché le connessioni bloccate interrompono spesso l'installazione dei pacchetti.

• Problemi di rendering della TUI

Se OpenCode si apre ma appare difettoso, disallineato o mostra testo illeggibile, il problema è solitamente legato alla compatibilità del terminale.

Utilizza un emulatore di terminale moderno che supporti i colori reali e il rendering Unicode, come Windows Terminal, WezTerm o iTerm2. L'aggiornamento delle impostazioni del terminale o il passaggio a un altro ambiente risolve in genere immediatamente i problemi di visualizzazione.

Una corretta installazione e configurazione di OpenCode garantiscono prestazioni fluide su sistemi diversi, riducendo al contempo il rischio di errori comuni di configurazione. Gestendo correttamente dipendenze, impostazioni del terminale e connessioni API, gli utenti possono risolvere rapidamente i problemi e mantenere un ambiente di sviluppo stabile. L'integrazione di servizi esterni come Kimi API aumenta ulteriormente la flessibilità, consentendo l'accesso a modelli avanzati all'interno dei flussi di lavoro.