配置结构

注意： 未明确说明为必填的字段均为可选字段。

version

• 必需

cache

skillSync

请参阅：Skill Sync 对象结构

messageFilter

请参阅：Message Filter Object Structure

fileStrategy

• 选项: "local" | "firebase" | "s3" | "azure_blob" | "cloudfront"

• 注意:
  • "cloudfront" 将文件存储在 S3 中，并返回 CloudFront URL 以实现稳定的媒体分发、签名 Cookie 和签名下载。
  • "firebase" 通过 Firebase Storage 和 Firebase Hosting 边缘节点提供文件服务。
  • S3 通过会过期的 预签名 URL（临时签名令牌）提供文件服务。一旦过期，UI 中任何引用该 URL 的图像或头像都将显示为损坏。这使得 S3 不适合作为视觉资产的主要存储策略。详情请参阅 相关讨论。
  • 为了获得最佳的图像和头像性能，请使用 "cloudfront" 或 "firebase"，或者配置 fileStrategies 以将 avatar 和 image 路由到由 CDN 支持的策略。
  • 请参阅 File Storage & CDN documentation 以获取设置详情。

fileStrategies

允许对不同文件类型的文件存储策略进行细粒度控制。

• 可用策略: "local" | "firebase" | "s3" | "azure_blob" | "cloudfront"

子键：

• 注意:
  • 此设置的优先级高于单个 fileStrategy 选项
  • 如果未配置特定的文件类型，它将回退到 default，然后是 fileStrategy，最后是 "local"
  • 图像和头像需要持久、稳定的 URL 才能在 UI 中正确渲染。S3 预签名 URL 会过期（AWS 上限：IAM 用户为 7 天，基于 STS/角色的凭证为数小时），这会导致模型选择器和聊天 UI 中的图像无法显示。请参阅相关讨论以了解完整背景。请为 avatar 和 image 使用 "cloudfront" 或 "firebase" 以避免此问题。
  • S3 和 Azure Blob Storage 非常适合用于 document 存储，在这种场景下，使用短时效的预签名下载 URL 是合适的。
  • 请参阅 File Storage & CDN documentation 以获取各存储提供商的设置详情。

示例：

# 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

密钥：

子键 (Subkeys):

请参阅：CloudFront 对象结构 和 配合 S3 使用 CloudFront

filteredTools

• 注意:
  • 如果同时指定了 includedTools 和 filteredTools，则仅会识别 includedTools。
  • 同时影响 gptPlugins 和 assistants endpoint
  • 你可以在 api/app/clients/tools/manifest.json 中找到用于过滤的工具名称。
    • 使用 pluginKey 值
  • Also, any listed under the ".well-known" directory api/app/clients/tools/.well-known
    • 使用 name_for_model 值

includedTools

• 注意:
  • 如果同时指定了 includedTools 和 filteredTools，则仅会识别 includedTools。
  • 同时影响 gptPlugins 和 assistants endpoint
  • 你可以在 api/app/clients/tools/manifest.json 中找到用于过滤的工具名称。
    • 使用 pluginKey 值
  • Also, any listed under the ".well-known" directory api/app/clients/tools/.well-known
    • 使用 name_for_model 值

secureImageLinks

imageOutputType

• 注意：区分大小写。Google endpoint 仅支持 “jpeg” 和 “png” 输出类型。
• 选项: "png" | "webp" | "jpeg"

ocr

密钥：

子键 (Subkeys):

请参阅：OCR 配置对象结构

webSearch

密钥：

子键 (Subkeys):

请参阅：Web Search Object Structure

fileConfig

密钥：

子键 (Subkeys):

clientImageResize

密钥：

子键 (Subkeys):

描述：

clientImageResize 配置支持在上传前自动进行客户端图像缩放。此功能有助于：

• 防止上传失败，避免因图片文件过大而超出服务器限制
• 减少带宽使用，通过在传输前压缩图像
• 提升上传性能，减小文件大小
• 保持图像质量的同时优化文件大小

启用后，超过指定 maxWidth 或 maxHeight 尺寸的图像会在上传到服务器之前在客户端自动调整大小。调整大小时会保持原始宽高比，同时确保图像符合指定的边界。

示例：

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

注意：

• 仅适用于图像文件（JPEG、PNG、WebP 等）
• 当图片超过指定尺寸时，会自动进行调整大小。
• 调整大小时保留原始宽高比
• 此功能适用于所有受支持的图像上传 endpoint。
• 质量设置仅适用于 JPEG 和 WebP 格式
• 将质量设置得过低（< 0.5）可能会导致明显的图像质量下降

请参阅：文件配置对象结构

rateLimits

密钥：

子键 (Subkeys):

fileUploads 子键：

conversationsImport 子键：

tts 子键：

stt 子键：

