Installa facilmente OpenCode su Mac e Windows

Installare OpenCode può a volte risultare confuso 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 spesso incontrano difficoltà durante l'installazione iniziale. Questa guida all'installazione di OpenCode fornisce una soluzione completa per correggere gli errori più comuni e configurare correttamente OpenCode su Mac e Windows, sia che si utilizzi Desktop o CLI/TUI, in modo da poter iniziare a programmare senza ritardi.

Cos'è OpenCode?

OpenCode è un agent di coding AI open source progettato per aiutare gli sviluppatori a scrivere, modificare, eseguire il debug e gestire codice direttamente dall'ambiente preferito, che sia un terminale, un IDE o un'applicazione desktop. A differenza degli assistenti di coding AI tradizionali, che si concentrano principalmente sui suggerimenti di 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 AI e modelli locali, offrendo agli sviluppatori maggiore flessibilità e controllo su come costruiscono il software.

Prerequisiti per installare OpenCode

Prima di installare OpenCode, assicurati che il tuo sistema soddisfi i requisiti di base. I prerequisiti esatti dipendono dal fatto che tu intenda usare l'applicazione desktop o l'interfaccia da terminale, ma avere la configurazione giusta in atto aiuterà a garantire un processo di installazione senza intoppi.

Per Desktop

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 preferito. Assicurati che il tuo sistema utilizzi un sistema operativo compatibile, come macOS (Apple Silicon o Intel), Windows (x64) o Linux (.deb, .rpm).

Permessi per installare app: potrebbero essere necessari permessi di amministratore o a livello di sistema per scaricare e installare software sul tuo dispositivo. Questo è particolarmente importante sul posto di lavoro o in ambienti IT gestiti, dove i diritti di installazione potrebbero essere limitati.

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

Per Terminal/TUI

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 più metodi di installazione per adattarsi a diversi sistemi operativi e preferenze degli sviluppatori. Scegli il gestore di pacchetti o lo strumento di installazione più adatto al tuo ambiente, come npm, curl, brew, Scoop, Chocolatey o WSL.

Conoscenza di base della riga di comando: la familiarità con i comandi da terminale più comuni può semplificare notevolmente l'installazione e l'uso quotidiano. Anche se non è richiesta un'esperienza avanzata, si consiglia di comprendere la navigazione di base e l'esecuzione dei comandi.

Come installare OpenCode Desktop?

Installare OpenCode Desktop è un processo semplice che richiede solo pochi passaggi per far funzionare l'applicazione. Ecco i passaggi da seguire.

Passo 1: Scarica OpenCode Desktop

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

Passaggio 2: esegui il programma di installazione

Individua il file di installazione scaricato e fai doppio clic su di esso per avviare l'installazione. Segui le istruzioni a schermo per completare la configurazione.

Passaggio 3: completa l'installazione

Procedi seguendo le richieste di configurazione man mano che appaiono e seleziona una directory di installazione preferita quando richiesto. Poi lascia che il programma di installazione completi il processo di configurazione sul tuo sistema.

Passaggio 4: avvia OpenCode Desktop

Una volta terminata l'installazione, apri OpenCode Desktop dal menu Start o dal collegamento sul desktop. Poi avvia un nuovo progetto o apri una cartella esistente per iniziare a lavorare. Una volta caricato il tuo spazio di lavoro, puoi interagire con l'assistente AI per generare codice, correggere errori o sviluppare funzionalità direttamente all'interno del tuo progetto.

Come installare OpenCode Terminal/TUI su Mac?

OpenCode Terminal (TUI) su Mac può essere installato direttamente utilizzando i gestori di pacchetti ufficiali o un comando di installazione su una sola riga. È pensato per gli sviluppatori che preferiscono lavorare all'interno del terminale invece che tramite 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 ufficiale di download 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'applicazione Terminale su Mac

Avvia l'app Terminale sul tuo Mac. Puoi aprirla da Applicazioni > Utility > Terminale oppure trovarla rapidamente tramite Spotlight Search. È qui che 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 del terminale OpenCode

Una volta completata l'installazione, esegui il comando OpenCode nel Terminale per avviare l'interfaccia utente da terminale (TUI). L'interfaccia interattiva si aprirà direttamente nella finestra del terminale, permettendoti di connetterti a un provider AI, configurare le impostazioni e iniziare a lavorare con OpenCode.

Come installare OpenCode Terminal/TUI su Windows?

OpenCode supporta diversi metodi di installazione su Windows, tra cui WSL, npm e bun. Per la migliore compatibilità ed esperienza, la documentazione ufficiale consiglia di utilizzare Windows Subsystem for Linux (WSL). I passaggi seguenti utilizzano il metodo di installazione tramite 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. Una volta completata l'installazione, riavvia il computer. La prima volta che apri 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 è la prima volta che lo apri, completa la configurazione iniziale. Quindi esegui il seguente comando per installare OpenCode:

Attendi il completamento dell'installazione prima di procedere.

Passaggio 3: verifica l'installazione

Una volta completata l'installazione, esegui il seguente comando:

Se OpenCode Terminal/TUI si avvia correttamente, l'installazione è completa e puoi iniziare a utilizzare OpenCode per la programmazione assistita dall'AI.

Come integrare API esterne in OpenCode?

Uno dei principali vantaggi di OpenCode è la sua capacità di connettersi con provider di modelli AI esterni 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 sviluppo.

Integrare API esterne in OpenCode (passaggi generali)

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

Passaggio 1: crea un account e genera una chiave API

Inizia creando un account presso il provider AI di tua preferenza, come Kimi o un altro servizio supportato. Una volta 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 ai provider

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

