Estrutura de Configuração

Nota: Campos não mencionados especificamente como obrigatórios são opcionais.

version

• obrigatório

cache

skillSync

veja: Estrutura do Objeto Skill Sync

messageFilter

veja: Estrutura do Objeto de Filtro de Mensagens

fileStrategy

• Opções: "local" | "firebase" | "s3" | "azure_blob" | "cloudfront"

• Notas:
  • "cloudfront" armazena arquivos no S3 e retorna URLs do CloudFront para entrega estável de mídia, cookies assinados e downloads assinados.
  • "firebase" serve arquivos através do Firebase Storage e locais de borda (edge locations) do Firebase Hosting.
  • O S3 serve arquivos via presigned URLs (tokens assinados temporários) que expiram. Uma vez expirados, qualquer imagem ou avatar que referencie essa URL aparecerá como quebrado na interface. Isso torna o S3 inadequado como estratégia principal para ativos visuais. Veja a discussão relacionada para mais detalhes.
  • Para obter o melhor desempenho de imagens e avatares, use "cloudfront" ou "firebase", ou configure fileStrategies para rotear avatar e image para uma estratégia baseada em CDN.
  • Consulte a documentação de File Storage & CDN para detalhes de configuração

fileStrategies

Permite controle granular sobre estratégias de armazenamento de arquivos para diferentes tipos de arquivo.

• Estratégias Disponíveis: "local" | "firebase" | "s3" | "azure_blob" | "cloudfront"

Sub-chaves:

• Notas:
  • Esta configuração tem precedência sobre a opção única fileStrategy
  • Se um tipo de arquivo específico não estiver configurado, ele recorre a default, depois a fileStrategy e, finalmente, a "local".
  • Imagens e avatares precisam de URLs persistentes e estáveis para serem renderizados corretamente em toda a UI. URLs pré-assinadas do S3 expiram (limite da AWS: 7 dias para usuários IAM, horas para credenciais baseadas em STS/funções), causando imagens quebradas no seletor de modelos e na UI de chat. Veja a discussão relacionada para o contexto completo. Use "cloudfront" ou "firebase" para avatar e image para evitar isso.
  • O S3 e o Azure Blob Storage são adequados para armazenamento de document, onde URLs de download pré-assinadas de curta duração são apropriadas.
  • Consulte a documentação de File Storage & CDN para detalhes de configuração de cada provedor de armazenamento.

Exemplos:

# Use a single strategy for all file types
fileStrategies:
  default: 's3'

# Route images and avatars to CDN, keep documents in object storage
fileStrategies:
  avatar: 'cloudfront' # CDN delivery for avatars
  image: 'cloudfront' # CDN delivery for generated/uploaded images
  document: 's3' # Object storage for documents

# Only configure specific types, others use default
fileStrategies:
  default: 'local'
  avatar: 'firebase' # Only avatars use Firebase CDN, everything else is local

cloudfront

Chave:

Subchaves:

veja: Estrutura de Objeto do CloudFront e CloudFront com S3

filteredTools

• Notas:
  • Se includedTools e filteredTools forem ambos especificados, apenas includedTools será reconhecido.
  • Afeta ambos os endpoints gptPlugins e assistants
  • Você pode encontrar os nomes das ferramentas para filtrar em api/app/clients/tools/manifest.json
    • Use o valor de pluginKey
  • Além disso, qualquer um listado no diretório ".well-known" api/app/clients/tools/.well-known
    • Use o valor de name_for_model

includedTools

• Notas:
  • Se includedTools e filteredTools forem ambos especificados, apenas includedTools será reconhecido.
  • Afeta ambos os endpoints gptPlugins e assistants
  • Você pode encontrar os nomes das ferramentas para filtrar em api/app/clients/tools/manifest.json
    • Use o valor de pluginKey
  • Além disso, qualquer um listado no diretório ".well-known" api/app/clients/tools/.well-known
    • Use o valor de name_for_model

secureImageLinks

imageOutputType

• Nota: Diferencia maiúsculas de minúsculas. O endpoint Google suporta apenas os tipos de saída "jpeg" e "png".
• Opções: "png" | "webp" | "jpeg"

ocr

Chave:

Subchaves:

veja: Estrutura do Objeto de Configuração de OCR

webSearch

Chave:

Subchaves:

veja: Estrutura do Objeto de Pesquisa na Web

fileConfig

Chave:

Subchaves:

clientImageResize

Chave:

Subchaves:

Descrição:

A configuração clientImageResize permite o redimensionamento automático de imagens no lado do cliente antes do upload. Este recurso ajuda a:

