OpenCode Quickstart: Installa, configura e utilizza l'agente AI per la codifica del terminale

Come installare, configurare e utilizzare OpenCode

Indice

OpenCode è un agente AI open source che puoi eseguire nel terminale (TUI + CLI) con superfici opzionali per desktop e IDE. Questo è il Quickstart di OpenCode: installa, verifica, collega un modello/fornitore e esegui workflow reali (CLI + API).

Nota sulla versione: OpenCode si aggiorna rapidamente. I comandi “latest” qui sono stabili, ma l’output e le impostazioni predefinite possono cambiare — verifica sempre le documentazioni ufficiali del CLI e il changelog (vedi i collegamenti qui sotto).

Questo articolo fa parte di Strumenti AI per sviluppatori: La guida completa agli strumenti AI per lo sviluppo.

Cosa è OpenCode (e dove si colloca)

OpenCode è progettato per la codifica agente-first nel terminale, mantenendo flessibilità nei fornitori/modelli. In pratica, è uno strato di workflow che può:

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

opencode con qwen3.5 27b LLM autohostato

Se stai costruendo un cluster /ai-devtools/, OpenCode è un forte candidato per un sottocluster perché si espande naturalmente in:

  • Analisi approfondita del CLI
  • comportamento e costi dei modelli/fornitori (confronto LLM all’interno di OpenCode)
  • configurazione & agenti
  • integrazioni (GitHub/GitLab/Copilot)
  • riferimento rapido

Requisiti preliminari

Ti servirà:

  • Un emulatore di terminale moderno (importante per l’esperienza TUI).
  • Accesso ad almeno un modello/fornitore (chiavi API o autenticazione tramite abbonamento, a seconda del fornitore).

Installa OpenCode (copia-incolla)

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

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

Opzioni per gestori di pacchetti (esempi ufficiali):

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

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

# Arch Linux (stabile)
sudo pacman -S opencode

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

Note per Windows (la guida ufficiale raccomanda spesso WSL per la migliore compatibilità). Alternative includono Scoop/Chocolatey o npm.

# Chocolatey (Windows)
choco install opencode

# Scoop (Windows)
scoop install opencode

Docker (utile per un rapido test):

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

Verifica l’installazione

opencode --version
opencode --help

Forma dell’output attesa (varierà in base alla versione):

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

Connetti un fornitore (due percorsi pratici)

Percorso A: /connect nel TUI (interattivo)

Avvia OpenCode:

opencode

Poi esegui:

/connect

Segui i passaggi dell’interfaccia utente per selezionare un fornitore e autenticarti (alcuni flussi apriranno un browser o un login sul dispositivo).

Percorso B: opencode auth login nel CLI (chiavi del fornitore)

OpenCode supporta la configurazione dei fornitori tramite:

opencode auth login

Note:

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

Avvia un progetto correttamente (prima esecuzione consigliata)

Dalla tua repo:

cd /path/to/your/repo
opencode

Poi inizializza:

/init

Questo analizza il tuo progetto e crea un file AGENTS.md nella radice del progetto. È generalmente utile committare questo file in modo che OpenCode (e i colleghi) condividano un contesto del progetto coerente.

Workflow principali del CLI (esempi copia-incolla)

OpenCode supporta esecuzioni non interattive:

opencode run "Spiega come funzionano le closure in JavaScript"

Workflow: generare codice (CLI)

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

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

Output atteso:

  • Un’esplicazione più codice in blocchi (funzione + test). Il codice esatto varia in base al modello/fornitore e al prompt.

Workflow: ristrutturare un file in modo sicuro (CLI + agente Plan)

Obiettivo: ristrutturare senza modifiche accidentali utilizzando un agente più restrittivo.

opencode run --agent plan --file ./src/auth.ts \
  "Ristruttura questo file per ridurre la complessità. Output: (1) un breve piano, (2) un blocco diff unificato, (3) rischi/casi limite da testare. Non eseguire comandi."

Output atteso:

  • Una sezione piano + un blocco diff --git ... + un elenco di test.
  • Il contenuto varia. Se non produce un diff, ripromptare: “Restituisci solo un diff unificato” o “Usa il formato diff --git.”

Workflow: porre domande sul repo (CLI)

Obiettivo: localizzare dettagli di implementazione velocemente.

opencode run --agent explore \
  "In questo repository, dove viene validata l'autenticazione per le richieste API? Elencare i file probabili e spiegare il flusso. Se non si è certi, indicare cosa è stato controllato."

Output atteso:

  • Una mappa breve dei percorsi dei file + descrizione del flusso.
  • L’output dipende dalla dimensione del repo e dagli strumenti di contesto del modello/fornitore.

