Documentazione

Oh My Pi

Oh My Pi gestisce i provider in un unico file YAML. Bastano tre righe sotto un nome a tua scelta — baseUrl, api e apiKey — e omp instrada le richieste a Claude e GPT usando un’unica chiave, mentre l’elenco dei modelli viene recuperato automaticamente anziché inserito a mano.

Un blocco provider in ~/.omp/agent/models.yml — baseUrl, api, apiKey — collega Oh My Pi a Kunavo, mentre il rilevamento compila l'elenco dei modelli da GET /v1/models.

~/.omp/agent/models.yml

providers:
  kunavo:
    baseUrl: https://api.kunavo.com/v1
    api: openai-completions
    apiKey: KUNAVO_API_KEY       # an env-var name; literal text also works
    discovery:
      type: openai-models-list   # reads GET /v1/models

# Prefer a fixed list to a discovered one? Drop the discovery block and
# declare ids instead. Omitted metadata defaults to a 128,000-token context
# window and a 16,384-token output limit, so set the real numbers from
# /models when they differ.
#
#     models:
#       - id: claude-sonnet-5
#         name: Claude Sonnet 5
#         contextWindow: ...
#         maxTokens: ...

L’URL di base mantiene il suffisso /v1. omp definisce baseUrl come «radice dell’endpoint» e openai-completions come «Chat Completions compatibili con OpenAI», mentre la sua guida alla risoluzione dei 404 afferma: «Gli URL di base OpenAI-compatible generici terminano spesso con /v1». Tutti gli esempi di provider personalizzati in entrambe le pagine terminano nello stesso modo. «Spesso» è una riserva, non una garanzia; Kunavo però serve /v1/chat/completions, quindi https://api.kunavo.com/v1 è la radice che lo raggiunge. È il contrario dei client in stile Anthropic, che richiedono la sola origine.

Su questo percorso, lascia fuori authHeader. omp lo indica per un gateway che «richiede specificamente l’inserimento di Authorization: Bearer come normale intestazione» e precisa che «i client standard dei provider applicano già il proprio schema di autenticazione», cosa che fa il client compatibile con OpenAI e che Kunavo accetta. Aggiungilo solo se riscontri un 401 che la curl qui sotto non riproduce.

Questa configurazione è stata ricavata dalla documentazione di omp alla data indicata sotto. Kunavo non ha eseguito omp sul proprio endpoint: né una sessione, né un turno in streaming, né uno scambio con strumenti, né una verifica dell’instradamento. Una pagina di configurazione pubblicata non è un test e non va interpretata come tale. La curl qui sotto è la parte che puoi verificare in dieci secondi; il resto dipende da te e da omp.

Kunavo non offre modelli di embedding, sintesi vocale o riconoscimento vocale; questo provider risponde quindi solo alle chat. Qualsiasi componente della tua configurazione che trascrive audio o crea un indice vettoriale continuerà a usare la chiave del provider già assegnata.

Non hai ancora una chiave? Crea un account Kunavo, genera una chiave (inizia con sk-kn-) e aggiungi credito da $10: le chiamate vengono pagate con quel saldo e le chiamate non riuscite non vengono addebitate. La dashboard si apre quindi sulla configurazione Oh My Pi.

Passo dopo passo

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
Esportala come KUNAVO_API_KEY nella shell da cui avvii omp. omp interpreta prima apiKey come nome di variabile di ambiente e, se non la trova, usa il testo come chiave letterale; un errore nel nome della variabile quindi non viene segnalato e si manifesta solo alla prima richiesta. Un valore che inizia con ! viene invece eseguito come comando shell: è il metodo usato con 1Password.
Inserisci il blocco qui sopra in ~/.omp/agent/models.yml. L’ID del provider, qui kunavo, lo scegli tu e diventa la prima parte di ogni selettore.
Esegui omp models kunavo per caricare il file ed elencare solo questo provider. Un errore YAML o di schema mostra models.yml validation failed e il campo non valido; omp models refresh kunavo forza una nuova chiamata di rilevamento anziché usare il catalogo memorizzato nella cache.
Provalo con un selettore esatto: omp -p --model kunavo/claude-sonnet-5 "Reply with only OK". Poi avvia omp, digita /model e assegna l’ID desiderato a Default: l’hub dei modelli ricarica models.yml all’apertura. /switch modifica solo la sessione corrente.