• Evite falhas de upload devido a arquivos de imagem grandes que excedem os limites do servidor
• Reduza o uso de largura de banda comprimindo imagens antes da transmissão
• Melhore o desempenho de upload com tamanhos de arquivo menores
• Mantenha a qualidade da imagem enquanto otimiza o tamanho do arquivo

Quando ativado, imagens que excedem as dimensões maxWidth ou maxHeight especificadas são redimensionadas automaticamente no lado do cliente antes de serem enviadas para o servidor. O redimensionamento mantém a proporção original, garantindo que a imagem se ajuste aos limites especificados.

Exemplo:

fileConfig:
  clientImageResize:
    enabled: true
    maxWidth: 1920
    maxHeight: 1080
    quality: 0.8
    compressFormat: 'jpeg'

Notas:

• Aplica-se apenas a arquivos de imagem (JPEG, PNG, WebP, etc.)
• O redimensionamento ocorre automaticamente quando as imagens excedem as dimensões especificadas
• A proporção original é preservada durante o redimensionamento
• O recurso funciona com todos os endpoints de upload de imagem suportados
• A configuração de qualidade aplica-se apenas aos formatos JPEG e WebP
• Definir a qualidade muito baixa (< 0.5) pode resultar em uma degradação perceptível da imagem

veja: Estrutura do Objeto de Configuração de Arquivo

rateLimits

Chave:

Subchaves:

Subchaves de fileUploads:

Subchaves de conversationsImport:

Subchaves tts:

Subchaves stt:

• Exemplo:

rateLimits:
  fileUploads:
    ipMax: 100
    ipWindowInMinutes: 60
    userMax: 50
    userWindowInMinutes: 60
  conversationsImport:
    ipMax: 100
    ipWindowInMinutes: 60
    userMax: 50
    userWindowInMinutes: 60
  stt:
    ipMax: 100
    ipWindowInMinutes: 1
    userMax: 50
    userWindowInMinutes: 1
  tts:
    ipMax: 100
    ipWindowInMinutes: 1
    userMax: 50
    userWindowInMinutes: 1

registration

Chave:

Subchaves:

veja também:

• socialLogins,
• alloweddomains,
• Estrutura do Objeto de Registro

memory

Chave:

Subchaves:

veja: Estrutura do Objeto de Memória

summarization

Chave:

Subchaves:

veja: Estrutura do Objeto de Resumo

actions

Chave:

Subchaves:

veja também:

• allowedDomains,
• allowedAddresses,
• Estrutura do Objeto Actions

interface

Chave:

Subchaves:

veja: Estrutura do Objeto de Interface

modelSpecs

Chave:

Subchaves:

veja: Estrutura do Objeto Model Specs

endpoints

Chave:

Subchaves:

Nota: Os endpoints suportam Shared Endpoint Settings como streamRate, headers, titleModel, titleMethod, titlePrompt, titlePromptTemplate, titleEndpoint e maxToolResultChars. Estes podem ser configurados individualmente por endpoint ou globalmente usando a chave all. Os headers são mesclados, com os valores de nível de endpoint prevalecendo em caso de conflitos de chave. A chave all não aceita baseURL.

Nota: endpoints.allowedAddresses aplica-se a valores de baseURL fornecidos pelo usuário (quando um administrador configura um endpoint personalizado com apiKey: 'user_provided' e baseURL: 'user_provided'). Cada baseURL fornecida pelo usuário é validada contra o bloqueio de SSRF no momento da solicitação; as entradas listadas aqui estão isentas. Consulte mcpSettings.allowedAddresses para a semântica do campo — as mesmas regras se aplicam (apenas espaço de IP privado, porta obrigatória, sem URLs/caminhos/CIDR/hosts simples/literais de IP público).

mcpSettings

Chave:

Subchaves:

• Notas:
  • Este é um recurso de segurança para proteger contra abuso / uso indevido de endereços internos via servidores MCP
  • Por padrão, o LibreChat restringe a conexão de servidores MCP a endereços de rede internos, locais ou privados.
  • Servidores MCP que utilizam endereços IP locais ou domínios podem ser adicionados à lista de permissões estrita allowedDomains (que então se torna o único conjunto acessível) ou — para manter destinos públicos acessíveis — isentos como serviços host:port exatos via allowedAddresses
  • Como em todas as alterações de configuração yaml, uma reinicialização do LibreChat é necessária para que entrem em vigor.
  • Suporta domínios, subdomínios curinga (*.example.com), domínios Docker e endereços IP

