Guida Rapida Oh My Opencode per OpenCode: Installazione, Configurazione ed Esecuzione

Installa Oh My Opencode e rilascia più velocemente.

Indice

Oh My Opencode trasforma OpenCode in un harness per la programmazione multi-agente: un orchestratore assegna il lavoro ad agenti specializzati che si eseguono in parallelo.

agenti oh my opencode con laptop e gpu

Il modello mentale più breve di cui hai bisogno: installa il plugin, quindi usa la parola chiave ultrawork (o ulw) quando hai bisogno di esecuzione multi-agente a pieno potenziale.

Questo avvio rapido copre l’installazione e la configurazione del primo giorno. Una volta operativo:

Per la catena di strumenti di coding AI più ampia, consulta la panoramica sugli strumenti per sviluppatori AI. Se preferisci un’alternativa a OpenCode sandboxata e compatibile con il browser, OpenHands adotta un approccio architettonico diverso al coding agentico.

Perché esiste Oh My Opencode

OpenCode è un agente di coding AI open source che si esegue come interfaccia a terminale e gestisce le esecuzioni CLI non interattive per scripting e automazione.

Oh My Opencode spinge questo limite molto più in alto. Aggiunge un layer completo di orchestrazione basato sull’agente “Sisyphus”, la collaborazione multi-specialista e un’integrazione degli strumenti più stretta. Il risultato è un sistema in cui compiti ingegneristici complessi — del tipo che normalmente richiederebbe di sorvegliare diversi prompt — vengono pianificati, delegati e verificati in un unico flusso di lavoro.

Due conciti emergono costantemente, quindi assicurati di padroneggiarli prima di tutto il resto:

  • Modalità Ultrawork: un cambio di flusso di lavoro attivato da parola chiave. Aggiungere ultrawork o ulw al tuo prompt attiva l’esecuzione di background parallela, l’integrazione LSP, la gestione del contesto e la decomposizione automatica dei compiti — non è solo una scelta stilistica.
  • Agenti specializzati: ruoli nominati come @oracle per l’architettura e @librarian per la ricerca e la documentazione. Puoi chiamarli esplicitamente o lasciare che l’orchestratore li instradi automaticamente.

Questo articolo usa Oh My Opencode, oh-my-opencode e Oh My OpenCode in modo intercambiabile — si riferiscono tutti allo stesso plugin nell’ecosistema OpenCode.

Prerequisiti e terminologia

Hai bisogno di OpenCode installato e funzionante prima. Consulta il nostro Avvio rapido OpenCode per imparare come installare, configurare e avviarlo.

Di default, opencode avvia l’interfaccia a terminale quando viene eseguito senza argomenti, e puoi anche usare opencode run ... per l’esecuzione non interattiva.

Oh My Opencode richiede almeno un provider configurato. OpenCode carica i provider dalle credenziali, dalle variabili d’ambiente o da un .env del progetto. Il modo più veloce per sistemarlo:

opencode auth login
opencode auth list

Le credenziali risiedono in ~/.local/share/opencode/auth.json.

Una particolarità di denominazione da conoscere in anticipo: il repository GitHub upstream è ora brandizzato come oh-my-openagent (“precedentemente oh-my-opencode”), ma il nome del plugin e del package nelle configurazioni rimane oh-my-opencode. Entrambi i nomi circolano nei post della community — sono la stessa cosa.

Avvio rapido dell’installazione

Ci sono più strade (installer CLI, clone manuale del repo, o “lascia che un agente lo installi”). La scelta giusta dipende da se desideri un flusso di installazione ripetibile o il controllo manuale completo.

Se hai Bun installato, bunx è l’equivalente di npx di Bun, progettato per eseguire pacchetti npm rapidamente senza un passaggio di installazione globale separato.

Per installare bunx su linux:

curl -fsSL https://bun.com/install | bash

Installazione automatica con OpenCode

Puoi eseguire il prompt in OpenCode e installerà Oh My Opencode automaticamente

Installa e configura oh-my-opencode seguendo le istruzioni qui:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

Ti farà alcune domande sulle tue sottoscrizioni LLM e registrerà Oh My Opencode nei plugin di OpenCode.

