Key Takeaways

• Molteplici percorsi di installazione: npm, Homebrew, script curl, Go install, Docker e compilazione da sorgente -- scegli quello che meglio si adatta alla tua toolchain.
• Cinque minuti alla prima esecuzione: Il percorso più veloce (script di installazione curl) permette di eseguire OpenCode in meno di cinque minuti su qualsiasi sistema Unix.
• Indipendente dal provider: OpenCode funziona con OpenAI, Google Gemini, modelli locali Ollama e altri ancora -- non sei vincolato a un singolo provider AI.
• La configurazione è minima: Un singolo file config.toml e una variabile d'ambiente sono tutto ciò di cui hai bisogno per iniziare a programmare con l'AI nel tuo terminale.

Come installare OpenCode: Guida alla configurazione passo dopo passo (2026)

OpenCode è l'agente di programmazione AI open-source creato per il terminale. Porta la potenza dei modelli linguistici di grandi dimensioni direttamente nella tua riga di comando, permettendoti di scrivere, rifattorizzare, eseguire il debug e comprendere il codice senza lasciare il tuo editor o il flusso di lavoro del terminale.

Sia che tu stia configurando OpenCode per la prima volta o che stia migrando da un altro strumento di programmazione AI, questa guida ti accompagnerà attraverso ogni metodo di installazione, configurazione iniziale, impostazione del provider e passaggi per la risoluzione dei problemi di cui avrai bisogno.

---

Prerequisiti

Prima di installare OpenCode, conferma che il tuo sistema soddisfi i seguenti requisiti.

Sistema Operativo

OpenCode funziona su macOS, Linux e Windows. Per gli utenti Windows, si raccomanda caldamente WSL (Windows Subsystem for Linux). È disponibile anche il supporto nativo per Windows tramite Scoop.

Requisiti di Runtime (dipende dal metodo di installazione)

Metodo di installazione	Requisito
npm	Node.js 18 o superiore
Homebrew	macOS o Linux con Homebrew installato
Script curl	bash, curl
Go install	Go 1.22 o superiore
Docker	Docker Engine 20+
Compilazione da sorgente	Go 1.22+, Git

Requisiti del terminale

OpenCode fornisce una TUI (Terminal User Interface), quindi il tuo emulatore di terminale deve supportare true color e un corretto rendering Unicode. La maggior parte dei terminali moderni (iTerm2, Alacritty, WezTerm, Windows Terminal, Ghostty) funziona correttamente. I terminali più datati come il Terminal.app predefinito di macOS potrebbero presentare problemi di rendering.

Controlla la tua versione di Node.js:

node --version

Controlla la tua versione di Go (se usi il metodo Go install):

go version

---

Metodo 1: Script di installazione (Il più veloce)

Lo script di installazione ufficiale è il modo più rapido per avviare OpenCode. Rileva il tuo OS e la tua architettura, scarica il binario corretto e lo inserisce nel tuo PATH.

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

Questo singolo comando gestisce tutto. Una volta completato, verifica l'installazione:

opencode --version

Questo metodo funziona su macOS e Linux. Non richiede Node.js o Go.

---

Metodo 2: Installazione tramite npm

Se hai già Node.js nel tuo flusso di lavoro, npm è l'opzione più familiare.

npm install -g opencode-ai@latest

Il nome del pacchetto su npm è opencode-ai, non opencode. Questa è una comune fonte di confusione.

Per verificare:

opencode --version

Se riscontri errori di permessi, correggi i permessi della tua directory globale npm o usa npx per eseguirlo senza un'installazione globale:

npx opencode-ai@latest

---

Metodo 3: Homebrew (macOS e Linux)

Gli utenti Homebrew possono installare OpenCode dal tap ufficiale:

brew install anomalyco/tap/opencode

Questo installa l'ultima versione stabile e gestisce gli aggiornamenti tramite brew upgrade.

Per verificare:

opencode --version

---

Metodo 4: Go Install

Se hai Go 1.22+ installato, puoi installare direttamente dai sorgenti tramite go install:

go install github.com/opencode-ai/opencode@latest

Assicurati che $GOPATH/bin (o $HOME/go/bin per impostazione predefinita) sia nel tuo PATH. Aggiungilo al tuo profilo shell se non è già presente:

export PATH="$PATH:$(go env GOPATH)/bin"

Verifica:

opencode --version

---

Metodo 5: Docker

Eseguire OpenCode in Docker è utile per le pipeline CI/CD o quando si desidera un ambiente isolato.

docker pull ghcr.io/opencode-ai/opencode:latest

Eseguilo con la directory del tuo progetto montata:

docker run -it --rm \
  -v "$(pwd)":/workspace \
  -w /workspace \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  ghcr.io/opencode-ai/opencode:latest

