Documentazione

LibreChat

LibreChat accetta il gateway in un blocco di librechat.yaml: quattro campi obbligatori, una variabile d'ambiente per la chiave e un riavvio. Il selettore consente poi di usare ID Claude e GPT tramite un unico nome endpoint.

LibreChat usa un gateway come blocco endpoints.custom in librechat.yaml — quattro campi obbligatori, la chiave da .env e un riavvio prima che il selettore lo mostri.

librechat.yaml

# librechat.yaml — project root, beside your .env
version: 1.3.5          # the value the documentation's own example carries

endpoints:
  custom:
    # Required: name, apiKey, baseURL, models. The name must be unique and
    # must not reuse a built-in endpoint name such as openAI or anthropic.
    - name: "Kunavo"
      apiKey: "${KUNAVO_API_KEY}"        # resolved from .env, not written here
      # Keep the /v1. LibreChat appends /chat/completions to this by default.
      baseURL: "https://api.kunavo.com/v1"
      models:
        default: ["claude-sonnet-5", "claude-haiku-4-5"]
        fetch: true                      # fills the picker from GET /v1/models
      titleConvo: true
      titleModel: "claude-haiku-4-5"         # titles are a separate call — pin a cheap id
      modelDisplayLabel: "Kunavo"

      # Optional but worth the four lines: without it LibreChat prices your
      # traffic from a table it ships. prompt/completion are USD per million
      # tokens; context is that model's own window. All three required.
      tokenConfig:
        claude-sonnet-5:
          prompt: 1.4
          completion: 7
          context: 1000000
        claude-haiku-4-5:
          prompt: 0.7
          completion: 3.5
          context: 200000

baseURL mantiene /v1. La documentazione chiarisce il punto a parole, non con un esempio: spiega che directEndpoint serve quando l'URL di base è già l'endpoint completo delle completions e che è “necessario perché l'app aggiunge ‘/chat/completions’ o ‘/completion’ a baseURL per impostazione predefinita”. Quindi https://api.kunavo.com/v1 si risolve in /v1/chat/completions, il percorso da usare, e directEndpoint resta non impostato. Entrambi gli esempi pratici del sito terminano allo stesso modo: https://api.mistral.ai/v1 e https://openrouter.ai/api/v1. Se qui usi un'origine senza suffisso, ottieni un 404, non un errore di autenticazione.

Su Docker non basta modificare il file. La pagina di avvio rapido specifica che librechat.yaml deve trovarsi nella radice del progetto, essere montato nel container API e che LibreChat deve essere riavviato prima che la modifica appaia nell'interfaccia. Se un nuovo endpoint non appare nel selettore, quasi sempre il problema è questo, non le credenziali: verifica queste ultime separatamente con il curl qui sotto.

Il registro dei consumi calcola l'addebito di LibreChat, non quello effettivo. LibreChat calcola il costo di una richiesta usando una tabella integrata, abbinata all'ID del modello; di conseguenza, un ID del gateway può essere addebitato alla tariffa di un altro modello. Il blocco tokenConfig qui sopra serve proprio a sovrascrivere tale valore. Dichiaralo per ogni ID che esponi, oppure considera il registro una stima e il saldo su /app/billing il dato effettivo.

Questa configurazione è stata ricavata dalla documentazione di LibreChat alla data riportata sotto. Kunavo non ha eseguito LibreChat sul proprio endpoint: nessuna conversazione, nessuno scambio con streaming, nessun ciclo di chiamata agli strumenti, nessuna esecuzione di Agents. Una pagina di configurazione pubblicata non è un test e non va interpretata come tale; ciò che puoi verificare in dieci secondi è il curl qui sotto. Il comportamento del client dipende da LibreChat.

Kunavo non offre modelli di embedding, sintesi vocale o riconoscimento vocale: questo endpoint gestisce solo le chat completions. È importante perché LibreChat include funzioni secondarie che richiedono altri tipi di provider: la chat sui file usa il proprio indice vettoriale tramite un'API RAG separata, con una chiave e un URL di base specifici; anche le funzioni vocali richiedono credenziali proprie. Questi servizi continuano a usare il provider già configurato; la chiave nel blocco qui sopra serve per l'endpoint personalizzato e per nient'altro in questa pagina.

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

Passo dopo passo

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
Su Docker, monta prima la configurazione: la guida introduttiva indica di copiare docker-compose.override.yml.example in docker-compose.override.yml e decommentare il volume librechat.yaml. Un'installazione bare metal non richiede questo passaggio.
Crea o modifica librechat.yaml nella radice del progetto, accanto al file .env, e aggiungi la voce endpoints.custom riportata sopra.
Inserisci la chiave in .env come KUNAVO_API_KEY=sk-kn-.... Il segnaposto ${KUNAVO_API_KEY} nel file YAML viene sostituito con il valore corrispondente, così il segreto non finisce nel file di configurazione che invii al repository.
Riavvia LibreChat, poi apri il selettore degli endpoint: Kunavo apparirà come voce separata accanto a quelli integrati. L'elenco dei modelli verrà recuperato da GET /v1/models oppure, se il recupero non riesce, verrà usato l'array models.default.
Invia un messaggio, poi verifica che il selettore dei modelli passi effettivamente da un modello all'altro: gli ID vengono risolti all'endpoint, quindi qui è normale avere un ID Claude e uno GPT sotto la stessa voce, non è un errore di configurazione.

Verificato rispetto a Riferimento dell'oggetto endpoint personalizzato di LibreChat 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 costo effettivo di LibreChat.

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

