Documentação

LobeChat

Uma instalação autogerenciada do LobeChat precisa de três variáveis de ambiente para se conectar ao Kunavo: uma chave, uma URL de proxy e a lista de IDs de modelos que você quer ver no seletor.

Defina OPENAI_API_KEY com sua chave sk-kn-…, OPENAI_PROXY_URL com https://api.kunavo.com/v1 e informe os IDs desejados em OPENAI_MODEL_LIST. Assim, Claude e GPT ficam disponíveis no mesmo seletor e usam o mesmo 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

O sufixo /v1 deve fazer parte de OPENAI_PROXY_URL. O LobeChat encaminha as solicitações para a URL informada, em vez de reconstruir o caminho da OpenAI. Por isso, a própria documentação do .env.example indica o valor padrão como https://api.openai.com/v1, incluindo o sufixo.

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
Adicione as três variáveis ao ambiente da sua implantação: ao arquivo .env em uma instalação simples ou ao bloco environment no Docker.
Reinicie o contêiner para que as novas variáveis de ambiente sejam carregadas.
Abra o LobeChat, inicie uma sessão e selecione um dos IDs informados em 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

A referência do próprio LobeChat para essas variáveis é a página de variáveis de ambiente dos provedores de modelos.

Verifique antes de depurar o contêiner

Uma única solicitação permite saber se a falha está no endpoint, na chave ou na lista de modelos do LobeChat. Se ela retornar uma lista JSON de IDs de modelos, a mesma URL e a mesma chave funcionam. Se depois disso o seletor continuar vazio, o problema está em OPENAI_MODEL_LIST, não no 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-..."

Quais IDs incluir

Todos os modelos de texto do Kunavo podem ser incluídos em OPENAI_MODEL_LIST. A lista completa está na página de modelos e é obtida em tempo real de GET /v1/models. As tarifas são em USD por 1M tokens, entrada / saída.

ID do modelo	Entrada / saída da Kunavo	Indicação de uso
`claude-haiku-4-5`	$0.70 / $3.50	Claude mais barato: para sessões longas de chat em que o custo por turno importa
`claude-sonnet-5`	$1.40 / $7.00	O equilíbrio padrão entre qualidade e preço
`claude-opus-5`	$3.50 / $17.50	A categoria Claude de mais alta qualidade
`gpt-5-6-terra`	$0.70 / $4.20	A mesma chave, outra família: sem precisar configurar um segundo provedor

Um cliente de chat reenvia toda a conversa a cada turno. Por isso, o consumo de tokens no LobeChat cresce com a duração da sessão, em vez de permanecer constante por mensagem. Nesse padrão, o fator que mais importa é o cache de prompts. A cobrança é por token, usando um saldo pré-pago e sem mensalidade; portanto, um mês sem uso não custa nada. Consulte os detalhes em cobrança.

Perguntas frequentes

Como direciono o LobeChat para um endpoint personalizado compatível com OpenAI?

Defina OPENAI_PROXY_URL como a URL base do endpoint e OPENAI_API_KEY como sua chave no ambiente de implantação — para o Kunavo, os valores são https://api.kunavo.com/v1. O próprio .env.example do LobeChat usa https://api.openai.com/v1 como valor de exemplo para essa variável, lembrando que o sufixo /v1 deve fazer parte do valor, e não ser acrescentado posteriormente.

Por que meu modelo personalizado não aparece na lista de modelos do LobeChat?

O LobeChat exibe os modelos que recebeu a informação de que existem, e não tudo o que o endpoint pode oferecer. Por isso, um ID de modelo que não esteja na lista fica invisível, mesmo quando o endpoint responde a ele. Informe os IDs em OPENAI_MODEL_LIST como uma lista separada por vírgulas. A documentação do LobeChat também define uma sintaxe de prefixos para essa variável: um + no início adiciona um modelo, um - no início oculta um modelo, e model_name=display_name renomeia um modelo no seletor.

O LobeChat pode usar modelos Claude por meio do provedor OpenAI?

Sim, quando são disponibilizados por um endpoint compatível com OpenAI. O provedor OpenAI do LobeChat envia o ID do modelo para o endereço indicado por OPENAI_PROXY_URL; assim, um ID Claude é resolvido no gateway, e não dentro do LobeChat, sem envolver credenciais da Anthropic. No Kunavo, os IDs Claude e GPT usam uma única chave. Portanto, para adicionar uma família, basta incluir um ID em OPENAI_MODEL_LIST.

A geração de imagens do LobeChat funciona por meio de um endpoint personalizado?

Isso depende das rotas implementadas pelo endpoint, não do LobeChat. O provedor de chat precisa de /v1/chat/completions; a geração de imagens usa uma rota separada. O Kunavo implementa a geração de imagens e vídeos em seus próprios endpoints, documentados nas seções de imagens e vídeo. Por isso, o padrão confiável é usar o LobeChat para chat e chamar diretamente os endpoints de mídia, sem presumir que uma única configuração de provedor cubra os dois casos.