Documentazione

NextChat

Un'istanza self-hosted di NextChat raggiunge Kunavo tramite le variabili già previste per OpenAI: OPENAI_API_KEY contiene la chiave, BASE_URL l'origine e CUSTOM_MODELS gli ID. Non serve un fork né una patch.

Tre variabili d'ambiente — OPENAI_API_KEY, BASE_URL (origine senza percorso) e CUSTOM_MODELS — collegano un NextChat self-hosted a Claude e GPT tramite una sola chiave.

Variabili d'ambiente — impostazioni del progetto Vercel, docker -e oppure .env.local

CODE=your-access-password
OPENAI_API_KEY=sk-kn-...
BASE_URL=https://api.kunavo.com
HIDE_USER_API_KEY=1
CUSTOM_MODELS=-all,+claude-sonnet-5@OpenAI,+claude-opus-5@OpenAI,+claude-haiku-4-5@OpenAI,+gpt-5-6-sol@OpenAI,+gpt-5-6-terra@OpenAI

BASE_URL deve contenere l'origine senza percorsi aggiuntivi, senza /v1. La pagina della documentazione non spiega il suffisso in una frase, ma la riga dedicata al campo chiarisce il punto: il valore predefinito documentato è https://api.openai.com, non https://api.openai.com/v1. NextChat aggiunge il resto del percorso. Se aggiungi manualmente /v1, diventa /v1/v1/chat/completions: il risultato è un 404 che sembra indicare un endpoint non funzionante, anziché un errore di digitazione.

Chi detiene la chiave dipende dalla configurazione dell'istanza; non è stabilito per impostazione predefinita. Se imposti OPENAI_API_KEY, il server chiama Kunavo con la tua chiave e chiunque superi CODE spende il tuo saldo. La documentazione descrive HIDE_USER_API_KEY=1 così: «Se non vuoi che gli utenti inseriscano la propria chiave API, imposta questo valore su 1». Se invece lo lasci non impostato, ogni visitatore può inserire la propria chiave in Settings: è la configurazione adatta a un'istanza condivisa.

Il prefisso -all e il suffisso @OpenAI non compaiono nella tabella documentata, che include solo +, - e name=displayName. Derivano dal codice di raccolta dei modelli di NextChat, esaminato lo stesso giorno: -all svuota l'elenco integrato, così il selettore non propone ID che Kunavo rifiuterebbe; @OpenAI associa ogni nuovo ID al provider OpenAI, così che venga inviato a BASE_URL. Un ID scritto senza quel suffisso viene associato a un provider che porta il suo stesso nome e non segue il percorso configurato. Le maiuscole e le minuscole sono letterali.

Kunavo non offre modelli di sintesi vocale o riconoscimento vocale, quindi le funzioni vocali di NextChat qui non hanno un modello a cui rivolgersi. Lascia non impostato anche ENABLE_BALANCE_QUERY: il controllo del saldo chiama i percorsi di fatturazione della dashboard di OpenAI, che non fanno parte dell'interfaccia compatibile con OpenAI. Il saldo è disponibile su /app/billing.

Questa pagina è stata ricavata dalla documentazione di NextChat, non da una prova pratica: Kunavo non ha eseguito NextChat su questo endpoint e una pagina di configurazione pubblicata non è un test di compatibilità. Da entrambe le parti, le chat completion sono l’interfaccia documentata; tutto ciò che va oltre non è stato testato qui.

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 NextChat.

Passo dopo passo

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
Imposta OPENAI_API_KEY su quella chiave e BASE_URL su https://api.kunavo.com. In Vercel sono variabili di ambiente del progetto; in Docker sono flag -e; in locale vanno in .env.local.
Imposta CODE su una password di accesso, altrimenti chiunque trovi l’URL potrà usare il servizio mentre la spesa ricadrà sulla tua chiave.
Elenca in CUSTOM_MODELS gli ID che vuoi usare, ciascuno con il suffisso @OpenAI, iniziando con -all per escludere quelli predefiniti.
Esegui nuovamente il deployment: le variabili di ambiente vengono lette dal server, quindi un progetto Vercel richiede un nuovo deployment e un container deve essere riavviato. Modificare la variabile da solo non cambia nulla in un’istanza già in esecuzione.
Apri l’app, seleziona uno dei tuoi ID nel selettore dei modelli e invia un messaggio. Se ricevi una risposta, le tre variabili sono impostate correttamente.

Verificato rispetto a La pagina delle variabili di ambiente di NextChat 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.

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 NextChat.

# 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 NextChat
`claude-sonnet-5`	$1.40 / $7.00	la conversazione di tutti i giorni: scambi lunghi senza dover controllare il saldo
`claude-opus-5`	$3.50 / $17.50	la domanda della settimana che merita il modello più costoso
`claude-haiku-4-5`	$0.70 / $3.50	riepiloghi, rinomina delle chat e i brevi scambi che predominano in un’istanza condivisa
`gpt-5-6-sol`	$2.00 / $12.00	una seconda famiglia nello stesso selettore, con la stessa chiave
`gpt-5-6-terra`	$0.70 / $4.20	documenti lunghi incollati, per cui la finestra di contesto è la caratteristica decisiva

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.

Domande frequenti

Come si configura NextChat per usare un endpoint API personalizzato?

Imposta BASE_URL sull’origine dell’endpoint e OPENAI_API_KEY sulla chiave che ti è stata fornita, entrambe come variabili di ambiente nel deployment self-hosted. La pagina delle variabili di ambiente di NextChat indica BASE_URL come «Sovrascrivi l’URL di base delle richieste API OpenAI», quindi non serve modificare il codice: l’app continua a usare il formato OpenAI e invia le richieste a un altro indirizzo. Poi esegui nuovamente il deployment: i valori vengono letti dal server, quindi un’istanza già in esecuzione non li acquisisce.

BASE_URL di NextChat deve terminare con /v1?

No. NextChat aggiunge il segmento della versione e il percorso della route, perciò il valore predefinito documentato di BASE_URL è la sola origine https://api.openai.com, non https://api.openai.com/v1. Scrivi https://api.kunavo.com e nient’altro. Se aggiungi tu il suffisso, il percorso viene duplicato e si ottiene un 404, che è facile interpretare erroneamente come un’indisponibilità dell’endpoint.

Come si aggiunge un modello personalizzato all’elenco dei modelli di NextChat?

CUSTOM_MODELS accetta un elenco separato da virgole: + aggiunge un modello, - lo nasconde e name=displayName ne cambia il nome visualizzato. Un ID sconosciuto a NextChat viene creato al momento, quindi +claude-sonnet-5@OpenAI aggiunge quell’ID al selettore. Ci sono due dettagli da copiare esattamente: inizia l’elenco con -all per rimuovere gli ID OpenAI predefiniti, così chi ne seleziona uno non riceve un errore, e mantieni il suffisso @OpenAI affinché l’ID venga instradato tramite BASE_URL invece che verso un provider che prende il nome dal modello.

NextChat deve usare una chiave API del server o lasciare che ogni utente inserisca la propria?

Sono supportate entrambe le opzioni e la scelta dipende da chi paga. Una chiave in OPENAI_API_KEY appartiene al server, quindi ogni visitatore che supera la password CODE spende dal saldo comune: una scelta ragionevole per un’istanza privata, costosa per un link condiviso. Se lasci HIDE_USER_API_KEY non impostata, un visitatore può inserire la propria chiave in Settings e pagare per sé; impostandola su 1, quel campo viene rimosso. In entrambi i casi, la chiave non raggiunge il browser, a meno che non sia l’utente a inserirla lì.