OpenCode Quickstart: Installa, Configura e Usa l'Agente AI di Coding da 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 OpenCode: installazione, verifica, connessione a un modello/fornitore ed esecuzione di flussi di lavoro reali (CLI + API).

Nota sulla versione: OpenCode viene rilasciato rapidamente. I comandi “più recenti” qui sono stabili, ma l’output e le impostazioni predefinite possono cambiare; verifica sempre la documentazione ufficiale della CLI e il changelog (linkati di seguito).

Questo articolo fa parte di Strumenti per sviluppatori AI: La guida completa allo sviluppo potenziato dall’AI.

Cos’è OpenCode (e dove si colloca)

OpenCode è progettato per il coding agentic con priorità al terminale, mantenendo al contempo flessibilità riguardo al fornitore/modello. In pratica, è uno strato di flusso di lavoro 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 programmatically tramite l’SDK JS/TS ufficiale @opencode-ai/sdk

Se vuoi confrontarlo con un altro assistente agentic open source in grado di eseguire piani multi-step in un ambiente sandboxed, vedi Guida rapida OpenHands Coding Assistant.

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

opencode con LLM qwen3.5 27b self-hosted

Prerequisiti

Ti serviranno:

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

Installa OpenCode (copia-incolla)

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

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

Opzioni del gestore pacchetti (esempi ufficiali):

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

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

# Arch Linux (stable)
sudo pacman -S opencode

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

Note per Windows (la guida ufficiale consiglia 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 un test rapido):

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

Verifica l’installazione

opencode --version
opencode --help

Output atteso (varierà in base alla versione):

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

Connetti un fornitore (due percorsi pratici)

Percorso A: /connect TUI (interattivo)

Avvia OpenCode:

opencode

Poi esegui:

/connect

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

Percorso B: CLI opencode auth login (chiavi fornitore)

OpenCode supporta la configurazione dei fornitori tramite:

opencode auth login

Note:

  • Le credenziali vengono memorizzate 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 OpenAI. Per lo sviluppo locale, molti utenti eseguono Ollama e puntano OpenCode su di esso. Recentemente ho avuto un’esperienza molto positiva configurando ed eseguendo OpenCode con llama.cpp invece: llama-server espone endpoint compatibili OpenAI, quindi puoi usare modelli GGUF con lo stesso flusso di lavoro. Se preferisci un controllo più granulare su memoria e runtime, o vuoi uno stack più leggero senza Python (BTW, ollama è implementato in Go), llama.cpp vale la pena provarlo. Mi è piaciuto molto l’opportunità di configurare i layer offloaded, la facilità d’uso dei modelli in formato GGUF e la compatibilità molto migliore/rapida con nuovi modelli, come Qwen3.5. Se vuoi sapere quali modelli funzionano davvero bene all’interno di OpenCode — in termini di compiti di coding e accuratezza dell’output strutturato — vedi il mio confronto pratico LLM per OpenCode.

Avvia un progetto correttamente (primo avvio consigliato)

Dal tuo repo:

cd /path/to/your/repo
opencode

Poi inizializza:

/init

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

Flussi di lavoro CLI principali (esempi copia-incolla)

OpenCode supporta esecuzioni non interattive:

opencode run "Spiega come funzionano le closure in JavaScript"

Flusso di lavoro: genera codice (CLI)

Obiettivo: generare una piccola funzione testabile con contesto minimo.

opencode run "Scrivi una funzione Go ParsePort(envVar string, defaultPort int) (int, error). Dovrebbe leggere la variabile d'ambiente, parsare un int, convalidare 1-65535 e restituire defaultPort se vuota. Includi 3 test table-driven."

Output atteso:

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

Flusso di lavoro: refattorizza un file in sicurezza (CLI + Agente Plan)

Obiettivo: refattorizzare senza modifiche accidentali usando un agente più restrittivo.

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

Output atteso:

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

Flusso di lavoro: fai domande al repo (CLI)

Obiettivo: individuare i dettagli di implementazione rapidamente.

opencode run --agent explore \
  "In questo repository, dove viene validata l'autenticazione per le richieste API? Elenca i file probabili e spiega il flusso. Se non sei sicuro, dì cosa hai controllato."

Output atteso:

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

Flusso di lavoro: accelera le esecuzioni CLI ripetute con un server persistente

Se stai scriptando o eseguendo più chiamate 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 repo e i principali entrypoint."
opencode run --attach http://localhost:4096 "Ora proponi 3 refactoring ad alto impatto e perché."

Output atteso:

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

Uso programmatico (SDK JS/TS ufficiale)

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

Installa:

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

console.log(`Server running at: ${opencode.server.url}`);

// Check di base health/versione
const health = await opencode.client.global.health();
console.log("Healthy:", health.data.healthy, "Version:", health.data.version);

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

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

console.log(result.data);

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

Esegui:

node scripts/opencode-sdk-demo.mjs

Output atteso:

  • “Server running at …”
  • Una risposta health che include una stringa di versione
  • Un oggetto di risposta del prompt della sessione (la struttura esatta dipende da responseStyle e dalla versione dello SDK)

Config OpenCode minima che puoi copiare

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

Crea opencode.jsonc nella root del tuo repo:

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

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

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

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

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

Breve cheatsheet (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 lista modelli
opencode auth login            # configura credenziali fornitore
opencode serve                 # server HTTP headless (OpenAPI)
opencode web                   # server headless + interfaccia web
opencode session list          # elenca sessioni
opencode stats                 # statistiche token/costo

Comandi TUI da memorizzare

/connect   # connetti un fornitore
/init      # analizza repo, genera AGENTS.md
/share     # condividi una sessione (se abilitata)
/undo      # annulla una modifica
/redo      # ripristina una modifica
/help      # guida/scorciatoie

Concetto di “leader key” predefinita (TUI)

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

Tabella cheatsheet OpenCode stampabile in una pagina

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

Compito Comando / scorciatoia Note
Avvia TUI opencode Il comportamento predefinito è lanciare 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’execution opencode run --model provider/model "..." Le stringhe del modello sono provider/model
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 la lista cached
Configura credenziali fornitore opencode auth login Memorizza le credenziali in ~/.local/share/opencode/auth.json
Elenca fornitori autenticati opencode auth list / opencode auth ls Conferma cosa vede OpenCode
Avvia server headless opencode serve --port 4096 --hostname 127.0.0.1 Spec OpenAPI a http://host:port/doc
Allega execution al server opencode run --attach http://localhost:4096 "..." Utile per evitare avvieri a freddo ripetuti
Abilita auth di base OPENCODE_SERVER_PASSWORD=... opencode serve L’username predefinito è opencode a meno che non sia sovrascritto
Modalità Web UI opencode web Avvia server + apre browser
Esporta una sessione opencode export [sessionID] Utile per archiviare o condividere contesto
Importa una sessione opencode import session.json Puoi anche importare da un URL di condivisione
Vedi flag globali CLI opencode --help / opencode --version --print-logs + --log-level per il debugging
Concetto leader key TUI leader key predefinita spesso ctrl+x Personalizzabile in tui.json

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

Una volta che OpenCode è in esecuzione, il passo naturale successivo è 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-compiti ad agenti specialisti che eseguono in parallelo, ciascuno sulla famiglia di modelli per cui i suoi prompt sono ottimizzati.

Tre articoli lo trattano in profondità:

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

Fonti (prima ufficiali)

Ufficiali:

Riferimento di integrazione autorevole:

Confronti/tutorial reputati:

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.