Documentazione

LobeChat

Per comunicare con Kunavo, un’installazione self-hosted di LobeChat richiede tre variabili d’ambiente: una chiave, un URL proxy e l’elenco degli ID modello da mostrare nel selettore.

Imposta OPENAI_API_KEY sulla tua chiave sk-kn-…, OPENAI_PROXY_URL su https://api.kunavo.com/v1 e indica gli ID desiderati in OPENAI_MODEL_LIST. Claude e GPT condivideranno così un unico selettore e un unico saldo.

.env

OPENAI_API_KEY=sk-kn-...
OPENAI_PROXY_URL=https://api.kunavo.com/v1

# LobeChat only shows models it knows about, so name the ones you want.
OPENAI_MODEL_LIST=claude-sonnet-5,claude-haiku-4-5,claude-opus-5,gpt-5-6-terra

Il suffisso /v1 va incluso in OPENAI_PROXY_URL. LobeChat inoltra le richieste all’URL fornito, senza ricostruire il percorso OpenAI. Per questo, nella documentazione di LobeChat, il valore predefinito è .env.example: https://api.openai.com/v1, suffisso incluso.

Passo dopo passo

Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
Aggiungi le tre variabili all’ambiente della tua distribuzione: al file .env per un’installazione semplice oppure al blocco environment per Docker.
Riavvia il container per applicare le nuove variabili d’ambiente.
Apri LobeChat, avvia una sessione e scegli uno degli ID indicati in OPENAI_MODEL_LIST.

docker-compose.yml

services:
  lobe-chat:
    image: lobehub/lobe-chat
    ports:
      - "3210:3210"
    environment:
      OPENAI_API_KEY: sk-kn-...
      OPENAI_PROXY_URL: https://api.kunavo.com/v1
      OPENAI_MODEL_LIST: claude-sonnet-5,claude-haiku-4-5,gpt-5-6-terra

Il riferimento di LobeChat per queste variabili è la pagina sulle variabili d’ambiente dei provider di modelli.

Verifica prima di eseguire il debug del container

Una sola richiesta permette di stabilire se il problema riguarda l’endpoint, la chiave o l’elenco dei modelli di LobeChat. Se restituisce un elenco JSON di ID modello, lo stesso URL e la stessa chiave funzionano: se a quel punto il selettore è vuoto, il problema è OPENAI_MODEL_LIST, non l’endpoint.

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

Quali ID inserire nell’elenco

Puoi inserire in OPENAI_MODEL_LIST tutti i modelli di testo disponibili su Kunavo: l’elenco completo si trova nella pagina dei modelli e viene restituito in tempo reale da GET /v1/models. Tariffe in USD per 1M di token, input / output.

ID del modello	Kunavo ingresso / uscita	Ideale per
`claude-haiku-4-5`	$0.70 / $3.50	Il Claude più economico: per sessioni di chat lunghe in cui conta il costo per turno
`claude-sonnet-5`	$1.40 / $7.00	Il miglior equilibrio tra qualità e prezzo
`claude-opus-5`	$3.50 / $17.50	La fascia Claude di qualità più elevata
`gpt-5-6-terra`	$0.70 / $4.20	Stessa chiave, famiglia diversa: non serve configurare un secondo provider

A ogni turno, un client di chat invia di nuovo l’intera conversazione; quindi, la spesa in token su LobeChat cresce con la lunghezza della sessione, anziché restare costante per messaggio. In questo caso, la memorizzazione nella cache dei prompt è la leva più efficace. La fatturazione avviene per token, usando un saldo prepagato e senza canone mensile, quindi un mese di inattività non costa nulla. Maggiori dettagli nella sezione fatturazione.

Domande frequenti

Come indirizzo LobeChat a un endpoint personalizzato compatibile con OpenAI?

Imposta OPENAI_PROXY_URL sull'URL di base dell'endpoint e OPENAI_API_KEY sulla tua chiave nell'ambiente di distribuzione: per Kunavo, l'URL è https://api.kunavo.com/v1. Nel proprio file .env.example, LobeChat usa https://api.openai.com/v1 come valore d'esempio per quella variabile; il suffisso /v1 va quindi incluso nel valore, non viene aggiunto automaticamente.

Perché il mio modello personalizzato non compare nell’elenco dei modelli di LobeChat?

LobeChat mostra i modelli che gli sono stati indicati, non tutti quelli che l’endpoint è in grado di servire; quindi, se un ID modello non è nel suo elenco, resta invisibile anche quando l’endpoint risponde alle richieste per quel modello. Indica gli ID in OPENAI_MODEL_LIST come elenco separato da virgole. La documentazione di LobeChat definisce anche una sintassi con prefissi per questa variabile: un + iniziale aggiunge un modello, un - iniziale ne nasconde uno e model_name=display_name ne cambia il nome nel selettore.

LobeChat può usare modelli Claude tramite il provider OpenAI?

Sì, quando sono disponibili tramite un endpoint compatibile con OpenAI. Il provider OpenAI di LobeChat invia l’ID del modello all’indirizzo indicato da OPENAI_PROXY_URL; quindi, un ID Claude viene risolto al gateway, non all’interno di LobeChat, e non sono necessarie credenziali Anthropic. Su Kunavo, gli ID Claude e GPT usano un’unica chiave: per aggiungere una famiglia basta inserire un ID in OPENAI_MODEL_LIST.

La generazione di immagini di LobeChat funziona tramite un endpoint personalizzato?

Dipende dalle route implementate dall’endpoint, non da LobeChat. Il provider di chat richiede /v1/chat/completions; la generazione di immagini usa una route separata. Kunavo implementa la generazione di immagini e video sui propri endpoint, documentati nelle sezioni immagini e video. Perciò, il metodo affidabile consiste nell’usare LobeChat per la chat e chiamare direttamente gli endpoint multimediali, senza presumere che un’unica impostazione del provider copra entrambi i casi.