OpenCode: installazione, modelli e primo avvio

OpenCode è un agente di programmazione basato sull’IA open source per il terminale: lo strumento è gratuito (licenza MIT) e puoi collegarvi qualsiasi modello, da Claude e GPT a un modello locale tramite Ollama. Il repository del progetto ha già superato le duecentomila stelle su GitHub. L’espressione «Claude Code gratuito con qualsiasi modello» suona allettante, ma va chiarita: lo strumento è gratuito; le condizioni d’uso dipendono dal modello scelto.

Di seguito trovi tutto secondo la documentazione ufficiale: che cos’è lo strumento, come installarlo su macOS, Linux o Windows, come collegare un modello e cosa fare al primo avvio. C’è una sezione separata sui costi, perché qui «gratuito» si riferisce solo allo strumento: i modelli costano e questo è ciò che genera più spesso confusione.

Le informazioni pratiche per lavorare con Ailoot sono nella documentazione.

Che cos’è OpenCode, in parole semplici?#

In breve, OpenCode fa lo stesso di Claude Code: riceve un’attività in linguaggio naturale e la svolge nel tuo progetto. Si differenziano in due aspetti. Il codice è completamente aperto, quindi puoi leggerlo e ispezionarlo. Inoltre, lo strumento non è vincolato a un solo provider di modelli: funziona con più di 75 provider, da Anthropic e OpenAI a un modello locale eseguito sul tuo hardware.

Il progetto è sviluppato dal team Anomaly. Il repository è stato creato il 30 aprile 2025 e, al 4 ottobre 2026, ha più di 211 mila stelle e 28 mila fork (verificati con una richiesta all’API di GitHub). Il linguaggio è TypeScript. La documentazione viene aggiornata continuamente, quindi le istruzioni riportate di seguito si basano sulla versione attuale.

Non confondere i nomi: il pacchetto npm della linea attuale si chiama opencode-ai, il repository è anomalyco/opencode e il comando del terminale è semplicemente opencode. Gli articoli più vecchi possono indicare l’indirizzo sst/opencode: l’organizzazione ha cambiato nome e il vecchio link ora reindirizza a quello nuovo.

Aggiornato il 4 ottobre 2026: il team ha rilasciato OpenCode 2.0, la nuova generazione principale dello strumento. Le istruzioni di installazione e collegamento dei modelli riportate di seguito riguardano ancora la linea attuale 1.x (installata con il comando curl -fsSL https://opencode.ai/install | bash; la versione attuale al 30 settembre 2026 è la 1.18.34): è supportata attivamente ed è la versione installata dalla documentazione ufficiale su opencode.ai/docs. Una sezione separata qui sotto spiega cosa è cambiato esattamente nella seconda versione e quando passare a quella.

In cosa OpenCode è diverso da Claude Code e Codex?#

Se hai già un abbonamento Claude, ha senso continuare a usare Claude Code come strumento principale: ne parliamo nella nostra guida dettagliata all’installazione. OpenCode è utile in tre casi: vuoi lavorare tramite un abbonamento ChatGPT Plus o GitHub Copilot, vuoi eseguire un modello locale senza costi API oppure vuoi un’unica interfaccia per più modelli. Abbiamo anche una guida alla recensione e all’installazione di Codex.

Se stai ancora scegliendo uno strumento, inizia da questa panoramica: con cosa si programma nel 2026. Se invece hai già installato OpenCode e vuoi collegarlo ad altri agenti in Devin Desktop tramite ACP, consulta la nostra guida alla configurazione.

Che cosa è cambiato in OpenCode 2.0?#

La seconda versione si installa con il comando curl -fsSL https://opencode.ai/v2/install | bash. Secondo la guida ufficiale alla migrazione (opencode.ai/v2/docs/migrate-v1), entrambe le versioni usano lo stesso comando opencode e non vengono più installate affiancate per impostazione predefinita: il programma d’installazione della v2 sostituisce il binario della v1 e, prima di installare la v2 tramite un gestore di pacchetti, la documentazione chiede esplicitamente di rimuovere prima la versione v1. Tuttavia, la configurazione viene letta dagli stessi file, ~/.config/opencode/ e <project>/.opencode/, quindi impostazioni, agenti e server MCP si trasferiscono senza riscritture. Tre elementi vanno invece riscritti: i plugin (hanno una nuova API), le integrazioni con l’API del server (il protocollo è cambiato) e le impostazioni del terminale (ora c’è un solo file condiviso cli.json invece di diversi file tui.json).

Le due nuove funzionalità più rilevanti della v2 sono queste. Primo, è stato introdotto Console, un servizio a pagamento per i team con tracciamento dell’utilizzo, budget e criteri condivisi per tutti i membri. Secondo, il team ha finalmente annunciato il prezzo dell’abbonamento Go: $10 al mese per Go e $40 al mese per Go Plus, con limiti più alti (pagina opencode.ai/go, verificata il 4 ottobre 2026). In precedenza la documentazione si limitava a parlare di «abbonamento a basso costo», senza indicare una cifra.

Se sei alle prime armi e vuoi solo installare l’agente, segui le istruzioni qui sotto: riguardano la prima versione attuale, raccomandata dalla documentazione stessa. Valuta la v2 se ti servono le nuove funzionalità dei plugin o Console per i team, ma preparati a riscrivere alcuni plugin più vecchi per la nuova API. Se ti interessa di più un’applicazione desktop open source che non richiede il terminale, abbiamo una recensione di ZCode, un altro agente simile con un’interfaccia propria.

Che cosa serve prima di installare?#

Qualche dettaglio in più sul terminale, perché è l’unico punto in cui l’installazione potrebbe non andare come previsto. OpenCode mostra nel terminale un’interfaccia completa con pannelli ed evidenziazione, per questo la documentazione richiede un emulatore moderno. Se dopo l’avvio l’interfaccia appare male, installa prima una delle quattro opzioni indicate: WezTerm (funziona su tutti i sistemi), Alacritty, Ghostty o Kitty. Su Windows, il percorso principale passa da WSL, a cui è dedicata una sezione qui sotto.

La seconda cosa è un modello. OpenCode funziona tramite il modello che colleghi: da solo non elabora le richieste. Ci sono quattro opzioni: un abbonamento (ChatGPT Plus, GitHub Copilot, GitLab Duo), una chiave API di qualsiasi provider, OpenCode Zen, l’aggregatore del team stesso, oppure un modello locale tramite Ollama. Tutte e quattro le opzioni sono illustrate nella sezione dedicata al collegamento di un modello.

Senza una descrizione del progetto, l’agente deve indovinare i comandi di compilazione, la struttura dei file e le convenzioni in uso, da cui derivano le «allucinazioni». OpenCode usa a questo scopo un file AGENTS.md. Lo stesso approccio si applica a Claude Code e a qualsiasi altro agente; cambia solo il nome del file delle istruzioni.

Come installare OpenCode su macOS e Linux?#

Il percorso consigliato è il programma d’installazione ufficiale:

1. Esegui il programma d’installazione

   curl -fsSL https://opencode.ai/install | bash
   

   Lo script rileva il sistema e scarica OpenCode. Se al termine dell’installazione il comando non viene trovato, chiudi e riapri il terminale: il percorso verrà rilevato nella nuova sessione.

2. Verifica che l’installazione sia riuscita

   opencode --version
   

   Il comando restituisce un numero di versione, il che significa che l’installazione è riuscita. Se compare «command not found», torna al primo passaggio: avvia una nuova sessione del terminale o modifica manualmente PATH.

Se preferisci gestire i pacchetti autonomamente, ecco le opzioni:

brew install anomalyco/tap/opencode

npm install -g opencode-ai

Il comando Homebrew inizia appositamente con anomalyco/tap/: la documentazione consiglia il loro tap perché il team Homebrew aggiorna meno spesso la formula per brew install opencode. Lo stesso nome del pacchetto, opencode-ai, funziona anche con bun, pnpm e yarn (bun install -g opencode-ai, yarn global add opencode-ai). Su Arch Linux, usa sudo pacman -S opencode dal repository stabile oppure paru -S opencode-bin per la versione più recente da AUR.

Aggiorna OpenCode con opencode upgrade; quando viene avviato, scarica anche gli aggiornamenti autonomamente se l’aggiornamento automatico è abilitato. Dopo l’aggiornamento, verifica la versione con il consueto comando opencode --version. È disponibile anche la disinstallazione integrata:

opencode uninstall

Il comando mostra esattamente cosa verrà eliminato e chiede conferma. Se vuoi, puoi conservare la configurazione e i dati delle sessioni usando i flag --keep-config e --keep-data.

Come installare OpenCode su Windows?#

La prima opzione consigliata dagli stessi sviluppatori è WSL. Installalo con un unico comando in PowerShell avviato come amministratore:

wsl --install

Dopo il riavvio, apri Ubuntu dal menu Start ed esegui al suo interno il consueto comando:

curl -fsSL https://opencode.ai/install | bash

I file sui dischi Windows sono accessibili in WSL tramite /mnt/: il disco C: si trova in /mnt/c/ e il disco D: in /mnt/d/. Quindi puoi aprire un progetto in C:\Users\Name\project così:

cd /mnt/c/Users/Name/project
opencode

La seconda opzione consiste nel saltare WSL e usare i gestori di pacchetti Windows. In PowerShell:

choco install opencode

scoop install opencode

La terza opzione è l’applicazione desktop e la versione web. L’applicazione si installa come un normale programma e mostra l’interfaccia in una finestra, senza terminale. La versione web si avvia con il comando opencode web: apre OpenCode in un browser e la documentazione consiglia di avviarla anche da WSL, per evitare problemi di accesso ai file. La documentazione elenca inoltre opzioni meno comuni: mise, Docker e un binario già pronto dalla pagina delle release GitHub. L’installazione tramite bun su Windows è ancora in corso; se bun è il tuo gestore di pacchetti principale, usa l’opzione npm.

Come collegare un modello a OpenCode?#

OpenCode supporta più di 75 provider tramite AI SDK e Models.dev, oltre ai modelli locali. La maggior parte si collega con il comando /connect nell’interfaccia; per i modelli locali, specifichi anche l’indirizzo del server nella configurazione. Le opzioni differiscono per metodo di pagamento e requisiti del computer:

La documentazione consiglia ai principianti di iniziare con OpenCode Zen. Il team ha selezionato modelli che funzionano bene specificamente come agenti e ha testato le loro combinazioni con i provider usando le proprie attività.

Il collegamento funziona così: digita /connect, scegli OpenCode Zen, accedi e aggiungi un metodo di pagamento su opencode.ai/auth, ottieni una chiave e incollala. Quindi /models mostrerà l’elenco dei modelli consigliati. Al 4 ottobre 2026, l’elenco include, per esempio, GPT 6.1 Sol, GPT 6 Astra, Claude Opus 5.5, Claude Sonnet 5, GLM 5.3 e Kimi K2.5. La documentazione avverte correttamente che l’elenco non è esaustivo e diventa rapidamente obsoleto perché ogni settimana escono nuovi modelli.

Gli abbonamenti si collegano con lo stesso comando /connect: scegli ChatGPT Plus o GitHub Copilot dall’elenco e accedi al tuo account, senza ulteriori configurazioni.

Se scegli Anthropic, /connect offre due opzioni: inserire manualmente una chiave API oppure scegliere Claude Pro/Max e autenticarti tramite browser. Tuttavia, Anthropic vieta i plugin di terze parti per usare un abbonamento Claude Pro/Max e i plugin integrati di questo tipo sono stati rimossi da OpenCode a partire dalla versione 1.3.0. Se trovi un articolo più vecchio su «OpenCode tramite un abbonamento Claude», si riferisce a quei plugin rimossi, non all’autorizzazione ufficiale. Gli abbonamenti ChatGPT Plus, GitHub Copilot, GitLab Duo (indicato come sperimentale) e Atomic Chat funzionano senza configurazioni aggiuntive.

OpenCode memorizza nel file ~/.local/share/opencode/auth.json le chiavi inserite tramite /connect. Se non vuoi scegliere un modello ogni volta, imposta quello predefinito nel file di configurazione opencode.json nella radice del progetto:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

Il formato è provider/model; entrambi gli identificativi sono mostrati nell’output di /models.

Come collegare un modello locale tramite Ollama?#

Questa opzione significa zero costi API: il modello viene eseguito sul tuo computer. Se in generale stai scegliendo tra modelli gratuiti, abbiamo una recensione separata su quali funzionano ragionevolmente bene come agenti e quali solo in teoria. Per OpenCode, installa Ollama dal sito ufficiale e scarica un modello:

ollama pull qwen3-coder

Un dettaglio utile della documentazione: Ollama può configurarsi automaticamente per OpenCode; c’è una guida d’integrazione separata. Se vuoi configurare tutto manualmente, aggiungi a opencode.json un provider con l’indirizzo del tuo server Ollama locale:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

Poi, nell’interfaccia, /models mostrerà il modello locale nell’elenco. Selezionalo e mettiti al lavoro. Un avvertimento pratico della documentazione: se l’agente smette di richiamare gli strumenti (modificare file o eseguire comandi), aumenta num_ctx nelle impostazioni di Ollama; inizia con valori di 16k–32k. I modelli locali sono più deboli di quelli cloud proprio nei compiti da agente e una finestra di contesto ridotta peggiora la situazione. Se la versione locale non basta, puoi collegare Qwen dal cloud con una chiave; la guida come ottenere una chiave API per Qwen Code spiega dove trovarla.

Quanto costano OpenCode e il suo utilizzo?#

Qui tutti i costi riguardano il modello e ci sono quattro scenari. Con una chiave API o Zen paghi in base all’utilizzo effettivo e l’importo dipende da quanto lavora l’agente. Go è un piano in abbonamento del team OpenCode per modelli open: $10 al mese per Go e $40 al mese per Go Plus, con limiti più alti (verificato sulla pagina opencode.ai/go il 4 ottobre 2026). Il limite dipende dal modello: per esempio, Go consente circa 110 richieste ogni 5 ore (440 al mese) per Kimi K3 e circa 26.000 richieste ogni 5 ore per il più leggero DeepSeek V4.1 Flash. Per accedere a un modello specifico oltre il limite, la documentazione indica un prezzo separato ($15 al mese per Kimi K3, $60 per Go Plus). Consulta la pagina dell’abbonamento al momento del collegamento per l’elenco completo dei modelli e dei limiti. Con ChatGPT Plus o Copilot, le richieste sono coperte dall’abbonamento che già paghi; ricorda soltanto che gli abbonamenti hanno limiti di utilizzo. Infine, le richieste a un modello locale tramite Ollama non costano nulla, ma serve un computer abbastanza potente da eseguirlo rapidamente.

Che cosa fare al primo avvio?#

Primo avvio, dalla cartella del progetto:

cd path/to/project
opencode

L’interfaccia si apre con un campo di input. Per prima cosa, usa il comando /init: l’agente analizza i file importanti del repository, se necessario pone un paio di domande e scrive un file AGENTS.md, una guida alla struttura del progetto, ai comandi da usare per compilazioni e test e alle convenzioni adottate. La documentazione consiglia di aggiungere questo file a git; OpenCode lo usa quindi come istruzione permanente per il progetto. Per funzione, AGENTS.md è l’equivalente diretto di CLAUDE.md nell’ecosistema OpenCode.

In secondo luogo, usa la modalità Plan. Il tasto Tab permette di passare tra i due agenti principali: Build lavora con pieno accesso a file e comandi, mentre Plan serve per analisi e pianificazione: per impostazione predefinita, in modalità Plan le modifiche ai file e i comandi bash richiedono la tua approvazione. Per le nuove attività, la documentazione consiglia di iniziare con un piano: leggi cosa intende fare l’agente, modifica la formulazione e solo dopo torna a Build premendo Tab.

La documentazione dà questo consiglio:

Più specifica è l’attività e più contesto fornisci, meno dovrai rifare il lavoro. Aggiungi file a una richiesta con @: inizia a digitare un nome e l’interfaccia li troverà con la ricerca fuzzy. Puoi trascinare immagini direttamente nel terminale; un messaggio che inizia con ! viene eseguito come comando shell e il suo output viene aggiunto al contesto dell’agente. Se hai sbagliato l’attività o l’agente ha fatto la cosa sbagliata, /undo annulla le modifiche e puoi eseguirlo più volte di seguito. Hai cambiato idea di nuovo? /redo ripristina ciò che era stato annullato. /share crea un link alla conversazione per il tuo team; senza questo comando, la conversazione non viene pubblicata da nessuna parte.

Che cos’altro può fare OpenCode?#

Comandi personalizzati. Qualsiasi richiesta ricorrente può diventare un comando: inserisci un file markdown in .opencode/commands/, imposta description, agent e model nel frontmatter e scrivi sotto un modello di prompt. Poi richiama il comando con /. Controlli del progetto prima della pubblicazione, revisione degli errori recenti, generazione di una migrazione: qualsiasi attività chiedi regolarmente.

Subagenti. Oltre a Build e Plan, ce ne sono altri tre: General per le attività in più passaggi (ha accesso a tutti gli strumenti tranne l’elenco delle attività), Explore per leggere rapidamente il codice senza il permesso di modificarlo e Scout per cercare librerie esterne. Richiamali menzionandoli con @ in un messaggio.

Server MCP. Collega strumenti esterni tramite la sezione mcp della configurazione opencode.json: sono supportati server locali e remoti. Ogni server MCP aggiunge i propri strumenti al contesto e un server vorace come GitHub può consumarlo molto rapidamente; collegane solo quelli necessari. Abbiamo una guida con configurazioni già pronte al concetto di MCP; parla di Claude Code, ma il protocollo è condiviso.

Versione web e server. opencode web apre l’interfaccia in un browser. Per accedervi da un’altra macchina, usa opencode serve --hostname 0.0.0.0 --port 4096; quando c’è accesso alla rete, imposta una password con la variabile OPENCODE_SERVER_PASSWORD. Senza password, il server non è protetto.

Che cosa fare se l’installazione non va a buon fine?#

«opencode: command not found» dopo l’installazione. Il terminale non ha ancora rilevato il nuovo percorso. Per prima cosa, chiudi e riapri il terminale. Se non basta, trova dove il programma d’installazione ha collocato il binario e aggiungi quella cartella a PATH del terminale.

Il modello non risponde o segnala un errore di autorizzazione. Controlla che il provider sia collegato: digita /connect e ripeti l’autenticazione. Le chiavi sono memorizzate in ~/.local/share/opencode/auth.json; se hai spostato l’installazione da un altro computer o eliminato delle cartelle, il file potrebbe mancare. La documentazione tratta separatamente gli errori ProviderInitError e AI_APICallError: per il primo, autorizza di nuovo il provider; per il secondo, svuota la cartella ~/.cache/opencode e riavvia.

L’interfaccia è danneggiata: i pannelli sono sparsi oppure al posto dei simboli compaiono caratteri illeggibili. Per prima cosa, controlla il terminale. Installa una delle opzioni consigliate — WezTerm funziona su tutti e tre i sistemi — e avvia OpenCode da lì.

Se non funziona nulla, controlla i log: su macOS e Linux si trovano in ~/.local/share/opencode/log/; su Windows, premi Win+R e inserisci %USERPROFILE%\.local\share\opencode\log. Vengono conservati i dieci file più recenti; abilita la registrazione dettagliata con il flag opencode --log-level DEBUG. Con questi log puoi inviare una segnalazione di bug nel repository GitHub del progetto.

Che cos’altro chiedono le persone su OpenCode?#

Apri Ailoot.