Percorso manuale: esegui l’installer di Oh My Opencode con bunx o npx

Installer interattivo che chiede informazioni sui tuoi provider e genera automaticamente una configurazione “ottimale”, e anche una modalità non interattiva per l’automazione e gli agenti.

Installazione interattiva:

bunx oh-my-opencode install
# o se preferisci gli strumenti npm
npx oh-my-opencode install

Installazione non interattiva (utile per script di provisionamento, immagini CI o “installazioni di agenti”):

bunx oh-my-opencode install --no-tui \
  --claude=<yes|no|max20> \
  --openai=<yes|no> \
  --gemini=<yes|no> \
  --copilot=<yes|no>

Cosa fa l’installer, a grandi linee:

  • registra il plugin nella configurazione di OpenCode
  • genera assegnazioni di modelli in base alla disponibilità del provider e alle regole di fallback
  • scrive la configurazione oh-my-opencode insieme ai file di configurazione di OpenCode

Percorso manuale: clona il repo ed esegui lo script di installazione

C’è anche un flusso manuale “umano”: clona il repo, installa le dipendenze, quindi esegui uno script di installazione che rileva la posizione della tua configurazione OpenCode, crea un backup e unisce le impostazioni.

git clone https://github.com/code-yeongyu/oh-my-opencode.git ~/.oh-my-opencode
cd ~/.oh-my-opencode
npm install
npm run install

Se lo script non riesce a trovare la tua configurazione OpenCode automaticamente, imposta esplicitamente la variabile d’ambiente del percorso della configurazione prima di rieseguire l’installer.

Checklist rapida di verifica

Dopo l’installazione, valida tre cose:

  • il tuo file di configurazione Oh My Opencode esiste in una posizione riconosciuta
  • gli agenti specializzati possono essere invocati
  • l’attivazione della parola chiave ultrawork funziona come previsto

Esempi da copiare:

# Mostra il file di configurazione del plugin (prova la posizione che corrisponde alla tua configurazione)
cat .opencode/oh-my-opencode.json
cat ~/.config/opencode/oh-my-opencode.json

# Test rapido dell'agente
opencode run "Usa @oracle per analizzare l'architettura del progetto corrente"

# Test rapido di attivazione ultrawork
opencode run "ulw elenca tutti i file di configurazione in questo progetto"

Se tutti e tre passano, sei genuinamente pronto — non solo installato.

Configurazione e tuning

Dove risiede la configurazione e come funziona la precedenza

Oh My Opencode cerca i file di configurazione in un ordine di priorità, con la configurazione a livello di progetto che prende il sopravvento su quella a livello utente. L’ordine di ricerca documentato è:

  • .opencode/oh-my-opencode.json (livello progetto, priorità più alta)
  • ~/.config/opencode/oh-my-opencode.json (livello utente su macOS e Linux)
  • %APPDATA%\opencode\oh-my-opencode.json (livello utente su Windows)

OpenCode stesso supporta anche più fonti di configurazione e le unisce invece di sostituirle, con le fonti successive che sovrascrivono quelle precedenti solo quando le chiavi confliggono. Questo è importante perché tipicamente desideri una baseline globale stabile più override per singolo repository.

Supporto JSONC per configurazioni ragionevoli

Sia OpenCode che Oh My Opencode supportano JSONC, il che significa che puoi mantenere commenti e virgole finali nei file di configurazione senza rompere il parsing. Questo è particolarmente utile per documentare perché certi limiti o modelli sono stati scelti.

La parola chiave “ultrawork” e ciò che abilita

ultrawork (o ulw) è il cambio di modalità a cui ricorri più spesso. Inseriscilo nella descrizione del tuo compito e il sistema abilita l’esecuzione parallela di background, l’integrazione LSP, la gestione del contesto e la decomposizione automatica dei compiti. Non è un suggerimento per il modello — è un trigger rigido che cambia come l’intera esecuzione è strutturata.

Concorrenza e compiti di background

Oh My Opencode espone controlli di concorrenza per l’esecuzione di background tramite sisyphus.max_concurrent_tasks.

Non inseguire una concorrenza elevata qui. Ogni piano del provider ha un limite — ad esempio, Claude Max20 si ferma a 3 compiti paralleli — e spingere oltre produce completamenti instabili e timeout difficili da debuggare. Inizia in modo conservativo e aumenta solo dopo esecuzioni pulite.

Una configurazione di concorrenza minima sembra così:

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "task_timeout": 300
  }
}

Una concorrenza di 2 è un punto di partenza sicuro per la maggior parte dei piani.

Instradamento dei modelli per agente e per categoria

Oh My Opencode è costruito sull’idea che compiti diversi beneficino di modelli diversi, quindi la configurazione supporta:

  • selezione del modello, varianti ed estensioni del prompt per agente
  • instradamento basato su categoria per lavori “veloci” vs “approfonditi”
  • modelli di fallback quando il tuo provider preferito non è disponibile

L’approfondimento sugli agenti specializzati copre il sistema completo di instradamento dei modelli in dettaglio — incluso perché certi agenti non devono essere commutati sulla famiglia di modelli sbagliata, le catene di fallback complete e come sovrascrivere in sicurezza i modelli per configurazioni auto-ospitate.

La risoluzione del modello è stratificata: la tua sovrascrittura esplicita vince, poi il fallback del provider, poi il predefinito di sistema. La catena di fallback inizia con i tuoi provider nativi e può scendere ad alternative come GitHub Copilot se non c’è altro disponibile — il che significa che un agente mal configurato è improbabile che fallisca in silenzio; userà semplicemente un modello più debole.

Una configurazione di partenza pratica che puoi adattare (consigliato JSONC):

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  // Mantieni la concorrenza conservativa finché non ti fidi dei limiti del tuo provider
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "task_timeout": 300
  },

  // Tuning degli agenti
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "openai/gpt-5.2",
      "variant": "high",
      "temperature": 0.7,
      "prompt_append": "Fornisci compromessi concisi e una raccomandazione chiara"
    },
    "librarian": {
      "enabled": true,
      "model": "google/gemini-3.1-pro"
    }
  },

  // Instradamento per categoria per query veloci vs lavori più profondi
  "categories": {
    "quick": { "model": "opencode/gpt-5-nano" },
    "visual-engineering": { "model": "google/gemini-3.1-pro" }
  }
}

Il campo $schema vale la pena essere mantenuto — sblocca l’autocompletamento nella maggior parte degli editor e intercetta i refusi nei nomi degli agenti prima di sprecare un’esecuzione su una configurazione rotta.

Integrazione MCP e hook

Oh My Opencode supporta i server MCP (Model Context Protocol) tramite un blocco di configurazione dove definisci il comando del server, gli argomenti e le variabili d’ambiente.

In pratica, il percorso più semplice è gestire gli MCP direttamente attraverso OpenCode usando il gruppo di comandi opencode mcp — gestisce l’aggiunta, l’elenco e l’autenticazione OAuth senza che tu tocchi manualmente i file di configurazione.

Esempi di workflow da copiare

I due esempi qui sotto sono intenzionalmente “a forma di repo reale”: mostrano come attivare l’orchestrazione, come indirizzare agenti specializzati e come mantenere i risultati verificabili.

Esempio: Revisione dell’architettura con Oracle e una mappa del repo

Usa questo quando ti unisci a una nuova codebase o erediti un servizio e hai bisogno di una visione rapida e azionabile dell’architettura. Oracle è uno specialista in sola lettura — non può apportare modifiche, solo consigliare.

Eseguilo dalla radice del tuo progetto:

opencode

OpenCode avvierà la sua interfaccia a terminale di default quando lanciato senza argomenti.

Poi chiedi a Oracle di produrre un’analisi dell’architettura e un piano concreto di refactoring o modularizzazione:

Usa @oracle per analizzare l'architettura di questo repository.
Identifica i contesti delimitati chiave, i principali spigoli di dipendenza e i componenti a più alto rischio.
Concludi con un piano di refactoring che possa essere eseguito in piccole PR.

Per la registrazione o lo scripting, salta completamente la TUI e usa opencode run:

opencode run "Usa @oracle per analizzare l'architettura di questo repository e proporre un piano di refactoring a tappe"