I flag -it sono essenziali perché OpenCode utilizza una TUI interattiva. Il flag -v monta la directory corrente del tuo progetto in modo che OpenCode possa leggere e modificare i tuoi file.

---

Metodo 6: Compilazione da sorgente

Per i contributori o per chiunque desideri la versione all'avanguardia:

git clone https://github.com/opencode-ai/opencode.git
cd opencode
go build -o opencode .

Sposta il binario in una directory nel tuo PATH:

sudo mv opencode /usr/local/bin/

La compilazione da sorgente richiede Go 1.22+ e Git. Questo ti dà accesso a funzionalità non ancora rilasciate e ti permette di modificare lo strumento per le tue esigenze.

---

Metodo 7: Scoop (Windows)

Gli utenti Windows che preferiscono un'esperienza nativa rispetto a WSL possono usare Scoop:

scoop install opencode

Scoop gestisce automaticamente la configurazione del PATH.

---

Primo avvio e configurazione

Con OpenCode installato, naviga in qualsiasi directory di progetto e avvialo:

cd your-project
opencode

Al primo avvio, OpenCode apre la sua TUI e ti chiede di connettere un provider AI. Puoi usare il comando interattivo /connect per aggiungere la tua API key:

/connect

Questo ti guiderà nella selezione di un provider (OpenAI, Google, Anthropic, etc.) e nell'inserimento della tua API key. Le credenziali sono memorizzate in ~/.local/share/opencode/auth.json.

Per un avvio più rapido, puoi anche inizializzare il tuo progetto con:

/init

Questo analizza la struttura del tuo repository e crea un file agents.md con il contesto della tua codebase, aiutando l'AI a fornire risposte più accurate fin dall'inizio.

---

Configurare i provider AI

OpenCode supporta molteplici provider AI. Ecco come configurare ognuno di essi.

OpenAI (GPT-5.4, GPT-4.1, o3)

Imposta la API key come variabile d'ambiente:

export OPENAI_API_KEY="sk-your-key-here"

O aggiungila al tuo profilo shell (~/.zshrc, ~/.bashrc) per la persistenza.

Google Gemini (Gemini 2.5 Pro, Gemini 2.5 Flash)

export GOOGLE_API_KEY="your-google-api-key"

Puoi ottenere una Google API key da Google AI Studio.

Ollama (Modelli locali -- Gratuiti, Privati)

Ollama ti permette di eseguire modelli localmente senza alcuna API key. Installa prima Ollama, scarica un modello, quindi configura OpenCode:

# Installa Ollama (se non è già installato)
curl -fsSL https://ollama.com/install.sh | sh

# Scarica un modello di programmazione
ollama pull qwen2.5-coder:32b

# OpenCode rileva Ollama automaticamente quando è in esecuzione su localhost:11434

Nessuna API key è necessaria per Ollama. OpenCode lo rileva automaticamente quando è in esecuzione localmente.

Anthropic (Claude -- Accesso limitato)

Anthropic ha limitato l'accesso a Claude in strumenti di terze parti, incluso OpenCode. Se hai una API key che funziona ancora:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

Tuttavia, la maggior parte degli utenti nel 2026 utilizza OpenAI o Gemini come provider primario con OpenCode a causa di queste restrizioni.

---

Configurazione essenziale: Panoramica di config.toml

OpenCode utilizza un file di configurazione TOML per un controllo granulare. Il file di configurazione si trova in ~/.config/opencode/config.toml (o nella root del tuo progetto come opencode.json per impostazioni specifiche del progetto).

Ecco un esempio pratico di un config.toml:

# Provider configuration
[provider.openai]
apiKey = "{env:OPENAI_API_KEY}"

[provider.openai.models.gpt]
id = "gpt-5.4"

[provider.google]
apiKey = "{env:GOOGLE_API_KEY}"

[provider.google.models.gemini]
id = "gemini-2.5-pro"

# Disable providers you do not use
disabled_providers = ["anthropic"]

Punti chiave da notare:

• Sostituzione delle variabili: Usa {env:VARIABLE_NAME} per fare riferimento alle variabili d'ambiente invece di inserire le chiavi direttamente nel codice.
• Selezione del modello: Puoi specificare esattamente quale modello usare sotto ogni provider.
• Provider disabilitati: Impedisci a OpenCode di caricare provider di cui non possiedi le credenziali, evitando avvisi all'avvio.
• Sovrascrittura della URL di base: Se usi un proxy o un endpoint personalizzato, aggiungi baseURL = "https://your-proxy.com/v1" sotto la sezione del provider.

Per la configurazione a livello di progetto, crea un opencode.json nella root del tuo progetto:

