OpenCode Quickstart: installazione, configurazione e utilizzo dell’agente AI di coding per terminale

Come installare, configurare e utilizzare OpenCode

Indice

OpenCode è un agente di coding AI open source che puoi eseguire nel terminale (TUI + CLI), con interfacce desktop e IDE opzionali. Questa è la Guida rapida di OpenCode: installazione, verifica, connessione a un modello/provider ed esecuzione di flussi di lavoro reali (CLI + API).

Nota sulla versione: OpenCode viene rilasciato con rapidità. I comandi “più recenti” qui riportati sono stabili, ma l’output e i valori predefiniti possono cambiare: verifica sempre la documentazione ufficiale della CLI e il changelog (collegati di seguito).

Questo articolo fa parte di Strumenti per sviluppatori AI: La guida completa allo sviluppo potenziato dall’AI. Se mantieni anche un assistente self-hosted come Nous Hermes, la scheda di riferimento rapido per Hermes Agent CLI mappa il set di comandi hermes accanto a questa guida rapida di OpenCode.

Cos’è OpenCode (e dove si posiziona)

OpenCode è progettato per il coding agenziale orientato al terminale, mantenendo al contempo flessibilità su provider/modelli. In pratica, è un livello di workflow che può:

  • avviare un’interfaccia utente del terminale (TUI) quando esegui opencode
  • eseguire prompt “one-shot” non interattivi tramite opencode run (script/automazione)
  • esporre un server HTTP headless tramite opencode serve (e un’interfaccia web tramite opencode web)
  • essere controllato programmaticamente tramite l’SDK ufficiale JS/TS @opencode-ai/sdk

Se desideri confrontarlo con un altro assistente agenziale open source in grado di eseguire piani multi-step in un ambiente sandbox, consulta la Guida rapida per l’assistente di coding OpenHands.

Per l’agente orientato al terminale di Anthropic con la stessa storia di “modello locale via HTTP” (Ollama o llama.cpp, permessi, prezzi), consulta Installazione e configurazione di Claude Code per Ollama, llama.cpp, prezzi.

Per un approccio deliberatamente minimale alla stessa idea di agente terminale — quattro strumenti predefiniti, nessun sandbox integrato, tutto il resto tramite estensioni — consulta la recensione di Pi Coding Agent.

opencode con LLM self-hosted qwen3.5 27b

Prerequisiti

Ti serviranno:

  • Un emulatore di terminale moderno (importante per l’esperienza TUI).
  • Accesso ad almeno un modello/provider (chiavi API o autenticazione tramite abbonamento, a seconda del provider). Le opzioni locali come Ollama o llama.cpp funzionano senza chiavi API se esegui un server compatibile localmente.

Installare OpenCode (copia-incolla)

Script di installazione ufficiale (Linux/macOS/WSL):

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

Opzioni di gestione dei pacchetti (esempi ufficiali):

# Installazione globale Node.js
npm install -g opencode-ai

# Homebrew (consigliato da OpenCode per le release più aggiornate)
brew install anomalyco/tap/opencode

# Arch Linux (stabile)
sudo pacman -S opencode

# Arch Linux (ultimo da AUR)
paru -S opencode-bin

Note per Windows (le linee guida ufficiali raccomandano comunemente WSL per la migliore compatibilità). Le alternative includono Scoop/Chocolatey o npm.

# chocolatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (utile per una prova rapida):

docker run -it --rm ghcr.io/anomalyco/opencode

Verifica dell’installazione

opencode --version
opencode --help

Formato dell’output atteso (varia in base alla versione):

# Esempio:
# <stampa un numero di versione, es. vX.Y.Z>
# <stampa l'aiuto con i comandi/sottocomandi disponibili>

Collegare un provider (due percorsi pratici)

Percorso A: /connect TUI (interattivo)

Avvia OpenCode:

opencode

Poi esegui:

/connect

Segui i passaggi dell’interfaccia per selezionare un provider e autenticarti (alcuni flussi aprono un browser o un login dispositivo).

Percorso B: CLI opencode auth login (chiavi del provider)

OpenCode supporta la configurazione dei provider tramite:

opencode auth login

Note:

  • Le credenziali vengono salvate in ~/.local/share/opencode/auth.json.
  • OpenCode può anche caricare le chiavi da variabili d’ambiente o da un file .env nel tuo progetto.

Hosting LLM locale (Ollama, llama.cpp)

OpenCode funziona con qualsiasi API compatibile con OpenAI. Per lo sviluppo locale, molti utenti eseguono Ollama e puntano OpenCode su di essa. Recentemente ho avuto un’esperienza molto buona configurando ed eseguendo OpenCode con llama.cpp}), invece: llama-server espone endpoint compatibili con OpenAI, quindi puoi utilizzare modelli GGUF con lo stesso workflow. Se preferisci un controllo fine sulla memoria e sul runtime, o desideri uno stack più leggero senza Python (tra l’altro, ollama è implementato in Go), llama.cpp vale la pena provarlo. Ho apprezzato molto l’opportunità di configurare i livelli offloadati, la facilità d’uso dei modelli in formato GGUF e la compatibilità molto migliore/più veloce implementata con i nuovi modelli, come Qwen3.5. Se vuoi sapere quali modelli funzionano effettivamente bene all’interno di OpenCode — in termini di task di coding e accuratezza dell’output strutturato — consulta il mio confronto pratico LLM per OpenCode.