• 示例:

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

密钥：

子键 (Subkeys):

另请参阅：

• socialLogins,
• alloweddomains,
• 注册对象结构

memory

密钥：

子键 (Subkeys):

请参阅：Memory Object Structure

summarization

密钥：

子键 (Subkeys):

请参阅：Summarization Object Structure

actions

密钥：

子键 (Subkeys):

另请参阅：

• allowedDomains,
• allowedAddresses,
• Actions 对象结构

interface

密钥：

子键 (Subkeys):

请参阅：Interface Object Structure

modelSpecs

密钥：

子键 (Subkeys):

请参阅：Model Specs 对象结构

endpoints

密钥：

子键 (Subkeys):

注意： 端点支持 Shared Endpoint Settings，例如 streamRate、headers、titleModel、titleMethod、titlePrompt、titlePromptTemplate、titleEndpoint 和 maxToolResultChars。这些设置可以针对每个端点单独配置，也可以使用 all 键进行全局配置。headers 会进行合并，当键冲突时，端点级别的设置值优先。all 键不支持 baseURL。

注意： endpoints.allowedAddresses 适用于用户提供的 baseURL 值（当管理员配置了 apiKey: 'user_provided' 和 baseURL: 'user_provided' 的自定义 endpoint 时）。每个用户提供的 baseURL 都会在请求时根据 SSRF 拦截规则进行验证；此处列出的条目将被豁免。有关字段语义，请参阅 mcpSettings.allowedAddresses —— 适用相同的规则（仅限私有 IP 空间、必须包含端口、不支持 URL/路径/CIDR/裸主机名/公网 IP 字面量）。

mcpSettings

密钥：

子键 (Subkeys):

• 注意:
  • 这是一个旨在防止通过 MCP 服务器滥用/误用内部地址的安全功能。
  • 默认情况下，LibreChat 会限制 MCP 服务器连接到内部、本地或私有网络地址。
  • 使用本地 IP 地址或域名的 MCP 服务器，既可以添加到严格的 allowedDomains 白名单中（此时该列表将成为唯一可访问的集合），也可以为了保持对公共目标的访问权限，通过 allowedAddresses 将其作为精确的 host:port 服务进行豁免。
  • 与所有 yaml 配置更改一样，需要重启 LibreChat 才能生效。
  • 支持域名、通配符子域名 (*.example.com)、Docker 域名以及 IP 地址

示例：

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

请参阅：MCP Settings Object Structure

mcpServers

密钥：

子键 (Subkeys):

• 注意:
  • 初始化在启动时进行，必须重启应用才能使更改生效。
  • <serverName> 是每个 MCP 服务器配置的唯一标识符。
  • 每个 MCP server 都可以使用四种连接类型之一进行配置：
    • stdio
    • websocket
    • sse
    • streamable-http
  • type 字段指定了连接到 MCP server 的连接类型。
  • 如果省略 type，它将根据 url 或 command 的存在与否及其格式进行默认设置：
    • 如果指定了 url 且以 http 或 https 开头，则 type 默认为 sse。
    • 如果指定了 url 且以 ws 或 wss 开头，则 type 默认为 websocket。
    • 如果指定了 command，type 将默认为 stdio。
  • 其他配置选项包括：
    • timeout: MCP 服务器请求的超时时间（以毫秒为单位）。决定了等待工具请求响应的时长。
    • initTimeout: MCP 服务器初始化的超时时间（以毫秒为单位）。决定了等待服务器初始化的时长。
    • serverInstructions: 控制是否将服务器指令包含在 Agent 上下文中。可以是 true（使用服务器提供的指令）、false（禁用）或自定义字符串（覆盖服务器提供的指令）。
    • customUserVars: （可选）定义用户可以为 MCP 服务器设置的自定义变量（例如 API 密钥、URL）。这些通过 UI 提供的用户专属值，随后可以在服务器的 headers 或 env 配置中使用 {{VARIABLE_NAME}} 语法进行引用。这允许针对 MCP 工具进行用户级的身份验证或自定义。
  • 请参阅：MCP Servers Object Structure

示例：

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

请参阅：MCP Servers Object Structure

speech

密钥：

子键 (Subkeys):

请参阅：Speech Object Structure

turnstile

密钥：

子键 (Subkeys):

请参阅：Turnstile 对象结构

transactions

密钥：

子键 (Subkeys):

请参阅：Transactions Object Structure

其他链接

• 摘要对象结构
• AWS Bedrock 对象结构
• 自定义 Endpoint 对象结构
• Azure OpenAI 端点对象结构
• Assistants Endpoint 对象结构
• Agents
• OCR 配置对象结构
• 语音对象结构
• Turnstile 对象结构
• Transactions 对象结构
• 余额对象结构
• Web Search 对象结构
• 内存对象结构