Verificato rispetto a La pagina dei provider di omp il 21 settembre 2026. Le impostazioni di terze parti cambiano; se il nome di un campo qui non corrisponde più a quello visualizzato, fa fede quella pagina, non questa.

Questa è la versione breve. La guida completa, con scelta del modello, costo di una sessione reale e modalità di errore, è in il confronto tra Oh My Pi e OpenCode.

Verifica prima di eseguire il debug del client

Una sola richiesta stabilisce se il problema riguarda l'endpoint, la chiave o il file di configurazione. Se restituisce JSON, lo stesso base URL e la stessa chiave funzionano in Oh My Pi.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Quale model id inserire nel campo

Ogni modello di testo è raggiungibile come model id: l'elenco aggiornato è GET /v1/models e il catalogo con i prezzi è nella pagina dei modelli. Le tariffe sono in USD per 1M di token, input / output.

ID del modello	Kunavo ingresso / uscita	Dove si inserisce in Oh My Pi
`claude-sonnet-5`	$1.40 / $7.00	il ruolo predefinito: il modello usato effettivamente dalla maggior parte delle sessioni
`claude-opus-5`	$3.50 / $17.50	il ruolo di pianificazione, per cui un piano errato costa più dei token
`claude-haiku-4-5`	$0.70 / $3.50	il ruolo smol: selezione iniziale, riepiloghi e richieste continue
`gpt-5-6-sol`	$2.00 / $12.00	un secondo parere da un’altra famiglia, con lo stesso blocco del provider

La fatturazione è per token, usando un saldo prepagato senza canone mensile: vedi billing. In presenza di contesto ripetuto, che costituisce la maggior parte di ciò che invia un editor o un client di chat, prompt caching incide sulla spesa più della scelta del modello.

Rilevamento: quale tipo scegliere e cosa compare nel selettore

omp offre sei valori discovery.type e due sembrano adatti a un gateway. In realtà, ne va usato uno solo. proxy è documentato per «un proxy misto OpenAI/Anthropic le cui righe dei modelli dichiarano supported_endpoint_types» e ricava da quel campo il protocollo di ciascun modello. GET /v1/models di Kunavo non lo pubblica, quindi con proxy ogni riga userebbe il valore api a livello di provider oppure, se non è impostato, verrebbe esclusa. openai-models-list, documentato come «endpoint GET /v1/models generico compatibile con OpenAI», è quello da usare; per questo il blocco qui sopra mantiene api: openai-completions: la regola di omp è che «ad eccezione di proxy, il rilevamento richiede api a livello di provider».

C’è una conseguenza da conoscere prima di aprire il selettore. L’elenco dei modelli Kunavo comprende l’intero catalogo abilitato, quindi il provider rilevato mostra ID di immagini, video e musica insieme a quelli per la chat; il trasporto chat non può però usarli. Kunavo pubblica context_length sulle righe dei modelli di chat, il campo che, secondo la documentazione di omp sui modelli, il rilevamento generico legge dopo max_model_len; lo omette invece dalle righe dei contenuti multimediali, che vengono quindi presentate con il valore predefinito di omp, 128,000 token, anziché con un numero effettivo. Per ottenere un selettore breve e corretto, rimuovi il blocco di rilevamento e dichiara i tre o quattro ID che usi davvero.