Exemplo:

mcpSettings:
  # Strict whitelist mode:
  # allowedDomains:
  #   - "example.com"           # Specific domain
  #   - "*.example.com"         # All subdomains
  #   - "http://mcp-server:3000" # Internal service, explicitly whitelisted

  # Default SSRF mode with private service exemptions:
  allowedAddresses:
    - 'host.docker.internal:8080' # Permit one private host on one port
    - '10.0.0.5:8000' # Permit one private IP on one port

veja: Estrutura do Objeto MCP Settings

mcpServers

Chave:

Subchaves:

• Notas:
  • A inicialização ocorre na inicialização, e o aplicativo deve ser reiniciado para que as alterações entrem em vigor.
  • O <serverName> é um identificador único para cada configuração de servidor MCP.
  • Cada servidor MCP pode ser configurado usando um dos quatro tipos de conexão:
    • stdio
    • websocket
    • sse
    • streamable-http
  • O campo type especifica o tipo de conexão com o servidor MCP.
  • Se type for omitido, ele assume um padrão com base na presença e no formato de url ou command:
    • Se url for especificado e começar com http ou https, type assume sse como padrão.
    • Se url for especificado e começar com ws ou wss, type assume websocket como padrão.
    • Se command for especificado, type assume stdio como padrão.
  • Opções de configuração adicionais incluem:
    • timeout: Timeout em milissegundos para requisições de servidor MCP. Determina quanto tempo aguardar por uma resposta para requisições de ferramentas.
    • initTimeout: Tempo limite em milissegundos para a inicialização do servidor MCP. Determina quanto tempo aguardar pela inicialização do servidor.
    • serverInstructions: Controla se as instruções do servidor são incluídas no contexto do agente. Pode ser true (usa as fornecidas pelo servidor), false (desativado) ou uma string personalizada (substitui as fornecidas pelo servidor).
    • customUserVars: (Opcional) Define variáveis personalizadas (por exemplo, chaves de API, URLs) que usuários individuais podem definir para um servidor MCP. Esses valores por usuário, fornecidos através da interface, podem então ser referenciados nas configurações de headers ou env do servidor usando a sintaxe {{VARIABLE_NAME}}. Isso permite autenticação ou personalização por usuário para ferramentas MCP.
  • veja: Estrutura do Objeto MCP Servers

Exemplo:

mcpServers:
  everything:
    # type: sse # type can optionally be omitted
    url: http://localhost:3001/sse
    timeout: 30000
    initTimeout: 10000
    serverInstructions: true # Use server-provided instructions
  puppeteer:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-puppeteer'
    timeout: 30000
    initTimeout: 10000
    serverInstructions: 'Do not access any local files or local/internal IP addresses'
  filesystem:
    # type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - /home/user/LibreChat/
    iconPath: /home/user/LibreChat/client/public/assets/logo.svg
  mcp-obsidian:
    command: npx
    args:
      - -y
      - 'mcp-obsidian'
      - /path/to/obsidian/vault
  streamable-http-example:
    type: streamable-http
    url: https://example.com/mcp
    headers:
      Authorization: 'Bearer ${API_TOKEN}'
    timeout: 30000
  per-user-crendentials-example:
    type: sse
    url: 'https//some.mcp/sse'
    headers:
      X-Custom-Auth-Token: '{{USER_API_KEY}}' # Placeholder for the user-provided API key, defined in `customUserVars` below.
    customUserVars:
      USER_API_KEY:
        title: 'Service API Key'
        description: "Your personal API key for this service. You can get it <a href='https://example.com/api-keys' target='_blank'>here</a>."
    serverInstructions: true

veja: Estrutura do Objeto MCP Servers

speech

Chave:

Subchaves:

veja: Estrutura do Objeto Speech

turnstile

Chave:

Subchaves:

veja: Estrutura do Objeto Turnstile

transactions

Chave:

Subchaves:

veja: Estrutura do Objeto Transactions

Links adicionais

• Estrutura do Objeto de Resumo
• Estrutura de Objeto do AWS Bedrock
• Estrutura do Objeto de Endpoint Personalizado
• Estrutura do Objeto do endpoint Azure OpenAI
• Estrutura do Objeto do endpoint Assistants
• Agents
• Estrutura do Objeto de Configuração OCR
• Estrutura do Objeto de Fala
• Estrutura de Objeto do Turnstile
• Estrutura do Objeto Transactions
• Estrutura do Objeto Balance
• Estrutura do Objeto de Pesquisa na Web
• Estrutura do Objeto de Memória