Workflow: velocizzare esecuzioni ripetute del CLI con un server persistente

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

Termine 1:

opencode serve --port 4096 --hostname 127.0.0.1

Termine 2:

opencode run --attach http://localhost:4096 "Riassumi la struttura del repo e gli entrypoint principali."
opencode run --attach http://localhost:4096 "Ora propone 3 ristrutturazioni ad alto impatto e perché."

Output atteso:

  • Lo stesso di opencode run, ma generalmente con meno overhead di avvio ripetuto.

Utilizzo programmabile (SDK ufficiale JS/TS)

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

Installazione:

npm install @opencode-ai/sdk

Esempio: avvia 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/model (esempio solo)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

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

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

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

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

console.log(result.data);

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

Esegui:

node scripts/opencode-sdk-demo.mjs

Forma dell’output attesa:

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

Configurazione OpenCode minima che puoi copiare

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

Crea opencode.jsonc nella radice del tuo repo:

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

  // Scegli un modello predefinito (provider/model). Mantieni questa allineata con ciò che mostra `opencode models`.
  "model": "provider/model",

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

  // Opzionale: impostazioni predefinite del server OpenCode (usate da serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

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

Riferimento rapido (tabella di cheat sheet)

Comandi che utilizzerai 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 credenziali del fornitore
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   # connetti un fornitore
/init      # analizza il repo, genera AGENTS.md
/share     # condividi una sessione (se abilitato)
/undo      # annulla un cambiamento
/redo      # ripristina un cambiamento
/help      # aiuto/shortcut

Concetto di “tasto leader” predefinito (TUI)

OpenCode utilizza un “tasto leader” configurabile (spesso ctrl+x) per evitare conflitti con il terminale. Molti shortcut sono “Leader + tasto”.

FAQ (pronto per schema)

Cosa è OpenCode?

OpenCode è un agente AI open source progettato per funzionare nel tuo terminale (TUI + CLI) con superfici aggiuntive per desktop/IDE.

OpenCode è gratuito?

Lo strumento è open source. Il costo di utilizzo dipende dal modello/fornitore che colleghi. Alcuni fornitori potrebbero offrire un’autenticazione basata su abbonamento o livelli gratuiti.

Come posso eseguire OpenCode senza aprire il TUI?

Utilizza opencode run "..." per la modalità non interattiva (utile per script/automazione).

Dove OpenCode memorizza le credenziali del fornitore?

opencode auth login memorizza le credenziali in ~/.local/share/opencode/auth.json.

OpenCode ha un API / SDK?

Sì. OpenCode può eseguire un server HTTP headless (opencode serve) con una specifica OpenAPI a /doc, e fornisce un SDK ufficiale JS/TS: @opencode-ai/sdk.

Posso utilizzare GitHub Copilot con OpenCode?

GitHub ha annunciato che Copilot supporta l’autenticazione con OpenCode tramite un’integrazione formale. La disponibilità esatta dipende dal tuo piano Copilot e dal flusso di autenticazione corrente del fornitore.

Tabella di cheat sheet OpenCode stampabile in una pagina

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

Task Comando / scorciatoia Note
Avvia TUI opencode Il comportamento predefinito è avviare l’interfaccia utente del terminale
Esegui un prompt one-shot opencode run "..." Modalità non interattiva per script/automazione
Allega file(s) al prompt opencode run --file path/to/file "..." Usa più flag --file per più file
Scegli un modello per un run opencode run --model provider/model "..." Le stringhe del modello sono provider/model
Scegli un agente opencode run --agent plan "..." Plan è progettato per lavoro “nessun cambiamento” più sicuro (restrizioni di permesso)
Elenca i modelli opencode models [provider] Usa --refresh per aggiornare l’elenco memorizzato
Configura credenziali del fornitore opencode auth login Memorizza le credenziali in ~/.local/share/opencode/auth.json
Elenca fornitori autenticati opencode auth list / opencode auth ls Conferma ciò che OpenCode vede
Avvia un server headless opencode serve --port 4096 --hostname 127.0.0.1 Specifica OpenAPI a http://host:port/doc
Collega le esecuzioni al server opencode run --attach http://localhost:4096 "..." Utile per evitare avvii ripetuti
Abilita l’autenticazione base OPENCODE_SERVER_PASSWORD=... opencode serve L’username 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 Si può anche importare da un URL di condivisione
Visualizza flag CLI globali opencode --help / opencode --version --print-logs + --log-level per il debug
Concetto di tasto leader TUI il tasto leader predefinito spesso ctrl+x Configurabile in tui.json

Fonti (ufficiali prime)

Ufficiali:

Riferimento autoritativo per le integrazioni:

Confronti e tutorial riconosciuti: