Documentação

LibreChat

O LibreChat recebe um gateway como bloco em librechat.yaml: quatro campos obrigatórios, uma variável de ambiente para a chave e uma reinicialização. Em seguida, o seletor mostra IDs Claude e GPT sob um único nome de endpoint.

O LibreChat usa um gateway como um bloco endpoints.custom em librechat.yaml — quatro campos obrigatórios, a chave proveniente de .env e uma reinicialização antes que ele apareça no seletor.

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 mantém o /v1. A documentação esclarece isso em texto, não com um exemplo: ela diz que directEndpoint existe para uma URL base que já seja o endpoint completo de completions e que isso é “necessário porque o aplicativo acrescenta ‘/chat/completions’ ou ‘/completion’ à baseURL por padrão”. Portanto, https://api.kunavo.com/v1 é resolvido como /v1/chat/completions, a rota que deve ser chamada, e directEndpoint deve permanecer sem definição. Os dois exemplos práticos do próprio site terminam da mesma forma — https://api.mistral.ai/v1 e https://openrouter.ai/api/v1. Uma origem sem sufixo aqui resulta em 404, não em erro de autenticação.

Editar o arquivo não basta no Docker. A página de início rápido especifica que librechat.yaml precisa existir na raiz do projeto, ser montado no contêiner da API e que o LibreChat deve ser reiniciado para que a alteração apareça na interface. Se um novo endpoint não aparecer no seletor, quase sempre esse é o problema, não as credenciais — verifique as credenciais separadamente com o curl abaixo.

O registro de uso reflete os cálculos do LibreChat, não a cobrança. O LibreChat calcula o preço de uma solicitação usando uma tabela própria, com base no ID do modelo. Assim, um ID de gateway pode ser contabilizado pela tarifa de outro modelo — o que o bloco tokenConfig acima permite corrigir. Declare esse bloco para cada ID exposto ou considere o registro uma estimativa e o saldo em /app/billing como o valor real.

Esta configuração foi extraída da documentação do próprio LibreChat na data abaixo. O Kunavo não executou o LibreChat em seu endpoint — não houve conversa, turno com streaming, ida e volta de chamada de ferramenta nem execução de Agents. Uma página de configuração publicada não é um teste e não deve ser interpretada como tal; o que você pode verificar em dez segundos é o curl abaixo. O comportamento do cliente depende do LibreChat.

O Kunavo não oferece modelos de embedding, conversão de texto em fala ou conversão de fala em texto; portanto, este endpoint responde a solicitações de conclusão de chat e nada mais. Isso é relevante aqui porque o LibreChat tem recursos complementares que usam outros tipos de provedor: o chat com arquivos executa seu índice vetorial por meio de uma API RAG separada, com chave e URL base próprias, e os recursos de fala também usam credenciais próprias. Esses recursos continuam apontados para o provedor que já utilizam; a chave no bloco acima serve para o endpoint personalizado e para nenhum outro recurso desta página.

Ainda não tem uma chave? Crie uma conta na Kunavo, gere uma chave (ela começa com sk-kn-) e adicione crédito a partir de $10 — as chamadas são pagas com esse saldo, e chamadas malsucedidas não são cobradas. O painel então abre na configuração de LibreChat.

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
No Docker, monte primeiro a configuração: o guia de início rápido orienta copiar docker-compose.override.yml.example para docker-compose.override.yml e descomentar o volume librechat.yaml. Uma instalação diretamente na máquina dispensa essa etapa.
Crie ou edite librechat.yaml na raiz do projeto — o mesmo diretório do seu .env — e adicione a entrada endpoints.custom acima.
Coloque a chave em .env como KUNAVO_API_KEY=sk-kn-.... O marcador ${KUNAVO_API_KEY} no YAML é substituído pelo valor correspondente, mantendo o segredo fora do arquivo de configuração que você envia ao repositório.
Reinicie o LibreChat e abra o seletor de endpoints: Kunavo aparecerá como uma entrada própria ao lado das opções integradas, com a lista de modelos obtida de GET /v1/models ou, se a consulta falhar, da matriz models.default.
Envie uma mensagem e confirme se o seletor de modelos realmente alterna entre eles — os IDs são resolvidos no endpoint; portanto, é normal ter um ID Claude e um ID GPT na mesma entrada, isso não indica um erro de configuração.

Verificado em Referência do objeto de endpoint personalizado do LibreChat em 21 de setembro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Esta é a versão resumida. O guia completo — escolha do modelo, custo de uma sessão real e modos de falha — está em quanto realmente custa usar o LibreChat.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em 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-..."

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

ID do modelo	Entrada / saída da Kunavo	Onde se encaixa em LibreChat
`claude-sonnet-5`	$1.40 / $7.00	a entrada padrão em models.default — o modelo para conversas do dia a dia
`claude-opus-5`	$3.50 / $17.50	o ID usado em análises longas, nas quais vale a pena dedicar um turno para obter uma resposta melhor
`claude-haiku-4-5`	$0.70 / $3.50	o tráfego de volume de uma instância compartilhada e titleModel — o LibreChat dá um título a cada conversa em uma chamada separada
`gpt-5-6-terra`	$0.70 / $4.20	documentos longos colados, em que a janela de contexto é o fator decisivo

A cobrança é por token, usando um saldo pré-pago e sem tarifa mensal — consulte billing. Em contextos repetidos — que representam a maior parte do que um editor ou cliente de chat envia — o cache de prompt altera a conta mais do que a escolha do modelo.

Três campos opcionais com comportamentos diferentes em um gateway

Tudo nesta tabela vem da mesma referência de campos, consultada na data acima. É a descrição da própria configuração do LibreChat — não um resultado de teste do Kunavo nem uma afirmação sobre o comportamento de determinado ID de modelo depois que a solicitação sai do cliente.

Campo	O que diz a referência	Por que isso importa para um gateway
`provider`	Encaminha um endpoint personalizado por meio de um cliente de provedor nativo. Atualmente, Anthropic é o valor compatível.	Ele troca o protocolo de comunicação, não o fornecedor: o mesmo bloco pode usar Anthropic Messages em vez de chat completions. A busca de modelos no estilo OpenAI não é usada nesse caminho; portanto, liste os IDs em models.default explicitamente.
`models.fetch`	Quando definido como true, tenta obter uma lista de modelos da API e pode causar lentidão no uso inicial se a resposta demorar.	O Kunavo responde a GET /v1/models, então o seletor é preenchido automaticamente. models.default serve como alternativa se essa chamada falhar — por isso, vale a pena preenchê-lo mesmo com a busca ativada.
`tokenConfig`	Define janelas de contexto específicas para cada modelo e tarifas por milhão de tokens para acompanhar custos e calcular o uso.	Sem esse campo, o registro calcula o preço do seu tráfego usando a tabela incluída no LibreChat, que compara o ID com um modelo para o qual a tabela nunca foi criada. Com ele, os valores exibidos na interface correspondem aos que você definiu.

O passo a passo em quatro etapas — montar, configurar, definir a variável de ambiente e reiniciar — está na página de início rápido do LibreChat para endpoints personalizados, que usa um gateway como exemplo prático.

Perguntas frequentes

Como adiciono um endpoint personalizado ao LibreChat?

Crie librechat.yaml na raiz do projeto, ao lado do arquivo .env, e adicione uma entrada em endpoints.custom com os quatro campos obrigatórios: name, apiKey, baseURL e models. O nome precisa ser exclusivo e não pode repetir o nome de um endpoint integrado, como openAI ou anthropic. Coloque a credencial em .env e faça referência a ela no YAML como ${YOUR_ENV_VAR}; em seguida, reinicie o serviço. No Docker, o arquivo também precisa ser montado no contêiner da API por meio de docker-compose.override.yml, e a nova entrada só aparecerá no seletor de endpoints depois da reinicialização.

A baseURL do LibreChat precisa terminar em /v1?

Sim, para um gateway compatível com OpenAI. A referência de campos do próprio LibreChat diz que a opção directEndpoint existe para uma URL base que já seja o endpoint completo de completions e que isso é necessário porque o aplicativo acrescenta /chat/completions ou /completion à baseURL por padrão. Portanto, a URL base é a raiz da API com o sufixo /v1 — https://api.kunavo.com/v1 —, e directEndpoint deve permanecer sem definição. Os dois exemplos no site do LibreChat seguem esse formato. Se configurar incorretamente, você receberá um erro 404 em vez de uma falha de autenticação, o que permite distinguir o problema de uma chave inválida.

Por que os custos informados pelo LibreChat não correspondem ao valor cobrado pelo provedor?

Porque o LibreChat calcula o preço de uma solicitação usando uma tabela própria, em vez de usar o valor cobrado pelo provedor, e compara o ID do modelo com essa tabela. Um ID de gateway semelhante a uma entrada da tabela será contabilizado pela tarifa dessa entrada; se não corresponder a nenhuma, será aplicada uma tarifa fixa. Para corrigir isso, adicione um bloco tokenConfig ao endpoint personalizado e declare prompt, completion e context para cada ID exposto, em USD por milhão de tokens. O LibreChat verifica esse ajuste antes de consultar a própria tabela. Considere o registro no aplicativo uma estimativa e o saldo do provedor o valor oficial.

O LibreChat pode usar modelos Claude por meio de um endpoint personalizado?

Sim, de duas formas. Um endpoint personalizado simples, compatível com OpenAI, encaminha o ID do modelo diretamente para sua baseURL. Assim, um ID Claude é resolvido nesse endpoint, não no LibreChat, e não é necessária uma conta Anthropic. Como alternativa, o campo provider encaminha o mesmo bloco pelo cliente Anthropic Messages nativo do LibreChat — atualmente, anthropic é o valor compatível. Nesse caminho, a busca de modelos no estilo OpenAI não é usada; portanto, liste os IDs desejados em models.default em vez de depender da busca.

O Kunavo testou o LibreChat?

Não. A configuração desta página foi transcrita da documentação de endpoints personalizados do próprio LibreChat na data indicada, e nada nela é resultado de execução — não houve conversa, turno com streaming, ida e volta de chamada de ferramenta nem execução de Agents. Isso vale para todos os clientes documentados aqui: uma página de configuração publicada não é um teste. Você pode verificar por conta própria em dez segundos se a URL base e a chave funcionam; é para isso que serve o comando curl nesta página. Todo o restante depende do comportamento do LibreChat com o ID de modelo escolhido.