Cos'è OpenCode?
OpenCode è un agent di programmazione AI open source che viene eseguito nel terminale e può essere usato anche tramite flussi di lavoro desktop, IDE e basati su server. Aiuta gli sviluppatori a lavorare su una codebase leggendo i file, spiegandone la struttura, modificando il codice, revisionando le modifiche ed eseguendo attività tramite provider LLM collegati. Lo colleghi a un provider di modelli, come Kimi API, e OpenCode usa quel provider per pianificare, ragionare e agire all'interno del tuo ambiente di sviluppo.
Cosa puoi fare con OpenCode?
Puoi scegliere OpenCode quando vuoi un flusso di lavoro di programmazione AI in grado di lavorare direttamente sul tuo progetto. Ad esempio:
Scrivere, modificare e rifattorizzare codice: puoi chiedere a OpenCode di aggiungere una funzionalità, modificare un file esistente, rifattorizzare una funzione o spiegare come dovrebbe essere modificato un modulo. Per risultati migliori, indicagli i file o le directory esatti coinvolti.
Eseguire il debug degli errori e generare test: OpenCode può analizzare l'output degli errori, leggere i file correlati, suggerire correzioni e aggiungere test. È particolarmente utile quando il problema dipende dal contesto del progetto.
Revisionare le modifiche al codice: puoi usare OpenCode per revisionare le modifiche locali prima del commit. Può individuare possibili bug, test mancanti, pattern incoerenti e modifiche rischiose.
Automatizzare i flussi di lavoro di sviluppo: OpenCode supporta anche flussi di lavoro non interattivi e basati su server. Ad esempio, puoi eseguire un prompt singolo dalla riga di comando oppure avviare un server OpenCode headless e collegarvi un altro client o integrazione.
Prerequisiti per configurare OpenCode con un'API LLM
Prima di configurare OpenCode con un'API LLM, prepara quanto segue:
Un terminale funzionante su macOS, Linux o Windows (con WSL consigliato).
Node.js, Homebrew o un altro metodo di installazione supportato.
Una cartella di progetto in cui puoi fare test in sicurezza.
Un account presso un provider di modelli.
Per OpenCode, tieni presente che le credenziali del provider sono informazioni sensibili. Non incollare la tua chiave in issue pubbliche, screenshot condivisi, file sorgente o configurazioni sottoposte a commit.
Passo 1: installa OpenCode
Il metodo di installazione più rapido indicato nella documentazione ufficiale di OpenCode è lo script di installazione. Esegui questo comando nel terminale:
OpenCode supporta anche l'installazione tramite npm, Homebrew e altri comandi. Se preferisci la versione desktop, puoi scaricare quella adatta al tuo dispositivo.
Passo 2: avvia OpenCode
Vai al progetto su cui vuoi far lavorare OpenCode:
Avvia OpenCode:
Se è la prima volta che usi OpenCode in questo progetto, inizializzalo dall'interno della TUI:
Come configurare OpenCode con un'API LLM
Nella maggior parte dei casi, usare "OpenCode API" significa collegare OpenCode a un provider LLM esterno tramite una chiave API. Il provider fornisce il modello, mentre OpenCode gestisce il flusso di lavoro dell'agente di coding all'interno del tuo progetto. I passaggi seguenti usano Kimi API come esempio di provider.
Passo 1: crea la tua chiave API Kimi
Apri la Kimi Open Platform. Crea una chiave API dalla console, quindi conservala in un password manager o in un gestore di segreti. Se la console mostra la chiave completa una sola volta, copiala prima di lasciare la pagina.
Passo 2: collega un provider di modelli
Avvia OpenCode nel tuo progetto:
All'interno dell'interfaccia OpenCode, esegui:
Cerca Moonshot AI o la voce del provider compatibile con Kimi mostrata dalla tua versione di OpenCode. La documentazione ufficiale sui provider di OpenCode include un flusso per il provider Moonshot AI: crea una chiave nella console Moonshot AI, esegui /connect, cerca Moonshot AI e inserisci la chiave API.
Se la tua versione non elenca Moonshot AI, aggiorna OpenCode e aggiorna l'elenco dei modelli:
Passo 3: inserisci la tua chiave API Kimi
Quando OpenCode richiede la chiave API, incolla la tua chiave API Kimi.
OpenCode memorizza le credenziali del provider nel proprio file di autenticazione locale. La documentazione ufficiale del provider indica questo percorso:
Normalmente non è necessario modificare quel file manualmente. Usa invece il flusso /connect del provider di OpenCode.
Passo 4: seleziona un modello Kimi
Dopo aver collegato il provider, scegli un modello dall'interno di OpenCode:
Seleziona il modello Kimi che vuoi usare. Per nuovi flussi di lavoro con agenti di coding, inizia con:
Se devi eseguire OpenCode in modalità non interattiva con un modello specifico, usa il formato provider/modello mostrato nell'elenco dei modelli di OpenCode. Ad esempio:
Poi usa l'identificatore esatto del modello stampato da OpenCode.
Passo 5: esegui il tuo primo task di coding
Inizia con un task a basso rischio, così puoi verificare che provider, modello, accesso al progetto e permessi funzionino tutti correttamente:
Risultato atteso:
Poi prova un piccolo task di coding:
Questo conferma che OpenCode è in grado di leggere il progetto e ragionare sul codice prima di consentirgli di apportare modifiche.
Perché usare Kimi API con OpenCode?
Kimi API è una scelta adatta per OpenCode quando cerchi un provider di modelli compatibile con OpenAI per flussi di lavoro di coding e con agenti.
Solide capacità di coding e ragionamento
{{KIMI_MODEL_LATEST_FULL}} è ufficialmente pensato per coding a lungo termine, capacità di seguire istruzioni, autocorrezione ed esecuzione agentica. Questo lo rende adatto a task di OpenCode come modifiche multi-file, debugging, refactoring e revisione del codice.
Supporto per contesto lungo per progetti più grandi
La documentazione ufficiale di {{KIMI_MODEL_LATEST_FULL}} indica il supporto per contesto lungo per {{KIMI_MODEL_LATEST_FULL}} e diversi modelli della serie K2. In un flusso di lavoro con agent, il contesto lungo può essere utile quando il task richiede la lettura di più file, il confronto tra pattern di implementazione o la conservazione di una grande quantità di cronologia del task.
API compatibile con OpenAI per una configurazione più semplice
Kimi API è compatibile con il formato dell'API di OpenAI. Per gli strumenti che già supportano i chat completions in stile OpenAI, questo spesso significa che devi solo configurare l'API key, il Base URL e il nome del modello.
Utilizzo flessibile oltre OpenCode
Puoi usare la stessa API key di Kimi in altri strumenti di sviluppo compatibili con OpenAI, in script diretti o in flussi di lavoro interni. Se in seguito utilizzi il server OpenCode o l'OpenCode SDK, configura prima Kimi come provider del modello.
Impostazioni chiave dell'API di OpenCode da conoscere
Queste impostazioni riguardano la maggior parte dei problemi di configurazione dell'API e del provider in OpenCode.
API key
L'API key autentica la tua richiesta verso il provider del modello. In OpenCode, di solito la aggiungi con:
Provider
Il provider indica a OpenCode da dove proviene il modello. In questa guida, il provider è Moonshot AI / Kimi API. Altri provider possono essere configurati separatamente, ma ciascuno richiede le proprie credenziali e il proprio elenco di modelli.
Base URL
Il Base URL è l'endpoint usato per le richieste dirette all'API compatibile con OpenAI. Per gli esempi con Kimi API, usa l'endpoint indicato nella documentazione attuale di Kimi API o nella console del tuo account.
Nome del modello
Il nome del modello deve corrispondere esattamente a quello indicato dal provider. Un piccolo errore di digitazione può causare un errore di modello non trovato.
Esempio comune:
In OpenCode, verifica l'identificativo provider/modello con:
Risoluzione dei problemi comuni con l'API di OpenCode
La maggior parte dei problemi di configurazione dipende da uno di questi cinque fattori: credenziali, endpoint, provider, nome del modello o dimensione del contesto.
Autenticazione non riuscita
L'autenticazione può non riuscire se l'API key è stata incollata in modo errato, eliminata o rinnovata. Può accadere anche se viene selezionato il provider sbagliato, oppure se la key appartiene a un account o a una regione diversi da quelli attualmente configurati in OpenCode.
Soluzione:
Riconnetti il provider e incolla una nuova API key. Se usi variabili d'ambiente per test diretti, reimposta la key:
Errore di endpoint non valido
Un errore di endpoint non valido di solito significa che OpenCode non riesce a raggiungere l'endpoint corretto del provider. Le cause più comuni sono un Base URL scritto male, l'uso combinato degli endpoint .ai e .cn tra diversi strumenti, oppure un proxy o firewall che modifica le richieste prima che raggiungano il provider.
Soluzione:
Controlla l'endpoint indicato nella documentazione o nella console attuale di Kimi API. Per i test diretti dell'API, usa sempre lo stesso endpoint in modo coerente:
Modello non supportato
Questo errore può verificarsi quando il nome del modello è scritto male, il modello selezionato non è disponibile per il tuo account, oppure la cache dell'elenco modelli di OpenCode non è aggiornata. Può accadere anche quando l'identificativo provider/modello usato da OpenCode è diverso dal nome del modello grezzo indicato nella documentazione del provider.
Soluzione:
Poi seleziona nuovamente il modello:
Limite di velocità superato
Un errore di limite di velocità di solito significa che il provider ha ricevuto troppe richieste in troppo poco tempo. Può accadere se più task agentici vengono eseguiti contemporaneamente, oppure se uno script o un'integrazione ritenta le richieste fallite in modo troppo aggressivo.
Soluzione:
Interrompi il task, riduci le esecuzioni parallele e controlla lo stato della quota o della fatturazione nella console del provider. Evita di scrivere cicli di retry infiniti attorno a OpenCode o alle chiamate dirette a Kimi API.
Overflow della finestra di contesto
Un overflow della finestra di contesto di solito significa che il task è troppo grande per essere elaborato dal modello in un'unica volta. Può accadere se sono inclusi troppi file, se a OpenCode viene chiesto di analizzare l'intero repository, oppure se una sessione lunga ha accumulato troppa cronologia della conversazione.
Soluzione:
Chiedi a OpenCode di lavorare su un ambito più ristretto:
Puoi anche avviare una nuova sessione per un'attività più circoscritta.
Conclusione
OpenCode può collegare il tuo codebase a provider di modelli ed eseguire attività di programmazione dal terminale. Kimi API può fornire il backend del modello per questi flussi di lavoro tramite una configurazione compatibile con OpenAI. Se vuoi un flusso di lavoro pratico con un agent di programmazione, crea la tua chiave Kimi API, collega Moonshot AI in OpenCode, scegli un modello Kimi ed esegui un piccolo task di progetto per verificare la configurazione.
Domande frequenti
/connect. OpenCode salva le credenziali del provider localmente, e la documentazione ufficiale indica ~/.local/share/opencode/auth.json come percorso del file delle credenziali.opencode models. Per Kimi API, scegli l'identificatore esatto del modello Kimi mostrato nella tua lista di modelli OpenCode, ad esempio kimi-k2.6 quando disponibile per il tuo account./connect.