Configuração Personalizada

Crie, monte e configure o arquivo librechat.yaml para endpoints de IA personalizados e configurações avançadas do LibreChat

O que é o librechat.yaml?

O arquivo librechat.yaml é o principal arquivo de configuração do LibreChat para endpoints de IA personalizados, configurações de modelo, opções de interface e recursos avançados como servidores MCP e agentes. Ele é opcional -- o LibreChat funciona com padrões sensatos caso o arquivo não exista.

Siga as etapas abaixo para criar o arquivo, montá-lo para o seu tipo de implantação e verificar se ele funciona.

Se você só se lembrar de uma coisa

Para instalações via Docker, editar o librechat.yaml não é suficiente. O arquivo deve existir na raiz do projeto, ser montado no container da API e o LibreChat deve ser reiniciado antes que as alterações apareçam na UI.

Prefere uma interface gráfica? Use o Painel de Administração

O Painel de Administração do LibreChat gerencia essa mesma configuração a partir de um navegador -- incluindo substituições por função e por grupo que entram em vigor no login sem reiniciar o LibreChat. Ele é fornecido com as pilhas oficiais do Docker Compose. Use o librechat.yaml para configuração baseada em arquivo ou inicialização, e o painel de administração para o gerenciamento contínuo.

Configuração

Localize ou Crie o Arquivo

Crie um novo librechat.yaml na raiz do seu projeto (o mesmo diretório do seu arquivo .env):

touch librechat.yaml

Você também pode copiar o exemplo de configuração como um ponto de partida:

cp librechat.example.yaml librechat.yaml

Caminho de arquivo alternativo

Você pode definir um caminho de arquivo personalizado usando a variável de ambiente CONFIG_PATH:

CONFIG_PATH="/alternative/path/to/librechat.yaml"

Montar o arquivo de configuração

O Docker precisa de um volume mount para acessar seu arquivo librechat.yaml dentro do container.

Copie o arquivo de substituição de exemplo:

cp docker-compose.override.yml.example docker-compose.override.yml

Edite o docker-compose.override.yml e certifique-se de que a montagem de volume do librechat.yaml esteja descomentada:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

Isso utiliza o padrão docker-compose.override.yml -- o Docker Compose o mescla automaticamente com o docker-compose.yml principal, para que suas personalizações sobrevivam às atualizações.

Coloque o librechat.yaml no diretório raiz do projeto (o mesmo diretório do seu arquivo .env). Nenhuma montagem adicional é necessária para instalações locais.

Reiniciar o LibreChat

docker compose down && docker compose up -d

Interrompa o processo em execução (Ctrl+C) e reinicie:

npm run backend

Verifique se funciona

Abra o LibreChat no seu navegador. Se a sua configuração incluir endpoints personalizados, você deverá vê-los no menu suspenso de seleção de modelo.

Se o servidor falhar ao iniciar, verifique os logs para erros de validação:

docker compose logs api

Exemplo: Adicionando OpenRouter

Este exemplo orienta sobre como adicionar o OpenRouter como um endpoint personalizado -- uma das configurações mais populares.

1. Obtenha uma chave de API em openrouter.ai/keys.

2. Adicione a chave ao seu .env file:

OPENROUTER_KEY=sk-or-v1-your-key-here

Nome da Variável de Ambiente

Use OPENROUTER_KEY, não OPENROUTER_API_KEY. Usar OPENROUTER_API_KEY fará com que o endpoint da OpenAI também utilize o OpenRouter.

3. Adicione o endpoint ao librechat.yaml:

version: 1.3.5
cache: true
endpoints:
  custom:
    - name: "OpenRouter"
      apiKey: "${OPENROUTER_KEY}"
      baseURL: "https://openrouter.ai/api/v1"
      models:
        default: ["meta-llama/llama-3-70b-instruct"]
        fetch: true
      titleConvo: true
      titleModel: "meta-llama/llama-3-70b-instruct"
      dropParams: ["stop"]
      modelDisplayLabel: "OpenRouter"

4. Reinicie o LibreChat (veja os comandos de reinicialização acima) e selecione OpenRouter no seletor de modelos.

Para o arquivo de configuração anotado completo com mais exemplos de endpoint, veja a configuração de exemplo.

Referência

Para documentação detalhada em nível de campo, consulte as páginas de referência abaixo.

Endpoints de IA

Provedores de IA compatíveis e exemplos de configurações de endpoint

→

Estrutura do Objeto

Referência completa de campos para cada opção do librechat.yaml

→

Solução de problemas

A alteração não aparece no LibreChat

Se você editou o librechat.yaml e nada mudou na UI:

Confirme se o arquivo está na raiz do projeto LibreChat, a menos que você tenha definido CONFIG_PATH.
Para Docker, confirme se o arquivo está montado em docker-compose.override.yml.
Reinicie o LibreChat com docker compose down && docker compose up -d.
Verifique os logs da API com docker compose logs api.
Valide o arquivo com o YAML Validator.

Endpoints personalizados como OpenRouter só aparecem após todas as três partes estarem corretas: o .env contém a chave, o librechat.yaml define o endpoint e o Docker consegue ler o arquivo de configuração montado.

Validação de Configuração

O LibreChat encerra com um erro (código de saída 1) se o librechat.yaml contiver erros de validação. Esse comportamento de falha rápida detecta problemas de configuração precocemente.

Para validar sua sintaxe YAML antes de reiniciar, use o YAML Validator ou o yamlchecker.com.

O servidor fecha imediatamente ao iniciar

Se o seu servidor encerrar imediatamente após a inicialização, é provável que seja um erro de validação de configuração.

Para diagnosticar:

Verifique os logs do servidor: docker compose logs api
Valide sua sintaxe YAML com o YAML Validator
Erros comuns: indentação incorreta, dois-pontos ausentes, chaves desconhecidas, valores inválidos

Solução temporária (não recomendada para produção):

CONFIG_BYPASS_VALIDATION=true

Aviso

CONFIG_BYPASS_VALIDATION=true faz com que o servidor ignore a validação e utilize a configuração padrão. Sempre corrija os erros de validação em vez disso.

Configuração Personalizada

Endpoints de IA

Estrutura do Objeto

Nesta página