opencode run passa il prompt direttamente ed esce quando ha finito — esattamente ciò che vuoi per i passaggi CI o le pipeline di automazione.

Esempio: Implementazione completa di funzionalità con orchestrazione ultrawork

Usa questo quando hai bisogno di una funzionalità che tocca più file o livelli, o quando vuoi abilitare automaticamente i compiti di background e gli agenti specializzati.

Inizia con un prompt ultrawork:

opencode run "ultrawork implementa un nuovo endpoint /health con controlli di readiness e liveness, aggiungi test, aggiorna la documentazione e verifica che si esegua localmente"

La parola chiave ultrawork attiva tutti gli agenti specializzati configurati, il parallelismo dei compiti di background e gli strumenti più profondi in un colpo solo. Non hai bisogno di prompt separati per pianificazione, implementazione e test.

Quando usi ultrawork, puoi ancora dirigere esplicitamente il comportamento degli agenti. Ad esempio, potresti forzare prima la progettazione dell’architettura:

opencode run "ultrawork chiedi a @oracle di progettare prima il contratto dell'endpoint e le dipendenze, quindi implementa con modifiche minime e aggiungi test"

Combinare ultrawork con menzioni esplicite di agenti come @oracle è il punto dolce: ottieni l’orchestrazione completa ma mantieni il controllo su quale specialista gestisce le decisioni di progettazione critiche.

Una cosa da fare bene per compiti ultrawork più grandi: mantieni la concorrenza entro i limiti del tuo provider. Inizia a 2, esegui alcuni compiti in modo pulito, poi decidi se aumentare. Spingere oltre il soffitto del tuo piano non rende le cose più veloci — le rende inaffidabili.

Risoluzione dei problemi e migliori pratiche

La parola chiave Ultrawork non si attiva

Se ulw o ultrawork vengono ignorati, trattalo come un segnale per controllare il caricamento del plugin e la compatibilità della versione. C’è stata almeno una regressione riportata in cui il rilevamento della parola chiave non ha iniettato il prompt della modalità ultrawork previsto, con l’indagine che puntava all’hook dedicato al rilevamento delle parole chiave.

In pratica, le correzioni più rapide sono:

  • conferma che il plugin è registrato e i file di configurazione sono presenti (vedi la checklist di verifica precedente)
  • aggiorna OpenCode o il plugin se sei su una versione nota per regredire nel rilevamento delle parole chiave

Lo script di installazione non può trovare la tua configurazione OpenCode

Verifica che OpenCode sia installato (opencode --version), quindi imposta esplicitamente la variabile d’ambiente del percorso della configurazione prima di rieseguire l’installer.

Troppi compiti di background o problemi di throttling

Se incontri limiti di velocità, timeout o completamenti instabili, la correzione è sempre la stessa: riduci la concorrenza e riesegui. Inseguire un parallelismo più elevato quando il tuo provider ti sta già throttling è una battaglia persa.

Quando non dovresti usare ultrawork

Ultrawork è potente, ma non è gratuito — ogni agente parallelo costa token e conta contro i tuoi limiti di velocità. Riservalo per grandi refactoring, lavori di funzionalità full-stack e compiti complessi multi-step. Per una piccola modifica a singolo file o una domanda veloce, un prompt normale è più veloce ed economico.

Una regola empirica solida:

  • usa prompt normali per piccole modifiche e domande semplici
  • usa ultrawork quando vuoi che il sistema decomponga, deleghi, esegua e verifichi attraverso il repository

Nota sulla conformità per i termini del provider

Alcune discussioni della community su questo ecosistema toccano restrizioni dei provider e termini di servizio, in particolare riguardo a OAuth di terze parti e layer di compatibilità. Questi sono vincoli reali — rivedi i termini del tuo provider prima di eseguire workflow automatizzati o paralleli su larga scala, e non dare per scontato che un’integrazione funzionante significhi che è permessa.

Pronto ad approfondire? L’approfondimento sugli agenti specializzati spiega il ruolo di ogni agente, i requisiti del modello e le opzioni di auto-ospitare. Per dati onesti sulle prestazioni e rischi di fatturazione riportati dalla community, consulta l’articolo sull’esperienza Oh My Opencode.