omp (Oh My Pi) + JoinGonka Gateway: agente con ruoli dei modelli

Passo 1: installare omp. I metodi ufficiali dal README del progetto:

# macOS and Linux
curl -fsSL https://omp.sh/install | sh

# Homebrew
brew install can1357/tap/omp

# via Bun (requires Bun 1.3.14 or newer)
bun install -g @oh-my-pi/pi-coding-agent

# Windows (PowerShell)
irm https://omp.sh/install.ps1 | iex

Passo 2: ottenere la chiave. Registrati su gate.joingonka.ai/register, conferma l'indirizzo e crea una chiave con prefisso jg- nella sezione «Chiavi API». Una sola chiave e un solo saldo valgono per tutti i modelli della rete.

Passo 3: avviare l'installer.

npx @joingonka/setup --tool omp

L'installer chiederà la chiave — non viene passata come argomento da riga di comando, per non rimanere nella cronologia della shell — e farà quattro cose:

• registrerà il provider joingonka in ~/.omp/agent/models.yml: l'indirizzo del gateway, il protocollo openai-completions, la chiave in chiaro e tre modelli della rete con le reali finestre di contesto e i limiti di risposta; il file riceverà i permessi 600;
• imposterà il modello predefinito — modelRoles.default in ~/.omp/agent/config.yml — su DeepSeek V4 Flash, ma solo se il ruolo è vuoto o punta a un modello uscito dalla rete: non intercetta la scelta altrui, ma suggerisce come cambiarla;
• prima di scrivere farà un backup del file precedente, lasciando invariati gli altri provider, i ruoli e i commenti;
• alla fine invierà una richiesta reale al gateway e dirà chiaramente se chiave, indirizzo e modello sono stati accettati.

Un altro modello predefinito si imposta con il flag --model seguito dall'abbreviazione deepseek, glm o minimax — un modello specificato esplicitamente viene sempre scritto. Per i dotfile e i server esiste una modalità senza domande, in cui la chiave viene presa da una variabile d'ambiente:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool omp --model glm --non-interactive

L'installer tiene conto da solo delle posizioni non standard dei config: il profilo con nome (OMP_PROFILE) e la directory dell'agente spostata (PI_CODING_AGENT_DIR). Il models.json ereditato lo trasferisce in models.yml esattamente come farebbe omp stesso — i provider precedenti non andranno persi. E se accanto c'è un vecchio settings.json senza config.yml, l'installer non creerà config.yml, per evitare che omp salti la propria migrazione delle impostazioni: chiederà di avviare omp una volta e ripetere il comando.

Tutto ciò che fa l'installer si può scrivere a mano. I file sono due, e ognuno ha il suo compito: models.yml descrive provider e modelli, config.yml conserva le impostazioni — compreso quale modello ricopre quale ruolo.

# ~/.omp/agent/models.yml
providers:
  joingonka:
    baseUrl: https://gate.joingonka.ai/v1
    api: openai-completions
    apiKey: jg-your-key
    models:
      - id: deepseek-ai/DeepSeek-V4-Flash-0731
        name: DeepSeek V4 Flash (Gonka)
        input: [text]
        contextWindow: 380000
        maxTokens: 32768
        reasoning: true
      - id: zai-org/GLM-5.3-Flash
        name: GLM-5.3 Flash (Gonka)
        input: [text]
        contextWindow: 390000
        maxTokens: 8192
        reasoning: true
      - id: MiniMaxAI/MiniMax-M2.7
        name: MiniMax M2.7 (Gonka)
        input: [text]
        contextWindow: 200000
        maxTokens: 8192

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731

La chiave in chiaro è la scelta più priva di grattacapi: omp parte da qualsiasi ambiente, e per mettere al sicuro il file basta il comando chmod 600 ~/.omp/agent/models.yml. Se preferisci tenere la chiave fuori dal file, scrivi in apiKey il nome di una variabile, ad esempio JOINGONKA_API_KEY, ed esportala nella shell da cui avvii omp: è esattamente l'ordine di risoluzione della chiave descritto nella documentazione del progetto.

Il campo opzionale cost (prezzo per milione di token) serve solo a stimare il costo della sessione nell'interfaccia di omp. L'installer vi inserisce il prezzo live del gateway al momento dell'installazione; in un config scritto a mano puoi anche ometterlo — questa stima non ha alcun effetto sulla tua fattura, il consumo effettivo lo mostra la dashboard.

Il selettore del modello si scrive come provider/model-id. Il nome del provider si separa alla prima barra, quindi gli ID della rete con una barra propria si scrivono così come sono: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731. Invece di modificare config.yml puoi assegnare il ruolo dall'interfaccia — con il comando /model dentro la sessione o nella procedura guidata omp setup.

In omp il modello non viene scelto una volta per tutto, ma in base ai ruoli — questa è la principale leva di configurazione. Ruoli integrati per il dialogo: default, smol, slow, plan, commit, task, tiny, memory, advisor e vision. Non è necessario assegnarli tutti: smol e slow non specificati adottano inizialmente il modello del ruolo default, i sub-agenti senza ruolo task lavorano sul modello della sessione corrente, commit e tiny seguono smol. Una configurazione di una sola riga default è perfettamente funzionante.

Dividere i ruoli tra i modelli della rete non è per risparmiare — il prezzo di DeepSeek V4 Flash, GLM-5.3 Flash e MiniMax M2.7 è lo stesso — ma per il comportamento e la capacità: il modello di ragionamento pianifica meglio, il modello con una risposta lunga scrive meglio, e le piccole attività di background non devono stare nella stessa coda dell'attività principale.