# 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 LibreChat
`claude-sonnet-5`	$1.40 / $7.00	la voce predefinita in models.default, il modello per le conversazioni di tutti i giorni
`claude-opus-5`	$3.50 / $17.50	l'ID da selezionare per un'analisi lunga, quando vale la pena dedicare un turno a una risposta migliore
`claude-haiku-4-5`	$0.70 / $3.50	il traffico di un'istanza condivisa e titleModel: LibreChat assegna un titolo a ogni conversazione con una chiamata separata
`gpt-5-6-terra`	$0.70 / $4.20	documenti lunghi incollati, per i quali la finestra di contesto è il fattore determinante

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.

Tre campi facoltativi con comportamenti diversi dietro un gateway

Tutti i dati di questa tabella provengono dallo stesso riferimento ai campi, consultato alla data indicata sopra. Descrivono la configurazione di LibreChat secondo la documentazione di LibreChat: non sono risultati di test di Kunavo e non indicano come si comporta un ID modello specifico dopo che la richiesta lascia il client.

Campo	Cosa dice il riferimento	Perché è rilevante per un gateway
`provider`	Instrada un endpoint personalizzato tramite un client provider nativo. Attualmente è supportato il valore Anthropic.	Cambia il protocollo di comunicazione, non il fornitore: lo stesso blocco può usare Anthropic Messages anziché chat completions. In questo percorso non viene usato il recupero dei modelli in stile OpenAI, quindi inserisci esplicitamente gli ID in models.default.
`models.fetch`	Se impostato su true, tenta di recuperare un elenco di modelli dall'API e può rallentare il primo utilizzo se la risposta tarda ad arrivare.	Kunavo risponde a GET /v1/models, quindi il selettore si popola da solo. models.default è il valore di riserva se la chiamata non riesce: per questo conviene compilarlo anche quando il recupero automatico è attivo.
`tokenConfig`	Definisce le finestre di contesto specifiche per modello e le tariffe per milione di token, per il monitoraggio dei costi e il calcolo dei consumi.	Senza questo blocco, il registro calcola il costo del traffico usando la tabella integrata di LibreChat, abbinandola a un ID per cui non è stata creata. Con il blocco, l'interfaccia mostra i valori che hai impostato.

La guida in quattro passaggi — montare, configurare, impostare la variabile d'ambiente e riavviare — è nella guida introduttiva di LibreChat per gli endpoint personalizzati, che usa un gateway come esempio pratico.

Domande frequenti

Come aggiungo un endpoint personalizzato a LibreChat?

Crea librechat.yaml nella radice del progetto, accanto al file .env, e aggiungi una voce sotto endpoints.custom con i quattro campi obbligatori: name, apiKey, baseURL e models. Il nome deve essere univoco e non può coincidere con quello di un endpoint integrato, come openAI o anthropic. Inserisci la credenziale in .env e richiamala nel file YAML come ${YOUR_ENV_VAR}, poi riavvia. Su Docker, il file deve anche essere montato nel container API tramite docker-compose.override.yml; la nuova voce apparirà nel selettore degli endpoint solo dopo il riavvio.

L'URL base di LibreChat deve terminare con /v1?

Sì, per un gateway compatibile con OpenAI. Il riferimento ufficiale dei campi di LibreChat spiega che l'opzione directEndpoint serve quando l'URL di base è già l'endpoint completo delle completions, perché per impostazione predefinita l'app aggiunge /chat/completions o /completion a baseURL. L'URL di base deve quindi essere la radice API con il suffisso /v1 — https://api.kunavo.com/v1 — e directEndpoint deve restare non impostato. I due esempi sul sito di LibreChat seguono la stessa struttura. Un valore errato produce un 404 anziché un errore di autenticazione, così puoi distinguerlo da una chiave non valida.

Perché i costi riportati da LibreChat non corrispondono a quelli addebitati dal provider?

Perché LibreChat calcola il costo di una richiesta usando una tabella dei prezzi integrata, anziché l'importo addebitato dal provider, e abbina la tariffa all'ID del modello. Se l'ID del gateway assomiglia a una voce della tabella, il costo viene calcolato alla tariffa di quella voce; se non corrisponde a nessuna voce, viene applicata una tariffa fissa. Per risolvere, aggiungi un blocco tokenConfig sotto l'endpoint personalizzato, specificando prompt, completion e context per ogni ID esposto, in USD per milione di token. LibreChat controlla questa sovrascrittura prima di consultare la propria tabella. Considera il registro nell'app una stima e il saldo presso il provider il dato effettivo.

LibreChat può usare modelli Claude tramite un endpoint personalizzato?

Sì, in due modi. Un endpoint personalizzato standard compatibile con OpenAI inoltra l'ID del modello direttamente al tuo URL di base, quindi un ID Claude viene risolto a quell'endpoint, non all'interno di LibreChat, e non serve un account Anthropic. In alternativa, il campo provider instrada lo stesso blocco tramite il client nativo Anthropic Messages di LibreChat: al momento il valore supportato è anthropic. In questo percorso non viene usato il recupero dei modelli in stile OpenAI; inserisci gli ID desiderati in models.default anziché affidarti al recupero automatico.

Kunavo ha testato LibreChat?

No. La configurazione in questa pagina è trascritta dalla documentazione ufficiale di LibreChat sugli endpoint personalizzati alla data indicata; nessuna parte è il risultato di un'esecuzione: nessuna conversazione, nessuno scambio con streaming, nessun ciclo di chiamata agli strumenti, nessuna esecuzione di Agents. Questo vale per ogni client documentato qui: una pagina di configurazione pubblicata non è un test. Puoi verificare autonomamente in dieci secondi se l'URL di base e la chiave funzionano, usando il curl indicato in questa pagina; tutto il resto dipende dal comportamento di LibreChat con l'ID modello scelto.