{
  "provider": "openai",
  "model": "gpt-5.4"
}

Questo sovrascrive le impostazioni globali per quel progetto specifico.

---

Verifica la tua installazione

Controlla questa lista per confermare che tutto funzioni correttamente.

1. Controlla la versione

opencode --version

Dovresti vedere stampato il numero della versione. A partire da Marzo 2026, l'ultima versione stabile è nella gamma 0.x.

2. Avvia la TUI

cd any-project-directory
opencode

Dovresti vedere l'interfaccia terminale di OpenCode con un prompt in basso.

3. Testa un semplice prompt

Nella TUI di OpenCode, digita una semplice richiesta:

Explain what this project does based on the file structure.

Se ricevi una risposta dall'AI, la configurazione del tuo provider funziona.

4. Testa le operazioni sui file

Chiedi a OpenCode di creare un piccolo file di test:

Create a file called test-opencode.txt with the text "OpenCode is working"

Controlla che il file sia stato creato nella directory del tuo progetto, quindi eliminalo.

---

Risoluzione dei problemi comuni

"command not found: opencode"

Il binario non è nel tuo PATH. Le soluzioni dipendono dal tuo metodo di installazione:

• npm: Esegui npm list -g opencode-ai per confermare l'installazione. Se installato, controlla che la directory bin globale di npm sia nel tuo PATH: npm config get prefix e aggiungi /bin a quel percorso.
• Go: Aggiungi $(go env GOPATH)/bin al tuo PATH.
• Script Curl: Esegui nuovamente lo script di installazione o sposta manualmente il binario in /usr/local/bin/.

Errori di permessi durante l'installazione npm

Non usare sudo npm install -g. Invece, correggi la directory predefinita di npm:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g opencode-ai@latest

"Error: Node.js version too old"

Il pacchetto npm di OpenCode richiede Node.js 18+. Controlla la tua versione:

node --version

Se sei su una versione precedente, aggiorna usando nvm:

nvm install 18
nvm use 18

Errori di rete dietro un firewall aziendale

Se l'installazione npm si blocca o fallisce a causa di restrizioni di rete:

npm install -g opencode-ai@latest --registry https://registry.npmmirror.com

O scarica il binario direttamente dalla pagina delle release di GitHub e inseriscilo manualmente nel tuo PATH.

"API key not found" o "No provider configured"

Assicurati che la tua variabile d'ambiente API key sia esportata nella stessa sessione della shell:

echo $OPENAI_API_KEY

Se non stampa nulla, impostala di nuovo:

export OPENAI_API_KEY="sk-your-key-here"

Per la persistenza, aggiungi la riga di export al tuo ~/.zshrc o ~/.bashrc ed esegui source ~/.zshrc.

Problemi di rendering della TUI (testo distorto, bordi mancanti)

Passa a un emulatore di terminale moderno che supporti true color. Opzioni consigliate: iTerm2 (macOS), Alacritty (multi-piattaforma), WezTerm (multi-piattaforma) o Windows Terminal (Windows).

Go install: "go: command not found"

Go non è installato o non è nel tuo PATH. Installa Go da go.dev/dl e assicurati che sia nel tuo PATH:

export PATH="$PATH:/usr/local/go/bin"

---

Aggiornare OpenCode

Mantieni OpenCode aggiornato per ottenere il supporto ai modelli più recenti e le correzioni di bug.

npm:

npm update -g opencode-ai

Homebrew:

brew upgrade opencode

Script Curl: Esegui nuovamente il comando di installazione:

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

Go install: Esegui nuovamente con @latest:

go install github.com/opencode-ai/opencode@latest

---

Passaggi successivi

Ora che OpenCode è installato e configurato, sei pronto per iniziare a usarlo nel tuo flusso di lavoro quotidiano.

• Impara i comandi: Consulta il nostro OpenCode Tutorial 2026 per una panoramica completa di comandi, flussi di lavoro e funzionalità avanzate.
• Configura l'integrazione GitHub: Installa l'App GitHub di OpenCode per utilizzare la revisione del codice assistita dall'AI e le risposte alle issue direttamente nei tuoi repository.
• Esplora il comando /init: Esegui /init nel tuo progetto per generare un file agents.md che fornisca a OpenCode un contesto approfondito sull'architettura della tua codebase.
• Prova molteplici provider: Configura due o tre provider e passa dall'uno all'altro per trovare quale modello funziona meglio per i tuoi compiti di programmazione.

OpenCode è uno degli strumenti AI open-source a più rapida crescita nel 2026 perché incontra gli sviluppatori dove già lavorano: il terminale. Con l'installazione che richiede meno di cinque minuti e la configurazione che necessita di una sola API key, non c'è motivo di non provarlo oggi stesso.