omp supporta anche anthropic-messages e Kunavo risponde a /v1/messages. Questa pagina non include un blocco di configurazione per questa combinazione: le due pagine citate chiariscono il formato dell’URL di base per il percorso compatibile con OpenAI, ma non spiegano come viene gestito un /v1 finale nel percorso Anthropic. Lo scopo di un blocco di configurazione è poter essere copiato e incollato. Se scegli questo percorso, disableStrictTools: true è la soluzione documentata ai problemi delle chiamate agli strumenti che restituiscono 400 su un endpoint compatibile con Anthropic.

Domande frequenti

Come si aggiunge un provider API personalizzato a Oh My Pi?

La configurazione si trova tutta in ~/.omp/agent/models.yml. Aggiungi una chiave sotto `providers:` — il nome lo scegli tu e diventa la parte del selettore che identifica il provider — e assegnale baseUrl, api e apiKey, nell’ordine usato dall’esempio «Add a custom provider» di omp. Puoi elencare i modelli a mano sotto `models:` oppure aggiungere un blocco `discovery:` e lasciare che omp li recuperi. Poi esegui `omp models <your-provider-id>` per verificare che il file sia stato caricato e seleziona un modello con `omp --model <provider>/<model-id>` o con l’hub /model durante una sessione.

L’URL base di Oh My Pi deve terminare con /v1?

Per un endpoint compatibile con OpenAI, sì. omp chiama baseUrl la radice dell’endpoint e aggiunge la route corrispondente alla famiglia api dichiarata; quindi, con `api: openai-completions`, richiede le chat completion sotto la radice specificata. Nella propria nota di risoluzione dei 404, omp afferma che gli URL di base OpenAI-compatible generici terminano spesso con /v1, e tutti gli esempi di provider personalizzati nella sua documentazione lo confermano. Kunavo serve /v1/chat/completions, quindi la radice da indicare è https://api.kunavo.com/v1: se manca /v1, si ottiene un 404 o un errore «endpoint non supportato», non un errore di autenticazione.

Dove cerca Oh My Pi la chiave API e quale valore ha la precedenza?

Un apiKey in models.yml viene risolto in tre passaggi: se il valore inizia con !, viene eseguito come comando shell e si usa il relativo stdout dopo aver rimosso gli spazi iniziali e finali; altrimenti omp cerca una variabile di ambiente con esattamente quel nome e, se non esiste, tratta il testo stesso come chiave. Quest’ultimo ripiego è insidioso: un nome di variabile scritto male viene accettato senza avvisi e causa un errore alla prima richiesta. Nell’ordine generale di precedenza, una chiave in models.yml prevale sulle credenziali OAuth salvate; omp afferma che ciò è intenzionale, quindi una chiave per un gateway non viene sostituita da un accesso upstream.

Quale tipo di rilevamento dovrebbe usare un gateway in omp?

openai-models-list, non proxy, a meno che il gateway non dichiari supported_endpoint_types su ogni riga del modello: è il campo che proxy usa per decidere se instradare un modello a /v1/messages o a /v1/chat/completions. Senza questo campo, i modelli usano come ripiego api a livello di provider oppure vengono esclusi. La route /v1/models di Kunavo non pubblica quel campo, quindi il tipo corretto è l’elenco OpenAI generico; inoltre, omp richiede un api a livello di provider per tutti i tipi di rilevamento tranne proxy. Esegui `omp models refresh <provider>` per forzare un nuovo recupero anziché usare il catalogo memorizzato nella cache.

Kunavo ha testato Oh My Pi sul proprio endpoint?

No. Il 21 settembre 2026 è stata consultata la documentazione di omp: i nomi e l’ordine dei campi, la regola di risoluzione della chiave e i tipi di rilevamento sono citati da quella documentazione; inoltre, due dettagli sono stati verificati sulla route /v1/models di Kunavo anziché essere dati per scontati. Qui non è stata avviata alcuna sessione omp su api.kunavo.com, né viene dichiarato che lo streaming, gli scambi con strumenti o l’instradamento dei modelli nel client funzionino. L’unica verifica isolata possibile è accertare che l’endpoint e la chiave funzionino; a questo serve il comando curl riportato in questa pagina.