Installazione di OpenCode e configurazione di OmniProxy

OpenCode è un assistente di programmazione open source che permette di scrivere codice dal terminale, dall’IDE o dall’app desktop. Non conserva il codice né il contesto, quindi è adatto ai progetti che richiedono particolare attenzione alla privacy. build serve per modificare il progetto, mentre plan è in sola lettura per impostazione predefinita ed è utile per comprendere codice poco familiare e pianificare le modifiche. Puoi scegliere il servizio di modelli in base alle tue esigenze.

Preparazione prima dell’installazione

Lo script di installazione è il metodo più semplice. Ti serve un terminale moderno, ossia un’applicazione da terminale che consenta di eseguire comandi e lavorare sui file del progetto, come WezTerm, Alacritty, Ghostty o Kitty. Su Windows è preferibile usare WSL, uno strumento che esegue un ambiente Linux all’interno di Windows e offre funzionalità e prestazioni più complete.

Il modo più semplice

Script di installazione

• curl opencode.ai/install
• Usalo direttamente su macOS Linux
• Su Windows è consigliato WSL

macOS Linux

Homebrew tap

• anomalyco/tap/opencode
• Si aggiorna più spesso rispetto alla formula
• Esiste un pacchetto anche per Arch

Windows nativo

Gestore di pacchetti

• choco o scoop
• Oppure installa globalmente con npm
• Puoi anche scaricare da Releases

Prepara anche l’ID del modello presente nell’elenco corrente dei modelli. L’ID del modello è il nome utilizzato dal servizio per identificare con precisione uno specifico modello.

Installazione e primo avvio

Il comando di installazione più semplice è:

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

Puoi anche utilizzare uno dei seguenti metodi di installazione:

• Node.js: npm install -g opencode-ai. Sono disponibili anche i corrispondenti comandi di installazione globale per Bun, pnpm e Yarn; consulta la pagina introduttiva indicata alla fine della guida.
• Homebrew su macOS e Linux: brew install anomalyco/tap/opencode. Usa questo tap, perché viene aggiornato più frequentemente rispetto a brew install opencode, mantenuto dal team di Homebrew.
• Arch Linux: per la versione stabile usa sudo pacman -S opencode; per una versione più recente puoi usare il pacchetto AUR opencode-bin.
• Windows: choco install opencode oppure scoop install opencode; in alternativa, puoi usare npm install -g opencode-ai. È inoltre possibile scaricare il file binario da Releases. Il supporto per l’installazione tramite Bun su Windows è ancora in fase di sviluppo.

Accedi alla directory del progetto e avvia OpenCode:

cd /path/to/project
opencode

Al primo utilizzo puoi eseguire /init. Il comando analizza il progetto e crea AGENTS.md nella directory principale. Puoi includere questo file in Git per conservare queste istruzioni nel progetto.

Ottenere i parametri di connessione da OmniProxy

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: copia l'ID completo dall'elenco corrente dei modelli di OmniProxy

baseURL è l’indirizzo del servizio, API Key è la credenziale di accesso e Model ID è il nome completo del modello.

Quando si usa /v1/chat/completions, il pacchetto npm è @ai-sdk/openai-compatible. In questo contesto, Chat Completions è un’interfaccia per le richieste di chat. Passa a @ai-sdk/openai soltanto se il modello utilizza /v1/responses. Quando OmniProxy viene utilizzato tramite il percorso Chat Completions, mantieni il pacchetto di compatibilità.

Copia per intero l’ID del modello dall’elenco corrente di OmniProxy, conservando anche le barre. Al 2026-10-09, i due ID di riferimento erano claude-sonnet-5-5 e gpt-6-luna. gpt-6-luna supporta Chat Completions; nelle Chat Completions, la chiamata di funzioni è supportata soltanto quando reasoning_effort è impostato su none. Non copiare ID che non compaiono nell’elenco.

Inserire la configurazione dello strumento

Un Provider può essere considerato un insieme di impostazioni utilizzate da OpenCode per collegarsi a un servizio di modelli. La documentazione dei Provider definisce come Provider personalizzato un servizio compatibile con OpenAI che non compare nell’elenco di /connect. Un servizio compatibile con OpenAI usa lo stesso formato delle richieste e può essere chiamato dalla stessa categoria di client.