Questo comando apre il menu di connessione ai provider, dove puoi aggiungere e gestire servizi AI esterni.

Passaggio 3: aggiungi la tua chiave API

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

Passaggio 4: visualizza i modelli disponibili

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

OpenCode mostrerà un elenco dei modelli supportati insieme ai loro nomi e alle opzioni di configurazione.

Passaggio 5: seleziona un modello e inizia a usarlo

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

Integrare le API Kimi in OpenCode

OpenCode supporta diversi provider AI, permettendo agli sviluppatori di connettere modelli esterni tramite chiavi API per una maggiore flessibilità. Una delle opzioni più potenti è l'API Kimi.

L'API Kimi, offerta dalla Moonshot AI Open Platform, dà accesso ai modelli linguistici Kimi avanzati tramite un'interfaccia compatibile con OpenAI. Può essere integrata facilmente in strumenti di sviluppo, applicazioni e flussi di lavoro basati su AI utilizzando una chiave API sicura. La piattaforma include una gamma di modelli Kimi ottimizzati per attività di coding, 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 su API Keys e fai clic su Create API Key.

3. Dopo che la chiave è stata generata (inizia con sk-), copiala immediatamente e conservala in modo sicuro. La chiave viene mostrata una sola volta e viene usata per autenticare le richieste tra OpenCode e Moonshot AI.

Passaggio 2: collega Moonshot AI a OpenCode

Apri il tuo workspace OpenCode ed esegui:

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

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

Una volta verificata, OpenCode salverà in modo sicuro la credenziale in ~/.local/share/opencode/auth.json e la assocerà alla configurazione del tuo provider Moonshot AI.

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

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

Se riscontri un errore No endpoints found dopo la connessione, o se devi personalizzare la configurazione del provider, aggiungi la configurazione di Moonshot AI al tuo file opencode.json:

Salva il file e riavvia OpenCode per applicare le modifiche.

Passaggio 4: visualizza i modelli Kimi disponibili

Dopo aver connesso il provider, esegui:

OpenCode mostrerà tutti i modelli disponibili tramite il tuo account Moonshot AI, tra cui:

Passaggio 5: seleziona un modello Kimi e inizia a programmare

Seleziona moonshotai/kimi-k2.6 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'AI.

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 (come errori di validazione dello JSON Schema), si tratta di un problema di compatibilità noto tra i requisiti rigorosi dello schema di Moonshot AI e il formato dei parametri degli strumenti di OpenCode. Per la massima stabilità, valuta di usare la modalità Chat, oppure installa il plugin opencode-moonshot-compatibility per gestire automaticamente la compatibilità della temperatura.

Vantaggi dell'utilizzo della Kimi API

La 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 alla generazione di codice, è in grado di comprendere diversi tipi di input, adattarsi ai requisiti del progetto e automatizzare le attività ingegneristiche di routine. Ecco alcuni dei suoi principali vantaggi:

• Trasformare input multimodali in implementazioni funzionanti

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

• Gestire attività di coding a lungo termine e problemi ingegneristici complessi

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

• Ragionare sui problemi con chiamate di strumenti multi-step

La Kimi API può ragionare su attività multi-step e chiamare strumenti quando necessario. Questo aiuta con il debugging, l'analisi del codice e i flussi di lavoro che non possono essere completati in un'unica risposta.

Come risolvere i problemi durante l'installazione di OpenCode?

Installare OpenCode è generalmente semplice, ma gli utenti potrebbero incontrare errori di configurazione comuni dovuti a incompatibilità dell'ambiente, dipendenze o problemi di configurazione. Di seguito una guida chiara e pratica per aiutarti a risolvere rapidamente ed efficacemente i problemi di installazione più frequenti.

• Command not found: opencode

Se visualizzi questo errore, significa che il sistema non riesce a individuare l'eseguibile di OpenCode nel tuo PATH. Questo di solito accade quando l'installazione è incompleta o quando le variabili d'ambiente non sono impostate correttamente.

Per risolverlo, verifica prima l'installazione e assicurati che la directory dei binari sia aggiunta al PATH di sistema. Se installato tramite npm, controlla il percorso globale bin di npm e aggiorna di conseguenza la configurazione della shell. Riavviare il terminale spesso risolve il problema dopo le correzioni.

• Versione di Node.js troppo vecchia

OpenCode richiede Node.js 18 o versioni successive; versioni precedenti causeranno errori di installazione o di esecuzione.

Per risolvere il problema, controlla la tua versione attuale usando node --version. Se è obsoleta, aggiorna Node.js usando un version manager come nvm. Dopo l'aggiornamento, reinstalla OpenCode per garantire la compatibilità con l'ambiente di runtime aggiornato.

• Errori di permessi di npm

Gli errori di permessi si verificano tipicamente quando npm tenta di installare pacchetti globali senza gli opportuni permessi di scrittura.

Invece di usare sudo, configura una directory globale npm dedicata nella tua cartella home e aggiorna le impostazioni PATH. Questo garantisce installazioni più sicure e stabili. Dopo aver risolto i permessi, riesegui il comando di installazione per completare la configurazione con successo.

• Problemi di rete/firewall

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

Per risolvere questo problema, passa a un registro npm alternativo o 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 spesso interrompono l'installazione dei pacchetti.

• Problemi di rendering della TUI

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

Usa un emulatore di terminale moderno che supporti i true color e il rendering Unicode, come Windows Terminal, WezTerm o iTerm2. Aggiornare le impostazioni del terminale o cambiare ambiente risolve solitamente i problemi di visualizzazione immediatamente.

Conclusione

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