# ~/.omp/agent/config.yml
modelRoles:
  default: joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
  slow: joingonka/zai-org/GLM-5.3-Flash
  plan: joingonka/zai-org/GLM-5.3-Flash
  tiny: joingonka/MiniMaxAI/MiniMax-M2.7

retry:
  fallbackChains:
    default:
      - joingonka/zai-org/GLM-5.3-Flash

Il blocco retry.fallbackChains è un'assicurazione per l'ora di punta: quando il modello principale risponde costantemente 429, omp trasmette il resto della mossa alla voce successiva della catena e, dopo una pausa, torna al principale. La chiave della catena può essere un ruolo, un modello specifico o l'intero provider (joingonka/*).

Per un singolo avvio il ruolo viene ridefinito tramite flag: omp --model slow avvia la sessione sul modello del ruolo slow, e --smol, --slow e --plan sostituiscono il modello del ruolo stesso. All'interno della sessione Ctrl+P scorre i modelli dei ruoli, e /model apre la scelta; nella scheda Roles lì stesso si assegnano i ruoli e i loro sostituti.

Al valore del ruolo si può aggiungere il livello di riflessione — :low, :medium, :high. Questa è la sintassi di omp, mentre come il singolo modello interpreta il livello dipende da esso stesso: GLM-5.3 Flash, ad esempio, ha un interruttore binario — i dettagli sono nella recensione del modello. E un altro dettaglio utile: i ruoli possono essere ridefiniti per un repository con un file <repo>/.omp/config.yml con lo stesso blocco modelRoles. I provider e le chiavi rimangono nella directory home, quindi la chiave non finirà nel repository.

Per prima cosa verifica che omp veda il provider:

omp models joingonka

La risposta è una tabella di tre righe con le finestre di contesto e i limiti di output da models.yml, arrotondati alle migliaia (output ridotto: omp ha anche le colonne thinking e images):

joingonka (3)
model                                context  max-out
deepseek-ai/DeepSeek-V4-Flash-0731      380K      33K
MiniMaxAI/MiniMax-M2.7                  200K     8.2K
zai-org/GLM-5.3-Flash                   390K     8.2K

Poi passa a un'esecuzione una tantum senza interfaccia. Metti in una cartella vuota un file con un errore evidente e chiedi di trovarlo:

omp -p "Read calc.py and tell me in one sentence whether it has a bug."

L'agente deve chiamare da solo lo strumento di lettura e rispondere nel merito, indicando l'espressione in cui si trova l'errore. Nella nostra esecuzione del 21 settembre 2026 questo ciclo — richiesta, chiamata allo strumento, risultato, risposta — è filato liscio sia con DeepSeek V4 Flash sia con GLM-5.3 Flash; per MiniMax M2.7 vale l'ultima riga della tabella qui sotto.

Terzo controllo, dal lato gateway: nella dashboard, alla voce «Utilizzo», la richiesta comparirà nella suddivisione «Per modello», mentre nel blocco «Per chiave» si aggiornerà l'ora dell'ultima richiesta. Se lì è vuoto, omp sta parlando con un altro provider: controlla cosa è impostato sui ruoli con il comando omp config get modelRoles.

Se qualcosa è andato storto, la diagnosi di solito si legge direttamente dal messaggio:

Uno strumento agente consuma token in modo diverso da una chat: per ogni tua frase, omp aggiunge un prompt di sistema e le descrizioni degli strumenti, e l'attività solitamente richiede diversi passaggi. Nel nostro test, anche con un solo strumento di lettura abilitato, ogni passaggio comportava circa 3,5 mila token di input; con una suite completa saranno di più. Pertanto, il prezzo per token qui è decisivo.

Tramite JoinGonka Gateway, i token costano $0.0069 per milione in entrata e $0.021 per milione in uscita: il prezzo è uguale per tutti i modelli della rete e viene prelevato in questa pagina da una fonte in tempo reale.

Le stime nella colonna di destra si basano sui prezzi di settembre 2026. Per confronto, ecco come si può generalmente pagare per i modelli in omp:

La barra di stato di omp mostra una stima del costo della sessione. Viene calcolata utilizzando il campo cost da models.yml: il programma di installazione inserisce il prezzo del gateway al momento dell'installazione, ma il prezzo in dollari nella rete fluttua con il tasso di cambio GNK, quindi la stima è indicativa. Il consumo esatto e il saldo sono disponibili nel pannello, nelle sezioni "Utilizzo" e "Fatturazione". Il motivo per cui la scelta predefinita è ricaduta su DeepSeek V4 Flash è spiegato in dettaglio nella panoramica del modello.

Modalità di approvazione. Per impostazione predefinita omp funziona in modalità yolo: approva da sé lettura, scrittura ed esecuzione dei comandi. Sul proprio progetto è comodo, sul codice altrui è un motivo per irrigidire la modalità o passare a un container:

omp config set tools.approvalMode write

In modalità write l'agente chiede il permesso solo per l'esecuzione dei comandi, in always-ask anche per la scrittura. Per una singola esecuzione lo stesso si imposta con il flag --approval-mode. È una proprietà di omp stesso: non dipende dal provider del modello.

Pi e omp sono parenti con configurazioni diverse. Le impostazioni di uno strumento non passano all'altro: directory, formati e nomi dei campi sono distinti.

Più ambienti. Un profilo con nome (omp --profile work o la variabile OMP_PROFILE) sposta tutte le impostazioni in ~/.omp/profiles/<name>/agent — comodo per separare chiavi di lavoro e personali. La directory corrente dell'agente si stampa con omp config path.

Se serve l'agente nell'editor. omp sa lavorare dentro Zed tramite il protocollo ACP — è lo stesso agente con le stesse impostazioni, non serve riconfigurare provider e ruoli.