Configuración personalizada

Cree, monte y configure el archivo librechat.yaml para endpoints de IA personalizados y configuraciones avanzadas de LibreChat

¿Qué es librechat.yaml?

El archivo librechat.yaml es el archivo de configuración principal de LibreChat para endpoints de IA personalizados, ajustes de modelos, opciones de interfaz y funciones avanzadas como servidores MCP y agentes. Es opcional: LibreChat funciona con valores predeterminados razonables si el archivo no existe.

Siga los pasos a continuación para crear el archivo, montarlo para su tipo de despliegue y verificar que funcione.

Si solo recuerdas una cosa

Para instalaciones de Docker, editar librechat.yaml no es suficiente. El archivo debe existir en la raíz del proyecto, estar montado en el contenedor de la API y LibreChat debe reiniciarse antes de que los cambios aparezcan en la UI.

Configuración

Localizar o crear el archivo

Cree un nuevo librechat.yaml en la raíz de su proyecto (el mismo directorio que su archivo .env):

touch librechat.yaml

También puedes copiar la configuración de ejemplo como punto de partida:

cp librechat.example.yaml librechat.yaml

Ruta de archivo alternativa

Puede establecer una ruta de archivo personalizada utilizando la variable de entorno CONFIG_PATH:

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

Montar el archivo de configuración

Docker necesita un montaje de volumen para acceder a su archivo librechat.yaml dentro del contenedor.

Copie el archivo de anulación de ejemplo:

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

Edita docker-compose.override.yml y asegúrate de que el montaje de volumen de librechat.yaml no esté comentado:

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

Esto utiliza el patrón docker-compose.override.yml: Docker Compose lo combina automáticamente con el docker-compose.yml principal, por lo que tus personalizaciones sobreviven a las actualizaciones.

Reiniciar LibreChat

docker compose down && docker compose up -d

Verificar que funciona

Abra LibreChat en su navegador. Si su configuración incluye endpoints personalizados, debería verlos en el menú desplegable del selector de modelos.

Si el servidor no logra iniciarse, revisa los registros en busca de errores de validación:

docker compose logs api

Ejemplo: Agregar OpenRouter

Este ejemplo explica cómo añadir OpenRouter como un endpoint personalizado, una de las configuraciones más populares.

1. Obtén una API key en openrouter.ai/keys.

2. Agregue la clave a su archivo .env:

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

Nombre de la variable de entorno

Use OPENROUTER_KEY, no OPENROUTER_API_KEY. Usar OPENROUTER_API_KEY también sobrescribirá el endpoint de OpenAI para usar OpenRouter.

3. Añade el endpoint a 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 LibreChat (consulte los comandos de reinicio anteriores) y seleccione OpenRouter en el selector de modelos.

Para obtener el archivo de configuración anotado completo con más ejemplos de endpoint, consulte la configuración de ejemplo.

Referencia

Para obtener documentación detallada a nivel de campo, consulte las páginas de referencia a continuación.

Endpoints de IA

Proveedores de IA compatibles y ejemplos de configuraciones de endpoint

→

Estructura del objeto

Referencia completa de campos para cada opción de librechat.yaml

→

Solución de problemas

Los cambios no se reflejan en LibreChat

Si editaste librechat.yaml y no hubo cambios en la interfaz de usuario:

Confirme que el archivo se encuentre en la raíz del proyecto LibreChat a menos que haya configurado CONFIG_PATH.
Para Docker, confirme que el archivo esté montado en docker-compose.override.yml.
Reinicie LibreChat con docker compose down && docker compose up -d.
Revisa los registros de la API con docker compose logs api.
Valide el archivo con el YAML Validator.

Los endpoints personalizados como OpenRouter solo aparecen después de que las tres partes sean correctas: .env contiene la clave, librechat.yaml define el endpoint y Docker puede leer el archivo de configuración montado.

Validación de configuración

LibreChat se cierra con un error (código de salida 1) si librechat.yaml contiene errores de validación. Este comportamiento de fallo rápido detecta problemas de configuración de forma temprana.

Para validar la sintaxis de tu YAML antes de reiniciar, utiliza el YAML Validator o yamlchecker.com.

El servidor se cierra inmediatamente al iniciar

Si tu servidor se cierra inmediatamente después de iniciarse, es probable que se trate de un error de validación de configuración.

Para diagnosticar:

Revise los registros del servidor: docker compose logs api
Valida tu sintaxis YAML con el YAML Validator
Errores comunes: sangría incorrecta, dos puntos faltantes, claves desconocidas, valores no válidos

Solución temporal (no recomendada para producción):

CONFIG_BYPASS_VALIDATION=true

Advertencia

CONFIG_BYPASS_VALIDATION=true hace que el servidor omita la validación y utilice la configuración predeterminada. Siempre corrija los errores de validación en su lugar.