Inizializzare correttamente un progetto (primo avvio consigliato)

Dal tuo repository:

cd /path/to/your/repo
opencode

Poi inizializza:

/init

Questo analizza il tuo progetto e crea un file AGENTS.md nella radice del progetto. Di solito vale la pena commitare questo file in modo che OpenCode (e i colleghi) condividano un contesto del progetto coerente.

Workflow CLI principali (esempi copia-incolla)

OpenCode supporta esecuzioni non interattive:

opencode run "Spiega come funzionano le closure in JavaScript"

Per i pattern di workflow da riga di comando — piping dell’output di git, target Makefile e CI, politiche di permesso per esecuzioni non presidiate — e le modalità di errore attese, consulta la [guida pratica CLI di OpenCode](https://www.glukhov.org/it/ai-devtools/opencode/opencode-cli-in-practice/ “Una guida pratica a OpenCode dalla riga di comando: opencode run, scripting, automazione CI, agenti, permessi, modelli locali e reali modalità di fallimento.”}. Si basa su questa guida rapida senza ripeterla.

Workflow: generare codice (CLI)

Obiettivo: generare una piccola funzione testabile con un contesto minimo.

opencode run "Scrivi una funzione Go ParsePort(envVar string, defaultPort int) (int, error). Deve leggere la variabile d'ambiente, analizzare un int, validare 1-65535 e restituire defaultPort se vuota. Includi 3 test basati su tabelle."

Output atteso:

  • Una spiegazione più blocchi di codice (funzione + test). Il codice esatto varia in base al modello/provider e al prompt.

Workflow: rifattorizzare un file in sicurezza (CLI + agente Plan)

Obiettivo: confermare che l’agente più restrittivo plan venga eseguito prima di affidarsi ad esso.

opencode run --agent plan --file ./src/auth.ts \
  "Rifattorizza questo file per ridurre la complessità. Output solo un piano breve. Non eseguire comandi."

Output atteso: una sezione di piano, nessuna modifica ai file, nessun comando eseguito.

Workflow: fare domande sul repository (CLI)

Obiettivo: confermare che l’agente explore possa localizzare i dettagli di implementazione.

opencode run --agent explore \
  "Dove viene convalidata l'autenticazione per le richieste API in questo repository?"

Output atteso: una breve mappa dei percorsi dei file e una descrizione del flusso.

Entrambi questi sono test di fumo one-shot. Per la versione di produzione vincolata degli stessi task — output esplicito di rischi/casi limite, patch unified-diff, prompt di esplorazione consapevoli dei permessi e cosa fare quando il modello non si adegua — consulta la sezione “Migliori casi d’uso della CLI di OpenCode” della [guida pratica CLI di OpenCode](https://www.glukhov.org/it/ai-devtools/opencode/opencode-cli-in-practice/ “Una guida pratica a OpenCode dalla riga di comando: opencode run, scripting, automazione CI, agenti, permessi, modelli locali e reali modalità di fallimento.”}.

Workflow: accelerare le esecuzioni CLI ripetute con un server persistente

Se stai scriptizzando o eseguendo più chiamate a opencode run, puoi avviare un server headless una volta:

Terminale 1:

opencode serve --port 4096 --hostname 127.0.0.1

Terminale 2:

opencode run --attach http://localhost:4096 "Riassumi la struttura del repository e i principali entrypoint."
opencode run --attach http://localhost:4096 "Ora proponi 3 rifattorizzazioni ad alto impatto e il motivo."

Output atteso:

  • Stesso come opencode run, ma di solito con meno overhead di avvio ripetuto.

Utilizzo programmatico (SDK ufficiale JS/TS)

OpenCode espone un server HTTP (OpenAPI) e fornisce un client JS/TS type-safe.

Installazione:

npm install @opencode-ai/sdk

Esempio: avviare server + client, poi prompt

Crea scripts/opencode-sdk-demo.mjs:

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // Il formato della stringa del modello è provider/modello (solo esempio)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Server in esecuzione a: ${opencode.server.url}`);

// Verifica di base di salute/versione
const health = await opencode.client.global.health();
console.log("Sano:", health.data.healthy, "Versione:", health.data.version);

// Crea una sessione e un prompt
const session = await opencode.client.session.create({ body: { title: "Demo guida rapida SDK" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Genera una piccola sezione di README che descrive questo repository." }],
  },
});

console.log(result.data);

// Chiudi il server quando hai finito
opencode.server.close();

Esecuzione:

node scripts/opencode-sdk-demo.mjs

Formato dell’output atteso:

  • “Server in esecuzione a …”
  • Una risposta di salute che include una stringa di versione
  • Un oggetto di risposta del prompt della sessione (la struttura esatta dipende da responseStyle e versione SDK)

Configurazione minima di OpenCode che puoi copiare

OpenCode supporta configurazioni JSON e JSONC. Questo è un punto di partenza ragionevole per una configurazione locale del progetto.

Crea opencode.jsonc nella radice del tuo repository:

{
  "$schema": "https://opencode.ai/config.json",

  // Scegli un modello predefinito (provider/modello). Mantienilo in linea con ciò che mostra `opencode models`.
  "model": "provider/modello",

  // Opzionale: un "piccolo modello" più economico per task leggeri (titoli, ecc.)
  "small_model": "provider/piccolo-modello",

  // Opzionale: valori predefiniti del server OpenCode (usati da serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // Opzionale sicurezza: richiede conferma prima di modifiche/comandi
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Per una politica di permessi più completa mirata a lavori non presidiati di opencode run, consulta la [guida pratica CLI di OpenCode](https://www.glukhov.org/it/ai-devtools/opencode/opencode-cli-in-practice/ “Una guida pratica a OpenCode dalla riga di comando: opencode run, scripting, automazione CI, agenti, permessi, modelli locali e reali modalità di fallimento.”}.

Breve scheda di riferimento (riferimento rapido)

Comandi che userai quotidianamente

opencode                       # avvia TUI
opencode run "..."             # esecuzione non interattiva (automazione)
opencode run --file path "..." # allega file al prompt
opencode models --refresh      # aggiorna l'elenco dei modelli
opencode auth login            # configura le credenziali del provider
opencode serve                 # server HTTP headless (OpenAPI)
opencode web                   # server headless + interfaccia web
opencode session list          # elenca le sessioni
opencode stats                 # statistiche token/costo

Comandi TUI da memorizzare

/connect   # collega un provider
/init      # analizza il repository, genera AGENTS.md
/share     # condivide una sessione (se abilitato)
/undo      # annulla una modifica
/redo      # ripristina una modifica
/help      # aiuto/scorciatoie

Concetto di “tasto leader” predefinito (TUI)

OpenCode utilizza un tasto “leader” configurabile (comunemente ctrl+x) per evitare conflitti con il terminale. Molte scorciatoie sono “Leader + tasto”.

Tabella della scheda di riferimento di OpenCode su una pagina

Questa versione è intenzionalmente densa e “adatta alla stampa”. (Puoi incollarla in seguito in una pagina dedicata /ai-devtools/opencode/cheatsheet/.)

Compito Comando / scorciatoia Note
Avvia TUI opencode Il comportamento predefinito è avviare l’interfaccia del terminale
Esegui prompt one-shot opencode run "..." Modalità non interattiva per scripting/automazione
Allega file al prompt opencode run --file path/to/file "..." Usa più flag --file per più file
Scegli modello per un’esecuzione opencode run --model provider/modello "..." Le stringhe dei modelli sono provider/modello
Scegli agente opencode run --agent plan "..." Plan è progettato per lavori più sicuri “senza modifiche” (permessi limitati)
Elenca modelli opencode models [provider] Usa --refresh per aggiornare l’elenco in cache
Configura credenziali provider opencode auth login Salva le credenziali in ~/.local/share/opencode/auth.json
Elenca provider autenticati opencode auth list / opencode auth ls Conferma ciò che vede OpenCode
Avvia server headless opencode serve --port 4096 --hostname 127.0.0.1 Specifica OpenAPI a http://host:port/doc
Allega esecuzioni al server opencode run --attach http://localhost:4096 "..." Utile per evitare riavvii a freddo ripetuti
Abilita autenticazione di base OPENCODE_SERVER_PASSWORD=... opencode serve Il nome utente predefinito è opencode a meno che non venga sovrascritto
Modalità interfaccia web opencode web Avvia il server + apre il browser
Esporta una sessione opencode export [sessionID] Utile per archiviare o condividere il contesto
Importa una sessione opencode import session.json Può anche importare da un URL di condivisione
Visualizza flag globali CLI opencode --help / opencode --version --print-logs + --log-level per il debug
Concetto di tasto leader TUI tasto leader predefinito spesso ctrl+x Personalizzabile in tui.json

Oh My Opencode — porta OpenCode oltre con l’orchestrazione multi-agente

Una volta che OpenCode è in esecuzione, il passo successivo naturale è Oh My Opencode — un plugin della community che avvolge OpenCode in un’impalcatura multi-agente. L’idea principale: digita ultrawork (o ulw) in una sessione e un orchestratore (Sisyphus) prende il controllo, delegando sotto-task ad agenti specializzati che vengono eseguiti in parallelo, ciascuno sulla famiglia di modelli per cui i suoi prompt sono ottimizzati.

Tre articoli lo coprono in dettaglio:

OpenCode è stato uno dei primi strumenti colpiti dalla politica di Anthropic di bloccare l’accesso ai servizi di abbonamento Claude di terze parti — una mossa fatta a gennaio 2026, un mese prima che la stessa restrizione colpisse OpenClaw. La cronologia dell’ascesa e della caduta di OpenClaw documenta entrambi gli eventi e il pattern più ampio che rappresentano per gli strumenti di agenti basati su calcolo in abbonamento.

Fonti (ufficiali prima di tutto)

Ufficiali:

Riferimento di integrazione autorevole:

Confronti/tutorial affidabili:

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.