1. In OpenCode, esegui /connect e scorri fino a Other.
2. Inserisci un Provider ID. Nell’esempio seguente viene usato omniproxy. Scegli un ID facile da ricordare, perché dovrai utilizzare lo stesso valore nel file di configurazione.
3. Inserisci l’API Key di OmniProxy. Questo passaggio salva soltanto la credenziale; l’indirizzo e i modelli devono comunque essere aggiunti a opencode.json. La credenziale viene salvata in ~/.local/share/opencode/auth.json.
4. Crea o modifica opencode.json nella directory del progetto:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

5. Esegui /models: il Provider personalizzato e i relativi modelli compariranno nell’elenco.

L’ID inserito in /connect deve corrispondere alla chiave presente in opencode.json. Non inserire la chiave reale in questo file. Se non usi /connect, puoi anche specificare una variabile d’ambiente in options.apiKey, ad esempio {env:nome_variabile}. Nei test del 2026-10-09 con OpenCode 1.18.34, la connessione ha funzionato anche inserendo direttamente la chiave in options.apiKey del progetto, senza passare da /connect. Se il gateway non verifica la chiave, questo valore può essere una stringa segnaposto utilizzata soltanto in locale. Le chiavi in models devono contenere gli ID completi presenti nell’elenco.

Chiave

/connect

• Seleziona Other in fondo
• Imposta liberamente il Provider ID
• Viene salvato in auth.json

Progetto

opencode.json

• La chiave provider deve avere lo stesso nome
• Con npm usa un pacchetto compatibile
• baseURL termina con /v1

Selezione

/models

• Il modello compare nell'elenco
• Selezionane uno e poi fai una domanda
• L'ID deve corrispondere all'elenco del gateway

Verificare un’attività reale

Esegui innanzitutto un’attività reale nella directory del progetto. Il formato di riferimento del modello è Provider ID/ID modello; conserva le barre presenti nell’ID del modello:

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Spiega che cosa fa un file da me specificato, senza modificare alcun file."

--auto consente all’esecuzione di utilizzare strumenti come la lettura dei file. Nel test del 2026-10-09 con OpenCode 1.18.34, il contenuto del file specificato è stato letto correttamente. La prima esecuzione ha richiesto circa due minuti.

Per l’uso interattivo, esegui opencode e poi seleziona il modello tramite /models. Puoi usare @ per cercare i file. Puoi inoltre eseguire opencode auth list per verificare le credenziali registrate tramite /connect, quindi controllare nei registri delle chiamate di OmniProxy l’origine della richiesta e l’ID del modello.

Avvio

opencode si avvia

• Esegui prima cd nel progetto
• auth list mostra l'ID
• Il file di configurazione è nel progetto

Attività

Ha letto il codice

• Chiedi di un file specifico
• Leggi la sua descrizione
• Se non va bene, usa /undo

Registri

Visibile dal gateway

• La fonte è OpenCode
• L'ID del modello corrisponde
• Non eseguire il commit della chiave

Errori comuni

• OmniProxy non compare in /models: verifica che l’ID di /connect corrisponda alla chiave in opencode.json, che npm sia impostato su @ai-sdk/openai-compatible e che baseURL termini con /v1.
• La credenziale è scomparsa: esegui opencode auth list. I Provider come Bedrock, che si basano su variabili d’ambiente, non compaiono in questo elenco; un Provider personalizzato configurato tramite /connect dovrebbe invece essere visibile.
• Le funzionalità su Windows sono incomplete: usa lo script di installazione all’interno di WSL.
• L’ID del modello non è valido: copialo nuovamente dall’elenco corrente di OmniProxy e aggiorna la relativa chiave in models.
• La richiesta usa l’interfaccia errata: per Chat Completions mantieni @ai-sdk/openai-compatible. Non cambiare pacchetto per usare l’interfaccia Responses, a meno che quello specifico modello su OmniProxy utilizzi effettivamente /v1/responses.

Riferimenti ufficiali

Per l’installazione, consulta Introduzione a OpenCode. Per i Provider personalizzati, consulta Providers. Gli ID dei modelli usati negli esempi sono disponibili in Panoramica dei modelli Claude e GPT-6 Luna.

Sostituisci ogni segnaposto con valori dalla tua configurazione OmniProxy personale. Non pubblicare mai una chiave reale.

Un risultato salvato o HTTP 200 da soli non provano la piena compatibilità con l'Agente. Controlla l'origine e il modello nel registro delle chiamate di OmniProxy.

Fonti ufficiali · OpenCode ↗