OpenCode Quickstart: installare, configurare e utilizzare l’agente AI di coding per il terminale

Come installare, configurare e utilizzare OpenCode

Indice

OpenCode è un agente di coding AI open source che puoi eseguire nel terminale (TUI + CLI) con superfici desktop e IDE opzionali. Questa è la Guida Rapida OpenCode: installazione, verifica, connessione a un modello/provider 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 variare: 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. Se mantieni anche un assistente self-hosted come Nous Hermes, la scheda rapida della CLI Hermes Agent mappava il set di comandi hermes accanto a questa guida rapida di OpenCode.

Cos’è OpenCode (e dove si inserisce)

OpenCode è progettato per il coding agentico prioritario per terminale, rimanendo flessibile su provider/modelli. In pratica, è un layer di flusso di lavoro che può:

  • avviare un’interfaccia utente terminale (TUI) 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 programmaticamente tramite l’SDK ufficiale JS/TS @opencode-ai/sdk

Se vuoi confrontarlo con un altro assistente agentico open source in grado di eseguire piani multi-step in un ambiente sandbox, consulta la Guida Rapida CLI OpenHands.

Per l’agente prioritario per terminale di Anthropic con la stessa storia del “modello locale via HTTP” (Ollama o llama.cpp, autorizzazioni, prezzi), consulta la Guida all’installazione e configurazione di Claude Code per Ollama, llama.cpp e prezzi.

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

opencode con LLM qwen3.5 27b self-hosted

Prerequisiti

Avrai bisogno di:

  • Un’emulazione di terminale moderna (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 localmente un server compatibile.

Installare OpenCode (copia-incolla)

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

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

Opzioni del package manager (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 (più recente da AUR)
paru -S opencode-bin

Note su Windows (la guida ufficiale raccomanda 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 tentativo rapido):

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

Verificare l’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 comandi/sottocomandi disponibili>

Collegare un provider (due percorsi pratici)

Percorso A: TUI /connect (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 del dispositivo).

Percorso B: CLI opencode auth login (chiavi provider)

OpenCode supporta la configurazione dei provider tramite:

opencode auth login

Note:

  • Le credenziali sono salvate in ~/.local/share/opencode/auth.json.
  • OpenCode può anche caricare le chiavi da variabili di 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 verso di essa. Di recente ho avuto un’esperienza molto buona nella configurazione ed esecuzione di OpenCode con llama.cpp} invece—llama-server espone endpoint compatibili con OpenAI, quindi puoi usare modelli GGUF con lo stesso flusso di lavoro. Se preferisci un controllo dettagliato su memoria e runtime, o vuoi uno stack più leggero senza Python (tra l’altro, Ollama è implementato in Go), vale la pena provare llama.cpp. Ho apprezzato molto l’opportunità di configurare i livelli offload, la facilità d’uso dei modelli in formato GGUF e la compatibilità molto migliore/veloce implementata con nuovi modelli, come Qwen3.5. Se vuoi sapere quali modelli prestano effettivamente bene all’interno di OpenCode — nei task di coding e nell’accuratezza dell’output strutturato — consulta il mio confronto pratico dei LLM per OpenCode.

Inizia un progetto correttamente (prima esecuzione consigliata)

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. Vale tipicamente la pena commitare questo file in modo che OpenCode (e i colleghi di team) condividano un contesto di progetto coerente.

Flussi di lavoro CLI core (esempi copia-incolla)

OpenCode supporta esecuzioni non interattive:

opencode run "Spiega come funzionano le closure in JavaScript"

Per i pattern di flusso di lavoro della riga di comando — piping dell’output di git, target Makefile e CI, policy di autorizzazione per esecuzioni non supervisionate — e i modalità di guasto attesi, consulta la guida pratica CLI OpenCode. Si basa su questa guida rapida piuttosto che ripeterla.

Flusso di lavoro: generare 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, 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 a modello/provider e prompt.

Flusso di lavoro: refattorizzare un file in sicurezza (CLI + agente Plan)

Obiettivo: confermare che l’agente plan più restrittivo viene eseguito prima di fare affidamento su di esso.

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

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

Flusso di lavoro: fare domande sul repository (CLI)

Obiettivo: confermare che l’agente explore può localizzare i dettagli dell’implementazione.

opencode run --agent explore \
  "Dove viene validata 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 smoke one-shot. Per la versione di produzione vincolata degli stessi task — output esplicito di rischi/casi limite, patch in formato unified-diff, prompt di esplorazione consapevoli delle autorizzazioni e cosa fare quando il modello non si conforma — consulta la sezione “Migliori casi d’uso CLI OpenCode” della guida pratica CLI OpenCode.

Flusso di lavoro: accelerare 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 "Sintetizza la struttura del repository e i punti di ingresso principali."
opencode run --attach http://localhost:4096 "Ora proponi 3 refactoring ad alto impatto e perché."

Output atteso:

  • Lo stesso di opencode run, ma in genere con meno sovraccarichi 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, quindi fare 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 stringa del modello è provider/modello (solo esempio)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

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

// Controllo 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 fai prompt
const session = await opencode.client.session.create({ body: { title: "Demo avvio rapido SDK" } });

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

console.log(result.data);

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

Esecuzione:

node scripts/opencode-sdk-demo.mjs

Formato dell’output atteso:

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

Config minimale di OpenCode da copiare

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

Crea opencode.jsonc nella radice del tuo repository:

{
  "$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 task leggeri (titoli, ecc.)
  "small_model": "provider/small-model",

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

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

Per una policy di autorizzazione più completa mirata a task opencode run non supervisionati, consulta la guida pratica CLI OpenCode.

La memoria di progetto tra le sessioni è un’installazione separata. Hindsight Memory per OpenCode, Cursor e altri agenti di coding aggiunge il plugin al file ~/.config/opencode/opencode.json a livello di utente, un file diverso dall’opencode.jsonc di progetto sopra.

Scheda rapida breve (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 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   # connetta un provider
/init      # analizza il repo, genera AGENTS.md
/share     # condividi 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 nel terminale. Molte scorciatoie sono “Leader + tasto”.

Tabella scheda rapida OpenCode per stampa su una pagina

Questa versione è deliberatamente densa e “adatta alla stampa”. (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 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ù bandiere --file per più file
Scegli modello per un’esecuzione opencode run --model provider/model "..." Le stringhe di modello sono provider/model
Scegli agente opencode run --agent plan "..." Plan è progettato per lavoro più sicuro “nessuna modifica” (limitato da autorizzazioni)
Elenco 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
Elenco 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 su http://host:port/doc
Allega esecuzioni al server opencode run --attach http://localhost:4096 "..." Utile per evitare riavvii a freddo ripetuti
Abilita auth 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 bandiere CLI globali 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 uno harness 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 girano in parallelo, ciascuno sulla famiglia di modelli per i quali 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 di terze parti all’abbonamento Claude — una mossa fatta nel gennaio 2026, un mese prima che la stessa restrizione colpisse OpenClaw. La [linea del tempo dell’ascesa e del crollo di OpenClaw](https://www.glukhov.org/it/ai-systems/openclaw/openclaw-rise-and-fall-timeline/ “Come OpenClaw è cresciuto fino a 247.000 stelle su GitHub e poi è crollato quando Anthropic ha bloccato l’accesso all’abbonamento Claude.”} documenta entrambi gli eventi e il pattern più ampio che rappresentano per gli strumenti agentici costruiti su compute in abbonamento.

Fonti (ufficiali per prime)

Ufficiali:

Riferimento di integrazione autorevole:

Confronti/tutorial affidabili:

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.