跳到主要内容

环境变量配置

概述​

Open WebUI 提供了大量的环境变量，允许您自定义和配置应用程序的各个方面。本页面将作为所有可用环境变量的完整参考，提供它们的类型、默认值以及详细描述。 随着新变量的引入，本页面将持续更新以反映不断增加的配置选项。

信息

本页面内容与 Open WebUI 发布版本 v0.9.5 保持同步，但我们仍在持续完善中，后续将补充更准确的描述、环境变量的可用选项列表、默认值以及改进相关说明。

关于 PersistentConfig 环境变量的重要说明​

备注

首次启动 Open WebUI 时，所有的环境变量都会被一视同仁地用于配置应用程序。然而，对于被标记为 PersistentConfig 的环境变量，它们的值将被持久化并存储在系统内部（数据库中）。

在首次启动之后，如果您重启容器，被标记为 PersistentConfig 的环境变量将不再读取外部环境变量的值。相反，它们将优先使用系统内部存储的值。

与此相反，普通的非持久化环境变量在每次后续重启时仍会继续更新并应用。

您可以直接在 Open WebUI 内部更新这些 PersistentConfig 环境变量的值，这些更改将被存储在内部。这允许您独立于外部环境变量来管理这些配置设置。

请注意，我们在下面的文档中清晰地标记了哪些是 PersistentConfig 环境变量，以便您了解它们的行为方式。

要禁用此行为并强制 Open WebUI 始终使用您的环境变量（忽略数据库中的配置），请将 ENABLE_PERSISTENT_CONFIG 设置为 False。

关键警告： 当 ENABLE_PERSISTENT_CONFIG 为 False 时，您可能仍能在管理员 UI 中编辑设置。但是，这些修改不会永久保存。它们仅在当前会话中生效，并在您重启容器时丢失，因为系统在启动时会回滚到您环境变量中定义的值。

排除忽略环境变量的故障 🛠️​

如果您更改了环境变量（例如 ENABLE_SIGNUP=True）但在 UI 中没有看到更改生效（例如，注册按钮仍然缺失），这很可能是因为之前的运行或持久化的 Docker 卷已经将该值保存在数据库中。

方法 1：使用 ENABLE_PERSISTENT_CONFIG（临时修复）​

在您的环境中设置 ENABLE_PERSISTENT_CONFIG=False。这会强制 Open WebUI 直接读取您的环境变量。请注意，在此模式下，通过 UI 进行的设置修改将无法在重启后保留。

方法 2：通过管理员 UI 更新（推荐）​

修改 PersistentConfig 设置最简单、最安全的方法是直接通过 Open WebUI 内部的管理员面板进行。即使设置了环境变量，在 UI 中所做的更改也会优先保存到数据库中。

方法 3：手动更新数据库（仅作为无奈之举 / 锁定恢复）​

如果您被系统锁定或无法访问 UI，可以通过 Docker 手动更新 SQLite 数据库：

docker exec -it open-webui sqlite3 /app/backend/data/webui.db "UPDATE config SET data = json_set(data, '$.ENABLE_SIGNUP', json('true'));"

（请将 ENABLE_SIGNUP 和 true 替换为您需要修改的具体设置和值。）

方法 4：重置以进行全新安装​

如果您正在进行全新安装，并希望确保所有环境变量都从零开始生效：

  1. 停止容器。
  2. 删除持久化卷：docker volume rm open-webui。
  3. 重启容器。
危险

警告： 删除持久化卷会删除所有用户数据，包括聊天记录和账号信息。

App/Backend​

以下环境变量由 backend/open_webui/config.py 使用，以提供 Open WebUI 启动配置。请注意，某些变量的默认值可能会有所不同，这取决于您是直接运行 Open WebUI 还是通过 Docker 运行。有关日志环境变量的更多信息，请参阅我们的日志文档。

常规​

WEBUI_URL​

  • 类型: str
  • 默认值: http://localhost:3000
  • 描述: 指定可访问您 Open WebUI 实例的 URL。这对于搜索引擎支持和 OAuth/SSO 是必需的。
  • 持久化: 此环境变量是 PersistentConfig 变量。
注意

在开始使用 OAuth/SSO 进行身份验证之前，必须先设置好此变量。 由于这是一个持久化配置环境变量，您只能通过以下方式之一来更改它：

  • 通过使用 ENABLE_PERSISTENT_CONFIG 临时禁用持久化配置
  • 在管理员面板 > 设置中更改 "WebUI URL"。

未能在使用 OAuth/SSO 前设置 WEBUI_URL 将导致登录失败。

ENABLE_SIGNUP​

  • 类型: bool
  • 默认值: True
  • 描述: 开启或关闭用户账号创建。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_SIGNUP_PASSWORD_CONFIRMATION​

  • 类型: bool
  • 默认值: False
  • 描述: 如果设置为 True，注册页面将增加一个“确认密码”输入框，以帮助用户避免在创建密码时输入错别字。

WEBUI_ADMIN_EMAIL​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 指定在首次启动且数据库中不存在任何用户时自动创建的管理员账号的电子邮箱地址。这使得无头部署/自动化部署无需手动创建账号。当与 WEBUI_ADMIN_PASSWORD 配合使用时，管理员账号会在应用程序启动期间创建，且 ENABLE_SIGNUP 会自动被禁用以防止未经授权的账号创建。
信息

此变量专为手动创建管理员账号不切实际的自动化/容器化部署而设计。管理员账号仅在满足以下条件时创建：

  • 数据库中不存在任何用户（全新安装）
  • 同时配置了 WEBUI_ADMIN_EMAIL 和 WEBUI_ADMIN_PASSWORD

管理员账号创建后，出于安全考虑，系统会自动禁用注册功能。如果需要，您稍后可以通过管理员面板重新启用它。

WEBUI_ADMIN_PASSWORD​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 指定在首次启动且不存在任何用户时自动创建的管理员账号的密码。必须与 WEBUI_ADMIN_EMAIL 配合使用。在保存到数据库之前，密码会使用与手动创建账号相同的机制进行安全哈希处理。
危险

安全注意事项

  • 在生产环境部署中，请使用强且独特的密码
  • 考虑使用凭据管理工具（Docker secrets、Kubernetes secrets、环境变量注入），而不是直接在明文配置文件中存储密码
  • 初始设置完成后，通过 UI 修改管理员密码以增强安全性
  • 严禁将此值提交到版本控制系统中

WEBUI_ADMIN_NAME​

  • 类型: str
  • 默认值: Admin
  • 描述: 指定自动创建的管理员账号的显示名称。当配置了 WEBUI_ADMIN_EMAIL 和 WEBUI_ADMIN_PASSWORD 进行无头管理员创建时使用此名称。

ENABLE_LOGIN_FORM​

  • 类型: bool
  • 默认值: True
  • 描述: 开启或关闭电子邮箱、密码、登录按钮以及“或”分隔符元素（仅在 ENABLE_OAUTH_SIGNUP 设置为 True 时）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_PASSWORD_CHANGE_FORM​

  • 类型: bool
  • 默认值: True
  • 描述: 控制设置 > 账户中修改密码 UI 的可见性。当设置为 False 时，用户将看不到密码更新表单，这对于以 SSO 为主的部署非常有用，因为在此类部署中不需要在 UI 中展示修改密码功能。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_PASSWORD_AUTH​

  • 类型: bool
  • 默认值: True
  • 描述: 当设置为 True 时，允许密码登录和 SSO 身份验证方法共存。当设置为 False 时，它将禁用在 /signin 和 /ldap 端点上的所有基于密码的登录尝试，从而强制实行严格的仅限 SSO 身份验证。在完全配置了 SSO 的生产环境中禁用此设置，可以防止基于凭据的账户夺取攻击；如果您需要将密码身份验证作为备用方案，或者尚未完成 SSO 配置，请保持启用。如果未使用 OAUTH/SSO，则绝不应该禁用此项。此设置控制后端身份验证行为，而 ENABLE_PASSWORD_CHANGE_FORM 控制密码修改控件的 UI 可见性。
提示

如果您仅使用 SSO/OAUTH 进行登录，并且将 Open WebUI 公开暴露在公网上，则应该将此值设置为 False，以防止基于密码的登录。

危险

此变量仅在同时使用 ENABLE_OAUTH_SIGNUP 且设置为 True 时，才能被设置为 False。如果未使用 OAUTH/SSO，绝不要禁用此项。 否则将导致无法登录系统。

DEFAULT_LOCALE​

  • 类型: str
  • 默认值: en
  • 描述: 设置应用程序的默认语言区域。
  • 持久化: 此环境变量是 PersistentConfig 变量。

DEFAULT_MODELS​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 设置默认的语言模型（Language Model）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

DEFAULT_PINNED_MODELS​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 以逗号分隔的模型 ID 列表，用于为尚未自定义置顶模型的新用户默认置顶这些模型。这可以为新账户的模型选择器中提供一组预先选好的常用模型。
  • 示例: gpt-4,claude-3-opus,llama-3-70b
  • 持久化: 此环境变量是 PersistentConfig 变量。

DEFAULT_MODEL_METADATA​

  • 类型: dict (JSON 对象)
  • 默认值: {}
  • 描述: 为所有模型设置全局默认元数据（模型能力和其他模型信息）。这些默认值充当基线——单模型覆盖设置将始终优先。对于能力（capabilities），默认值和单模型值将合并（发生冲突时以单模型设置为准）。对于其他元数据字段，仅在模型未设置值时才应用默认值。可通过管理员设置 → 模型进行配置。
  • 持久化: 此环境变量是 PersistentConfig 变量。存储在配置键 models.default_metadata 中。
信息

DEFAULT_MODEL_METADATA 在启动时作为 JSON 字符串从环境中读取。

  • 请使用有效的 JSON（例如：{"capabilities":{"vision":true,"web_search":true}}）
  • 如果解析失败，Open WebUI 会记录错误并回退到 {}
  • 解析后的值即使在禁用持久化配置时也会应用，因此在启动时会遵守配置的默认值。

DEFAULT_MODEL_PARAMS​

  • 类型: dict (JSON 对象)
  • 默认值: {}
  • 描述: 为所有模型设置全局默认参数（temperature, top_p, max_tokens, seed 等）。这些默认值在生成对话回复时作为基线应用——单模型参数覆盖设置将始终优先。可通过管理员设置 → 模型进行配置。
  • 持久化: 此环境变量是 PersistentConfig 变量。存储在配置键 models.default_params 中。
信息

DEFAULT_MODEL_PARAMS 在启动时作为 JSON 字符串从环境中读取。

  • 请使用有效的 JSON（例如：{"temperature":0.7,"function_calling":"native"}）
  • 如果解析失败，Open WebUI 会记录错误并回退到 {}

DEFAULT_USER_ROLE​

  • 类型: str
  • 可用选项:
    • pending - 新注册的用户处于待处理状态，直到管理员手动激活他们的账号。
    • user - 新注册的用户会自动激活，并获得普通用户权限。
    • admin - 新注册的用户会自动激活，并获得管理员权限。
  • 默认值: pending
  • 描述: 设置分配给新用户的默认角色。
  • 持久化: 此环境变量是 PersistentConfig 变量。

DEFAULT_GROUP_ID​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 设置新用户注册时默认分配的组 ID。
  • 持久化: 此环境变量是 PersistentConfig 变量。

DEFAULT_GROUP_SHARE_PERMISSION​

  • 类型: str
  • 可用选项: members, true, false
  • 默认值: members
  • 描述: 控制新创建的组的默认“谁可以共享到此组”设置。members 意味着只有组成员可以共享到该组，true 意味着任何人都可以共享，false 意味着没有人可以共享到该组。这既适用于手动创建的组，也适用于自动创建的组（例如通过 SCIM 或 OAuth 组同步）。已存在的组不受影响——这只为新组设置初始默认值。

PENDING_USER_OVERLAY_TITLE​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 为待处理用户遮罩层（Overlay）设置自定义标题。
  • 持久化: 此环境变量是 PersistentConfig 变量。

PENDING_USER_OVERLAY_CONTENT​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 为待处理用户遮罩层（Overlay）设置自定义文本内容。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_CALENDAR​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用日历功能。启用后，用户可以创建日历、管理事件，并通过访问授权与其他用户或组共享日历。处于活动状态的自动化任务将作为虚拟事件自动呈现在专用的“已调度任务”日历上。需要 features.calendar 用户权限（管理员始终自动通过）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_CHANNELS​

  • 类型: bool
  • 默认值: False
  • 描述: 启用或禁用频道（Channels）支持。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_FOLDERS​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用文件夹功能，允许用户在侧边栏中将他们的聊天整理到文件夹中。
  • 持久化: 此环境变量是 PersistentConfig 变量。

FOLDER_MAX_FILE_COUNT​

  • 类型: int
  • 默认值: ("") 空字符串
  • 描述: 设置每个文件夹允许处理的最大文件数。
  • 持久化: 此环境变量是 PersistentConfig 变量。可以在管理员面板 > 设置 > 常规 > 文件夹最大文件数中进行配置。默认无限制（空字符串）。

ENABLE_AUTOMATIONS​

  • 类型: bool
  • 默认值: True
  • 描述: 在全局启用或禁用自动化（Automations）功能。禁用后，调度器会跳过自动化任务的处理，自动化 API 端点将返回 403 Forbidden，自动化内置工具将不会被注入，侧边栏中的自动化入口也会隐藏。需要 features.automations 用户权限（管理员始终自动通过）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

AUTOMATION_MAX_COUNT​

  • 类型: int
  • 默认值: ("") 空字符串（无限制）
  • 描述: 设置非管理员用户可以创建的最大自动化数量。当设置为正整数时，达到此限制的用户在尝试创建更多自动化时将收到 403 Forbidden 错误。管理员不受此限制约束。
  • 持久化: 此环境变量是 PersistentConfig 变量。

AUTOMATION_MIN_INTERVAL​

  • 类型: int（秒）
  • 默认值: ("") 空字符串（无最小间隔）
  • 描述: 设置非管理员用户自动化循环执行的最小允许间隔（秒）。设置后，任何执行频率高于此值的自动化日程都将被拒绝，并返回 400 Bad Request 错误。单次执行的自动化（COUNT=1）免受此检查限制。管理员不受此限制约束。
  • 持久化: 此环境变量是 PersistentConfig 变量。
AUTOMATION_MIN_INTERVAL 的常见值
值含义
60每次运行之间至少间隔 1 分钟
300每次运行之间至少间隔 5 分钟
900每次运行之间至少间隔 15 分钟
3600每次运行之间至少间隔 1 小时

SCHEDULER_POLL_INTERVAL​

  • 类型: int（秒）
  • 默认值: 10
  • 描述: 设置调度器 Tick 之间的间隔（秒）。统一调度器同时处理自动化执行和日历事件提醒。接受 AUTOMATION_POLL_INTERVAL 作为历史遗留的备用项。

CALENDAR_ALERT_LOOKAHEAD_MINUTES​

  • 类型: int（分钟）
  • 默认值: 10
  • 描述: 日历事件提醒的默认提前看（Lookahead）窗口（分钟）。在当前时间起此窗口内开始的事件将触发 Toast 提示和 Webhook 通知。单个事件可以在事件编辑器的**提醒（Reminder）**设置中覆盖此值（meta.alert_minutes）。

ENABLE_NOTES​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用笔记（Notes）功能，允许用户在 Open WebUI 内部创建和管理个人笔记。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_MEMORIES​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用记忆功能，允许模型存储和检索关于用户的长期信息。
  • 持久化: 此环境变量是 PersistentConfig 变量。

WEBHOOK_URL​

  • 类型: str
  • 描述: 设置用于与 Discord/Slack/Microsoft Teams 集成的 Webhook。
  • 持久化: 此环境变量是 PersistentConfig 变量.
管理员姿态切换 vs 安全边界

本节中的 ENABLE_ADMIN_* 和 BYPASS_ADMIN_ACCESS_CONTROL 切换控件用于控制管理员通过 Open WebUI 的管理员产品界面（管理员面板页面、聊天模型选择器、工作区列表、导出操作）能看到和做什么。它们并不构成针对管理员本身的安全边界。

Open WebUI 在架构上是单租户的，根据深思熟虑的设计，admin 角色在部署中等同于 Root 权限。管理员本身保留了对所有数据的无约束访问权，包括直接访问数据库、检查环境变量、访问服务器、运行仅限管理员的 Functions（在应用程序进程内模块导入时执行任意 Python 代码），以及拥有 workspace.tools 权限的 Tools（管理员可以将其授权给自己，并在服务器上运行 exec()）。

这些切换控件适用于：

  • 性能 —— 在拥有大量多用户的大型部署中，保持管理员界面的列表/选择器加载速度，因为加载每个用户的所有项目是一个严峻的性能难题。
  • 减少 UI 杂乱 —— 当存在来自其他用户的数千个项目时，保持这些界面的可用性。
  • 合规态势 —— 满足（特别是在劳动保护法更严格的司法管辖区，例如 德国 / 奥地利 / 欧盟）不让管理员随手就看到其他用户数据的合规要求，即使他们技术上仍能通过上述途径获取这些数据。

这些切换控件不适用于：

  • 管理员之间的跨租户数据隔离。在底层数据存储中，不存在加密的单租户隔离，没有多数据库拆分，也没有单管理员的作用域限制。对于真正的租户分离，支持的模式是为每个租户运行独立的 Open WebUI 实例。
  • 针对铁了心要读取其在 UI 界面中被隐藏的数据的管理员的安全边界。

请将这一组变量视为管理员在产品 UI 和 API 中能看到什么和能做什么，而不是管理员在技术上可以访问到什么部署资源。

ENABLE_ADMIN_EXPORT​

  • 类型: bool
  • 默认值: True
  • 描述: 控制管理员面板中的**导出（Export）**操作是否可用（包括数据、聊天和数据库导出）。禁用时，导出 API 端点会拒绝请求。数据库导出目前仅支持 SQLite 数据库。请注意，管理员仍保留通过部署端直接导出数据库的底层能力——此开关控制产品内的导出界面，参见上面的“管理员姿态切换”说明。需要重启才能生效。

ENABLE_ADMIN_CHAT_ACCESS​

  • 类型: bool
  • 默认值: True
  • 描述: 控制管理员面板中的**其他用户聊天（other-users-chats）**访问界面是否可用。禁用后，管理员无法再在管理员面板中访问其他用户的聊天记录，且相应的 API 端点会拒绝请求。如果您禁用此项，请考虑同时禁用 ENABLE_ADMIN_EXPORT（特别是在 SQLite 上），因为导出数据包含用户聊天，且会在不同的界面重新暴露相同的数据。请注意，无论如何，管理员都保留着底层数据库访问权限——此开关控制产品内的界面，参见上面的“管理员姿态切换”说明。

ENABLE_ADMIN_ANALYTICS​

  • 类型: bool
  • 默认值: True
  • 描述: 控制管理员面板中的**分析（Analytics）**选项卡是否可见，以及分析 API 路由是否挂载。当设置为 False 时，该选项卡将被隐藏，且相应的 API 端点不会注册。禁用此项不会停止底层数据的收集，且管理员仍保留直接从数据库查询这些数据的能力——此开关控制产品内的界面，参见上面的“管理员姿态切换”说明。需要重启才能生效。

BYPASS_ADMIN_ACCESS_CONTROL​

  • 类型: bool

  • 默认值: True

  • 描述: 控制管理员用户是否能在列表和选择器 UI 界面中看到其他用户的工作区项目（模型 / 知识库 / 提示词 / 工具 / 笔记 / 技能的工作区选项卡、聊天模型选择器、文件浏览器列表等）。当设置为 True（默认值）时，这些界面会显示每个用户的每一个项目——这在单管理员 / 小团队部署中非常方便。当设置为 False 时，这些界面将仅显示管理员自己的项目以及明确共享给他们的项目，与普通用户看到的界面一致。

    基于 ID 的直接访问 API 端点（GET /api/v1/<resource>/id/{id} 以及对应的更新/删除/访问更新路由）故意不受此标志限制，并且设计之初也从未打算受其限制——限制它们对于防止管理员通过数据库查询直接获取资源 ID 毫无用处，同时还会破坏管理员操作已知项目 ID 的合法流程。有关完整的架构原理解释，请参阅上面的“管理员姿态切换”说明。

    此环境变量废弃了 ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS。如果您仍在使用 ENABLE_ADMIN_WORKSPACE_CONTENT_ACCESS，请切换到 BYPASS_ADMIN_ACCESS_CONTROL。

ENABLE_USER_WEBHOOKS​

  • 类型: bool
  • 默认值: False
  • 描述: 启用或禁用用户 Webhooks。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RESPONSE_WATERMARK​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 设置在聊天中复制消息时包含的自定义水印文本。例如："This text is AI generated" -> 当复制任何消息时，都会在该消息中附加“This text is AI generated”。
  • 持久化: 此环境变量是 PersistentConfig 变量。

IFRAME_CSP​

  • 类型: str
  • 默认值: 空字符串（不注入 CSP）
  • 描述: 对 UI 中渲染的所有 srcdoc iframe（包括 Artifacts、代码/HTML 预览、文件预览和引用弹窗）应用内容安全策略（Content-Security-Policy）。设置后，将在 iframe 文档顶部注入 <meta http-equiv="Content-Security-Policy"> 标签，限制由 LLM 生成或用户上传的 HTML 能够加载和执行的内容（网络连接、脚本、样式、字体、iframe）。iframe 上的 sandbox 属性仍提供基线隔离；此 CSP 是针对需要约束已渲染 HTML 的出站网络请求的部署提供的额外深度防御层。示例值：default-src 'self' 'unsafe-inline' 'unsafe-eval' data: blob:; connect-src 'none'。留空以保持现有行为（仅限沙箱）。

THREAD_POOL_SIZE​

  • 类型: int
  • 默认值: 0
  • 描述: 设置 FastAPI/AnyIO 阻塞调用的线程池大小。默认情况下（设置为 0 时），FastAPI/AnyIO 使用 40 个线程。对于大型实例和大量并发用户，可能需要增加 THREAD_POOL_SIZE 以防止发生阻塞。
信息

如果您正在运行大型实例，您将需要将此值设置为更高的值，例如几百甚至上千（如 1000），否则当默认的线程池（40 个线程）占满时，您的应用程序可能会卡死并且不再响应。

ENABLE_CUSTOM_MODEL_FALLBACK​

  • 类型: bool
  • 默认值: False
  • 描述: 控制当自定义模型的指定基础模型缺失时，是否应该退回到默认模型。设置为 True 时，如果找不到自定义模型的基础模型，系统将使用配置的 DEFAULT_MODELS 列表中的第一个模型，而不是返回错误。

SHOW_ADMIN_DETAILS​

  • 类型: bool
  • 默认值: True
  • 描述: 切换是否在界面中展示管理员用户详情。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_PUBLIC_ACTIVE_USERS_COUNT​

  • 类型: bool
  • 默认值: True
  • 描述: 控制活跃用户数是向所有用户可见，还是仅限于管理员可见。当设置为 False 时，只有管理员用户可以看到当前有多少用户在线，这可以减轻后端负载，并解决大型部署中的隐私担忧。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_USER_STATUS​

  • 类型: bool
  • 默认值: True
  • 描述: 在全局启用或禁用用户状态功能。禁用后，整个应用程序中的状态 UI（包括闪烁的在线/离开指示器和状态消息）将被隐藏，且用户状态 API 端点将受到限制。
  • 持久化: 此环境变量是 PersistentConfig 变量。可以在管理员面板 > 设置 > 常规 > 用户状态中进行切换。

ENABLE_EASTER_EGGS​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用 UI 中的彩蛋功能，例如特殊主题（例如主题选择器中的“Her”主题选项）。设置为 False 可以对用户隐藏这些可选的趣味功能。

ADMIN_EMAIL​

  • 类型: str
  • 描述: 设置由 SHOW_ADMIN_DETAILS 显示的管理员邮箱。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENV​

  • 类型: str
  • 可用选项:
    • dev - 在 /docs 上启用 FastAPI 的 API 文档。
    • prod - 自动配置多个环境变量。
  • 默认值:
    • 后端默认值: dev
    • Docker 默认值: prod
  • 描述: 环境设置。

ENABLE_PERSISTENT_CONFIG​

  • 类型: bool
  • 默认值: True
  • 描述: 控制系统是否优先使用数据库中保存的配置，而不是环境变量。
    • True（默认）: 保存到数据库中（通过管理员 UI）的值优先。如果在 UI 中设置了某个值，外部的环境变量将被忽略。
    • False: 环境变量优先。如果存在环境变量，系统在启动时将不会从数据库加载配置（或者它将使用默认值）。
      • 关键警告： 当设置为 False 时，您在管理员 UI 中仍能看似成功地“更改”设置。这些更改将应用到当前运行的会话，但会在重启后丢失。每次启动时，系统都会恢复为您的环境变量中定义的值（或默认值）。
      • 使用场景： 如果您希望严格通过 docker-compose.yaml 或 .env 文件来管理配置，并防止 UI 更改在重启后保留，请将此项设置为 False。

CUSTOM_NAME​

  • 类型: str
  • 描述: 设置 WEBUI_NAME，但同时会向 api.openwebui.com 轮询元数据。

WEBUI_NAME​

  • 类型: str
  • 默认值: Open WebUI
  • 描述: 设置 WebUI 的主名称。如果被覆盖，则会附加 (Open WebUI)。

PORT​

  • 类型: int
  • 默认值: 8080
  • 描述: 设置运行 Open WebUI 的端口。
信息

如果您是通过 Python 运行应用程序并使用 open-webui serve 命令，您无法使用 PORT 配置来设置端口。相反，您必须直接通过命令行参数并使用 --port 标志来指定它。例如：

open-webui serve --port 9999

这将在端口 9999 上运行 Open WebUI。在此模式下，PORT 环境变量将被忽略。

ENABLE_REALTIME_CHAT_SAVE​

  • 类型: bool
  • 默认值: False
  • 描述: 启用后，系统会实时将流式传输的每一块聊天数据保存到数据库中。
极高的高性能风险：切勿在生产环境启用

强烈建议绝不要在生产或多用户环境中启用此设置。

启用 ENABLE_REALTIME_CHAT_SAVE 会导致 LLM 生成的每一个 Token 都触发一次独立的数据库写入操作。在多用户环境中，这将：

  1. 耗尽数据库连接池：高频的写入会迅速消耗所有可用的数据库连接，导致“QueuePool limit reached”错误和全局应用程序卡死。
  2. 严重的性能影响：每分钟数千次数据库事务的开销将对所有用户造成巨大的延迟。
  3. 硬件损耗：会对您的存储系统产生巨大的 I/O 压力。

请保持设置为 False（默认值）。 聊天记录在生成完成后仍会自动保存。此设置仅适用于极端的调试场景或单用户环境，即对于此环境来说，微秒级的 Token 持久化比系统的稳定性更为重要。

ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION​

  • 类型: bool
  • 默认值: False
  • 描述: 设置为 True 时，它会自动上传 Markdown 中超过 1KB 的 Base64 编码图片，并将其转换为图片文件 URL，以减小响应文本的体积。某些多模态模型会直接在 Markdown 内容中输出 Base64 字符串形式的图片。这会导致响应体过大，给 CPU、网络、Redis 以及数据库资源带来负担。

ENABLE_IMAGE_CONTENT_TYPE_EXTENSION_FALLBACK​

  • 类型: bool
  • 默认值: False
  • 描述: 启用后，当系统 MIME 数据库和文件存储的 Content-Type 元数据都无法确定图片的 Content-Type 时，系统将使用硬编码的“扩展名-Mime”字典作为最终的备用机制。这主要适用于缺少 /etc/mime.types 的极简容器镜像（例如 wolfi-base）以及未存储 Content-Type 元数据的历史遗留文件。支持的扩展名包括 .webp, .png, .jpg, .jpeg, .gif, .svg, .bmp, .tiff, .ico, .heic, .heif 和 .avif。

ENABLE_PROFILE_IMAGE_URL_FORWARDING​

  • 类型: bool
  • 默认值: True
  • 描述: 控制用户和模型的头像端点是否通过发出 302 Found 重定向到原始源，来响应存储在 profile_image_url 中的外部 http(s):// URL。为 False 时，重定向将被抑制，端点将改为回退到内置的默认图片。设置为 False 可以防止由于攻击者存储的头像 URL，导致客户端 IP、User-Agent 和 Referer 泄漏到攻击者控制的源中（Data URI 和同源/静态图片仍会正常加载）。合理依赖外部头像 URL 的现有部署（例如由上游身份提供商提供的 Gravatar 重定向）应该保持默认值。此变量在启动时仅读取一次——它不是 PersistentConfig，无法从管理员 UI 更改。

PROFILE_IMAGE_ALLOWED_MIME_TYPES​

  • 类型: str（以逗号分隔的 MIME 类型）
  • 默认值: image/png,image/jpeg,image/gif,image/webp
  • 描述: 允许在提供 Base64 data: URI 作为头像时被接受的 MIME 类型白名单。MIME 类型会在流式传输响应之前，从 Data URI 前缀中解析出来并在此列表中进行检查；非白名单中的类型将退回到内置的默认图片。响应还会设置 X-Content-Type-Options: nosniff，以防止浏览器将响应体嗅探为可执行类型。SVG 故意不在默认列表中，因为它可以携带内联的 <script>。同样的白名单还驱动着 Pydantic 的 Data URI 前缀验证器，因此在此处添加一个类型，既会在读取路径上提供它，也会在写入路径上接受它。此变量在启动时仅读取一次——它不是 PersistentConfig，无法从管理员 UI 更改。

CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE​

  • 类型: int
  • 默认值: 1
  • 描述: 设置系统级的流式传输响应中，每次发送给客户端之前积攒的最小 Token 数量。这允许管理员通过防止过小的块尺寸导致的高 CPU 负载，来强制确保整个系统的基线性能和稳定性。用于响应的最终块大小将是此全局变量、模型的高级参数或单次对话设置中设置的最高值。默认值为 1，表示在全局级别不应用最小批处理。

CHAT_STREAM_RESPONSE_CHUNK_MAX_BUFFER_SIZE​

  • 类型: int
  • 默认值: 空字符串 (' ')，即禁用此限制（等同于 None）
  • 描述: 设置处理流式响应块时的最大缓冲区字节数。当单个响应块超过此限制时，系统会返回一个空的 JSON 对象，并跳过后续超大的数据，直到遇到大小正常的响应块。这可以防止处理来自某些服务商的极大型响应时的内存问题（例如 gemini-2.5-flash-image 模型或返回大量网页搜索数据的服务）。设置为空字符串或负值以完全禁用响应块大小限制。根据图片生成模型的图片大小，推荐值为 16-20 MB（16777216）或更大（4K 图片可能需要更多）。
信息

如果您在运行高并发、多用户以及使用极快流式传输模型的 Open WebUI 时，建议将此值设置为较高的一位数或较低的两位数值。

ENABLE_RESPONSES_API_STATEFUL​

  • 类型: bool
  • 默认值: False
  • 描述: 通过将 previous_response_id 转发到上游端点，为 Responses API 启用有状态的会话处理。启用后，Open WebUI 将每个响应锚定到前一个响应上，允许上游服务商在服务器端维护对话状态。
实验性功能

仅在您的上游 Responses API 端点支持有状态会话时才启用此功能（即支持带 previous_response_id 锚定的服务器端响应存储）。大多数代理和第三方端点是无状态的，如果启用此功能将会出错。此功能旨在用于直接连接到原生支持带会话状态的 Responses API 的服务商（如 OpenAI）。

BYPASS_MODEL_ACCESS_CONTROL​

  • 类型: bool
  • 默认值: False
  • 描述: 绕过模型访问控制。当设置为 true 时，所有用户（以及管理员）都将能够访问所有模型，而不管模型的隐私设置如何（私有、公开、与某些组共享）。这对于较小的或个人 Open WebUI 安装非常有用，因为在此类安装中可能不需要模型访问限制。

WEBUI_BUILD_HASH​

  • 类型: str
  • 默认值: dev-build
  • 描述: 用于在发布版本中识别构建的 Git SHA。

WEBUI_BANNERS​

  • 类型: list of dict
  • 默认值: []
  • 描述: 要展示给用户的横幅（Banners）列表。横幅的格式为：
[{"id": "string", "type": "string [info, success, warning, error]", "title": "string", "content": "string", "dismissible": false, "timestamp": 1000}]
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

在 .env 文件中设置此环境变量时，请确保通过将整个值用双引号包裹，并对内部的双引号使用转义字符（\"）来对引号进行转义。例如：

WEBUI_BANNERS="[{\"id\": \"1\", \"type\": \"warning\", \"title\": \"Your messages are stored.\", \"content\": \"Your messages are stored and may be reviewed by human people. LLM's are prone to hallucinations, check sources.\", \"dismissible\": true, \"timestamp\": 1000}]"

USE_CUDA_DOCKER​

  • 类型: bool
  • 默认值: False
  • 描述: 使用 NVIDIA CUDA 支持构建 Docker 镜像。为本地 Whisper 和嵌入模型启用 GPU 加速。

DOCKER​

  • 类型: bool
  • 默认值: False
  • 描述: 指示 Open WebUI 是否正在 Docker 容器内运行。在内部用于环境检测。

USE_CUDA​

  • 类型: bool
  • 默认值: False
  • 描述: 控制是否对本地模型使用 CUDA 加速。设置为 true 时，系统将尝试检测并使用可用的 NVIDIA GPU。代码会读取环境变量 USE_CUDA_DOCKER 来设置此内部布尔变量。

DEVICE_TYPE​

  • 类型: str
  • 默认值: cpu
  • 描述: 指定模型执行的设备类型。如果 CUDA 可用且启用，则自动设置为 cuda，或者在 Apple Silicon 上自动设置为 mps。

EXTERNAL_PWA_MANIFEST_URL​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 当定义为完全限定的 URL 时（例如 https://path/to/manifest.webmanifest），发往 /manifest.json 的请求将使用该外部 Manifest 文件。如果未定义，将使用默认的 manifest.json 文件。

ENABLE_TITLE_GENERATION​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用聊天标题自动生成。
  • 持久化: 此环境变量是 PersistentConfig 变量。

LICENSE_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定要使用的许可证密钥（仅限企业版用户）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SSL_ASSERT_FINGERPRINT​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定要使用的 SSL 断言指纹。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_COMPRESSION_MIDDLEWARE​

  • 类型: bool
  • 默认值: True
  • 描述: 为 HTTP 响应启用 Gzip 压缩中间件，从而减少带宽使用并改善加载时间。

DEFAULT_PROMPT_SUGGESTIONS​

  • 类型: list of dict
  • 默认值: []（这意味着使用内置的默认提示词建议）
  • 描述: 设置在开始新聊天时向用户展示的全局默认提示词建议。当没有配置特定模型的提示词建议时，将应用这些全局建议。也可以通过模型编辑器为每个模型单独配置提示词建议（参见 提示词建议），或者使用全局模型默认值功能为所有模型进行全局配置。其格式为：
[{"title": ["Title part 1", "Title part 2"], "content": "prompt"}]

AIOHTTP Client​

AIOHTTP_CLIENT_TIMEOUT​

  • 类型: int
  • 默认值: 300
  • 描述: 指定 AIOHTTP 客户端的超时时间（秒）。这会影响诸如与 Ollama 和 OpenAI 端点的连接。
信息

这是客户端在超时之前等待响应的最大时间。 如果设置为空字符串 (' ')，超时时间将被设置为 None，这会实际上禁用超时，并允许客户端无限期地等待。

AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST​

  • 类型: int
  • 默认值: 10
  • 描述: 设置从 Ollama 和 OpenAI 端点获取模型列表的超时时间（秒）。这会影响在加载可用模型时，Open WebUI 等待每个已配置端点的时长。
何时调整此值

降低超时时间（例如 3）如果：

  • 您配置了多个端点，并希望在一个端点无法访问时能够更快地进行故障转移
  • 即使某些慢速端点被跳过，您也更希望 UI 能够快速加载

增加超时时间（例如 30）如果：

  • 您的模型服务器响应缓慢（例如，冷启动、加载大模型）
  • 您正在高延迟网络上进行连接
  • 您正在使用像 OpenRouter 这样响应时间不稳定的服务商
数据库持久化

通过管理设置 UI 配置的连接 URL 将持久化保存在数据库中，并优先于环境变量。如果您保存了一个无法访问的 URL，导致 UI 失去响应，您可能需要使用以下恢复选项之一：

  • RESET_CONFIG_ON_START=true - 在下次启动时将数据库配置重置为环境变量的值
  • ENABLE_PERSISTENT_CONFIG=false - 始终使用环境变量（UI 中的更改不会持久化）

有关详细的恢复步骤，请参阅 模型列表加载问题 故障排除指南。

AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST​

  • 类型: int
  • 描述: 设置获取模型列表的超时时间（秒）。在网络延迟较大，需要更长的超时时长才能成功检索模型列表的情况下，此变量非常有用。

AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER​

  • 类型: int
  • 默认值: 未设置时继承 AIOHTTP_CLIENT_TIMEOUT 的值
  • 描述: 设置执行工具服务器 API 调用（由 Open WebUI 发起的 OpenAPI/MCPO 代理调用）的超时时间（秒）。使用此变量来控制 Open WebUI 等待实际工具执行响应的时长。
信息

如果此变量未设置或无效，Open WebUI 将退回到使用 AIOHTTP_CLIENT_TIMEOUT。

AIOHTTP_CLIENT_SESSION_SSL​

  • 类型: bool
  • 默认值: True
  • 描述: 在连接外部 API（例如 Ollama 嵌入模型）时，控制 AIOHTTP 客户端会话的 SSL/TLS 验证。

AIOHTTP_CLIENT_ALLOW_REDIRECTS​

  • 类型: bool
  • 默认值: False
  • 描述: 控制整个应用程序中的出站 HTTP 请求是否遵循 3xx 重定向。当为 False 时（自 v0.9.5 起的默认值），将不遵循重定向——这关闭了一类 SSRF 漏洞，即公共且经验证的 URL 发出 302 重定向到内部地址（RFC 1918、环回地址 127.0.0.1、云元数据服务 169.254.169.254），从而绕过原始的白名单检查。受影响的调用场景包括 RAG 网页加载器、图片加载和 Base64 转换、OAuth 预检、代码解释器登录以及工具服务器执行。仅当您的部署确实需要遵循重定向（例如短链接式 URL），并且您已实施其他 SSRF 保护措施（通常是出口防火墙或涵盖您内部网段的 WEB_FETCH_FILTER_LIST）时，才将其设置为 True。

AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA​

  • 类型: int
  • 默认值: 10
  • 描述: 设置获取工具服务器元数据/配置（例如，加载服务器数据/规范信息）的超时时间（秒）。

AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL​

  • 类型: bool
  • 默认值: True
  • 描述: 专门针对通过 AIOHTTP 客户端进行的工具服务器连接，控制其 SSL/TLS 验证。

AIOHTTP_POOL_CONNECTIONS​

  • 类型: int
  • 默认值: 未设置（无限制）
  • 描述: 用于出站请求（Ollama、OpenAI 兼容端点等）的共享 AIOHTTP 客户端连接池中，允许的最大总并发连接数。未设置时，没有总上限。如果您需要限制出站上游总并发，请降低此值。

AIOHTTP_POOL_CONNECTIONS_PER_HOST​

  • 类型: int
  • 默认值: 未设置（无限制）
  • 描述: 共享 AIOHTTP 连接池中，允许对任何单个主机发起的最大并发连接数。未设置时，没有针对单主机的上限。对于保持在服务商端速率或连接限制以内非常有用。

AIOHTTP_POOL_DNS_TTL​

  • 类型: int
  • 默认值: 300
  • 描述: 共享 AIOHTTP 连接池的 DNS 缓存 TTL（秒）。负值或无效值将退回到 300。对于稳定的基础设施环境，可提高此值；如果上游主机的 IP 经常变动，可降低此值。
信息

Open WebUI 复用单个长生命周期的 AIOHTTP 客户端会话来处理所有出站 HTTP 流量，从而实现了 TCP/TLS 连接复用、共享 DNS 缓存和有界的并发度。上述三个变量用于微调此连接池；在典型的部署中通常不需要设置它们。

REQUESTS_VERIFY​

  • 类型: bool
  • 默认值: True
  • 描述: 控制同步 requests（例如 Tika、外部 Reranker）的 SSL/TLS 验证。设置为 False 可以为自签名证书绕过证书验证。

目录​

DATA_DIR​

  • 类型: str
  • 默认值: ./data
  • 描述: 指定数据存储的基准目录，包括上传的文件、缓存、向量数据库等。

FONTS_DIR​

  • 类型: str
  • 描述: 指定字体文件目录。

FRONTEND_BUILD_DIR​

  • 类型: str
  • 默认值: ../build
  • 描述: 指定构建后的前端静态文件位置。

STATIC_DIR​

  • 类型: str
  • 默认值: ./static
  • 描述: 指定静态文件目录，例如网站图标（Favicon）。

日志​

GLOBAL_LOG_LEVEL​

  • 类型: str
  • 默认值: INFO
  • 描述: 设置所有 Open WebUI 组件的全局日志记录级别。有效值包括：DEBUG, INFO, WARNING, ERROR, CRITICAL。

LOG_FORMAT​

  • 类型: str
  • 默认值: 未设置（明文日志输出）
  • 描述: 控制日志的输出格式。设置为 json 时，可以将所有 stdout 日志切换为单行 JSON 对象，适用于 Loki, Fluentd, CloudWatch 和 Datadog 等日志收集器。当设置为 json 时，ASCII 启动横幅（Banner）也会被抑制，以保持日志流的可解析性。任何其他值（或未设置值）都会使用默认的明文格式。有关日志字段和示例的更多详情，请参阅 JSON 日志文档。

ENABLE_AUDIT_STDOUT​

  • 类型: bool
  • 默认值: False
  • 描述: 控制审计日志是否输出到 stdout（控制台）。这在通过 stdout 收集日志的容器化环境中非常有用。

ENABLE_AUDIT_LOGS_FILE​

  • 类型: bool
  • 默认值: True
  • 描述: 控制审计日志是否写入到文件中。启用时，日志将写入到 AUDIT_LOGS_FILE_PATH 指定的位置。

AUDIT_LOGS_FILE_PATH​

  • 类型: str
  • 默认值: ${DATA_DIR}/audit.log
  • 描述: 配置审计日志文件的存储位置。允许将日志存储在独立的持久卷或自定义位置中，以便更好地组织和持久化。
  • 示例: /var/log/openwebui/audit.log, /mnt/logs/audit.log

AUDIT_LOG_FILE_ROTATION_SIZE​

  • 类型: str
  • 默认值: 10MB
  • 描述: 指定审计日志文件触发轮转（Rotation）的最大体积（例如：10MB, 100MB, 1GB）。

AUDIT_UVICORN_LOGGER_NAMES​

  • 类型: str
  • 默认值: uvicorn.access
  • 描述: 以逗号分隔的日志记录器（Logger）名称列表，用于捕获进行审计日志记录。默认捕获 Uvicorn 的 access 日志记录器。

AUDIT_LOG_LEVEL​

  • 类型: str
  • 默认值: NONE
  • 可用选项: NONE, METADATA, REQUEST, REQUEST_RESPONSE
  • 描述: 控制审计日志记录的详细程度。METADATA 记录基本请求信息，REQUEST 包含请求体内容，REQUEST_RESPONSE 同时包含请求体和响应体内容。

MAX_BODY_LOG_SIZE​

  • 类型: int
  • 默认值: 2048
  • 描述: 设置审计日志中请求体/响应体内容记录的最大字节数。超出此体积的报文体将被截断。

AUDIT_EXCLUDED_PATHS​

  • 类型: str
  • 默认值: /chats,/chat,/folders
  • 描述: 以逗号分隔的需要从审计日志中排除的 URL 路径列表（黑名单模式）。系统会将路径去除前导斜杠，并与带有 /api/ 和 /api/v1/ 前缀的路由进行匹配。当设置了 AUDIT_INCLUDED_PATHS 时，此项将被忽略。

AUDIT_INCLUDED_PATHS​

  • 类型: str
  • 默认值: 空字符串（禁用）
  • 描述: 以逗号分隔的需要进行审计日志记录的 URL 路径列表（白名单模式）。当设置此项时，仅会对匹配的路径进行审计记录，且 AUDIT_EXCLUDED_PATHS 将被忽略。系统会将路径去除前导斜杠，并与带有 /api/ 和 /api/v1/ 前缀的路由进行匹配。无论处于何种过滤模式，身份验证相关的端点（signin, signout, signup）都将始终被记录日志。
白名单 vs 黑名单

在默认情况下，审计日志采用黑名单模式 —— 除 AUDIT_EXCLUDED_PATHS 中指定的路径外，所有路径都会被记录日志。如果您设置了 AUDIT_INCLUDED_PATHS，它将切换到白名单模式 —— 仅记录指定的路径。如果两项都设置了，白名单模式将优先，并且会在启动时记录一条警告日志。

Ollama​

ENABLE_OLLAMA_API​

  • 类型: bool
  • 默认值: True
  • 描述: 启用对 Ollama API 的使用。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OLLAMA_BASE_URL（OLLAMA_API_BASE_URL 已废弃）​

  • 类型: str
  • 默认值: http://localhost:11434
  • Docker 默认值:
    • 如果设置了 K8S_FLAG: http://ollama-service.open-webui.svc.cluster.local:11434
    • 如果 USE_OLLAMA_DOCKER=True: http://localhost:11434
    • 否则为 http://host.docker.internal:11434
  • 描述: 配置 Ollama 后端的 URL。

OLLAMA_BASE_URLS​

  • 类型: str
  • 描述: 配置以分号 ; 分隔的负载均衡 Ollama 后端主机列表。参见 OLLAMA_BASE_URL。此项优先于 OLLAMA_BASE_URL。
  • 示例: http://host-one:11434;http://host-two:11434
  • 持久化: 此环境变量是 PersistentConfig 变量。

USE_OLLAMA_DOCKER​

  • 类型: bool
  • 默认值: False
  • 描述: 在构建 Docker 镜像时打包内置的 Ollama 实例。

K8S_FLAG​

  • 类型: bool
  • 默认值: False
  • 描述: 如果设置此项，系统将假定采用 Helm Chart 部署，并自动将 OLLAMA_BASE_URL 设置为 http://ollama-service.open-webui.svc.cluster.local:11434

OpenAI​

ENABLE_OPENAI_API​

  • 类型: bool
  • 默认值: True
  • 描述: 启用对 OpenAI API 的使用。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OPENAI_API_BASE_URL​

  • 类型: str
  • 默认值: https://api.openai.com/v1
  • 描述: 配置 OpenAI 基础 API URL。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OPENAI_API_BASE_URLS​

  • 类型: str
  • 描述: 支持以分号分隔的负载均衡 OpenAI 基础 API URL 列表。
  • 示例: http://host-one:11434;http://host-two:11434
  • 持久化: 此环境变量是 PersistentConfig 变量。

OPENAI_API_KEY​

  • 类型: str
  • 描述: 设置 OpenAI API 密钥。
  • 示例: sk-124781258123
  • 持久化: 此环境变量是 PersistentConfig 变量。
服务商密钥范围（重要说明）

对于 OpenAI 兼容的后端和代理（包括 LiteLLM），在可能的情况下，请务必针对普通用户流量配置具有“最小权限（Least-Privilege）”的密钥。

除非您的部署明确需要并信任相应的特权级别，否则绝不要使用服务商的管理密钥（Management/Master Keys）。

OPENAI_API_KEYS​

  • 类型: str
  • 描述: 支持以分号分隔的多个 OpenAI API 密钥。
  • 示例: sk-124781258123;sk-4389759834759834
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_OPENAI_API_PASSTHROUGH​

  • 类型: bool
  • 默认值: False
  • 描述: 启用时，OpenAI 代理的通用路由（/{path:path}）会将任何请求直接转发给上游 OpenAI 兼容的 API，使用管理员配置的 API 密钥，且不进行额外的访问控制。禁用时（默认值），通用路由将返回 403 Forbidden。其他路由器（Ollama, Responses）没有通用的代理。
危险

除非您明确需要，否则请保持禁用状态。 通用代理在转发请求给上游 API 时，直接使用管理员的 API 密钥，且没有任何模型层面的访问控制。任何已通过身份验证的用户都可以使用管理员的凭据，访问任何上游 API 端点（包括 Open WebUI 本身未提供原生处理的端点）。只有当您完全理解并接受上述安全隐患时，方可启用此项。

任务​

TASK_MODEL​

  • 类型: str
  • 描述: 在使用 Ollama 模型时，用于聊天标题自动生成和网页搜索查询词生成等任务的默认模型。
  • 持久化: 此环境变量是 PersistentConfig 变量。

TASK_MODEL_EXTERNAL​

  • 类型: str
  • 描述: 在使用 OpenAI 兼容端点时，用于聊天标题自动生成和网页搜索查询词生成等任务的默认模型。
  • 持久化: 此环境变量是 PersistentConfig 变量。

TITLE_GENERATION_PROMPT_TEMPLATE​

  • 类型: str
  • 描述: 生成聊天标题时使用的提示词模板。
  • 默认值: DEFAULT_TITLE_GENERATION_PROMPT_TEMPLATE 环境变量的值。

DEFAULT_TITLE_GENERATION_PROMPT_TEMPLATE:


### Task:
Generate a concise, 3-5 word title with an emoji summarizing the chat history.

### Guidelines:
- The title should clearly represent the main theme or subject of the conversation.
- Use emojis that enhance understanding of the topic, but avoid quotation marks or special formatting.
- Write the title in the chat's primary language; default to English if multilingual.
- Prioritize accuracy over excessive creativity; keep it clear and simple.

### Output:
JSON format: { "title": "your concise title here" }

### Examples:
- { "title": "📉 Stock Market Trends" },
- { "title": "🍪 Perfect Chocolate Chip Recipe" },
- { "title": "Evolution of Music Streaming" },
- { "title": "Remote Work Productivity Tips" },
- { "title": "Artificial Intelligence in Healthcare" },
- { "title": "🎮 Video Game Development Insights" }

### Chat History:
<chat_history>
{{MESSAGES:END:2}}
</chat_history>
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_FOLLOW_UP_GENERATION​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用后续追问生成。
  • 持久化: 此环境变量是 PersistentConfig 变量。

FOLLOW_UP_GENERATION_PROMPT_TEMPLATE​

  • 类型: str
  • 描述: 用于生成数个相关后续追问问题的提示词模板。
  • 默认值: DEFAULT_FOLLOW_UP_GENERATION_PROMPT_TEMPLATE 环境变量的值。

DEFAULT_FOLLOW_UP_GENERATION_PROMPT_TEMPLATE:


### Task:
Suggest 3-5 relevant follow-up questions or prompts that the user might naturally ask next in this conversation as a **user**, based on the chat history, to help continue or deepen the discussion.

### Guidelines:
- Write all follow-up questions from the user’s point of view, directed to the assistant.
- Make questions concise, clear, and directly related to the discussed topic(s).
- Only suggest follow-ups that make sense given the chat content and do not repeat what was already covered.
- If the conversation is very short or not specific, suggest more general (but relevant) follow-ups the user might ask.
- Use the conversation's primary language; default to English if multilingual.
- Response must be a JSON array of strings, no extra text or formatting.

### Output:
JSON format: { "follow_ups": ["Question 1?", "Question 2?", "Question 3?"] }

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
  • 持久化: 此环境变量是 PersistentConfig 变量。

TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE​

  • 类型: str
  • 描述: 调用工具（Tools）时使用的提示词模板。
  • 默认值: DEFAULT_TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE 环境变量的值。

DEFAULT_TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE:

Available Tools: {{TOOLS}}

Your task is to choose and return the correct tool(s) from the list of available tools based on the query. Follow these guidelines:

- Return only the JSON object, without any additional text or explanation.

- If no tools match the query, return an empty array:
   {
     "tool_calls": []
   }

- If one or more tools match the query, construct a JSON response containing a "tool_calls" array with objects that include:
   - "name": The tool's name.
   - "parameters": A dictionary of required parameters and their corresponding values.

The format for the JSON response is strictly:
{
  "tool_calls": [
    {"name": "toolName1", "parameters": {"key1": "value1"}},
    {"name": "toolName2", "parameters": {"key2": "value2"}}
  ]
}
  • 持久化: 此环境变量是 PersistentConfig 变量。

代码执行​

ENABLE_CODE_EXECUTION​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用代码执行。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_EXECUTION_ENGINE​

  • 类型: str
  • 默认值: pyodide
  • 描述: 指定要使用的代码执行引擎。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_EXECUTION_JUPYTER_URL​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于代码执行的 Jupyter URL。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_EXECUTION_JUPYTER_AUTH​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于代码执行的 Jupyter 身份验证方法。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_EXECUTION_JUPYTER_AUTH_TOKEN​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于代码执行的 Jupyter 身份验证 Token。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_EXECUTION_JUPYTER_AUTH_PASSWORD​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于代码执行的 Jupyter 身份验证密码。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_EXECUTION_JUPYTER_TIMEOUT​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 Jupyter 代码执行的超时时间。
  • 持久化: 此环境变量是 PersistentConfig 变量。

代码解释器​

ENABLE_CODE_INTERPRETER​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用代码解释器。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_INTERPRETER_ENGINE​

  • 类型: str
  • 默认值: pyodide
  • 描述: 指定要使用的代码解释器引擎。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_INTERPRETER_BLACKLISTED_MODULES​

  • 类型: str (以逗号分隔的模块名称列表)
  • 默认值: 无
  • 描述: 指定在代码解释器中被列入黑名单、无法导入或使用的 Python 模块列表。这可以通过阻止对潜在敏感或系统级功能的访问来增强系统安全性。

CODE_INTERPRETER_PROMPT_TEMPLATE​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于代码解释器的提示词模板。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_INTERPRETER_JUPYTER_URL​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定用于代码解释器的 Jupyter URL。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_INTERPRETER_JUPYTER_AUTH​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定用于代码解释器的 Jupyter 身份验证方法。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_INTERPRETER_JUPYTER_AUTH_TOKEN​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定用于代码解释器的 Jupyter 身份验证 Token。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_INTERPRETER_JUPYTER_AUTH_PASSWORD​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定用于代码解释器的 Jupyter 身份验证密码。
  • 持久化: 此环境变量是 PersistentConfig 变量。

CODE_INTERPRETER_JUPYTER_TIMEOUT​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 Jupyter 代码解释器的超时时间。
  • 持久化: 此环境变量是 PersistentConfig 变量。

直接连接 (OpenAPI/MCPO 工具服务器)​

ENABLE_DIRECT_CONNECTIONS​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用直接连接功能。
  • 持久化: 此环境变量是 PersistentConfig 变量。

TOOL_SERVER_CONNECTIONS​

  • 类型: str (JSON 数组)
  • 默认值: []
  • 描述: 指定一个工具服务器连接配置的 JSON 数组。每个连接都应该定义必要的参数，以连接到实现 OpenAPI/MCPO 协议的外部工具服务器。对于基于 mcpo 的路由，path 应当指向已挂载的工具路由。JSON 必须格式正确，否则将退回使用空数组。
  • 字段说明:
    • url: 服务器的 Base URL。
    • path: 服务器暴露的具体工具路由。
    • auth_type: 连接的身份验证模式。
    • key: 所选身份验证模式使用的 API 密钥或 Token。
    • config: 单个连接配置对象，例如 { "enable": true }。
    • info: 在 UI 中显示的可选元数据，例如连接名称和描述。
    • spec_type / spec: 当连接基于规格 URL 或文件时，提供 OpenAPI 规格的位置信息。
  • 示例:
[
  {
    "type": "openapi",
    "url": "example-url",
    "spec_type": "url",
    "spec": "",
    "path": "openapi.json",
    "auth_type": "none",
    "key": "",
    "config": { "enable": true },
    "info": {
      "id": "",
      "name": "example-server",
      "description": "MCP server description."
    }
  }
]
  • 持久化: 此环境变量是 PersistentConfig 变量。
注意

随着新功能的引入，TOOL_SERVER_CONNECTIONS 的 JSON 数据结构可能会随着时间推移而演进。

终端服务器​

TERMINAL_SERVER_CONNECTIONS​

  • 类型: str (JSON 数组)
  • 默认值: []
  • 描述: 指定一个终端服务器连接配置的 JSON 数组。每个连接都定义了连接到 Open Terminal 实例或 Terminals orchestrator 所需的参数。与用户级别的工具服务器连接不同，这些是由管理员配置并通过 Open WebUI 进行代理的，这意味着终端 URL 和 API 密钥永远不会暴露给浏览器。支持通过 access_grants 进行基于组的访问控制。
  • 示例（直连 Open Terminal）：
[
  {
    "id": "unique-id",
    "url": "http://open-terminal:8000",
    "key": "your-api-key",
    "name": "Dev Terminal",
    "auth_type": "bearer",
    "config": {
      "access_grants": []
    }
  }
]
  • 示例（连接 Terminals 编排器）：
[
  {
    "id": "terminals",
    "url": "http://terminals-orchestrator:8080",
    "key": "your-api-key",
    "name": "Terminals",
    "auth_type": "bearer",
    "config": {
      "access_grants": [
        {"principal_type": "user", "principal_id": "*", "permission": "read"}
      ]
    }
  }
]
  • 持久化: 此环境变量是 PersistentConfig 变量。
Helm Chart 自动配置

在 Kubernetes 上使用 Open WebUI Helm Chart 部署且 terminals.enabled: true 时，会自动设置此变量以指向集群内部的编排器服务。有关详情，请参阅 Terminals (Orchestrator) 编排器指南。

注意

随着新功能的引入，TERMINAL_SERVER_CONNECTIONS 的 JSON 数据结构可能会随着时间推移而演进。

TERMINAL_PROXY_HEADERS​

  • 类型: str (JSON 对象)

  • 默认值: {}

  • 描述: 要注入到由终端代理返回的响应中的自定义 HTTP 响应头。终端代理会自动从上游响应中剥离一组固定的逐跳（Hop-by-hop）以及安全敏感的请求头；然后将此对象中的条目合并进来并优先应用冲突项，这使得管理员可以为代理终端内容设置针对部署的特定请求头，而无需改动应用程序。无效的 JSON 将回退到 {} 且不添加任何响应头。

    安全注意事项： 默认值 {} 意味着代理直接在 Open WebUI 同源（Same Origin）策略下将上游内容（HTML, JS 等）原封不动地进行转发。这是经过深思熟虑的——许多合规的 Open Terminal 使用场景（开发服务器、内部工具、管理员通过终端运行的 Web UI）都依赖于在代理响应中执行 JavaScript。对于相互信任的用户共享单个终端服务器连接的多用户部署，这没有任何问题。然而，对于同一信任组中的用户需要彼此间代理内容进行额外隔离的部署（或者终端服务器功能被公开给较低信任级别用户，超出已文档化的 多用户设置层级），请将其设置为沙箱 CSP，从而将代理 JS 锁定到不透明的源中，同时仍允许其在合法工作流中运行：

    TERMINAL_PROXY_HEADERS='{"Content-Security-Policy": "sandbox allow-scripts; default-src '\''none'\''; img-src '\''self'\'' data:; style-src '\''unsafe-inline'\''", "X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer", "X-Frame-Options": "DENY"}'

    注意：不要在 sandbox 指令中添加 allow-same-origin。此关键字会使使得沙箱防止 localStorage 信息外泄的源隔离失效。上述示例已特意将其省去。

自动补全​

ENABLE_AUTOCOMPLETE_GENERATION​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用自动补全生成。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

在启用 ENABLE_AUTOCOMPLETE_GENERATION 时，请确保您也相应配置了 AUTOCOMPLETE_GENERATION_INPUT_MAX_LENGTH 和 AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE。

AUTOCOMPLETE_GENERATION_INPUT_MAX_LENGTH​

  • 类型: int
  • 默认值: -1
  • 描述: 设置自动补全输入的最大长度。
  • 持久化: 此环境变量是 PersistentConfig 变量。

AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE​

  • 类型: str
  • 默认值: DEFAULT_AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE 环境变量的值。

DEFAULT_AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE:


### Task:
You are an autocompletion system. Continue the text in `<text>` based on the **completion type** in `<type>` and the given language.

### **Instructions**:
1. Analyze `<text>` for context and meaning.
2. Use `<type>` to guide your output:
   - **General**: Provide a natural, concise continuation.
   - **Search Query**: Complete as if generating a realistic search query.
3. Start as if you are directly continuing `<text>`. Do **not** repeat, paraphrase, or respond as a model. Simply complete the text.
4. Ensure the continuation:
   - Flows naturally from `<text>`.
   - Avoids repetition, overexplaining, or unrelated ideas.
5. If unsure, return: `{ "text": "" }`.

### **Output Rules**:
- Respond only in JSON format: `{ "text": "<your_completion>" }`.

### **Examples**:

#### Example 1:
Input:
<type>General</type>
<text>The sun was setting over the horizon, painting the sky</text>
Output:
{ "text": "with vibrant shades of orange and pink." }

#### Example 2:
Input:
<type>Search Query</type>
<text>Top-rated restaurants in</text>
Output:
{ "text": "New York City for Italian cuisine." }

---

### Context:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
<type>{{TYPE}}</type>
<text>{{PROMPT}}</text>

#### Output:
  • 描述: 设置自动补全生成所使用的提示词模板。
  • 持久化: 此环境变量是 PersistentConfig 变量。

评估竞技场模型​

ENABLE_EVALUATION_ARENA_MODELS​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用评估竞技场模型。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_MESSAGE_RATING​

  • 类型: bool
  • 默认值: True
  • 描述: 启用消息评分功能。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_COMMUNITY_SHARING​

  • 类型: bool
  • 默认值: True
  • 描述: 控制用户是否可以向 Open WebUI 社区共享内容并访问社区资源。启用后，此设置将在整个应用程序中展示以下 UI 元素：
    • 提示词工作区（Prompts Workspace）：“由 Open WebUI 社区制作”部分，其中包含发现社区提示词的链接，以及提示词菜单下拉列表中的“共享”按钮。
    • 工具工作区（Tools Workspace）：“由 Open WebUI 社区制作”部分，其中包含发现社区工具的链接，以及工具菜单下拉列表中的“共享”按钮。
    • 模型工作区（Models Workspace）：“由 Open WebUI 社区制作”部分，其中包含发现社区模型预设的链接，以及模型菜单下拉列表中的“共享”按钮。
    • 自定义函数管理员面（Functions Admin）：“由 Open WebUI 社区制作”部分，其中包含发现社区函数的链接。
    • 共享对话模态窗（Share Chat Modal）：共享对话时展示“共享到 Open WebUI 社区”按钮。
    • 评估反馈（Evaluation Feedbacks）：“共享到 Open WebUI 社区”按钮，用于向社区排行榜贡献反馈历史记录。
    • 统计同步模态窗（Stats Sync Modal）：允许向社区同步使用情况统计信息。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

当 ENABLE_COMMUNITY_SHARING 设置为 False 时，所有社区共享按钮和社区资源发现部分都将从 UI 中隐藏。用户仍可以从本地导出内容，但无法使用直接共享到 Open WebUI 社区的选项。

标签生成​

ENABLE_TAGS_GENERATION​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用标签生成。
  • 持久化: 此环境变量是 PersistentConfig 变量。

TAGS_GENERATION_PROMPT_TEMPLATE​

  • 类型: str
  • 默认值: DEFAULT_TAGS_GENERATION_PROMPT_TEMPLATE 环境变量的值。

DEFAULT_TAGS_GENERATION_PROMPT_TEMPLATE:


### Task:
Generate 1-3 broad tags categorizing the main themes of the chat history, along with 1-3 more specific subtopic tags.

### Guidelines:
- Start with high-level domains (e.g., Science, Technology, Philosophy, Arts, Politics, Business, Health, Sports, Entertainment, Education)
- Consider including relevant subfields/subdomains if they are strongly represented throughout the conversation
- If content is too short (less than 3 messages) or too diverse, use only ["General"]
- Use the chat's primary language; default to English if multilingual
- Prioritize accuracy over specificity

### Output:
JSON format: { "tags": ["tag1", "tag2", "tag3"] }

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
  • 描述: 设置标签生成的提示词模板。
  • 持久化: 此环境变量是 PersistentConfig 变量。

API 密钥端点限制​

ENABLE_API_KEYS​

  • 类型: bool
  • 默认值: False
  • 描述: 启用 API 密钥创建功能，允许用户生成 API 密钥以编程方式访问 Open WebUI。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

此变量取代了已被废弃的 ENABLE_API_KEY 环境变量。

信息

为了使 API 密钥的创建（以及 API 密钥本身）正常工作，需要满足以下条件：

  1. 使用此设置（ENABLE_API_KEYS）在全局启用 API 密钥。
  2. 对于非管理员用户，通过默认权限（Default Permissions）或用户组（User Groups）授予“API 密钥”权限。

注意： 只要启用了 ENABLE_API_KEYS，管理员便可随时生成 API 密钥，即使没有配置 features.api_keys。

ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS​

  • 类型: bool
  • 默认值: False
  • 描述: 启用 API 密钥端点限制以增强安全性和可配置性，允许管理员限制哪些端点可以通过 API 密钥进行访问。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

此变量取代了已被废弃的 ENABLE_API_KEY_ENDPOINT_RESTRICTIONS 环境变量。

API_KEYS_ALLOWED_ENDPOINTS​

  • 类型: str
  • 描述: 当启用了 API 密钥端点限制时，指定允许通过 API 密钥进行访问的端点 URL（以逗号分隔）。
  • 示例: /api/v1/messages,/api/v1/channels,/api/v1/chat/completions
  • 持久化: 此环境变量是 PersistentConfig 变量。
备注

API_KEYS_ALLOWED_ENDPOINTS 的值应为端点 URL 的逗号分隔列表，例如 /api/v1/messages, /api/v1/channels。

信息

此变量取代了已被废弃的 API_KEY_ALLOWED_ENDPOINTS 环境变量。

CUSTOM_API_KEY_HEADER​

  • 类型: str
  • 默认值: x-api-key
  • 描述: 身份验证中间件在检查 API 密钥凭据时检索的 HTTP 响应头名称。这对于将 Open WebUI 部署在反向代理或 API 网关后面，且该代理/网关会出于自身的身份验证机制消耗掉 Authorization 请求头的情况非常有用 —— 可以通过将此变量设置为一个独特的请求头（例如 X-OpenWebUI-Key），以便客户端能向系统提供它们的 Open WebUI API 密钥而不会与反向代理的身份验证相冲突。
  • 在启动时从进程运行环境中读取（不是 PersistentConfig）。

身份验证中间件获取凭据的检测顺序：

  1. Authorization: Bearer <token>（最常见 —— API 密钥或 JWT）
  2. token cookie（Bearer —— 由 WebUI 自身使用）
  3. 由 CUSTOM_API_KEY_HEADER 指定的请求头（默认值为 x-api-key）

如果以上三者都不存在，该请求将作为匿名请求被直接放行。

部署在吞掉 Authorization 的代理后面？

许多企业网关（基本身份验证、双向 TLS 适配器、SSO Sidecars）会消耗掉 Authorization 请求头且绝不会将其转发给上游。在这种情况下，请让您的客户端改用自定义的请求头：

curl -H "X-OpenWebUI-Key: sk-..." http://openwebui.internal/api/models

并在 Open WebUI 容器上设置环境变量：

CUSTOM_API_KEY_HEADER=X-OpenWebUI-Key

ASGI 层会对请求头名称执行不区分大小写的匹配，因此可根据您团队的命名惯例选择合适的值。

模型缓存​

ENABLE_BASE_MODELS_CACHE​

  • 类型: bool
  • 默认值: False
  • 描述: 启用后，会在内存中缓存来自已连接的 Ollama 和 OpenAI 兼容端点的基础模型列表。这减少了在加载模型选择器时向外部模型服务商发起的 API 调用次数，改善了系统的响应性能，特别是对于拥有大量用户或模型端点连接较慢的部署环境。也可以在 管理员面板 > 设置 > 连接 > “缓存基础模型列表”中进行配置。
  • 持久化: 此环境变量是 PersistentConfig 变量。

该缓存是如何工作的：

  • 初始化: 启用后，系统会在应用程序启动期间获取并缓存基础模型。
  • 存储: 缓存保存在应用程序内存中（app.state.BASE_MODELS）。
  • 缓存命中: 后续的模型获取请求将直接返回缓存的列表，而无需联系外部端点。
  • 缓存刷新: 缓存会在以下情况下进行刷新：
    • 应用程序重启
    • 在管理员面板 > 设置 > 连接中保存了连接设置（点击右下角的保存按钮将触发刷新，并使用最新获取的模型更新缓存）
  • 无 TTL: 不存在基于时间的自动过期机制。
性能考量

建议在模型列表相对稳定的生产环境中启用此设置。对于开发环境，或当您需要频繁地从 Ollama 中添加/删除模型时，您可能更希望保持其处于禁用状态，以便进行实时的模型发现。

MODELS_CACHE_TTL​

  • 类型: int
  • 默认值: 1
  • 描述: 设置缓存来自 OpenAI 和 Ollama 端点模型列表响应的生存时间（TTL，秒）。这会通过在指定时长内缓存可用模型列表来减少 API 调用次数。设置为空字符串可以完全禁用缓存。

此设置会缓存从已配置的 OpenAI 兼容和 Ollama API 端点检索出来的外部模型列表（而非 Open WebUI 内部的模型配置）。较高的值会通过减少向外部服务商发起的冗余 API 请求来提高性能，但可能会延迟在这些端点上新添加或已删除模型的呈现时间。设置为 0 时会禁用缓存并强制每次都发起新的 API 调用。

高并发环境推荐配置

在高并发流量场景下，增加此值（例如设置为 300 秒）可以显著减少外部 API 端点上的负载，同时仍能提供足够新鲜的模型数据。

两种缓存机制

Open WebUI 拥有两个独立的模型缓存机制，它们相互独立地工作：

设置项类型默认值刷新触发器
ENABLE_BASE_MODELS_CACHE内存缓存False应用重启 或 管理员保存设置
MODELS_CACHE_TTL基于 TTL 缓存1 秒TTL 到期后自动刷新

为了获得极致的性能，建议同时启用两者：ENABLE_BASE_MODELS_CACHE=True 且 MODELS_CACHE_TTL=300。

JWT_EXPIRES_IN​

  • 类型: str
  • 默认值: 4w
  • 描述: 设置 JWT 到期时间（秒）。有效的单位：s（秒）、m（分钟）、h（小时）、d（天）、w（周），或者 -1 表示永久有效不失效。
  • 持久化: 此环境变量是 PersistentConfig 变量。
注意

将 JWT_EXPIRES_IN 设置为 -1 将会禁用 JWT 过期，从而使签发的 Token 永久有效。这在生产环境中是极其危险的，如果 Token 泄露或被窃取，系统将面临严重的安全性风险。

在生产环境中请务必设置一个合理的过期时间（例如 3600s, 1h, 7d 等），以限制身份验证 Token 的生命周期。

绝对不要在生产环境中使用 -1。

如果您已经使用 JWT_EXPIRES_IN=-1 进行了部署，您可以轮换或更改您的 WEBUI_SECRET_KEY，以立即使所有现有 Token 失效。

安全变量​

ENABLE_FORWARD_USER_INFO_HEADERS​

  • 类型: bool
  • 默认值: False
  • 描述: 将用户和会话信息以 HTTP 请求头的形式转发给 OpenAI API, Ollama API, MCP 服务器和工具服务器。 如果启用，以下请求头将被转发：
    • X-OpenWebUI-User-Name
    • X-OpenWebUI-User-Id
    • X-OpenWebUI-User-Email
    • X-OpenWebUI-User-Role
    • X-OpenWebUI-Chat-Id
    • X-OpenWebUI-Message-Id

这为外部服务提供了单用户层面的授权、审计、限流和请求追踪等能力。聊天 ID 和消息 ID 请求头同样也是 外部工具事件触发 所必需的。

FORWARD_USER_INFO_HEADER_USER_NAME​

  • 类型: str
  • 默认值: X-OpenWebUI-User-Name
  • 描述: 自定义用于转发用户显示名称的请求头。如果您的基础架构需要特定前缀的请求头，请更改此值。

FORWARD_USER_INFO_HEADER_USER_ID​

  • 类型: str
  • 默认值: X-OpenWebUI-User-Id
  • 描述: 自定义用于转发用户 ID 的请求头。

FORWARD_USER_INFO_HEADER_USER_EMAIL​

  • 类型: str
  • 默认值: X-OpenWebUI-User-Email
  • 描述: 自定义用于转发用户邮箱的请求头。

FORWARD_USER_INFO_HEADER_USER_ROLE​

  • 类型: str
  • 默认值: X-OpenWebUI-User-Role
  • 描述: 自定义用于转发用户角色的请求头。

FORWARD_SESSION_INFO_HEADER_CHAT_ID​

  • 类型: str
  • 默认值: X-OpenWebUI-Chat-Id
  • 描述: 自定义用于转发当前聊天/会话 ID 的请求头。

FORWARD_SESSION_INFO_HEADER_MESSAGE_ID​

  • 类型: str
  • 默认值: X-OpenWebUI-Message-Id
  • 描述: 自定义用于转发当前消息 ID 的请求头。此请求头是 外部工具事件触发 所必需的。
自定义请求头前缀

当集成需要特定请求头命名规范的服务时，请使用这些变量。例如，AWS Bedrock AgentCore 要求请求头必须以 X-Amzn-Bedrock-AgentCore-Runtime-Custom- 为前缀：

FORWARD_USER_INFO_HEADER_USER_NAME=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Name
FORWARD_USER_INFO_HEADER_USER_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Id
FORWARD_USER_INFO_HEADER_USER_EMAIL=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Email
FORWARD_USER_INFO_HEADER_USER_ROLE=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Role
FORWARD_SESSION_INFO_HEADER_CHAT_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Chat-Id
FORWARD_SESSION_INFO_HEADER_MESSAGE_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Message-Id

ENABLE_WEB_LOADER_SSL_VERIFICATION​

  • 类型: bool
  • 默认值: True
  • 描述: 对网站上的 RAG 抓取操作，跳过 SSL 验证。
  • 持久化: 此环境变量是 PersistentConfig 变量。
  • 类型: str
  • 可用选项:
    • lax - 将 SameSite 属性设置为 lax，允许在由第三方网站发起的请求中发送会话 Cookie。
    • strict - 将 SameSite 属性设置为 strict，阻止在由第三方网站发起的请求中发送会话 Cookie。
    • none - 将 SameSite 属性设置为 none，允许在由第三方网站发起的请求中发送会话 Cookie，但必须在 HTTPS 协议下。
  • 默认值: lax
  • 描述: 设置会话 Cookie 的 SameSite 属性。
注意

当启用了 ENABLE_OAUTH_SIGNUP 时，将 WEBUI_SESSION_COOKIE_SAME_SITE 设置为 strict 可能会导致登录失败。这是因为 Open WebUI 需要使用会话 Cookie 来校验来自 OAuth 服务商的回调请求，这有助于防止 CSRF 攻击。

然而，strict 级别的会话 Cookie 不会在回调请求中被发送，从而导致潜在的登录问题。如果您遇到此问题，请改用默认的 lax 值。

  • 类型: bool
  • 默认值: False
  • 描述: 设置为 True 时，为会话 Cookie 启用 Secure 属性。
  • 类型: str
  • 可用选项:
    • lax - 将 SameSite 属性设置为 lax，允许在由第三方网站发起的请求中发送身份验证 Cookie。
    • strict - 将 SameSite 属性设置为 strict，阻止在由第三方网站发起的请求中发送身份验证 Cookie。
    • none - 将 SameSite 属性设置为 none，允许在由第三方网站发起的请求中发送身份验证 Cookie，但必须在 HTTPS 协议下。
  • 默认值: lax
  • 描述: 设置身份验证 Cookie 的 SameSite 属性。
信息

如果该值未设置，将退回到使用 WEBUI_SESSION_COOKIE_SAME_SITE。

  • 类型: bool
  • 默认值: False
  • 描述: 设置为 True 时，为身份验证 Cookie 启用 Secure 属性。
信息

如果该值未设置，将退回到使用 WEBUI_SESSION_COOKIE_SECURE。

WEBUI_AUTH​

  • 类型: bool
  • 默认值: True
  • 描述: 此设置用于启用或禁用身份验证。
危险

如果设置为 False，您的 Open WebUI 实例将禁用身份验证。然而，需要特别指出的是，只有在没有任何注册用户的全新安装时，才允许关闭身份验证。如果数据库中已经存在已注册的用户，您将无法直接禁用身份验证。如果您打算关闭 WEBUI_AUTH，请确保数据库中不存在任何用户。

ENABLE_PASSWORD_VALIDATION​

  • 类型: bool
  • 默认值: False
  • 描述: 为用户账户启用密码复杂度验证。启用时，密码在注册、密码更新和用户创建操作中必须满足由 PASSWORD_VALIDATION_REGEX_PATTERN 定义的复杂度要求。这有助于在整个应用程序中强制实施更强大的密码策略。
信息

密码校验适用于以下场景：

  • 新用户注册
  • 通过用户设置修改密码
  • 管理员启动的用户创建
  • 密码重置

拥有不符合新要求的密码的现有用户不会被强制要求自动更新其密码，但他们在下一次修改密码时需要满足这些新要求。

PASSWORD_VALIDATION_REGEX_PATTERN​

  • 类型: str
  • 默认值: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^\w\s]).{8,}$
  • 描述: 当启用了 ENABLE_PASSWORD_VALIDATION 时，用于验证密码复杂度的正则表达式模式。默认模式要求密码长度至少为 8 个字符，且至少包含一个大写字母、一个小写字母、一个数字以及一个特殊字符。
注意

自定义模式的注意事项

在定义自定义正则表达式模式时，请确保：

  • 它是一个可以被 Python 的 re 模块正常编译的有效正则表达式
  • 在安全要求和用户体验之间取得良好平衡
  • 在部署之前经过充分测试，以免将用户锁定在系统外

无效的正则表达式模式会导致密码验证出错，并可能阻碍用户的正常注册和密码修改。

PASSWORD_VALIDATION_HINT​

  • 类型: str
  • 默认值: ""（空字符串）
  • 描述: 当用户密码未通过复杂度校验时，向用户展示的自定义提示消息。当密码不满足由 PASSWORD_VALIDATION_REGEX_PATTERN 定义的要求时，此消息将以错误弹窗的形式展现在用户注册、密码修改以及管理员创建用户界面。请用对用户友好的文字来解释您特定的密码要求。
  • 示例: 密码必须至少为 12 位，且包含大小写字母、数字及特殊字符。
提示

当配置了自定义的 PASSWORD_VALIDATION_REGEX_PATTERN 时，请务必设置 PASSWORD_VALIDATION_HINT 来以通俗语言解释密码要求。如果没有设置提示，用户在出错时只会看到一个毫无指导意义的通用“密码无效”报错。

WEBUI_SECRET_KEY​

  • 类型: str
  • 默认值: 自动生成（参见下方说明）
  • 描述: 用于对 JSON Web Tokens (JWT) 进行签名，以及加密静态敏感数据（包括 MCP 的 OAuth 凭据）的密钥。可以通过 WEBUI_SECRET_KEY 环境变量或已被废弃的 WEBUI_JWT_SECRET_KEY 历史遗留变量进行设置。
密钥是如何生成的

对于安全的系统安装，您不需要手动配置此变量 —— 所有的标准启动方案在首次启动时，都会自动生成并持久化保存一个密码学安全的随机密钥：

启动方式是否自动生成？持久化保存至
Docker (start.sh)✅ 是容器内的 .webui_secret_key 文件
pip 安装 (open-webui serve)✅ 是工作目录下的 .webui_secret_key 文件
开发环境 (open-webui dev, 直接使用 uvicorn)❌ 否无 —— 回退使用代码层硬编码的值

代码层回退值（t0p-s3cr3t）仅出于开发便利性而存在，当 Open WebUI 通过标准 Docker 或 open-webui serve 方式启动时，该回退值绝不会被使用。上述这两种标准方式在启动前都会先检查环境变量，若未设置，则会自动生成一个安全随机密钥、将其保存到文件并注入到环境中 —— 所有的这些工作都会在应用程序启动前完成。

强烈推荐：配置一个显式的持久化值

虽然自动生成的密钥很安全，但它与容器内或工作目录下的文件紧密绑定。如果容器被重建（而不仅仅是重启），且密钥文件没有保存在持久卷中，系统将自动生成一个全新密钥，这将导致：

  1. 所有已有的用户会话均失效（用户会被强制登出）。
  2. 所有 OAuth 会话均失效。
  3. MCP 工具将报错断开（报错：Error decrypting tokens），因为使用之前密钥加密的 Token 无法再使用新密钥进行解密。

为了避免这种情况，请显式将 WEBUI_SECRET_KEY 设置为一个安全且不随容器重建而消失的持久化值：

# 生成一个安全的随机密钥
openssl rand -hex 32

然后，将其作为环境变量传递到您的 Docker Compose 或部署配置中。

注意

多 Worker 和多节点部署必需，同时在单 Worker 环境中强烈推荐

当使用 UVICORN_WORKERS > 1 或在带有负载均衡器的多节点/多工作节点集群（例如 helm/kubectl/kubernetes/k8s）中部署 Open WebUI 时，您必须在所有副本（Replicas）之间将此变量设置为完全相同的值。否则，将会引发以下严重问题：

  • 跨工作节点之间的会话管理失效
  • 实例之间的应用程序状态不一致
  • 架构部署中的 WebSocket 连接无法正常工作
  • 用户可能会经历断断续续的身份验证失败

ENABLE_VERSION_UPDATE_CHECK​

  • 类型: bool
  • 默认值: True
  • 描述: 启用后，应用程序将进行自动更新检查，并在有新版本发布时通知您。
信息

如果启用了 OFFLINE_MODE，此 ENABLE_VERSION_UPDATE_CHECK 标志将自动强制设置为 false。

OFFLINE_MODE​

  • 类型: bool
  • 默认值: False
  • 描述: 禁用 Open WebUI 的外网网络连接，以阻断版本更新检查和自动模型下载。
信息

启用此项后，以下功能将被禁用：

  • 自动版本更新检查（参见 ENABLE_VERSION_UPDATE_CHECK 标志）
  • 从 Hugging Face 社区下载嵌入模型
    • 如果您在激活 OFFLINE_MODE 之前没有预先下载嵌入模型，则任何 RAG、网页搜索和文档分析功能可能都无法正常工作
  • UI 界面中的更新通知（参见 ENABLE_VERSION_UPDATE_CHECK 标志）

以下功能仍将正常运行：

  • 外部 LLM API 连接（OpenAI 等）
  • OAuth 身份验证服务商
  • 使用外部 API 运行网页搜索和 RAG

有关 离线模式 的更多信息，请阅读 离线模式指南。

HF_HUB_OFFLINE​

  • 类型: int
  • 默认值: 0
  • 描述: 告知 Hugging Face 我们是否希望以离线模式启动，从而不连接 Hugging Face 并阻断所有自动模型下载。
信息

当此项设置为 1 时，模型、Sentence Transformers 以及其他可配置项的下载将无法正常工作。 如果在默认安装下将此项设置为 True，RAG 功能也将无法正常工作。

RESET_CONFIG_ON_START​

  • 类型: bool
  • 默认值: False
  • 描述: 在启动时重置 config.json 文件。

SAFE_MODE​

  • 类型: bool
  • 默认值: False
  • 描述: 启用安全模式，这将停用所有潜在不安全的功能，即禁用所有的 Functions 功能。

CORS_ALLOW_ORIGIN​

  • 类型: str
  • 默认值: *
  • 描述: 设置跨域资源共享（CORS）的允许来源。以分号 ; 分隔的允许来源列表。
注意

此变量必须进行合理配置，否则您可能会遇到 WebSocket 连接故障，并收到奇怪的 "{}" 响应或 "Unexpected token 'd', "data: {"id"... is not valid JSON" 错误。

信息

如果您遇到了 WebSocket 问题，请检查 Open WebUI 的日志。 如果您看到类似于以下的日志行 engineio.base_server:_log_error_once:354 - https://yourdomain.com is not an accepted origin.，这意味着您需要将 CORS_ALLOW_ORIGIN 的范围配置得更宽泛。

示例: CORS_ALLOW_ORIGIN: "https://yourdomain.com;http://yourdomain.com;https://yourhostname;http://youripaddress;http://localhost:3000"

将用户访问您 Open WebUI 时可能会使用的所有有效 IP 地址、域名以及主机名都添加到此变量中。 配置完成后，控制台中便不会再出现 WebSocket 问题或相关警告。

CORS_ALLOW_CUSTOM_SCHEME​

  • 类型: str
  • 默认值: ""（空字符串）
  • 描述: 设置跨域资源共享（CORS）允许的其他自定义协议列表。允许您指定标准 http 和 https 以外的其他自定义 URL 协议作为 CORS 的有效来源。
信息

这对于以下场景特别有用：

  • 与使用自定义协议的桌面应用程序进行集成（例如：app://, custom-app-scheme://）。
  • 可能采用非标准协议的本地开发环境或测试环境（例如，适用的 file:// 或 electron://）。

提供一个以分号分隔的协议名称列表，无需带有 ://。例如：app;file;electron;my-custom-scheme。

配置完成后，这些自定义协议将在 CORS_ALLOW_ORIGIN 中指定的任何来源上与 http 和 https 一起进行验证。

RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE​

  • 类型: bool
  • 默认值: False
  • 描述: 决定是否允许使用在 Hugging Face 社区自带的模型结构文件中定义了自定义结构的模型。

RAG_RERANKING_MODEL_TRUST_REMOTE_CODE​

  • 类型: bool
  • 默认值: False
  • 描述: 决定是否允许使用在 Hugging Face 社区自带的模型结构文件中定义了自定义结构的模型，来进行重排（Reranking）。

RAG_EMBEDDING_MODEL_AUTO_UPDATE​

  • 类型: bool
  • 默认值: True
  • 描述: 切换 Sentence-Transformer 模型的自动更新。

RAG_RERANKING_MODEL_AUTO_UPDATE​

  • 类型: bool
  • 默认值: True
  • 描述: 切换重排模型（Reranking Model）的自动更新。

Vector Database​

VECTOR_DB​

  • 类型: str
  • 可用选项:
    • chroma, elasticsearch, mariadb-vector, milvus, opensearch, pgvector, qdrant, pinecone, s3vector, oracle23ai, weaviate
  • 默认值: chroma
  • 描述: 指定要使用的向量数据库系统。此设置决定了由哪种向量存储系统来负责管理 Embeddings。
ChromaDB (默认值) 对于多 Worker 或多副本部署不安全

默认的 ChromaDB 配置使用了一个由 SQLite 支持的本地 PersistentClient。SQLite 不是 Fork 安全的 —— 当 Uvicorn 派生出多个工作进程（UVICORN_WORKERS > 1）时，每个工作节点都会继承同一 SQLite 连接的副本。来自这些派生进程的并发写入会导致系统立即崩溃（Child process died）或造成数据库损坏。

这也适用于多副本部署环境（Kubernetes, Docker Swarm），即多个容器同时指向同一个 ChromaDB 数据目录。

如果您需要多个 Worker 或多副本，您必须采取以下措施之一：

  1. 切换到客户端-服务器模式的向量数据库，例如 PGVector、MariaDB Vector、Milvus 或 Qdrant（推荐）。
  2. 将 ChromaDB 作为独立的 HTTP 服务器运行，并配置 CHROMA_HTTP_HOST / CHROMA_HTTP_PORT，以便 Open WebUI 使用 HttpClient 而非本地的 PersistentClient。

详见 扩容与高可用指南。

备注

PostgreSQL 依赖项 要使用 pgvector，请确保您已经安装了 PostgreSQL 相关的依赖：

pip install open-webui[all]
信息

Open WebUI 官方团队将仅持续维护 PGVector 和 ChromaDB。 其余的向量数据库存储均由社区添加，并由社区进行维护。

ChromaDB​

本地模式 vs. HTTP 模式

在默认情况下（当没有设置 CHROMA_HTTP_HOST 时），ChromaDB 将作为本地的 PersistentClient 运行，并使用 SQLite 存储。此模式仅对单 Worker、单实例部署是安全的（UVICORN_WORKERS=1，且仅有一个 Replica）。

对于多 Worker 或多副本架构，您必须配置 CHROMA_HTTP_HOST 和 CHROMA_HTTP_PORT 以指向独立的 ChromaDB 服务器，或者切换到其他向量数据库。参见上面的 VECTOR_DB 警告。

CHROMA_TENANT​

  • 类型: str
  • 默认值: chromadb.DEFAULT_TENANT 的值（chromadb 模块中的一个常量）
  • 描述: 设置用于 RAG 嵌入的 ChromaDB 租户（Tenant）。

CHROMA_DATABASE​

  • 类型: str
  • 默认值: chromadb.DEFAULT_DATABASE 的值（chromadb 模块中的一个常量）
  • 描述: 设置用于 RAG 嵌入的 ChromaDB 数据库名称。

CHROMA_HTTP_HOST​

  • 类型: str
  • 描述: 指定远程 ChromaDB 服务器的主机名。未设置时则使用本地的 ChromaDB 实例。对于多 Worker 或多副本部署，必须设置此变量 —— 它会将 ChromaDB 从本地基于 SQLite 的 PersistentClient 切换为 Fork 安全的 HttpClient。

CHROMA_HTTP_PORT​

  • 类型: int
  • 默认值: 8000
  • 描述: 指定远程 ChromaDB 服务器的端口。

CHROMA_HTTP_HEADERS​

  • 类型: str
  • 描述: 在发往 ChromaDB 的每个请求中包含的以逗号分隔的 HTTP 头部列表。
  • 示例: Authorization=Bearer heuhagfuahefj,User-Agent=OpenWebUI。

CHROMA_HTTP_SSL​

  • 类型: bool
  • 默认值: False
  • 描述: 控制与 ChromaDB 服务器的连接是否采用 SSL 加密。

CHROMA_CLIENT_AUTH_PROVIDER​

  • 类型: str
  • 描述: 指定远程 ChromaDB 服务器的身份验证服务商。
  • 示例: chromadb.auth.basic_authn.BasicAuthClientProvider

CHROMA_CLIENT_AUTH_CREDENTIALS​

  • 类型: str
  • 描述: 指定远程 ChromaDB 服务器的身份验证凭据。
  • 示例: username:password

Elasticsearch​

ELASTICSEARCH_API_KEY​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 Elasticsearch API 密钥。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ELASTICSEARCH_CA_CERTS​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 Elasticsearch 的 CA 证书路径。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ELASTICSEARCH_CLOUD_ID​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 Elasticsearch Cloud ID。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ELASTICSEARCH_INDEX_PREFIX​

  • 类型: str
  • 默认值: open_webui_collections
  • 描述: 指定 Elasticsearch 索引前缀。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ELASTICSEARCH_PASSWORD​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 Elasticsearch 的访问密码。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ELASTICSEARCH_URL​

  • 类型: str
  • 默认值: https://localhost:9200
  • 描述: 指定 Elasticsearch 实例的 URL。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ELASTICSEARCH_USERNAME​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 Elasticsearch 的用户名。
  • 持久化: 此环境变量是 PersistentConfig 变量。

Milvus​

注意

Milvus 目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 Milvus，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

MILVUS_URI（必需）​

  • 类型: str
  • 默认值: ${DATA_DIR}/vector_db/milvus.db
  • 示例（远程连接）: http://your-server-ip:19530
  • 描述: 指定用于连接 Milvus 向量数据库的 URI。根据不同的部署配置，此项可以指向本地文件或远程 Milvus 服务器。

MILVUS_DB​

  • 类型: str
  • 默认值: default
  • 示例: default
  • 描述: 指定连接到 Milvus 实例中的哪个数据库。

MILVUS_TOKEN（带身份验证的远程连接必需）​

  • 类型: str
  • 默认值: None
  • 示例: root:password（格式: username:password）
  • 描述: 指定 Milvus 的可选连接 Token。当连接到启用了身份验证的远程 Milvus 服务器时为必需。格式为 username:password。

MILVUS_INDEX_TYPE​

  • 类型: str
  • 默认值: HNSW
  • 可用选项: AUTOINDEX, FLAT, IVF_FLAT, HNSW, DISKANN
  • 描述: 指定在 Milvus 中创建新 Collection 时使用的索引类型。对于 Milvus 单机版，通常推荐使用 AUTOINDEX。HNSW 可以提供更好的性能，但它需要 Milvus 集群架构，并不适用于单机部署。
  • 持久化: 此环境变量是 PersistentConfig 变量。

MILVUS_METRIC_TYPE​

  • 类型: str
  • 默认值: COSINE
  • 可用选项: COSINE, IP, L2
  • 描述: 指定 Milvus 中进行向量相似度检索时的度量类型。
  • 持久化: 此环境变量是 PersistentConfig 变量。

MILVUS_HNSW_M​

  • 类型: int
  • 默认值: 16
  • 描述: 指定 Milvus 中 HNSW 索引类型对应的 M 参数。该值影响构建索引时为每个新元素创建的双向链接数量。仅在 MILVUS_INDEX_TYPE 为 HNSW 时有效。
  • 持久化: 此环境变量是 PersistentConfig 变量。

MILVUS_HNSW_EFCONSTRUCTION​

  • 类型: int
  • 默认值: 100
  • 描述: 指定 Milvus 中 HNSW 索引类型对应的 efConstruction 参数。该值影响构建索引期间用于最近邻搜索的动态列表大小。仅在 MILVUS_INDEX_TYPE 为 HNSW 时有效。
  • 持久化: 此环境变量是 PersistentConfig 变量。

MILVUS_IVF_FLAT_NLIST​

  • 类型: int
  • 默认值: 128
  • 描述: 指定 Milvus 中 IVF_FLAT 索引类型对应的 nlist 参数。这代表聚类单元的数量。仅在 MILVUS_INDEX_TYPE 为 IVF_FLAT 时有效。
  • 持久化: 此环境变量是 PersistentConfig 变量。

MILVUS_DISKANN_MAX_DEGREE​

  • 类型: int
  • 默认值: 56
  • 描述: 当 Milvus 处于 DISKANN 索引模式时，设置最大度数。通常建议保持默认。

MILVUS_DISKANN_SEARCH_LIST_SIZE​

  • 类型: int
  • 默认值: 100
  • 描述: 设置 Milvus DISKANN 的检索列表大小。通常建议保持默认。

ENABLE_MILVUS_MULTITENANCY_MODE​

  • 类型: bool
  • 默认值: false
  • 描述: 启用用于 Milvus 集合管理的“多租户模式”，这会通过合并相似的向量数据结构，来显著降低内存（RAM）使用率和计算开销。控制 Milvus 是否使用多租户集合架构。启用时，所有向量数据都会被合并存储在 5 个共享的 Collection 中（memories, knowledge, files, web_search, hash_based），而不再是为每个资源都创建独立的 Collection。数据的隔离将通过 resource_id 字段而非 Collection 级别的物理分割来实现。
信息

多租户模式的好处：

  • 极其显著地降低内存（RAM）消耗（由潜在的数百个 Collection 缩减至仅 5 个）
  • 减少由于集合管理所带来的额外计算开销
  • 缩短冷启动时长
  • 减轻索引维护成本

技术实现方案：

  • 所有用户记忆存入 {prefix}_memories
  • 所有知识库数据存入 {prefix}_knowledge
  • 所有上传的文件存入 {prefix}_files
  • 网页搜索结果存入 {prefix}_web_search
  • 基于哈希计算的集合存入 {prefix}_hash_based
  • 每条记录都会包含一个与原始集合名称相匹配的 resource_id 字段
  • 查询时会自动根据 resource_id 过滤，以维持数据的逻辑隔离
集合变量默认名称（后缀）代码中的路由与分发逻辑目的与用途
HASH_BASED_COLLECTION_hash_based集合名称是一个 63 位的十六进制字符串（SHA256 哈希值）。缓存通过 # 功能直接抓取的网页 URL 文本。
MEMORY_COLLECTION_memories集合名称以 user-memory- 开头。在实验性的记忆系统中存储特定用户的长期记忆。
FILE_COLLECTION_files集合名称以 file- 开头。存储上传的各类文档（PDF, DOCX 等）。
WEB_SEARCH_COLLECTION_web_search集合名称以 web-search- 开头。存储来自搜索引擎查询的临时过渡结果。
KNOWLEDGE_COLLECTION_knowledge其他所有情况（默认退路）。存储明确创建的知识库（Knowledge Bases）。
信息

从历史单 Collection 模式迁移到多租户模式

当您在已经含有数据的 Milvus 数据库中直接开启多租户模式时，会发生什么：

  • 现有的老 Collections（格式为 open_webui_{collection_name}）仍会保留在 Milvus 中，但 Open WebUI 将无法再读取到它们
  • 新产生的数据将被写入这 5 个共享的多租户 Collection 中
  • 系统中原有的知识库将呈现为“空”，直到它们被重新索引
  • 已上传的文件和历史记忆并不会自动迁移到新的多租户 Schema 中，因此会显示为“丢失”

从普通 Milvus 平滑迁移至多租户 Milvus 的路径：

  • 在开启多租户模式之前，请尽可能先从 UI 导出所有关键的知识库内容。
  • 设置 ENABLE_MILVUS_MULTITENANCY_MODE=true 并重启 Open WebUI。
  • 导航至 系统设置 > 文档 > 点击“重新索引知识库”。

这会且仅会将原知识库中的向量数据重建写入到新的多租户 Collection 中 已上传的文件、用户对话记忆和网页搜索历史并不会通过此操作自动迁移

校验知识库是否可正常访问和使用

  • 如果文件检索至关重要，请重新上传文件（原文件元数据虽然保留，但向量数据由于没有被迁移需要重算）
  • 用户聊天记忆将需要通过开启新的对话来重新生成

清理历史遗留的老 Collections： 在成功完成向多租户 Milvus 的迁移后，原先残留的老 Collections 仍会平白消耗资源。您需要手动删除它们：

  • 使用原生的 Milvus 客户端（pymilvus 或 Attu UI）连接数据库
  • 手动 Drop 掉所有老旧的 Collections

当前的 UI 限制：

  • 尚未提供一键式“迁移并清理”的按钮功能
  • 从 UI 界面执行的向量数据库重置操作（系统设置 > 文档 > 重置向量存储/知识库）将只影响当前活跃模式下的 Collections
  • 历史遗留的老旧 Collections 需要通过 Milvus 数据库客户端工具进行手动清理
注意

核心注意事项

在现有老系统上启用多租户模式前，请知悉：

  • 数据丢失风险：文件向量和用户记忆向量不会被自动迁移。仅有知识库内容能通过“重新索引”实现向新库的自动迁移。
  • 对 Collection 命名规范的强依赖：多租户功能极其依赖 Open WebUI 内部对集合名称的命名约定（user-memory-, file-, web-search- 等前缀规则）。如果 Open WebUI 在未来的升级中更改了这些名称生成规范，多租户路由将会失效，可能导致严重的数据损坏、数据不一致或在不同的资源之间检索到错误的数据。
  • 不支持自动回滚：在多租户模式下写入新数据后，如果再次关闭此功能，系统将无法再读取共享 Collections 中已写入的数据。必须要进行手动导出和重新导入。

对于全新安装的 Open WebUI，不存在任何迁移风险。

对于存在宝贵历史数据的现有老实例：

  • 如果您不想经历复杂的迁移工作并承担潜在的数据丢失风险，请不要迁移至多租户模式。
  • 请理解，旧文件和记忆必须经历重新上传或重新生成。
  • 强烈建议在开发或备份环境中先对迁移工作流进行充分验证！
  • 请评估您系统对内存（RAM）节省的急迫度，是否值得您付出这些迁移的精力。

如要执行彻底重置并直接开启多租户模式：

  • 请先在外部备份所有关键的知识库内容。
  • 导航至 系统设置 > 文档
  • 点击 重置向量存储/知识库（这会删除当前模式下的 Collections 和保存的知识库元数据）
  • 设置 ENABLE_MILVUS_MULTITENANCY_MODE=true
  • 重启 Open WebUI
  • 从零开始重新上传和创建您的知识库
注意

多租户路由的分发，极其依赖 Open WebUI 当前版本的 Collection 命名规范。

如果 Open WebUI 升级时修改了其生成集合名称的规则（例如：修改了 "user-memory-" 前缀、"file-" 前缀、网页检索哈希格式等），此映射分发将立即失效并导致数据被错误地写入。 这可能会在数据库内部造成极其严重的数据污染、数据不一致以及错误的关联！

如果您一定要使用多租户模式，在未来的每次版本大升级前，您都必须仔细检查其 Collection 命名规则是否发生改变，并高度谨慎地执行升级操作（务必提前做好快照和完整备份以备随时回滚）！

MILVUS_COLLECTION_PREFIX​

  • 类型: str
  • 默认值: open_webui
  • 描述: 设置 Milvus 集合名称的前缀。在多租户模式下，Collections 会命名为 {prefix}_memories、{prefix}_knowledge 等。在老单集合模式下，命名为 {prefix}_{collection_name}。修改此值会在 Milvus 中创建一个全新的命名空间——包含老前缀的 Collections 将不再能被 Open WebUI 读取到，但它们仍会残留并占用 Milvus 资源。请将此变量用于在共享的同一个 Milvus 数据库上实现真正的多实例物理隔离，而不是将其用于在单实例的不同模式间进行数据迁移。Milvus 仅支持下划线，使用连字符/中划线会报错。

MariaDB Vector​

注意

MariaDB Vector 目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 MariaDB Vector，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

备注

MariaDB 依赖项

Python 的 mariadb 连接驱动在默认情况下并未内置 —— 它已从捆绑依赖中移除。要使用 mariadb-vector，您必须手动进行安装：

pip install open-webui[mariadb]

官方 Docker 镜像中内置了编译该驱动连接器所需的系统级 C 语言库（libmariadb-dev），因此 pip install open-webui[mariadb] 在容器内部可以直接成功运行而无需安装其他系统包。对于非 Docker 的纯系统部署，在安装 Python 驱动前，您必须先在系统层面安装 MariaDB C 语言连接库（在 Debian/Ubuntu 上为 libmariadb-dev）。

信息

MariaDB Vector 强制要求必须使用官方的 MariaDB 连接驱动（mariadb+mariadbconnector://...）作为连接 Schema。这是强制性的，因为只有官方驱动才能为 VECTOR(n) 类型的 Float32 Payload 提供正确的 qmark 参数样式（paramstyle）和正确的二进制绑定。其他兼容 MySQL 的连接驱动均无法正常工作。

您的 MariaDB 服务器版本必须原生支持 VECTOR 和 VECTOR INDEX 特性（MariaDB 11.7+）。

MARIADB_VECTOR_DB_URL​

  • 类型: str
  • 默认值: None
  • 示例: mariadb+mariadbconnector://db_user:password@localhost:3306/openwebui
  • 描述: 用于连接 MariaDB 数据库的 URL。该 URL必须使用以 mariadb+mariadbconnector:// 开头的 Schema 连接字符串。这是为了让内置的 MariaDB 驱动连接器可以以二进制模式正常存取向量的 Float32 数据块。如果需要配置端口，必须在 URL 之后使用 : 进行指定，如 mariadb+mariadbconnector://user:pass@localhost:3306/db_name。

MARIADB_VECTOR_COLLECTION_PREFIX​

  • 类型: str
  • 默认值: open_webui
  • 描述: 设置在 MariaDB Vector 中创建集合时使用的前缀。

OpenSearch​

注意

OpenSearch 目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 OpenSearch，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

OPENSEARCH_API_KEY​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 OpenSearch API 密钥。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OPENSEARCH_CA_CERTS​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 OpenSearch 的 CA 证书路径。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OPENSEARCH_CLOUD_ID​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 OpenSearch Cloud ID。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OPENSEARCH_INDEX_PREFIX​

  • 类型: str
  • 默认值: open_webui_collections
  • 描述: 指定 OpenSearch 索引前缀。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OPENSEARCH_PASSWORD​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 OpenSearch 的访问密码。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OPENSEARCH_URL​

  • 类型: str
  • 默认值: https://localhost:9200
  • 描述: 指定 OpenSearch 实例的 URL。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OPENSEARCH_USERNAME​

  • 类型: str
  • 默认值: 空字符串 (' ')，因为默认为 None。
  • 描述: 指定 OpenSearch 的用户名。
  • 持久化: 此环境变量是 PersistentConfig 变量。

Oracle 23ai Vector​

注意

Oracle 23ai Vector 目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 Oracle 23ai Vector，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

ORACLE_DB_USER​

  • 类型: str
  • 默认值: None
  • 描述: 连接到 Oracle 23ai 数据库的用户名。

ORACLE_DB_PASSWORD​

  • 类型: str
  • 默认值: None
  • 描述: 连接到 Oracle 23ai 数据库的密码。

ORACLE_DB_DSN​

  • 类型: str
  • 默认值: None
  • 描述: Oracle 数据库的数据源名称（DSN，如 localhost:1521/FREE 或连接描述符字符串）。

ORACLE_DB_CONFIG_DIR​

  • 类型: str
  • 默认值: None
  • 描述: Oracle 配置目录的绝对路径，用于指定包含网络配置文件（如 sqlnet.ora 或 tnsnames.ora）的目录。

ORACLE_DB_WALLET_LOCATION​

  • 类型: str
  • 默认值: None
  • 描述: 包含 Oracle 安全钱包文件的本地目录路径（在使用 mTLS 安全通道连接至 Autonomous 数据库时为必需）。

ORACLE_DB_WALLET_PASSWORD​

  • 类型: str
  • 默认值: None
  • 描述: 用于访问 Oracle 安全钱包的密码（如适用）。

PGVector​

注意

PGVector 目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 PGVector，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

PGVECTOR_DB_URL​

  • 类型: str
  • 默认值: None
  • 示例: postgresql+psycopg2://db_user:password@localhost:5432/openwebui
  • 描述: 指定用于连接 PGVector 数据库的 URL。该 URL 必须 使用以 postgresql+psycopg2:// 或类似的 psycopg 适配器 Schema 开头的连接字符串，才能被系统正确处理。如果在 URL 之后指定端口，必须使用 : 进行拼接，如 postgresql+psycopg2://user:pass@localhost:5432/db_name。

PGVECTOR_COLLECTION_PREFIX​

  • 类型: str
  • 默认值: open_webui
  • 描述: 指定在 PGVector 中创建集合时使用的前缀。

Pinecone​

注意

Pinecone 目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 Pinecone，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

PINECONE_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定连接 Pinecone 服务的 API 密钥。

PINECONE_INDEX​

  • 类型: str
  • 默认值: None
  • 描述: 指定在 Pinecone 服务中使用的索引（Index）名称。

Qdrant​

注意

Qdrant 目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 Qdrant，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

QDRANT_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定连接 Qdrant 服务的 API 密钥。

QDRANT_URL​

  • 类型: str
  • 默认值: None
  • 示例: http://localhost:6333
  • 描述: 指定远程 Qdrant 实例的 API 连接 URL。

QDRANT_COLLECTION_PREFIX​

  • 类型: str
  • 默认值: open_webui
  • 描述: 指定在 Qdrant 中创建集合时使用的前缀。

Weaviate​

注意

Weaviate 目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 Weaviate，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

WEAVIATE_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定连接 Weaviate 服务的 API 密钥。

WEAVIATE_URL​

  • 类型: str
  • 默认值: None
  • 示例: http://localhost:8080
  • 描述: 指定远程 Weaviate 实例的连接 URL。

WEAVIATE_COLLECTION_PREFIX​

  • 类型: str
  • 默认值: open_webui
  • 描述: 指定在 Weaviate 中创建集合时使用的前缀。

S3 向量存储​

注意

S3 向量存储目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 S3 向量存储，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

S3_VECTOR_STORE_URL​

  • 类型: str
  • 默认值: None
  • 描述: 指定 S3 服务的连接 Endpoint URL。

S3_VECTOR_STORE_KEY_ID​

  • 类型: str
  • 默认值: None
  • 描述: 指定连接 S3 存储桶所需要的 AWS Access Key ID 凭据。

S3_VECTOR_STORE_SECRET_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定连接 S3 存储桶所需要的 AWS Secret Access Key 凭据。

S3_VECTOR_STORE_BUCKET​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于向量存储的 S3 存储桶名称。

S3_VECTOR_STORE_REGION​

  • 类型: str
  • 默认值: None
  • 描述: 指定 S3 存储桶所属的 AWS Region 区域名称。

数据库配置​

以下环境变量由 SQLAlchemy 用于数据库池连接参数。通过调优这些参数，您可以根据实际并发量调整系统的数据库吞吐能力。如果遇到“QueuePool limit reached”类型的数据库连接耗尽错误，请重点检查这些参数。

DATABASE_URL​

  • 类型: str
  • 默认值: sqlite:///{DATA_DIR}/webui.db（SQLite 文件驱动）
  • 描述: 配置主应用数据库的连接 URL，该数据库存储了用户凭据、对话记录、横幅、公告及配置设置等所有重要应用状态。默认使用 SQLite 本地文件进行存储。在生产部署以及多副本、多 Worker 架构（如 Helm, K8s, Uvicorn Workers > 1）中，强烈建议使用外部的高可靠数据库（如 PostgresSQL）。对于连接至 PostgresSQL，请配置如 postgresql+psycopg2://user:pass@host:port/dbname 格式的 URL 字符串。
SQLite 对于高并发多副本不安全

SQLite 本身不支持并行的并发写入事务。如果开启了多个工作进程（UVICORN_WORKERS > 1）或者部署了多个容器实例（Replicas）并让它们共享读写同一个本地的 webui.db，这会极其频繁地触发数据库被死锁挂起或者损坏（报错：database is locked）甚至直接导致容器崩溃重启。

在高并发的集群或多 Worker 生产环境部署中，请务必配置 DATABASE_URL 切换至 PostgresSQL 等成熟的关系型数据库！

有关负载均衡以及高可用的实践部署，请阅读我们的 扩容与高可用指南。

DATABASE_POOL_SIZE​

  • 类型: int
  • 默认值: 0 (若为 0 且使用的是 PostgresSQL/MySQL 外部关系型数据库，SQLAlchemy 内部的底层池连接数将自动退回到默认的 5 个连接)
  • 描述: 设置 SQLAlchemy 数据库连接池中保持的长连接的最大容量上限（仅对 PostgresSQL/MySQL 等非 SQLite 的外部数据库生效）。

DATABASE_POOL_MAX_OVERFLOW​

  • 类型: int
  • 默认值: 0 (若为 0 且使用的是 PostgresSQL/MySQL 外部关系型数据库，SQLAlchemy 的溢出容量将退回默认的 10 个连接)
  • 描述: 设置当连接池满载且当前有爆发请求时，允许额外临时创建和使用最大超出容量的连接数。这些临时溢出的连接一旦闲置并在超时后会被销毁释放。

DATABASE_POOL_TIMEOUT​

  • 类型: int (秒)
  • 默认值: 30
  • 描述: 设置在连接池被耗尽、全负荷运转时，新来的查询请求在等待并试图获得可用连接之前的最大等待挂起时间。若在此时间内仍无连接返回，将引发 TimeoutError 报错。

DATABASE_POOL_RECYCLE​

  • 类型: int (秒)
  • 默认值: 0
  • 描述: 设置数据库连接在池内保持不动的最长回收周期。如果设置为一个正整数（例如 3600 秒，即 1 小时），SQLAlchemy 会在此连接到期后强制重新进行底层 TCP 握手。这对于防止服务器或中间防火墙由于连接静默时间过长而单方面强制阻断非常有帮助。
池调优推荐

对于高请求量且频繁与 PostgreSQL 数据库交互的部署，如果您的连接数经常耗尽，请增大这些值：

DATABASE_POOL_SIZE=30
DATABASE_POOL_MAX_OVERFLOW=50
DATABASE_POOL_TIMEOUT=60

RAG 引擎配置​

导入与分块​

RAG_TEXT_SPLITTER_CHUNK_SIZE​

  • 类型: int
  • 默认值: 1500
  • 描述: 设置在进行文档提取并存入向量库时，文本分块的单个字符上限。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_TEXT_SPLITTER_CHUNK_OVERLAP​

  • 类型: int
  • 默认值: 100
  • 描述: 设置相邻分块之间，为了维持上下文平滑度而重叠的字符数量。
  • 持久化: 此环境变量是 PersistentConfig 变量。
  • 类型: bool
  • 默认值: False
  • 描述: 启用或禁用 RAG 混合检索（Hybrid Search）。混合检索会同时进行向量的语义相似度搜索，以及传统基于词频的关键词匹配（基于 BM25 算法），然后合并并重排它们的结果以极大改善召回率。此混合匹配由 Open WebUI 的 Python 后端本地执行，适用于所有后端向量存储。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_HYBRID_SEARCH_BM25_K1​

  • 类型: float
  • 默认值: 1.5
  • 描述: 设置 BM25 关键词匹配的饱和度因子（k1），用于在混合检索中调节关键词词频的影响比重。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_HYBRID_SEARCH_BM25_B​

  • 类型: float
  • 默认值: 0.75
  • 描述: 设置 BM25 算法中文档长度的惩罚惩戒因子（b），用以消除超长篇幅文本对单纯词频得分的干扰。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_RELEVANCE_THRESHOLD​

  • 类型: float
  • 默认值: 0.0
  • 描述: RAG 模型检索文档的相关度判定阈值（最小相似度得分）。高于此阈值的数据分块才会被最终提交给大语言模型作为上下文。
  • 持久化: 此环境变量是 PersistentConfig 变量。
合理调整判定阈值

在初次尝试或测试中，如果您觉得在配置了一些过滤重排算法后，大模型无法顺利读取到文档的内容（大模型经常声称“没有可供回答的背景信息”），请先尝试将此变量设置重置为默认值 0.0 —— 这会向 LLM 完整且不经过滤地吐出最相关的那批分块，以便您校验各个环节是否通畅。

RAG_INTELLIGENT_CHUNK_MERGING_THRESHOLD​

  • 类型: int（字符数）
  • 默认值: 0
  • 描述: 智能分块合并机制的字符阈值。当文档分块处理之后产生的一些极细碎切片字符总数低于此阈值时，系统会尝试将其与相邻的前后分块进行智能合并，以避免大面积零散的小碎片干扰向量空间，进而引起相关性丢失或者对嵌入资源的无谓浪费。此功能强制要求必须先在系统中启用 ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER。设置为 0 则表示完全关闭合并。有关本机制的技术收益和配置要点，请查阅我们的 RAG 手册。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_TEXT_SPLITTER​

  • 类型: str
  • 可用选项:
    • character
    • token
  • 默认值: character
  • 描述: 设置 RAG 模型的文本分块器（Text Splitter）。使用 character 会使用 RecursiveCharacterTextSplitter，使用 token 则使用基于 Tiktoken 的 TokenTextSplitter。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER​

  • 类型: bool
  • 默认值: True
  • 描述: 启用 Markdown 标题文本分块作为进行字符或 Token 划分之前的预处理步骤。启用后，系统会先按照 Markdown 的标题层级（h1-h6）对文档进行第一层物理划分，然后将切出的各片文档段落进一步送入配置好的主文本分块器（RAG_TEXT_SPLITTER）中。这可以最大程度地在数据块中保留文档原始的层级结构与语境上下文。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

从原有的 markdown_header TEXT_SPLITTER 迁移说明

markdown_header 选项已从 RAG_TEXT_SPLITTER 中彻底移除。Markdown 标题分块现已演进为一个预处理步骤，并由 ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER 进行控制。如果您之前配置了 RAG_TEXT_SPLITTER=markdown_header，请将主分块器切换为 character 或 token，并确保 ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER 被设置为 True（默认已自动启用）。

TIKTOKEN_CACHE_DIR​

  • 类型: str
  • 默认值: {CACHE_DIR}/tiktoken
  • 描述: 指定 Tiktoken 的本地缓存目录。

TIKTOKEN_ENCODING_NAME​

  • 类型: str
  • 默认值: cl100k_base
  • 描述: 指定 Tiktoken 的 Token 编码规则名称。
  • 持久化: 此环境变量是 PersistentConfig 变量。

PDF_EXTRACT_IMAGES​

  • 类型: bool
  • 默认值: False
  • 描述: 在加载 PDF 文档时，利用 OCR 提取并处理文档中内嵌的图片。
  • 持久化: 此环境变量是 PersistentConfig 变量。

PDF_LOADER_MODE​

  • 类型: str
  • 可用选项:
    • page - 每一页生成一片独立文档（默认行为）。
    • single - 将所有页面合并为单篇文档，以便于更顺畅地跨页边界进行分块。
  • 默认值: page
  • 描述: 在使用内置默认内容提取引擎（PyPDFLoader）加载和划分 PDF 文档时，控制其分块组织模式。页（page）模式会为每页纸创建独立的文档对象，而单（single）模式则将全部页面内容拼接为整篇大文本，以便在段落跨页分布时切出质量更高的分块。在使用第三方外部提取引擎（如 Tika、Docling、Document Intelligence、MinerU 或 Mistral OCR）时，此设置没有任何作用，因为那些引擎拥有各自专用的文档处理和分块分派逻辑。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_FILE_MAX_SIZE​

  • 类型: int
  • 描述: 限制用户用于文档导入上传的单文件最大体积上限（单位：MB）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_FILE_MAX_COUNT​

  • 类型: int
  • 描述: 限制用户进行文档导入上传时，一次能同时选择上传的最大文件数量。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_ALLOWED_FILE_EXTENSIONS​

  • 类型: list of str
  • 默认值: [] (即代表无任何额外限制，系统原生支持的所有文档格式均可上传)
  • 描述: 以白名单列表形式，显式指定系统仅允许上传的特定文件扩展名。
  • 格式示例:
["pdf,docx,txt"]
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

在配置 RAG_FILE_MAX_SIZE 和 RAG_FILE_MAX_COUNT 时，请务必设置合理的阈值，以避免由于用户上传超大规模文件或超多文件而将服务带宽及 CPU 计算资源消耗完毕。

嵌入引擎配置​

通用嵌入设置​

RAG_EMBEDDING_BATCH_SIZE​

  • 类型: int
  • 默认值: 1
  • 描述: 当使用第三方外部嵌入服务商（Ollama, OpenAI, 或 Azure OpenAI）生成 Embeddings 时，控制在单次 API 请求中打包发送的文本块数量。将其调大（如 20-100+，最大推荐不超过 16000）可以通过合并请求来加速文档嵌入进度，但部分第三方服务商并不支持批量处理或者对单次提交的批次体积有强限制。在这种情况下，必须保持默认的 1 才能正常工作。此参数不对系统内置的 SentenceTransformers 离线嵌入起效。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

在调整此参数前，请首先查阅您的 API 供应商及对应嵌入模型的手册，验证其是否完整支持 Batch 批量接口。 仅当确认支持时才建议将此数值调大，否则会频繁触发未预料的 API 报错。

ENABLE_ASYNC_EMBEDDING​

  • 类型: bool
  • 默认值: true
  • 描述: 开启异步且并行的文本嵌入处理，以压榨最大吞吐性能。目前仅对 Ollama, OpenAI 和 Azure OpenAI 端点生效，离线 sentence-transformers 方案不受此变量影响。
  • 持久化: 此环境变量是 PersistentConfig 变量。
提示

当同时服务很多活跃用户且开启了本异步快速处理时，如果频繁由于线程等待引发错误，您可能需要相应调大主服务的 THREAD_POOL_SIZE。

注意

开启此功能可能会在极短时间内（数秒）对外部服务商 API 发送数千次高频的并发请求。 如果您在本地自主运行嵌入服务器，请确保该硬件可以扛住并发洪峰，否则建议关闭此功能以退回至单线程串行处理模式（虽然慢，但极为稳健）。 如果使用第三方云端服务，请确保您的 API 账户拥有足够充裕的并发速率配额（Rate Limits）。 (通常，即使是最低档的 OpenAI API 也能应对每分钟数千次的并发嵌入请求)。

RAG_EMBEDDING_CONCURRENT_REQUESTS​

  • 类型: int
  • 默认值: 0
  • 描述: 当开启了异步嵌入时，用于限制最大出站 API 请求的并发数目。内部通过 asyncio 信号量来实现并发限流与削峰。设置为 0 则表示完全没有任何额外限制（默认行为），设置为正整数则可强制限制最大并发，这对于遵守云端供应商的速率配额或给本地低配嵌入服务器减负非常实用。
  • 持久化: 此环境变量是 PersistentConfig 变量。
提示

如果您在使用外部嵌入服务时频繁遭遇 Rate Limit 限流熔断（收到 HTTP 429 报错），请将其设置为一个可以平滑处于当前 API 档位之下的安全值（例如 5 或 10）。这在使用包含大量切片的超长文档生成 Embeddings 时效果尤为显著。

RAG_EMBEDDING_TIMEOUT​

  • 类型: int (秒)
  • 默认值: None (无超时时间限制)
  • 描述: 设置进行文档提取嵌入时的超时时间（秒）。如果设置，所有超过此时长仍未成功返回的嵌入任务都会被系统强行熔断并报出超时错误。当不进行设置时（默认），嵌入处理将无限制时间一直挂起运行。此设置主要影响使用内置 SentenceTransformers 本地离线引擎的环境，因为在本地低配硬件（如 CPU）上运行 Embeddings 往往极为耗时。外部云服务（Ollama, OpenAI, Azure OpenAI）内置了其专属的超时策略，一般不受此项控制。
信息

此环境变量是与 Uvicorn Worker 在大文件文档上传期间被意外 Kill 掉的 Bug 修复 一起引入系统的。在早先版本中，本地 SentenceTransformers 的计算会彻底霸占整个主事件循环的线程，如果计算周期过长，会使得 Uvicorn 以为服务已经假死（触发默认的 5 秒心跳健康检查超时）并直接重启主进程。目前，底层的并发问题已通过使用 run_coroutine_threadsafe 将其分发至隔离线程运行来从根本上得以解决，这确保了事件循环对健康检查响应的敏锐度。因此，此超时参数仅作为一个纯粹用于终止异常超长任务的安全性指标，其存在不再会干扰 Worker 正常的健康检测。

RAG_EMBEDDING_CONTENT_PREFIX​

  • 类型: str
  • 默认值: None
  • 描述: 在将文本块送入嵌入模型生成向量之前，为该文本内容添加的全局前缀前置字符。一部分嵌入模型（如著名 nomic-embed-text）采取了特定任务导向的训练，要求在存储背景文档时和在查询搜索问题时，使用不同类型的前置提示符来进行物理特征区隔。针对 nomic-embed-text，存储文档内容时，应将本变量指定为：search_document: 。仅当您的模型官方文档中明确提出了此要求时才需要设置。

RAG_EMBEDDING_QUERY_PREFIX​

  • 类型: str
  • 默认值: None
  • 描述: 在对用户的提问进行向量转换时，为该搜索问题添加的全局前缀前置字符。此为 RAG_EMBEDDING_CONTENT_PREFIX 对应的查询端镜像。针对 nomic-embed-text，查询端的前缀应配置为：search_query: 。仅当您的模型官方文档中明确提出了此要求时才需要设置。

RAG_EMBEDDING_PREFIX_FIELD_NAME​

  • 类型: str
  • 默认值: None
  • 描述: 明确指定在请求嵌入 API 的 JSON 请求体中，用于传递上述前缀字符串的字段键名。如果设置了此键名且前缀不为空，系统将不会直接拼接前缀到文本头部，而是将前缀作为一个独立的 JSON 属性在 API 请求中传递给第三方服务。这对于要求前缀作为专用 API 参数传入、而非直接包含在文本行内的嵌入服务至关重要。

OpenAI Embeddings​

RAG_OPENAI_API_BASE_URL​

  • 类型: str
  • 默认值: ${OPENAI_API_BASE_URL}
  • 描述: 设置用于 RAG 嵌入的 OpenAI 基础 API URL。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_OPENAI_API_KEY​

  • 类型: str
  • 默认值: ${OPENAI_API_KEY}
  • 描述: 设置用于 RAG 嵌入的 OpenAI API 密钥。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_EMBEDDING_OPENAI_BATCH_SIZE​

  • 类型: int
  • 默认值: 1
  • 描述: 设置用于 OpenAI 嵌入的 Batch 批处理体积。

Azure OpenAI Embeddings​

RAG_AZURE_OPENAI_BASE_URL​

  • 类型: str
  • 默认值: None
  • 描述: 当使用 Azure 托管的 OpenAI 实例做嵌入时，指定该服务的 Endpoint Base URL，格式应当为：https://{your-resource-name}.openai.azure.com。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_AZURE_OPENAI_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 当使用 Azure 托管的 OpenAI 实例做嵌入时，配置对应的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_AZURE_OPENAI_API_VERSION​

  • 类型: str
  • 默认值: None
  • 描述: 当使用 Azure 托管的 OpenAI 实例做嵌入时，指定目标 API 的版本号，例如 2023-05-15, 2023-12-01-preview 或 2024-02-01。
  • 持久化: 此环境变量是 PersistentConfig 变量。

Ollama Embeddings​

RAG_OLLAMA_BASE_URL​

  • 类型: str
  • 描述: 设置用于 RAG 嵌入的 Ollama 基础 API 连接 URL。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_OLLAMA_API_KEY​

  • 类型: str
  • 描述: 设置用于 RAG 嵌入的 Ollama 连接凭据 API Key（如适用）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

重排​

RAG_RERANKING_ENGINE​

  • 类型: str
  • 可用选项: external（使用外部重排服务），或者保留为空白以代表使用本地 Sentence-Transformer CrossEncoder 离线模型。
  • 默认值: 空字符串 (使用本地离线重排)
  • 描述: 指定重排（Reranking）运算所采纳的引擎。若设置为 external，必须相应提供 RAG_EXTERNAL_RERANKER_URL；保留空白则使用本地部署的 CrossEncoder 离线模型。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_RERANKING_MODEL​

  • 类型: str
  • 描述: 指定具体的重排模型名称。在本地模式下，代表所下载的 Sentence-Transformer 路径或 Hugging Face id。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_RERANKING_BATCH_SIZE​

  • 类型: int
  • 默认值: 32
  • 描述: 在本地运行 CrossEncoder 重排时，控制单个批次（Batch）内同时进行评分排序的“问题-文档”对数量。较大的数值会带来更饱满的 GPU 利用率和更佳的并行加速，但也会急剧消耗显存（VRAM）。此配置直接对本地 ColBERT/CrossEncoder 重排模型中的 predict() 函数参数生效。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SENTENCE_TRANSFORMERS_CROSS_ENCODER_SIGMOID_ACTIVATION_FUNCTION​

  • 类型: bool
  • 默认值: True
  • 描述: 启用时（默认行为），会对本地 CrossEncoder 重排输出的预测得分应用 Sigmoid 归一化，强制将其概率分布限定在 0 至 1 之间。这非常关键，因为可以让全局的“检索相关度判定阈值”稳定针对像 MS MARCO 等吐出原始未经过滤 Logits 数值的模型起效。

RAG_EXTERNAL_RERANKER_TIMEOUT​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 设置向外部重排服务商 API 发送请求时的最长超时时间（秒）。留空则使用底层的默认长连接超时规则。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_EXTERNAL_RERANKER_URL​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 指定外部云端重排 API 接口的完整 Endpoint 链接路径。
  • 持久化: 此环境变量是 PersistentConfig 变量。
注意

在此您必须提供完整的接口完整路径，包括服务商自身的 API 路由终点（例如 https://api.yourprovider.com/v1/rerank）。系统在发送请求时，绝不会自作聪明地在您的链接末尾拼接 /v1/rerank 或者其他路径参数。

RAG_EXTERNAL_RERANKER_API_KEY​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 配置外部云端重排 API 的连接鉴权凭据 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

查询生成​

ENABLE_RETRIEVAL_QUERY_GENERATION​

  • 类型: bool
  • 默认值: True
  • 描述: 开启或关闭在检索背景信息时，由系统大模型自动对用户输入的问题进行提炼优化，生成 1 到 3 个检索查询词的功能。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_QUERIES_CACHE​

  • 类型: bool
  • 默认值: False
  • 描述: 启用在一个用户请求生命周期内，对大模型生成的网页搜索查询词进行局部缓存。启用后，系统为当前请求执行 Web Search 而生成出来的优质查询词，会被系统自动拦截缓存并在稍后的知识库/本地文档检索中复用。这会彻底消除重复的 LLM 调用，在网页搜索与文档 RAG 共同激活时，大幅缩短整体响应延时且节约了宝贵的 API Input Token。在大规模并发或团队部署环境中，我们高度建议开启此项。

QUERY_GENERATION_PROMPT_TEMPLATE​

  • 类型: str
  • 默认值: DEFAULT_QUERY_GENERATION_PROMPT_TEMPLATE 环境变量的值。

DEFAULT_QUERY_GENERATION_PROMPT_TEMPLATE:


### Task:
Analyze the chat history to determine the necessity of generating search queries, in the given language. By default, **prioritize generating 1-3 broad and relevant search queries** unless it is absolutely certain that no additional information is required. The aim is to retrieve comprehensive, updated, and valuable information even with minimal uncertainty. If no search is unequivocally needed, return an empty list.

### Guidelines:
- Respond **EXCLUSIVELY** with a JSON object. Any form of extra commentary, explanation, or additional text is strictly prohibited.
- When generating search queries, respond in the format: { "queries": ["query1", "query2"] }, ensuring each query is distinct, concise, and relevant to the topic.
- If and only if it is entirely certain that no useful results can be retrieved by a search, return: { "queries": [] }.
- Err on the side of suggesting search queries if there is **any chance** they might provide useful or updated information.
- Be concise and focused on composing high-quality search queries, avoiding unnecessary elaboration, commentary, or assumptions.
- Today's date is: {{CURRENT_DATE}}.
- Always prioritize providing actionable and broad queries that maximize informational coverage.

### Output:
Strictly return in JSON format:
{
  "queries": ["query1", "query2"]
}

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
  • 描述: 设置用于检索查询词生成的 Prompt 模板。
  • 持久化: 此环境变量是 PersistentConfig 变量。

文档智能 (Azure)​

注意

Document Intelligence 目前不由 Open WebUI 团队官方主动维护。它是由社区添加并由社区负责维护的。 如果您想使用 Document Intelligence，在升级 Open WebUI 时请务必小心（做好备份和快照以备回滚），以防 Open WebUI 的内部改动导致其损坏崩溃。

DOCUMENT_INTELLIGENCE_ENDPOINT​

  • 类型: str
  • 默认值: None
  • 描述: 指定 Azure Document Intelligence (原 Form Recognizer) 服务的 Endpoint 端点链接。
  • 持久化: 此环境变量是 PersistentConfig 变量。

DOCUMENT_INTELLIGENCE_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定 Azure Document Intelligence 服务的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

DOCUMENT_INTELLIGENCE_MODEL​

  • 类型: str
  • 默认值: None
  • 描述: 指定在分析提取文档时所选定的 Azure Document Intelligence 识别模型。
  • 持久化: 此环境变量是 PersistentConfig 变量。

高级设置​

BYPASS_EMBEDDING_AND_RETRIEVAL​

  • 类型: bool
  • 默认值: False
  • 描述: 绕过生成向量与检索的完整环节。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_FULL_CONTEXT​

  • 类型: bool
  • 默认值: False
  • 描述: 设定在执行 RAG 检索时，是否一股脑向模型吐出完整的整篇上下文。
  • 持久化: 此环境变量是 PersistentConfig 变量。

RAG_SYSTEM_CONTEXT​

  • 类型: bool
  • 默认值: False
  • 描述: 开启后，系统会将所检索出的 RAG 上下文背景内容，直接注入在 系统消息 (System Message) 中，而不是附着在用户的用户消息内。这对于针对原生完整支持 KV 缓存复用 (KV prefix caching) 或者 提示词缓存 (Prompt Caching) 功能的模型环境优化系统延时至关重要。这涵盖了各大主流本地离线推理端（如 Ollama, llama.cpp, vLLM）以及头部公有云大模型供应商（如 OpenAI, Vertex AI 等）。由于将庞大的文档背景固定放置在对话的最顶端系统栏内，后续多轮对话的上下文可以最大程度利用模型缓存，显著减免重复计算负担并缩短首字延迟。而在不开启本设置（默认行为）时，文档背景是附加在瞬息万变的用户提问末尾，每一轮新的追问都会引起缓存彻底失效并触发完全重新计算。

ENABLE_RAG_LOCAL_WEB_FETCH​

  • 类型: bool
  • 默认值: False
  • 描述: 设定网页检索模块在通过网络抓取网站内容时，是否被准许请求指向局域网、内网、私有网络或本地网络 IP 段的链接。
  • 持久化: 此环境变量是 PersistentConfig 变量。

在不开启此设置的默认情况下，Open WebUI 会主动拦截所有试图访问私有 IP 网段的抓取操作，涵盖：

  • 常见的 IPv4 私有网段 (10.x.x.x, 172.16.x.x–172.31.x.x, 192.168.x.x, 127.x.x.x 等环回地址)
  • 对应的 IPv6 局域网私有网段

这构成了系统层面的 服务端请求伪造 (SSRF) 安全性深度防护机制。如果不实施这一层主动限制，别有用心的恶意用户只需输入看似外网但实际解析指向内网的 URL 链接，即可轻松渗透并刺探您局域网内暴露的未授权敏感微服务、云主机元数据端点或者其他极其机密的系统内网资产。

注意

仅当您部署的 Open WebUI 服务处于完全受控受信任的私有隔离域，且整个系统的所有注册用户均 100% 绝对可靠，且您迫切需要系统抓取提取您企业内网私有百科（如 Confluence 知识库或内网 wiki）时，方可谨慎开启本设置！在任何多租户、对公网公开暴露或者包含低信任级用户的部署环境中激活此项，都意味着将您的内网基础架构彻底暴露在极高风险的 SSRF 漏洞下！

Google Drive​

ENABLE_GOOGLE_DRIVE_INTEGRATION​

  • 类型: bool
  • 默认值: False
  • 描述: 开启或关闭 Google Drive 网盘文件导入集成。如果设为 true 且同时配置了合法的 GOOGLE_DRIVE_CLIENT_ID 和 GOOGLE_DRIVE_API_KEY，Google Drive 就会作为一种全新的网盘上传选项展现在聊天框的文件上传栏中。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

在启用 GOOGLE_DRIVE_INTEGRATION 时，请务必细致校验并正确配置 GOOGLE_DRIVE_CLIENT_ID 与 GOOGLE_DRIVE_API_KEY 变量，并且您已熟知并遵守 Google 的相关授权条款及网盘接入规范。

GOOGLE_DRIVE_CLIENT_ID​

  • 类型: str
  • 描述: 设置连接 Google Drive 接口的 Client ID（对应的客户端接口凭证必须已开通 Drive API 和 Picker API 调用权限）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

GOOGLE_DRIVE_API_KEY​

  • 类型: str
  • 描述: 设置连接 Google Drive 网盘的文件选择器专用 API 密钥。
  • 持久化: 此环境变量是 PersistentConfig 变量。

OneDrive​

信息

关于极细致的一步步集成接入教程，请翻阅我们的官方专题手册：微软 OneDrive 与 SharePoint 云端服务整合配置。

ENABLE_ONEDRIVE_INTEGRATION​

  • 类型: bool
  • 默认值: False
  • 描述: 在系统全局开启或关闭 Microsoft OneDrive 网盘接入。
  • 持久化: 此环境变量是 PersistentConfig 变量。
注意

OneDrive 的成功接入配置流程相对繁琐，强制要求您必须首先前往 Azure 平台创建并精细配置您的 Application App Registration。 且在用户端点击链接时的登录流程极度依赖于浏览器的弹窗回调。请务必提醒并确保您用户的浏览器没有拦截您 Open WebUI 域名下的 Popup 新窗口弹窗，否则微软的登录授权及文件检索页面将无法正常展出。

ENABLE_ONEDRIVE_PERSONAL​

  • 类型: bool
  • 默认值: True
  • 描述: 设定在文件上传框中，是否向用户展示“个人版 OneDrive”这一上传子选项。此菜单选项仅会在系统相应配置了 ONEDRIVE_CLIENT_ID_PERSONAL (或旧版的 ONEDRIVE_CLIENT_ID) 时才会出现 —— 如果没有提供任何客户端 ID，即使您将其设置为 True，该菜单项也会聪明地保持隐藏以防止干扰用户。
  • 持久化: 此环境变量 is a PersistentConfig 变量。

ENABLE_ONEDRIVE_BUSINESS​

  • 类型: bool
  • 默认值: True
  • 描述: 设定在文件上传框中，是否向用户展示“工作/学校版 (商业版) OneDrive”这一上传子选项。此菜单选项仅会在系统相应配置了 ONEDRIVE_CLIENT_ID_BUSINESS (或旧版的 ONEDRIVE_CLIENT_ID) 时才会出现 —— 如果没有提供任何客户端 ID，即使您将其设置为 True，该菜单项也会保持隐藏。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ONEDRIVE_CLIENT_ID​

  • 类型: str
  • 默认值: None
  • 描述: 通用的旧版 OneDrive 客户端 ID 环境变量。在当下版本中，我们强烈推荐您细分并使用更专用的 ONEDRIVE_CLIENT_ID_PERSONAL 或 ONEDRIVE_CLIENT_ID_BUSINESS 变量。此变量仅作为保持向后兼容的旧版过渡备选项。

ONEDRIVE_CLIENT_ID_PERSONAL​

  • 类型: str
  • 默认值: None
  • 描述: 专门用于配置 个人版 OneDrive 的 Application (Client) ID。这要求您在 Azure 注册时开通支持个人 Microsoft 账号鉴权的专用 App Registration。请切记不要在此处误填商业版 OneDrive 证书！

ONEDRIVE_CLIENT_ID_BUSINESS​

  • 类型: str
  • 默认值: None
  • 描述: 专门用于配置 工作/学校版 (商业版) OneDrive 的 Application (Client) ID。这要求您在 Azure 注册中开通对应的商用账号服务。请切记不要在此处误填个人版网盘证书！
信息

您所获取到的这个 Client ID (亦称 Application ID)，应当是从您 Microsoft Entra ID (即早先的 Azure AD) 租户的 App 注册页面中完整拷贝出的。 而在 Azure 端配置此 App 的回调权限时，重定向链接 (Redirect URI) 必须严丝合缝地指向您 Open WebUI 服务的公共 URL，且该集成鉴权必须将其配置为 单页应用 (SPA) 验证模式，否则鉴权机制将报错拒签。

ONEDRIVE_SHAREPOINT_URL​

  • 类型: str
  • 默认值: None
  • 描述: 当集成商用/教育版网盘时，指定您公司或学校的 SharePoint 根站点路径，例如 https://companyname.sharepoint.com。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

此变量是打通工作/学校版云盘对接不可或缺的核心指标。它指示了您企业租户对应的 SharePoint 根服务器地址，以便于系统抓取并读取关联的 SharePoint 文档库。

ONEDRIVE_SHAREPOINT_TENANT_ID​

  • 类型: str
  • 默认值: None
  • 描述: 指定微软企业工作/学校账号所关联的租户 ID（Tenant ID），亦称 Directory ID。通常需要在您的商用级 Azure App Registration 面板中进行获取。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

本 Tenant ID 对于企业/学校版对接至关重要。您可以极为轻松地在微软 Entra ID / Azure 门户中，在您所创建的 App 注册项目的主页概览（Overview）中定位并拷贝到这一串 UUID。

  • 类型: bool
  • 默认值: False
  • 描述: 开启或关闭网页搜索（Web Search）的总开关。
  • 持久化: 此环境变量是 PersistentConfig 变量。

ENABLE_SEARCH_QUERY_GENERATION​

  • 类型: bool
  • 默认值: True
  • 描述: 此参数仅对已被废弃且系统不再主动技术维护的 默认函数调用 (Default Function Calling) 历史模式起作用。若开启：大模型会试图根据上下文语境自动精简提炼出一段适合搜索引擎的检索短语。若关闭：系统将一股脑把用户最后发出的一整条消息不做任何改动直接送往搜索引擎。当下的系统主流推荐机制为 原生智能体工具链 (Native Mode)，系统会在模型进行 search_web 的原生 Tool Call 时自动完成调度，此设置对主流 Native 机制毫无影响。
  • 持久化: 此环境变量是 PersistentConfig 变量。

WEB_SEARCH_TRUST_ENV​

  • 类型: bool
  • 默认值: False
  • 描述: 控制网页搜索模块在向外网请求数据时，是否主动读取并服从系统环境变量中定义的网络代理设置（即 http_proxy 和 https_proxy）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

WEB_FETCH_FILTER_LIST​

  • 类型: string (以逗号分隔的过滤白名单与黑名单规则)

  • 默认值: "" (留空，但系统底层的默认安全拦截黑名单会始终强制处于激活态)

  • 描述: 对网页搜索爬虫及外网数据提取逻辑配置更细致的主动拦截/放行规则，以筑牢安全防线并防止服务端请求伪造（SSRF）网络攻击。系统在底层打包并强制开启了一组高危的内置黑名单，会自动拦截任何试图刺探云厂商内部元数据端点（包括 AWS, Google Cloud, Azure, 阿里云等高敏资产）的意图。

    本过滤串中：不带有 ! 前缀的条目将被解释为白名单（系统将只被准许抓取这些域名之下的网页），而带有 ! 前缀的条目则会被加入黑名单（系统将永远拒绝访问这些域名下的网页）。

    系统底层的强制高危黑名单拦截包括了：!169.254.169.254, !fd00:ec2::254, !metadata.google.internal, !metadata.azure.com, 以及 !100.100.100.200。您在下方配置的自定义规则会与这些底层黑名单进行平滑合并。

自定义规则配置示例：
  • 添加额外的内网安全黑名单： WEB_FETCH_FILTER_LIST="!internal.company.com,!192.168.1.1"
  • 实施极严苛的仅放行指定信任域名： WEB_FETCH_FILTER_LIST="example.com,trusted-site.org"

WEB_SEARCH_DOMAIN_FILTER_LIST​

  • 类型: list of str
  • 默认值: []
  • 描述: 配置以逗号分隔的搜索引擎结果域名过滤表。以 ! 开头的域名将被无情过滤拉黑（不再展示在搜索结果中），而不带前缀的域名则构成白名单。
  • 示例: wikipedia.org,github.com,!malicious-site.com
  • 持久化: 此环境变量是 PersistentConfig 变量。

WEB_SEARCH_RESULT_COUNT​

  • 类型: int
  • 默认值: 3
  • 描述: 设定单次网页检索中，向爬虫抛出的最大网页爬取数量。在 Native / Agentic 架构的原生 Tool Call 下，这亦是当模型在调用 search_web 忘记提供 count 时，系统自动采用的默认值，同时构成当模型提供超大 count 时，系统予以强制封顶拦截的物理容量天花板。
  • 持久化: 此环境变量是 PersistentConfig 变量。

WEB_SEARCH_CONCURRENT_REQUESTS​

  • 类型: int
  • 默认值: 0
  • 描述: 限制对特定搜索引擎供应商 API 接口的瞬时最大并发调用数。设为 0 代表没有任何额外并发限制（默认）。针对一些对并发数限制极度严苛或者使用免费档位的供应商（例如 Brave 搜索的免费 Tier 限制了 QPS 必须小于 1），我们强烈建议将其设为 1 从而强行开启单通道串行排队请求，这能杜绝高频访问产生大面积 429 报错。
  • 持久化: 此环境变量是 PersistentConfig 变量。

WEB_FETCH_MAX_CONTENT_LENGTH​

  • 类型: int
  • 默认值: None (即无任何截断限制，抓回多少便向模型吐出多少)
  • 描述: 限制从外部抓取网页内容时，允许返回的最大字符长度。一旦设定，超出此长度的部分将被强行丢弃截断。此前在老版本系统中，此限制被无差别死锁在硬编码的 50,000 字符。将此项留空或不进行配置则重新恢复无限制抓取。这在面对大型文档网页、防止大文本直接撑爆大模型有限的 Context Window 上下文窗口上扮演着非常关键的阻断角色。
  • 持久化: 此环境变量是 PersistentConfig 变量。

WEB_LOADER_CONCURRENT_REQUESTS​

  • 类型: int
  • 默认值: 10
  • 描述: 指定网页加载爬虫从搜索引擎返回的那批结果链接里，同时并发多线程拉取和提取具体网页内容时的并发数。此数值的高低直接影响多张网页同步抓取的吞吐速度。
  • 持久化: 此环境变量是 PersistentConfig 变量。
警惕历史遗留的同名变量冲突

"WEB_LOADER_CONCURRENT_REQUESTS" 变量在早期版本里其实是被命名为 "WEB_SEARCH_CONCURRENT_REQUESTS"。 在当下版本中，"WEB_SEARCH_CONCURRENT_REQUESTS" 已经被精细重塑，被用于专门针对搜索引擎供应商 API 的调用并发数进行精准限制（参见上面参数说明）。 如果您今天迫切希望调整网页加载爬虫多线程并发拉取的效率，您必须将变量名更新并使用最新的 "WEB_LOADER_CONCURRENT_REQUESTS"。

WEB_SEARCH_ENGINE​

DDGS_BACKEND​

  • 类型: str
  • 默认值: auto
  • 可用选项: auto (自动随机分配), bing, brave, duckduckgo, google, grokipedia, mojeek, wikipedia, yahoo, yandex.
  • 描述: 明确指定免费的 DuckDuckGo 搜索引擎底层具体复用哪一家供应商的搜索后端（可以在 系统后台面板 > 网页搜索 > DDGS Backend 中在选择 DDGS 做主引擎时进行挑选）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

BYPASS_WEB_SEARCH_EMBEDDING_AND_RETRIEVAL​

  • 类型: bool
  • 默认值: False
  • 描述: 彻底绕过对网页搜索内容执行向量嵌入及相似性语义过滤重排的完整阶段。
  • 持久化: 此环境变量是 PersistentConfig 变量。

BYPASS_WEB_SEARCH_WEB_LOADER​

  • 类型: bool
  • 默认值: False
  • 描述: 开启后，系统在获取到搜索结果后将完全放弃多线程网页加载和内容爬取提取，改为一股脑将搜索引擎自身返回的那一小段基础 Snippets 段落摘要直接吐给大模型使用。这能让网络加载耗时呈断崖式缩减，但也意味着大模型能获取到的信息丰富度大大降低。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SEARXNG_QUERY_URL​

  • 类型: str
  • 描述: 用于连接您自建 SearXNG 搜索引擎 API 且要求支持 JSON 格式导出的完整链接。链接字符串中的 <query> 占位符会在执行搜索时自动被系统替换为用户的实际检索词。
  • 链接示例: http://searxng.local/search?q=<query>
  • 持久化: 此环境变量是 PersistentConfig 变量。

SEARXNG_LANGUAGE​

  • 类型: str
  • 默认值: all
  • 描述: 用于向 SearXNG 接口发包时，指定 "search language" 检索语言入参字段（对应参数名 "language"）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

GOOGLE_PSE_API_KEY​

  • 类型: str
  • 描述: 指定谷歌可编程自定义搜索引擎 (PSE) 服务的 API 调用 Key 凭证。
  • 持久化: 此环境变量是 PersistentConfig 变量。

GOOGLE_PSE_ENGINE_ID​

  • 类型: str
  • 描述: 指定您在谷歌 PSE 控制台中创建的自定义搜索引擎的 Engine ID (Cx ID)。
  • 持久化: 此环境变量是 PersistentConfig 变量。

BRAVE_SEARCH_API_KEY​

  • 类型: str
  • 描述: 配置 Brave Search API 接口的鉴权 Key 密钥。对普通的 brave 引擎和 brave_llm_context 智能总结引擎均同时生效。
  • 持久化: 此环境变量是 PersistentConfig 变量。
信息

Brave 的官方免费档 API QPS 速率配额死锁在仅有每秒 1 次。为了防止高频搜索引发系统爆出 HTTP 429 速率受限报错，Open WebUI 内部对 Brave 进行了智能补偿延迟重试。如果您只在使用免费档，我们高度建议您将 WEB_SEARCH_CONCURRENT_REQUESTS 设为 1 以强行锁定单通道顺序排队调用。关于 Brave 更多实战配置信息，请查阅我们的 Brave 搜索指南。

BRAVE_SEARCH_CONTEXT_TOKENS​

  • 类型: int
  • 默认值: 8192
  • 描述: 当 WEB_SEARCH_ENGINE=brave_llm_context 时，设定针对每一次搜索，允许从 Brave 端获取的文本数据最大 Token 总数上限。该值会作为 maximum_number_of_tokens 字段被系统传递给 Brave API。支持的合法配置区间为 1024 至 32768。更高的数值能拉取到极大丰富的提取页面，但也会剧烈加重 API 计费额度的耗损；较小值则能保持返回结果极度干练。可以通过 后台面板 → 网页搜索 → Context Tokens 进行平滑调整（仅当主引擎切到 brave_llm_context 时才会露出该滑块选项）。
  • 持久化: 此环境变量是 PersistentConfig 变量。内部被持久化存储在数据库 rag.web.search.brave_search_context_tokens 键名下。

KAGI_SEARCH_API_KEY​

  • 类型: str
  • 描述: 配置连接 Kagi 搜索服务的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

MOJEEK_SEARCH_API_KEY​

  • 类型: str
  • 描述: 配置连接 Mojeek 搜索服务的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SERPSTACK_API_KEY​

  • 类型: str
  • 描述: 配置连接 Serpstack 检索代发服务的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SERPSTACK_HTTPS​

  • 类型: bool
  • 默认值: True
  • 描述: 设定与 Serpstack 的通讯是否采用 HTTPS 安全加密。请特别注意，Serpstack 的免费账户套餐被微软/Serpstack 强制要求只能且必须使用不安全的 HTTP 协议发包。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SERPER_API_KEY​

  • 类型: str
  • 描述: 配置连接 Serper 快速搜索代理的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SERPLY_API_KEY​

  • 类型: str
  • 描述: 配置连接 Serply 搜索代理服务的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SEARCHAPI_API_KEY​

  • 类型: str
  • 描述: 配置连接 SearchAPI 搜索引擎接口的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SEARCHAPI_ENGINE​

  • 类型: str
  • 描述: 指定 SearchAPI 后端对接的实际搜索引擎名称。
  • 持久化: 此环境变量是 PersistentConfig 变量。

TAVILY_API_KEY​

  • 类型: str
  • 描述: 配置连接 Tavily AI 搜索引擎服务的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

JINA_API_KEY​

  • 类型: str
  • 描述: 配置连接 Jina 搜索提取服务的 API Key。
  • 持久化: 此环境变量是 PersistentConfig 变量。

JINA_API_BASE_URL​

  • 类型: str
  • 默认值: https://s.jina.ai/
  • 描述: 设定 Jina 搜索接口的 Base URL 链接。这对于希望配置 Jina 私有云或者拉取指定区域代理端点（如 https://eu-s-beta.jina.ai/）非常方便（可在 系统面板 > 网页搜索 > Jina API Base URL 中进行设置）。
  • 持久化: 此环境变量是 PersistentConfig 变量。

BING_SEARCH_V7_ENDPOINT​

  • 类型: str
  • 默认值: https://api.bing.microsoft.com/v7.0/search
  • 描述: 设置微软 Bing Search V7 搜索引擎服务的 API 端点地址。
  • 持久化: 此环境变量是 PersistentConfig 变量。

BING_SEARCH_V7_SUBSCRIPTION_KEY​

  • 类型: str
  • 描述: 设置微软 Bing Search V7 服务接口的 Subscription Key 订阅密钥。
  • 持久化: 此环境变量是 PersistentConfig 变量。

BOCHA_SEARCH_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 设置连接博查 Bocha 中文 AI 搜索服务接口的 API 密钥。
  • 持久化: 此环境变量是 PersistentConfig 变量。

EXA_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 设置连接 Exa AI 搜索服务的 API 密钥。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SERPAPI_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 设置连接 SerpAPI 服务的 API 密钥。
  • 持久化: 此环境变量是 PersistentConfig 变量。

SERPAPI_ENGINE​

  • 类型: str
  • 默认值: None
  • 描述: 指定 SerpAPI 后端要调用的目标底层搜索引擎。
  • 持久化: 此环境变量是 PersistentConfig 变量。

AZURE_AI_SEARCH_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 专门用于 Azure AI Search（原 Cognitive Search）搜索服务的 API 密钥（可配置只读 Query Key 或者 Admin Key 进行验证）。当使用 Azure AI Search 作为主网页搜索供应商时为必需参数。
  • 持久化: 此环境变量是 PersistentConfig 变量。

AZURE_AI_SEARCH_ENDPOINT​

  • 类型: str
  • 默认值: None
  • 描述: Azure Search 服务端点 URL。指定要连接的 Azure Search 服务实例。
  • 示例: https://myservice.search.windows.net, https://company-search.search.windows.net
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AZURE_AI_SEARCH_INDEX_NAME​

  • 类型: str
  • 默认值: None
  • 描述: 在你的 Azure Search 服务中要查询的搜索索引名称。不同的索引可以包含不同类型的可搜索内容。
  • 示例: my-search-index, documents-index, knowledge-base
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

SOUGOU_API_SID​

  • 类型: str
  • 默认值: None
  • 描述: 设置搜狗 API SID。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

SOUGOU_API_SK​

  • 类型: str
  • 默认值: None
  • 描述: 设置搜狗 API SK。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OLLAMA_CLOUD_WEB_SEARCH_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 设置 Ollama Cloud Web Search API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

TAVILY_EXTRACT_DEPTH​

  • 类型: str
  • 默认值: basic
  • 描述: 指定 Tavily 搜索结果的提取深度。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

YACY_QUERY_URL​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 设置 YaCy 搜索引擎集成的查询 URL。应指向 YaCy 实例的搜索 API 端点。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

YACY_USERNAME​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 指定用于身份验证访问 YaCy 搜索引擎的用户名。
  • 持久化: 此环境变量是一个 PersistentConfig 变量.

YACY_PASSWORD​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 指定用于身份验证访问 YaCy 搜索引擎的密码。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

EXTERNAL_WEB_SEARCH_URL​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 指定自定义搜索集成的外部 Web 搜索服务 API 端点 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

EXTERNAL_WEB_SEARCH_API_KEY​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 设置用于与外部 Web 搜索服务进行身份验证的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

EXTERNAL_WEB_LOADER_URL​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 指定用于获取和处理网页的外部 Web 内容加载器服务 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

EXTERNAL_WEB_LOADER_API_KEY​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 设置用于与外部 Web 加载器服务进行身份验证的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

YANDEX_WEB_SEARCH_URL​

  • 类型: str
  • 默认值: https://searchapi.api.cloud.yandex.net/v2/web/search
  • 描述: 指定 Yandex Web Search 服务 API 端点 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

YANDEX_WEB_SEARCH_API_KEY​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 设置用于与 Yandex Web Search 服务进行身份验证的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

YANDEX_WEB_SEARCH_CONFIG​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 用于 Yandex Web Search 的可选 JSON 配置字符串。可根据 Yandex API 文档用于设置如 searchType 或 region 等参数。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

PERPLEXITY_API_KEY​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 设置 Perplexity API 的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

PERPLEXITY_SEARCH_API_URL​

  • 类型: str
  • 默认值: https://api.perplexity.ai/search
  • 描述: 配置 Perplexity Search 的 API 端点。允许使用自定义或自托管的、兼容 Perplexity 的 API 端点（例如 LiteLLM 的 /search 端点），而不是官方 Perplexity API 的硬编码默认端点。这在将搜索请求路由到替代提供商或内部代理时提供了灵活性。注意：如果使用 LiteLLM，请在 URL 路径后追加特定的提供商名称。
  • 示例: http://my-litellm-server.com/search/perplexity-search
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

PERPLEXITY_MODEL​

  • 类型: str
  • 默认值: sonar
  • 描述: 当使用 Perplexity 作为 Web 搜索引擎时，指定用于搜索查询的 Perplexity AI 模型。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
信息

Perplexity 与 perplexity_search 不同。 如果你使用 perplexity_search，此变量与你无关。

PERPLEXITY_SEARCH_CONTEXT_USAGE​

  • 类型: str
  • 默认值: medium
  • 描述: 控制 Perplexity AI 使用的搜索上下文数量。选项通常包括 low、medium、high。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
信息

Perplexity 与 perplexity_search 不同。 如果你使用 perplexity，此变量与你无关。

YOUCOM_API_KEY​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 设置 You.com YDC Index API Web 搜索的 API Key。当 WEB_SEARCH_ENGINE 设置为 youcom 时必填。从 You.com API 获取 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

Web 加载器配置​

WEB_LOADER_ENGINE​

  • 类型: str
  • 默认值: (empty)
  • 描述: 指定用于检索和处理 Web 内容的加载器。
  • 选项:
    • safe_web (默认) - 使用具有增强错误处理的内部获取。
    • playwright - 使用 Playwright 进行支持 JavaScript 的页面渲染。
    • firecrawl - 使用 Firecrawl 服务。
    • tavily - 使用 Tavily 服务。
    • external - 使用外部 Web 加载器 API。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
信息

当使用 playwright 时，你拥有两个选项：

  1. 如果未设置 PLAYWRIGHT_WS_URI，Playwright 以及 Chromium 依赖项将在启动时自动安装在 Open WebUI 容器中。
  2. 如果设置了 PLAYWRIGHT_WS_URI，Open WebUI 将连接到远程浏览器实例，而不是在本地安装依赖项。

PLAYWRIGHT_WS_URL​

  • 类型: str
  • 默认值: None
  • 描述: 指定远程 Playwright 浏览器实例的 WebSocket URI。设置后，Open WebUI 将使用此远程浏览器，而不是在本地安装浏览器依赖项。这在容器化环境中特别有用，你希望保持 Open WebUI 容器轻量化并分离浏览器关注点。示例: ws://playwright:3000
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
提示

通过 PLAYWRIGHT_WS_URL 使用远程 Playwright 浏览器对以下方面有益：

  • 减小 Open WebUI 容器的体积
  • 使用默认 Chromium 之外的其他浏览器
  • 连接到非无头 (GUI) 浏览器

FIRECRAWL_API_BASE_URL​

  • 类型: str
  • 默认值: https://api.firecrawl.dev
  • 描述: 设置 Firecrawl API 的基准 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

FIRECRAWL_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 设置 Firecrawl API 的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

FIRECRAWL_TIMEOUT​

  • 类型: int
  • 默认值: None
  • 描述: 指定 Firecrawl 请求的超时时间（以毫秒为单位）。如果未设置，将使用默认的 Firecrawl 超时时间。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。它可以在 管理员面板 > 设置 > Web 搜索 > Firecrawl 超时 中进行配置。

PLAYWRIGHT_TIMEOUT​

  • 类型: int
  • 默认值: 空字符串 (' ')，因为默认设置为 None。
  • 描述: 指定 Playwright 请求的超时时间。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

WEB_LOADER_TIMEOUT​

  • 类型: float
  • 默认值: 空字符串 (' ')，因为默认设置为 None。
  • 描述: 指定 SafeWebBaseLoader 在抓取网页时的请求超时时间（以秒为单位）。若无此设置，网页抓取操作在面对缓慢或无响应的页面时可能会无限期挂起。根据你的网络状况，建议值为 10–30 秒。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
注意

此 超时仅在 WEB_LOADER_ENGINE 设置为 safe_web 或留空（默认）时适用。它对 Playwright 或 Firecrawl 加载器引擎没有影响，它们拥有自己的超时配置（分别为 PLAYWRIGHT_TIMEOUT 和 Firecrawl 内部设置）。

YouTube 加载器​

YOUTUBE_LOADER_PROXY_URL​

  • 类型: str
  • 描述: 设置 YouTube 加载器的代理 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

YOUTUBE_LOADER_LANGUAGE​

  • 类型: str
  • 默认值: en
  • 描述: 获取 YouTube 视频字幕时按优先级顺序尝试的逗号分隔语言代码列表。
  • 示例: 如果设置为 es,de，将首先尝试西班牙语字幕，如果西班牙语不可用，则尝试德语，最后尝试英语。
备注

注意：如果指定的语言都不可用，且 en 不在你的列表中，系统将自动尝试英语作为最终备用方案。

  • 持久化: 此环境变量是一个 PersistentConfig 变量。

音频​

BYPASS_PYDUB_PREPROCESSING​

  • 类型: bool
  • 默认值: False
  • 描述: 启用时，在将音频发送到 Speech-to-Text 引擎之前，跳过基于 pydub 的预处理（转换为 MP3 格式、压缩以及按大小进行分块切分）。当上游服务提供商已经处理这些步骤、主机上 ffmpeg 不可用，或者你希望原样传递音频时，这非常有用。适用于所有 STT 引擎。

Whisper 语音转文本 (本地)​

WHISPER_MODEL​

  • 类型: str
  • 默认值: base
  • 描述: 设置用于 Speech-to-Text 的 Whisper 模型。使用的后端是更快、量化为 int8 的 faster_whisper。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

WHISPER_MODEL_DIR​

  • 类型: str
  • 默认值: ${DATA_DIR}/cache/whisper/models
  • 描述: 指定存储 Whisper 模型文件的目录。

WHISPER_COMPUTE_TYPE​

  • 类型: str
  • 默认值: int8 (CPU), float16 (CUDA)
  • 描述: 设置 Whisper 模型推理的计算类型。对于 CPU 默认值为 int8，对于 CUDA 默认值为 float16（回退为 int8/int8_float16）。

WHISPER_VAD_FILTER​

  • 类型: bool
  • 默认值: False
  • 描述: 指定是否对 Whisper Speech-to-Text 应用语音活动检测 (VAD) 过滤器。

WHISPER_MODEL_AUTO_UPDATE​

  • 类型: bool
  • 默认值: False
  • 描述: 切换是否自动更新 Whisper 模型。

WHISPER_LANGUAGE​

  • 类型: str
  • 默认值: None
  • 描述: 指定 Whisper 用于 STT 的 ISO 639-1 语言代码（夏威夷语和粤语使用 ISO 639-2）。默认情况下 Whisper 会自动预测语言。

WHISPER_MULTILINGUAL​

  • 类型: bool
  • 默认值: False
  • 描述: 切换是否使用多语言 Whisper 模型。当设置为 False 时，系统将使用仅限英语的模型，以便在以英语为中心的项目中获得更好的性能。当为 True 时，它支持多种语言。

语音转文本 (OpenAI)​

AUDIO_STT_ENGINE​

  • 类型: str
  • 选项:
    • "" (空字符串) - 使用内置的本地 Whisper 引擎进行 Speech-to-Text。这将在后端服务器上运行 Whisper。
    • openai - 使用与 OpenAI 兼容的 API 进行 Speech-to-Text。
    • deepgram - 使用 Deepgram 引擎进行 Speech-to-Text。
    • azure - 使用 Azure 认知服务进行 Speech-to-Text。
    • mistral - 使用 Mistral API 进行 Speech-to-Text。
  • 描述: 指定要使用的 Speech-to-Text 引擎。当留空为字符串（默认值）时，后端运行本地 Whisper 实例。注意：在“用户设置”中看到的“Web API”选项是一个仅限前端的设置，它使用浏览器内置的语音识别，完全不调用此后端端点。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_MODEL​

  • 类型: str
  • 默认值: whisper-1
  • 描述: 指定用于兼容 OpenAI 端点的 Speech-to-Text 模型。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_OPENAI_API_BASE_URL​

  • 类型: str
  • 默认值: ${OPENAI_API_BASE_URL}
  • 描述: 设置用于 Speech-to-Text 的兼容 OpenAI 基准 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_OPENAI_API_KEY​

  • 类型: str
  • 默认值: ${OPENAI_API_KEY}
  • 描述: 设置用于 Speech-to-Text 的 OpenAI API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

语音转文本 (Azure)​

AUDIO_STT_AZURE_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于 Speech-to-Text 的 Azure API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_AZURE_REGION​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于 Speech-to-Text 的 Azure 区域。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_AZURE_LOCALES​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于 Azure Speech-to-Text 的区域语言属性（Locales）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_AZURE_BASE_URL​

  • 类型: str
  • 默认值: None
  • 描述: 为 Speech-to-Text 指定自定义 Azure 基准 URL。如果你拥有自定义 Azure 端点，请使用此项。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_AZURE_MAX_SPEAKERS​

  • 类型: int
  • 默认值: 3
  • 描述: 设置用于 Azure Speech-to-Text 说话人日志（Diarization）的最大说话人数量。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

语音转文本 (Deepgram)​

DEEPGRAM_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于 Speech-to-Text 的 Deepgram API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

语音转文本 (Mistral)​

AUDIO_STT_MISTRAL_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于 Speech-to-Text 的 Mistral API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_MISTRAL_API_BASE_URL​

  • 类型: str
  • 默认值: https://api.mistral.ai/v1
  • 描述: 指定用于 Speech-to-Text 的 Mistral API 基准 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_MISTRAL_USE_CHAT_COMPLETIONS​

  • 类型: bool
  • 默认值: False
  • 描述: 启用时，将聊天补全（Chat Completions）端点用于 Mistral Speech-to-Text，而不是专用的转录（Transcription）端点。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

语音转文本 (通用)​

AUDIO_STT_SUPPORTED_CONTENT_TYPES​

  • 类型: str
  • 默认值: None
  • 描述: 用于 Speech-to-Text 的受支持音频 MIME 类型的逗号分隔列表（例如 audio/wav,audio/mpeg,video/*）。留空以使用默认值。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_STT_ALLOWED_EXTENSIONS​

  • 类型: str
  • 默认值: mp3,wav,m4a,webm,ogg,flac,mp4,mpga,mpeg
  • 描述: Speech-to-Text 上传端点接受的音频文件扩展名逗号分隔列表。此列表之外扩展名的上传将被拒绝，并返回 400 Invalid audio file extension。比较时不区分大小写。设置为空值以跳过扩展名检查（通过 AUDIO_STT_SUPPORTED_CONTENT_TYPES 的 MIME 类型验证仍然适用）。可通过 管理员设置 → 音频 → STT 进行配置。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

文本转语音​

AUDIO_TTS_API_KEY​

  • 类型: str
  • 描述: 设置 Text-to-Speech 的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_TTS_ENGINE​

  • 类型: str
  • 选项:
    • "" (空字符串) - 慢用/禁用后端 TTS。 为空时，TTS 请求不会到达后端。所有 TTS 都在客户端使用浏览器的 Web Speech API 或“用户设置”中由用户配置的“Browser Kokoro”选项来处理。
    • openai - 使用与 OpenAI 兼容的 API 进行 Text-to-Speech。
    • mistral - 使用 Mistral 的 Text-to-Speech API。
    • elevenlabs - 使用 ElevenLabs 引擎进行 Text-to-Speech。
    • azure - 使用 Azure 认知服务进行 Text-to-Speech。
    • transformers - 使用基于 SentenceTransformers 的本地模型进行 Text-to-Speech（在后端运行）。
  • 描述: 指定要在后端使用的 Text-to-Speech 引擎。当留空为字符串（默认值）时，不会配置后端 TTS 服务，音频播放完全依赖于用户的浏览器功能或“Browser Kokoro”等前端选项。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_TTS_MODEL​

  • 类型: str
  • 默认值: tts-1
  • 描述: 指定要使用的 OpenAI 文本转语音模型。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_TTS_VOICE​

  • 类型: str
  • 默认值: alloy
  • 描述: 设置要使用的 OpenAI 文本转语音音色。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_TTS_SPLIT_ON​

  • 类型: str
  • 默认值: punctuation
  • 描述: 设置要使用的 OpenAI 文本转语音分句标志（按标点符号等拆分）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

Azure 文本转语音​

AUDIO_TTS_AZURE_SPEECH_REGION​

  • 类型: str
  • 描述: 设置 Azure 文本转语音的区域。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_TTS_AZURE_SPEECH_OUTPUT_FORMAT​

  • 类型: str
  • 默认值: audio-24khz-160kbitrate-mono-mp3
  • 描述: 设置 Azure 文本转语音的输出格式。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_TTS_AZURE_SPEECH_BASE_URL​

  • 类型: str
  • 默认值: None
  • 描述: 为 Text-to-Speech 指定自定义 Azure Speech 基准 URL。如果你拥有自定义 Azure 端点，请使用此项。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

语音模式​

ENABLE_VOICE_MODE_PROMPT​

  • 类型: bool
  • 默认值: True
  • 描述: 语音模式系统提示词的主开关。当为 True 时，语音模式聊天将预先追加自定义的 VOICE_MODE_PROMPT_TEMPLATE（如果已设置）或 DEFAULT_VOICE_MODE_PROMPT_TEMPLATE。当为 False 时，不会注入任何特定于语音的系统提示词 —— 模型仅使用常规系统提示词和聊天历史记录。可在 管理员设置 → 界面 → 语音模式自定义提示词（开关）中进行配置。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。存储于配置键 task.voice.prompt.enable。

VOICE_MODE_PROMPT_TEMPLATE​

  • 类型: str
  • 默认值: 环境变量 DEFAULT_VOICE_MODE_PROMPT_TEMPLATE 的值。
  • 描述: 配置用于语音模式交互的自定义系统提示词。允许管理员控制 AI 在语音通话中的响应方式（风格、长度、语气）。留空将使用专为语音通话优化的默认提示词，或提供自定义说明以定制语音助手的行为。仅在 ENABLE_VOICE_MODE_PROMPT 为 True 时应用。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OpenAI 文本转语音​

AUDIO_TTS_OPENAI_API_BASE_URL​

  • 类型: str
  • 默认值: ${OPENAI_API_BASE_URL}
  • 描述: 设置用于文本转语音的兼容 OpenAI 基准 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_TTS_OPENAI_API_KEY​

  • 类型: str
  • 默认值: ${OPENAI_API_KEY}
  • 描述: 设置用于文本转语音的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_TTS_OPENAI_PARAMS​

  • 类型: str (JSON)
  • 默认值: {}
  • 描述: 用于兼容 OpenAI TTS API 的附加参数（JSON 格式）。允许自定义特定于 API 的设置。
  • 示例: {"speed": 1.0}
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

Mistral 文本转语音​

AUDIO_TTS_MISTRAL_API_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 设置用于 Mistral Text-to-Speech 的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUDIO_TTS_MISTRAL_API_BASE_URL​

  • 类型: str
  • 默认值: https://api.mistral.ai/v1
  • 描述: 设置用于 Mistral Text-to-Speech 的基准 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
信息

当 AUDIO_TTS_ENGINE=mistral 且 AUDIO_TTS_MODEL 为空时，Open WebUI 将使用 mistral-tts-latest。

Elevenlabs 文本转语音​

ELEVENLABS_API_BASE_URL​

  • 类型: str
  • 默认值: https://api.elevenlabs.io
  • 描述: 配置自定义 ElevenLabs API 端点，从而支持欧盟居留权（EU Residency）API 要求以及其他区域化部署。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

图像生成​

通用设置​

ENABLE_IMAGE_GENERATION​

  • 类型: bool
  • 默认值: False
  • 描述: 启用或禁用图像生成功能。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_IMAGE_PROMPT_GENERATION​

  • 类型: bool
  • 默认值: True
  • 描述: 启用或禁用自动优化用户提示词以获得更好的图像生成结果。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

IMAGE_PROMPT_GENERATION_PROMPT_TEMPLATE​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于生成图像提示词的模板。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

DEFAULT_IMAGE_PROMPT_GENERATION_PROMPT_TEMPLATE:

### Task:
Generate a detailed prompt for an image generation task based on the given language and context. Describe the image as if you were explaining it to someone who cannot see it. Include relevant details, colors, shapes, and any other important elements.

### Guidelines:
- Be descriptive and detailed, focusing on the most important aspects of the image.
- Avoid making assumptions or adding information not present in the image.
- Use the chat's primary language; default to English if multilingual.
- If the image is too complex, focus on the most prominent elements.

### Output:
Strictly return in JSON format:
{
    "prompt": "Your detailed description here."
}

### Chat History:
<chat_history>
{{MESSAGES:END:6}}
</chat_history>

图像创建​

IMAGE_GENERATION_ENGINE​

  • 类型: str
  • 选项:
    • openai - 使用 OpenAI DALL-E 进行图像生成。
    • comfyui - 使用 ComfyUI 引擎进行图像生成。
    • automatic1111 - 使用 AUTOMATIC1111 引擎进行图像生成。
    • gemini - 使用 Gemini 进行图像生成。
  • 默认值: openai
  • 描述: 指定用于图像生成的引擎。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

IMAGE_GENERATION_MODEL​

  • 类型: str
  • 默认值: ``
  • 描述: 用于图像生成的默认模型（例如 dall-e-3、gemini-2.0-flash-exp）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

IMAGE_SIZE​

  • 类型: str
  • 默认值: 512x512
  • 描述: 设置生成图像的默认输出尺寸，采用 宽度x高度（WIDTHxHEIGHT）格式（例如 1024x1024）。设置为 auto 可以让模型决定合适的尺寸（仅由匹配 IMAGE_AUTO_SIZE_MODELS_REGEX_PATTERN 的模型支持）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

IMAGE_AUTO_SIZE_MODELS_REGEX_PATTERN​

  • 类型: str
  • 默认值: ^gpt-image
  • 描述: 用于匹配支持 IMAGE_SIZE = "auto" 的模型名称的正则表达式。当模型匹配此模式时，auto 尺寸选项变为可用，允许模型决定合适的输出尺寸。默认情况下，仅匹配以 gpt-image 开头的模型（例如 gpt-image-1）。

IMAGE_URL_RESPONSE_MODELS_REGEX_PATTERN​

  • 类型: str
  • 默认值: ^gpt-image
  • 描述: 用于匹配直接返回图像 URL 而不是 base64 编码数据的模型名称的正则表达式。匹配此模式的模型在 API 请求中不会包含 response_format: b64_json。默认情况下，仅匹配以 gpt-image 开头的模型。对于其他模型，Open WebUI 会请求 base64 响应并在内部处理转换。

IMAGE_STEPS​

  • 类型: int
  • 默认值: 50
  • 描述: 设置图像生成的默认迭代步数（Steps）。用于 ComfyUI 和 AUTOMATIC1111 引擎。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

图像编辑​

ENABLE_IMAGE_EDIT​

  • 类型: boolean
  • 默认值: true
  • 描述: 禁用时，将不会使用图像编辑功能，相反，图像将仅使用图像生成引擎进行创建。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

IMAGE_EDIT_ENGINE​

  • 类型: str
  • 选项:
    • openai - 使用 OpenAI DALL-E 进行图像编辑。
    • gemini - 使用 Gemini 进行图像编辑。
    • comfyui - 使用 ComfyUI 引擎进行图像编辑。
  • 默认值: openai
  • 描述: 配置用于图像编辑操作的引擎，从而能够使用文本提示词修改现有图像。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

IMAGE_EDIT_MODEL​

  • 类型: str
  • 默认值: ``
  • 描述: 指定在所选引擎中用于图像编辑操作的模型（例如 dall-e-2、gemini-2.5-flash）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

IMAGE_EDIT_SIZE​

  • 类型: str
  • 默认值: ``
  • 描述: 采用 宽度x高度（WIDTHxHEIGHT）格式（例如 1024x1024）定义已编辑图像的输出尺寸。留空以保留原始尺寸。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OpenAI DALL-E​

图像生成​

IMAGES_OPENAI_API_BASE_URL​
  • 类型: str
  • 默认值: ${OPENAI_API_BASE_URL}
  • 描述: 设置用于 DALL-E 图像生成的兼容 OpenAI 基准 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_OPENAI_API_VERSION​
  • 类型: str
  • 默认值: ${OPENAI_API_VERSION}
  • 描述: 可选设置。如果提供，它将在调用图像生成端点时设置 api-version 查询参数。Azure OpenAI 部署必填。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_OPENAI_API_KEY​
  • 类型: str
  • 默认值: ${OPENAI_API_KEY}
  • 描述: 设置用于 DALL-E 图像生成的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_OPENAI_API_PARAMS​
  • 类型: str (JSON)
  • 默认值: {}
  • 描述: 兼容 OpenAI 图像生成 API 的附加参数（JSON 格式）。允许自定义特定于 API 的设置，例如 DALL-E 模型的质量参数（例如用于 dall-e-3 的 {"quality": "hd"}）。
  • 示例: {"quality": "hd", "style": "vivid"}
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

图像编辑​

IMAGES_EDIT_OPENAI_API_BASE_URL​
  • 类型: str
  • 默认值: ${OPENAI_API_BASE_URL}
  • 描述: 专为图像编辑操作配置 OpenAI API 基准 URL，允许使用与图像生成不同的端点。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_EDIT_OPENAI_API_VERSION​
  • 类型: str
  • 默认值: ``
  • 描述: 指定用于图像编辑的 OpenAI API 版本，从而支持具有版本化端点的 Azure OpenAI 部署。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_EDIT_OPENAI_API_KEY​
  • 类型: str
  • 默认值: ${OPENAI_API_KEY}
  • 描述: 为 OpenAI 图像编辑 API 请求提供身份验证，支持与图像生成使用不同的 Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

Gemini​

提示

有关详细的设置指南和配置示例，请参考 Gemini 图像生成指南。

图像生成​

IMAGES_GEMINI_API_BASE_URL​
  • 类型: str
  • 默认值: ${GEMINI_API_BASE_URL}
  • 描述: 指定 Gemini 图像生成 API 的 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_GEMINI_API_KEY​
  • 类型: str
  • 默认值: ${GEMINI_API_KEY}
  • 描述: 设置用于图像生成的 Gemini API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_GEMINI_ENDPOINT_METHOD​
  • 类型: str
  • 选项:
    • predict - 使用 predict 端点（Imagen 模型的默认选项）。
    • generateContent - 使用 generateContent 端点（用于 Gemini 2.5 Flash 及更新模型）。
  • 默认值: ``
  • 描述: 指定用于图像生成的 Gemini API 端点方法，既支持传统的 Imagen 模型，也支持具有图像生成能力的较新 Gemini 模型。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

图像编辑​

IMAGES_EDIT_GEMINI_API_BASE_URL​
  • 类型: str
  • 默认值: ${GEMINI_API_BASE_URL}
  • 描述: 专为使用 Gemini 模型进行图像编辑的操作配置 Gemini API 基准 URL。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_EDIT_GEMINI_API_KEY​
  • 类型: str
  • 默认值: ${GEMINI_API_KEY}
  • 描述: 为 Gemini 图像编辑 API 请求提供身份验证。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ComfyUI​

图像生成​

COMFYUI_BASE_URL​
  • 类型: str
  • 默认值: ``
  • 描述: 指定 ComfyUI 图像生成 API 的 URL（例如 http://127.0.0.1:8188）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
COMFYUI_API_KEY​
  • 类型: str
  • 默认值: ``
  • 描述: 设置用于 ComfyUI 身份验证的 API Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
COMFYUI_WORKFLOW​
  • 类型: str (JSON)
  • 默认值:
{
  "3": {
    "inputs": {
      "seed": 0,
      "steps": 20,
      "cfg": 8,
      "sampler_name": "euler",
      "scheduler": "normal",
      "denoise": 1,
      "model": ["4", 0],
      "positive": ["6", 0],
      "negative": ["7", 0],
      "latent_image": ["5", 0]
    },
    "class_type": "KSampler",
    "_meta": {
      "title": "KSampler"
    }
  },
  "4": {
    "inputs": {
      "ckpt_name": "model.safetensors"
    },
    "class_type": "CheckpointLoaderSimple",
    "_meta": {
      "title": "Load Checkpoint"
    }
  },
  "5": {
    "inputs": {
      "width": 512,
      "height": 512,
      "batch_size": 1
    },
    "class_type": "EmptyLatentImage",
    "_meta": {
      "title": "Empty Latent Image"
    }
  },
  "6": {
    "inputs": {
      "text": "Prompt",
      "clip": ["4", 1]
    },
    "class_type": "CLIPTextEncode",
    "_meta": {
      "title": "CLIP Text Encode (Prompt)"
    }
  },
  "7": {
    "inputs": {
      "text": "",
      "clip": ["4", 1]
    },
    "class_type": "CLIPTextEncode",
    "_meta": {
      "title": "CLIP Text Encode (Prompt)"
    }
  },
  "8": {
    "inputs": {
      "samples": ["3", 0],
      "vae": ["4", 2]
    },
    "class_type": "VAEDecode",
    "_meta": {
      "title": "VAE Decode"
    }
  },
  "9": {
    "inputs": {
      "filename_prefix": "ComfyUI",
      "images": ["8", 0]
    },
    "class_type": "SaveImage",
    "_meta": {
      "title": "Save Image"
    }
  }
}
  • 描述: 采用 JSON 格式定义 ComfyUI 工作流配置。使用“保存（API 格式）”从 ComfyUI 中导出以确保兼容性。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
COMFYUI_WORKFLOW_NODES​
  • 类型: list[dict]
  • 默认值: []
  • 描述: 指定用于图像生成的 ComfyUI 工作流节点映射，定义哪些节点处理提示词、模型、尺寸和其他参数。可通过管理员界面自动配置。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

图像编辑​

IMAGES_EDIT_COMFYUI_BASE_URL​
  • 类型: str
  • 默认值: ``
  • 描述: 为图像编辑操作配置 ComfyUI 基准 URL，从而实现自托管的 ComfyUI 工作流进行图像处理。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_EDIT_COMFYUI_API_KEY​
  • 类型: str
  • 默认值: ``
  • 描述: 当 ComfyUI 实例要求 API Key 身份验证时，为 ComfyUI 图像编辑 API 请求提供身份验证。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_EDIT_COMFYUI_WORKFLOW​
  • 类型: str (JSON)
  • 默认值: ``
  • 描述: 采用 JSON 格式定义用于图像编辑操作的 ComfyUI 工作流配置。必须包含用于图像输入、提示词和输出的节点。使用“保存（API 格式）”从 ComfyUI 中导出。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
IMAGES_EDIT_COMFYUI_WORKFLOW_NODES​
  • 类型: list[dict]
  • 默认值: []
  • 描述: 指定用于图像编辑的 ComfyUI 工作流节点映射，定义哪些节点处理图像输入、提示词、模型、尺寸和其他参数。可通过管理员界面自动配置。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUTOMATIC1111​

AUTOMATIC1111_BASE_URL​

  • 类型: str
  • 默认值: ``
  • 描述: 指定 AUTOMATIC1111 的 Stable Diffusion API URL（例如 http://127.0.0.1:7860）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUTOMATIC1111_API_AUTH​

  • 类型: str
  • 默认值: ``
  • 描述: 如果需要，设置 AUTOMATIC1111 API 身份验证凭证。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

AUTOMATIC1111_PARAMS​

  • 类型: str (JSON)
  • 默认值: {}
  • 描述: 传递给 AUTOMATIC1111 API 请求的附加参数（JSON 格式，例如 {"cfg_scale": 7, "sampler_name": "Euler a", "scheduler": "normal"}）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAuth​

信息

你一次只能配置一个 OAuth 提供商。你不能同时配置两个或更多 OAuth 提供商。

ENABLE_OAUTH_SIGNUP​

  • 类型: bool
  • 默认值: False
  • 描述: 启用通过 OAuth 注册时的账户创建。与 ENABLE_SIGNUP 不同。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
危险

当 ENABLE_OAUTH_SIGNUP 设置为 True 时，ENABLE_LOGIN_FORM 必须设置为 False。否则将导致无法登录。

ENABLE_OAUTH_PERSISTENT_CONFIG​

  • 类型: bool
  • 默认值: True
  • 描述: 控制 OAuth 相关设置在首次启动后是否持久化在数据库中。
信息

默认情况下，在初始设置后，OAuth 配置存储在数据库中，并通过管理员面板进行管理。将此变量设置为 False 以强制 Open WebUI 在每次重启时始终从环境变量中读取 OAuth 设置。这对于使用 GitOps 或不可变基础设施的环境非常理想，在这些环境中，配置完全通过外部文件（例如 Docker Compose、Kubernetes ConfigMaps）进行管理。

OAUTH_SUB_CLAIM​

  • 类型: str
  • 默认值: None
  • 描述: 覆盖用于从 OAuth/OIDC 提供商的用户信息响应中识别用户唯一 ID（sub）的默认声明（Claim）。默认情况下，Open WebUI 尝试从提供商的配置中推断出这一点。此变量允许你显式指定要使用的声明。例如，如果你的身份提供商使用 'employee_id' as the unique identifier，你应将此变量设置为 'employee_id'。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_MERGE_ACCOUNTS_BY_EMAIL​

  • 类型: bool
  • 默认值: False
  • 描述: 如果启用，则将 OAuth 账户与使用相同电子邮件地址的现有账户进行合并。这被认为是不安全的，因为并非所有 OAuth 提供商都会验证电子邮件地址，这可能会导致潜在的账户被接管。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_OAUTH_WITHOUT_EMAIL​

  • 类型: bool
  • 默认值: False
  • 描述: 允许与不支持或不公开 email 范围的 OpenID Connect (OIDC) 提供商进行身份验证。启用时，Open WebUI 将创建和管理用户账户，而无需从 OAuth 提供商处获取电子邮件地址。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
注意

谨慎使用

启用此选项会绕过基于电子邮件的用户标识，这是在各种身份验证系统中唯一标识用户的标准方法。启用时：

  • 用户账户将使用 sub 声明（或在 OAUTH_SUB_CLAIM 中指定的声明）作为主要标识符进行创建
  • 基于电子邮件的功能（例如密码恢复、电子邮件通知以及通过 OAUTH_MERGE_ACCOUNTS_BY_EMAIL 进行的账户合并）将无法正常运行
  • 确保你的 OIDC 提供商的 sub 声明稳定且唯一，以防发生身份验证冲突

仅在你的身份提供商不支持 email 范围且你已部署了替代的用户标识机制时，才启用此选项。

此设置专为使用具备以下特点的身份提供商的企业环境而设计：

  • 使用员工 ID、用户名或其他非电子邮件标识符作为主要用户声明
  • 拥有防止通过 OAuth 共享电子邮件地址的隐私政策
  • 在无法使用基于电子邮件服务的物理隔离（Air-Gapped）或高度受限的网络中运行

对于大多数标准的 OAuth 提供商（Google、Microsoft、GitHub 等），此设置应保持为 False。

OAUTH_UPDATE_PICTURE_ON_LOGIN​

  • 类型: bool
  • 默认值: False
  • 描述: 如果启用，则在登录时使用 OAuth 提供的图片更新本地用户头像。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
信息

如果通过将 OAUTH_PICTURE_CLAIM 设置为 ''（空字符串）禁用了 OAuth 图片声明，那么将此变量设置为 true 也不会更新用户头像。

  • 类型: bool
  • 默认值: True
  • 描述: 控制在成功进行 OAuth 登录时是否在浏览器中设置旧版 oauth_id_token Cookie（不安全，不推荐，Token 可能会变陈旧或孤立）。此项专门为了与可能依赖抓取此 Cookie 的自定义工具或较旧版本保持向后兼容性而提供。全新且推荐的方法是使用服务端会话管理（Session Management）。
  • 用法: 对于新的安全部署，建议将此项设置为 False，以尽量减少向客户端暴露的信息。仅在你的集成依赖于旧的基于 Cookie 的方法时，才将其保持为 True。

ENABLE_OAUTH_TOKEN_EXCHANGE​

  • 类型: bool
  • 默认值: False
  • 描述: 启用 OAuth Token 交换端点，允许外部应用程序将 OAuth 提供商的 Access Token 交换为 Open WebUI JWT 会话 Token。这为已经从你的身份提供商处获取了 OAuth Token 的外部工具和服务提供了编程式身份验证。
  • 用法: 设置为 true 以启用位于 /api/v1/oauth/{provider}/token/exchange 的 Token 交换端点。启用时，外部应用程序可以向此端点 POST 一个 OAuth Access Token 以获取 Open WebUI 会话 Token。
注意

安全提示: 仅当你有外部应用程序需要使用来自你的身份提供商的 OAuth Token 向 Open WebUI 进行身份验证时，才应启用此功能。确保对使用此端点的任何外部应用程序实施了适当的访问控制。

请求示例:

curl -X POST "http://localhost:8080/api/v1/oauth/google/token/exchange" \
  -H "Content-Type: application/json" \
  -d '{"token": "ya29.a0AfH6SMB..."}'

响应:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_at": 1735682400,
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "profile_image_url": "https://...",
  "permissions": {...}
}

要求:

  • 用户必须已在 Open WebUI 中存在（他们必须至少通过 Web 界面登录过一次）
  • OAuth 提供商必须已正确配置
  • Token 交换使用与常规 OAuth 登录相同的用户查找逻辑（首先通过 OAuth sub 声明，如果启用了 OAUTH_MERGE_ACCOUNTS_BY_EMAIL，则随后通过电子邮件）

ENABLE_OAUTH_BACKCHANNEL_LOGOUT​

  • 类型: bool
  • 默认值: False
  • 描述: 启用 OpenID Connect 反向通道单点登出（Back-Channel Logout）支持。启用时，Open WebUI 将公开 POST /oauth/backchannel-logout，以便你的身份提供商可以触发服务端登出，而无需浏览器重定向。
  • 用法: 设置为 true 以启用该端点。你的身份提供商应发送遵循 OpenID Connect Back-Channel Logout 1.0 规范的表单编码 logout_token。
注意

JWT 撤销的 Redis 软性要求

反向通道登出通过基于 Redis 的撤销键撤销现有的 Open WebUI JWT 会话。在没有 Redis 的情况下，Open WebUI 仍然可以删除存储的 OAuth 会话，但已签发的 JWT 将保持有效，直至其自然过期。

对于生产环境的 SSO 部署，特别是具有多个 Worker 进程或副本的环境，在启用此功能时，请务必配置 REDIS_URL。

信息

行为说明

  • 对于有效的请求，该端点返回 200 且主体为空，包括未找到匹配用户的情况。
  • 无效或格式错误的 logout_token 请求将返回 400 且包含 invalid_request 详细信息。
  • 反向通道登出通过 提供商 + sub 声明匹配来撤销用户。目前不支持仅基于 sid 的登出匹配。

OAUTH_CLIENT_INFO_ENCRYPTION_KEY​

  • 类型: str
  • 默认值: 回退为 WEBUI_SECRET_KEY 的值。
  • 描述: 指定用于对存储在数据库服务端的 OAuth 客户端 Token 进行加密和解密的密钥。这是 OAuth 客户端 Token 的关键安全组件。如果未设置，它默认使用主 WEBUI_SECRET_KEY，但强烈建议在生产环境中将其设置为唯一的、安全生成的数值。OAUTH_CLIENT_INFO_ENCRYPTION_KEY 与 OAuth 2.1 MCP 服务端身份验证配合使用。

OAUTH_SESSION_TOKEN_ENCRYPTION_KEY​

  • 类型: str
  • 默认值: 回退为 WEBUI_SECRET_KEY 的值。
  • 描述: 指定用于对存储在数据库服务端的用户 OAuth Token 进行加密和解密的密钥。这是在静态状态下保护用户凭证的关键安全组件。如果未设置，它默认使用主 WEBUI_SECRET_KEY，但强烈建议在生产环境中将其设置为唯一的、安全生成的数值。
注意

多副本部署的强性要求 在运行多个 Open WebUI 实例的任何生产环境（例如 Docker Swarm、Kubernetes）中，必须显式将此变量设置为持久的共享密钥。如果保持未设置状态，每个副本将生成或使用不同的密钥，从而在用户请求跨实例进行负载均衡时，间歇性地导致会话解密失败。

OAUTH_MAX_SESSIONS_PER_USER​

  • 类型: int
  • 默认值: 10
  • 描述: 每个用户每个提供商允许的最大并发 OAuth 会话数。当用户登录且该用户/提供商组合的现有会话数达到或超过此限制时，将删去最旧的会话以为新会话腾出空间。这可以防止会话无限制增长，同时允许在多台设备上使用（例如，在桌面和移动设备上同时登录而不会使任何一方的会话失效）。

OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE​

  • 类型: bool
  • 默认值: False
  • 描述: 确保在刷新 Token 请求期间包含完整的 OAuth 范围（Scope），而不是依赖提供商的默认值。启用时，配置的范围（例如 MICROSOFT_OAUTH_SCOPE）将在 Token 刷新期间传递给身份提供商。这对于微软等提供商是必需的，在这些提供商中，缺失范围可能会导致刷新失败，尤其是在使用自定义 API 范围时。

WEBUI_AUTH_TRUSTED_EMAIL_HEADER​

  • 类型: str
  • 描述: 定义用于身份验证的可信请求标头。请参阅 SSO 文档。

WEBUI_AUTH_TRUSTED_NAME_HEADER​

  • 类型: str
  • 描述: 定义通过 WEBUI_AUTH_TRUSTED_EMAIL_HEADER 标头进行注册的可信用户名称请求标头。请参阅 SSO 文档。

WEBUI_AUTH_TRUSTED_GROUPS_HEADER​

  • 类型: str
  • 描述: 定义可信请求标头，当使用可信标头身份验证时，该标头包含用户群组数成员身份的逗号分隔列表。请参阅 SSO 文档。

WEBUI_AUTH_TRUSTED_ROLE_HEADER​

  • 类型: str
  • 描述: 定义可信请求标头，当使用可信标头身份验证时，该标头决定用户的角色（admin、user 或 pending）。设置后，用户的角色将在每次登录时更新以匹配标头值。无效的值将被忽略并记录警告。请参阅 SSO 文档。

Google​

请参阅 https://support.google.com/cloud/answer/6158849?hl=en

信息

你还必须设置 OPENID_PROVIDER_URL，否则登出可能无法正常工作。

GOOGLE_CLIENT_ID​

  • 类型: str
  • 描述: 设置 Google OAuth 的客户端 ID。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

GOOGLE_CLIENT_SECRET​

  • 类型: str
  • 描述: 设置 Google OAuth 的客户端密钥。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

GOOGLE_OAUTH_SCOPE​

  • 类型: str
  • 默认值: openid email profile
  • 描述: 设置 Google OAuth 身份验证的范围。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

GOOGLE_REDIRECT_URI​

  • 类型: str
  • 默认值: <backend>/oauth/google/callback
  • 描述: 设置 Google OAuth 的重定向 URI。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

GOOGLE_OAUTH_AUTHORIZE_PARAMS​

  • 类型: str (JSON 对象)
  • 默认值: {}
  • 描述: 向 OAuth /authorize 请求添加 Google 特定的参数。对于需要额外参数（如 prompt、login_hint 或 hd）的 Google 流程非常有用。
# Example (.env)
GOOGLE_OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com","hd":"example.com"}
注意

GOOGLE_OAUTH_AUTHORIZE_PARAMS 必须是有效的 JSON，并且必须是一个 JSON 对象。如果解析失败，Open WebUI 会将其忽略并记录警告。

Microsoft​

请参阅 https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app

信息

你还必须设置 OPENID_PROVIDER_URL，否则登出可能无法正常工作。

MICROSOFT_CLIENT_ID​

  • 类型: str
  • 描述: 设置 Microsoft OAuth 的客户端 ID。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

MICROSOFT_CLIENT_SECRET​

  • 类型: str
  • 描述: 设置 Microsoft OAuth 的客户端密钥。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

MICROSOFT_CLIENT_TENANT_ID​

  • 类型: str
  • 描述: 设置 Microsoft OAuth 的租户 ID。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

MICROSOFT_OAUTH_SCOPE​

  • 类型: str
  • 默认值: openid email profile
  • 描述: 设置 Microsoft OAuth 身份验证的范围。在启用了 OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE 时，该范围也将包含在刷新 Token 请求中，这是 Azure AD 避免 AADSTS90009 错误所必需的。如果你使用自定义 API 范围，请在此处包含它们（例如 openid email profile offline_access api://<Application ID URI>/<custom_scope>）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

MICROSOFT_REDIRECT_URI​

  • 类型: str
  • 默认值: <backend>/oauth/microsoft/callback
  • 描述: 设置 Microsoft OAuth 的重定向 URI。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

MICROSOFT_CLIENT_LOGIN_BASE_URL​

  • 类型: str
  • 默认值: https://login.microsoftonline.com
  • 描述: 设置 Microsoft OAuth 身份验证的基准登录 URL。允许配置用于政府云或自定义部署的备用登录端点。
  • 持久化: 此环境变量是一个 PersistentConfig 变量.

MICROSOFT_CLIENT_PICTURE_URL​

  • 类型: str
  • 默认值: https://graph.microsoft.com/v1.0/me/photo/$value
  • 描述: 指定用于在 OAuth 身份验证期间检索用户头像的 Microsoft Graph API 端点。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

GitHub​

请参阅 https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps

信息

你还必须设置 OPENID_PROVIDER_URL，否则登出可能无法正常工作。

GITHUB_CLIENT_ID​

  • 类型: str
  • 描述: 设置 GitHub OAuth 的客户端 ID。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

GITHUB_CLIENT_SECRET​

  • 类型: str
  • 描述: 设置 GitHub OAuth 的客户端密钥。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

GITHUB_CLIENT_SCOPE​

  • 类型: str
  • 默认值: user:email
  • 描述: 指定 GitHub OAuth 身份验证的范围。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

GITHUB_CLIENT_REDIRECT_URI​

  • 类型: str
  • 默认值: <backend>/oauth/github/callback
  • 描述: 设置 GitHub OAuth 的重定向 URI。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

飞书​

请参阅 https://open.feishu.cn/document/sso/web-application-sso/login-overview

FEISHU_CLIENT_ID​

  • 类型: str
  • 描述: 设置飞书 OAuth 的客户端 ID。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

FEISHU_CLIENT_SECRET​

  • 类型: str
  • 描述: 设置飞书 OAuth 的客户端密钥。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

FEISHU_OAUTH_SCOPE​

  • 类型: str
  • 默认值: contact:user.base:readonly
  • 描述: 指定飞书 OAuth 身份验证的范围。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

FEISHU_REDIRECT_URI​

  • 类型: str
  • 描述: 设置飞书 OAuth 的重定向 URI。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OpenID (OIDC)​

OAUTH_CLIENT_ID​

  • 类型: str
  • 描述: 设置 OIDC 的客户端 ID。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_CLIENT_SECRET​

  • 类型: str
  • 描述: 设置 OIDC 的客户端密钥。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OPENID_PROVIDER_URL​

  • 类型: str
  • 描述: 指向 .well-known/openid-configuration 端点的路径。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
危险

必须配置环境变量 OPENID_PROVIDER_URL，否则大多数提供商的登出功能将无法正常运行。 即使在使用 Microsoft、GitHub 或其他提供商时，你也必须设置 OPENID_PROVIDER_URL 环境变量。

或者，如果你的提供商不支持标准 OIDC 发现（例如 AWS Cognito），你可以将 OPENID_END_SESSION_ENDPOINT 设置为自定义登出 URL。

OPENID_END_SESSION_ENDPOINT​

  • 类型: str
  • 默认值: 空字符串 ("")
  • 描述: 设置自定义的结束会话（登出）端点 URL。配置后，Open WebUI 将在登出时重定向到此 URL，而不是尝试通过 OPENID_PROVIDER_URL 进行 OIDC 发现。这对于不支持标准 OIDC 发现进行登出的 OAuth 提供商（例如 AWS Cognito）非常有用。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OPENID_REDIRECT_URI​

  • 类型: str
  • 默认值: <backend>/oauth/oidc/callback
  • 描述: 设置 OIDC 的重定向 URI。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_SCOPES​

  • 类型: str
  • 默认值: openid email profile
  • 描述: 设置 OIDC 身份验证的范围。openid 和 email 是必需的。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_CODE_CHALLENGE_METHOD​

  • 类型: str
  • 选项:
    • S256 - 使用 SHA-256 哈希 code_verifier。
  • 默认值: 空字符串 (' ')，因为默认设置为 None。
  • 描述: 指定 OAuth 身份验证的代码挑战（Code Challenge）方法。当提供商需要 PKCE 时，设置为 S256。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_PROVIDER_NAME​

  • 类型: str
  • 默认值: SSO
  • 描述: 设置 OIDC 提供商的名称。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_USERNAME_CLAIM​

  • 类型: str
  • 默认值: name
  • 描述: 设置 OpenID 的用户名声明（Claim）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_EMAIL_CLAIM​

  • 类型: str
  • 默认值: email
  • 描述: 设置 OpenID 的电子邮件声明（Claim）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_PICTURE_CLAIM​

  • 类型: str
  • 默认值: picture
  • 描述: 设置 OpenID 的图片（头像）声明（Claim）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
信息

如果 OAUTH_PICTURE_CLAIM 被设置为 ''（空字符串），那么 OAuth 图片声明将被禁用，并且用户头像将不会被保存。

OAUTH_GROUP_CLAIM​

  • 类型: str
  • 默认值: groups
  • 描述: 指定 OAuth 身份验证的群组声明（Group Claim）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_OAUTH_ROLE_MANAGEMENT​

  • 类型: bool
  • 默认值: False
  • 描述: 启用 OAuth 委派的角色管理。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_OAUTH_GROUP_MANAGEMENT​

  • 类型: bool
  • 默认值: False
  • 描述: 启用或禁用 OAuth 群组管理。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_OAUTH_GROUP_CREATION​

  • 类型: bool
  • 默认值: False
  • 描述: 启用时，OAuth 声明中在 Open WebUI 内尚不存在的群组将被自动创建。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_GROUP_DEFAULT_SHARE​

  • 类型: str
  • 默认值: true
  • 选项:
    • true — 通过 OAuth 创建的群组将对任何人启用共享。
    • members — 通过 OAuth 创建的群组将仅允许与群组建成员共享。
    • false — 通过 OAuth 创建的群组将禁用共享（无人可以共享）。
  • 描述: 控制通过 OAuth 群组管理自动创建的群组的默认共享权限。仅在启用 ENABLE_OAUTH_GROUP_CREATION 时适用。现有群组不受此设置的影响。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_BLOCKED_GROUPS​

  • 类型: str
  • 默认值: []
  • 描述: 被阻止访问应用程序的群组名称的 JSON 数组。属于这些群组的用户即使拥有有效的 OAuth 凭据，也将被拒绝访问。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_ROLES_CLAIM​

  • 类型: str
  • 默认值: roles
  • 描述: 设置要在 OIDC Token 中寻找的角色声明。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_ALLOWED_ROLES​

  • 类型: str
  • 默认值: user,admin
  • 描述: 设置允许访问平台的角色。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_ADMIN_ROLES​

  • 类型: str
  • 默认值: admin
  • 描述: 设置被视为管理员的角色。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_ROLES_SEPARATOR​

  • 类型: str
  • 默认值: ,
  • 描述: 允许自定义角色分隔符，以拆分 OAUTH_*_ROLES 变量。专为包含逗号的 OAuth 角色而设计；适用于采用 LDAP 语法或其他将逗号作为角色名称一部分的系统中指定的角色。如果声明是一个字符串且包含该分隔符，它也将被该分隔符拆分。

OAUTH_GROUPS_SEPARATOR​

  • 类型: str
  • 默认值: ;
  • 描述: 指定用于从 OAuth 群组声明中解析多个群组名称的分隔符。当身份提供商将群组成员身份作为分隔字符串而不是数组返回时，将使用此分隔符。在与使用非标准分隔符的系统集成，或群组名称本身包含逗号时非常有用。

OAUTH_ALLOWED_DOMAINS​

  • 类型: str
  • 默认值: *
  • 描述: 指定允许进行 OAuth 身份验证的域名（例如 "example1.com,example2.com"）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OAUTH_AUDIENCE​

  • 类型: str
  • 默认值: 空字符串 (' ')
  • 描述: 指定在登录期间传递给 OAuth 提供商授权端点的受众（Audience）参数。某些提供商（例如 Auth0 和 Ory）使用此值来决定返回的 Access Token 类型——如果没有它，提供商通常会返回一个不透明的 Token，而如果有它，他们会返回一个可以解码 and 验证的 JWT。此参数不是官方 OAuth/OIDC 授权端点规范的一部分，但被某些提供商广泛支持。
信息

这在你需要一个 JWT Access Token 进行下游验证，或者你的 OAuth 提供商需要受众提示以生成正确的 Token 时非常有用。对于 Auth0，这通常是你的 API 标识符（例如 https://your-api.auth0.com/api/v2/）。对于 Ory，请指定你想要访问的资源服务器。

OAUTH_AUTHORIZE_PARAMS​

  • 类型: str (JSON 对象)
  • 默认值: {}
  • 描述: 在登录期间直接向 OAuth 提供商的授权端点传递额外参数。当你的提供商需要未被专用变量覆盖的自定义授权阶段参数时，请使用此项。

常见示例包括诸如 prompt、login_hint、domain_hint、resource、audience 或提供商特定的标志。

# Example (.env)
OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com"}
# Example (docker-compose)
environment:
  - OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com"}
注意

OAUTH_AUTHORIZE_PARAMS 必须是有效的 JSON 且必须是一个 JSON 对象（键/值映射）。如果解析失败，Open WebUI 会将其忽略并记录警告。

信息

如果你同时设置了 OAUTH_AUDIENCE 以及包含 audience 键的 OAUTH_AUTHORIZE_PARAMS，那么来自 OAUTH_AUTHORIZE_PARAMS 的值将优先采用。

OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE​

  • 类型: bool
  • 默认值: False
  • 描述: 启用时，在刷新 Token 请求中包含配置的 OAuth 范围（Scope）。某些 OAuth 提供商（特别是 Microsoft Azure AD）在刷新 Token 时要求显式提供范围。如果没有它，Azure AD 将把该请求视为应用程序正在为自身请求 Token，从而导致 AADSTS90009 错误。如果你在使用 OAuth 提供商时遇到 Token 刷新失败，请启用此项。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
信息

此设置符合 RFC 6749 Section 6 规范，其中 scope 参数在刷新 Token 请求期间是可选的。仅对要求该参数的提供商启用此项，例如某些 Azure AD 配置。

LDAP​

请参阅 https://openwebui.com/docs/features/authentication-access/auth/ldap

ENABLE_LDAP​

  • 类型: bool
  • 默认值: False
  • 描述: 启用 LDAP 身份验证。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_SERVER_URL​

  • 类型: str
  • 描述: 指定 LDAP 服务器 URL。
  • 示例: ldap://ldap.forumsys.com:389
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_USERNAME​

  • 类型: str
  • 描述: 指定用于 LDAP 身份验证的 Bind DN 或用户名。
  • 示例: cn=read-only-admin,dc=example,dc=com
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_PASSWORD​

  • 类型: str
  • 描述: 指定用于 LDAP 身份验证的密码。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_BASE_DN​

  • 类型: str
  • 描述: 指定用于 LDAP 搜索操作的 Base DN。
  • 示例: dc=example,dc=com
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_USER_DN​

  • 类型: str
  • 默认值: (empty)
  • 描述: 为用户查找指定自定义 User DN 模板或容器路径。这有助于缩小用户搜索范围。如果未设置，Open WebUI 将从 LDAP_BASE_DN 开始搜索。
  • 示例: ou=users,dc=example,dc=com 或 cn=users,dc=example,dc=com
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_SEARCH_FILTER​

  • 类型: str
  • 默认值: (|(sAMAccountName={username})(uid={username})(mail={username}))
  • 描述: 设置要使用的 LDAP 搜索过滤器。{username} 将被替换为输入的用户名。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_SEARCH_FILTER_BY_OBJECT_CLASS​

  • 类型: str
  • 默认值: (objectClass=person)
  • 描述: 将 LDAP 搜索结果限制为特定的对象类，以确保在同步操作期间仅查询相关的用户对象。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_ATTRIBUTE_MAPPING​

  • 类型: str (JSON 字符串)
  • 默认值: {"username": ["sAMAccountName", "uid"], "email": ["mail", "email"], "name": ["displayName", "cn"]}
  • 描述: 将 LDAP 属性映射到 Open WebUI 用户字段。指定哪些 LDAP 属性对应于用户的用户名、电子邮件和显示名称。
  • 示例: {"username": ["uid"], "email": ["mail"], "name": ["cn"]}
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_APP_DN​

  • 类型: str
  • 默认值: (empty)
  • 描述: 指定用户访问 Open WebUI 必须属于的群组 DN。如果设置，仅允许作为该群组（或其子群组）成员的用户登录。
  • 示例: cn=openwebui-users,ou=groups,dc=example,dc=com
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_APP_GROUP_FILTER​

  • 类型: str
  • 默认值: (member={user_dn})
  • 描述: 指定在配置了 LDAP_APP_DN 时用于验证群组成员身份的搜索过滤器。{user_dn} 会被动态替换为登录用户的完整 DN。可针对像 Active Directory 这样可能使用 memberOf 属性或备用语法的目录服务进行自定义。
  • 示例: 对于 Active Directory: (&(objectClass=user)(memberOf=cn=openwebui-users,ou=groups,dc=example,dc=com))
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_LDAP_ROLE_MANAGEMENT​

  • 类型: bool
  • 默认值: False
  • 描述: 启用基于 LDAP 群组的角色映射。启用时，将根据用户在 LDAP 目录中的群组成员身份，为用户分配 Open WebUI 角色（例如 admin）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_ADMIN_DN​

  • 类型: str
  • 描述: 指定 LDAP 群组 DN，其成员将在 Open WebUI 中被授予 admin 角色。
  • 示例: cn=openwebui-admins,ou=groups,dc=example,dc=com
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_ADMIN_GROUP_FILTER​

  • 类型: str
  • 默认值: (member={user_dn})
  • 描述: 指定用于检查用户是否属于 LDAP_ADMIN_DN 群组的搜索过滤器。{user_dn} 会被动态替换为登录用户的 DN。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_USER_DN_HEADER​

  • 类型: str
  • 描述: 当将可信标头身份验证与 LDAP 集成配合使用时，定义包含用户 LDAP DN 的可信请求标头。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_USER_GROUPS_HEADER​

  • 类型: str
  • 描述: 当将可信标头身份验证与 LDAP 集成配合使用时，定义包含用户所属 LDAP 群组列表的可信请求标头。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_LDAP_GROUP_MANAGEMENT​

  • 类型: bool
  • 默认值: False
  • 描述: 启用将 LDAP 群组映射到 Open WebUI 群组的功能。启用时，用户群组成员身份将在登录时从 LDAP 进行同步。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_GROUP_BASE_DN​

  • 类型: str
  • 描述: 指定 LDAP 群组所在的 Base DN。
  • 示例: ou=groups,dc=example,dc=com
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_GROUP_SEARCH_FILTER​

  • 类型: str
  • 默认值: (|(member={user_dn})(uniqueMember={user_dn}))
  • 描述: 设置用于查询用户群组成员身份的 LDAP 过滤器。{user_dn} 将被替换为用户的完整专有名称（Distinguished Name）。根据你的目录模式（Schema，例如 Active Directory 与 OpenLDAP）进行自定义。
  • 示例: 对于 Active Directory: (&(objectClass=group)(member={user_dn}))
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

LDAP_GROUP_ATTRIBUTE_MAPPING​

  • 类型: str (JSON 字符串)
  • 默认值: {"name": ["cn"]}
  • 描述: 指定 LDAP 群组属性到 Open WebUI 群组字段的 JSON 映射。通常将 name 映射到群组的常用名称（cn）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

SCIM​

请参阅 https://openwebui.com/docs/features/authentication-access/auth/scim

ENABLE_SCIM​

  • 类型: bool
  • 默认值: False
  • 描述: 启用跨域身份管理系统（SCIM）资源分配。SCIM 允许你从外部身份提供商（IdP，如 Okta、Azure AD/Entra ID 或 Google Workspace）自动执行用户资源分配（创建、更新和停用用户）。
注意

要使用 SCIM，你必须生成一个安全的 API Bearer Token。你可以使用 SCIM_AUTH_TOKEN 来配置此 Token。如果未配置，SCIM 请求将被拒绝。

SCIM_AUTH_TOKEN​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于对来自你的身份提供商的传入 SCIM 请求进行身份验证所需的 Bearer Token。此 Token 应该是一个安全的、随机生成的字符串。确保此 Token 与你的 IdP 的 SCIM 资源分配设置中配置的 Token 一致。

用户权限​

备注

这些是应用于新用户的默认权限。它们可以在针对每个用户单独进行覆盖。

聊天权限​

ENABLE_CHAT_DELETION​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户删除自己的聊天。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_CHAT_EDITING​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户编辑自己的聊天消息。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_CHAT_TEMPORARY​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户启动不保存到数据库的临时聊天。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

功能权限​

ENABLE_COMMUNITY_SHARING​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户与社区分享他们的自定义模型、提示词和工具。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_MESSAGE_RATING​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户对模型响应进行评分。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

工作区权限​

ENABLE_USER_MODELS​

  • 类型: bool
  • 默认值: True
  • 描述: 允许非管理员用户在其个人工作区内创建、更新和管理自己的自定义模型。禁用时，仅管理员可以管理模型。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_USER_PROMPTS​

  • 类型: bool
  • 默认值: True
  • 描述: 允许非管理员用户创建、更新和管理自己的自定义提示词。禁用时，仅管理员可以管理提示词。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_USER_TOOLS​

  • 类型: bool
  • 默认值: True
  • 描述: 允许非管理员用户创建、更新和管理自己的自定义工具。禁用时，仅管理员可以管理工具。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

分享 (私有)​

ENABLE_WORKSPACE_MODEL_SHARING​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户与其他工作区成员分享他们的自定义模型。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_PROMPT_SHARING​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户与其他工作区成员分享他们的自定义提示词。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_TOOL_SHARING​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户与其他工作区成员分享他们的自定义工具。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

分享 (公开)​

ENABLE_WORKSPACE_MODEL_PUBLIC_SHARING​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户公开推送/分享他们的自定义模型。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_PROMPT_PUBLIC_SHARING​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户公开推送/分享他们的自定义提示词。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_TOOL_PUBLIC_SHARING​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户公开推送/分享他们的自定义工具。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

访问授权​

ENABLE_WORKSPACE_MODEL_ACCESS_GRANTS​

  • 类型: bool
  • 默认值: True
  • 描述: 允许工作区管理员向特定用户授予对自定义模型的访问权限。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_PROMPT_ACCESS_GRANTS​

  • 类型: bool
  • 默认值: True
  • 描述: 允许工作区管理员向特定用户授予对自定义提示词的访问权限。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_TOOL_ACCESS_GRANTS​

  • 类型: bool
  • 默认值: True
  • 描述: 允许工作区管理员向特定用户授予对自定义工具的访问权限。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

导入 / 导出​

ENABLE_WORKSPACE_MODEL_EXPORT​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户导出他们的自定义模型。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_MODEL_IMPORT​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户导入自定义模型。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_PROMPT_EXPORT​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户导出他们的自定义提示词。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_PROMPT_IMPORT​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户导入自定义提示词。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_TOOL_EXPORT​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户导出他们的自定义工具。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_WORKSPACE_TOOL_IMPORT​

  • 类型: bool
  • 默认值: True
  • 描述: 允许用户导入自定义工具。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

设置权限​

ENABLE_ADMIN_EXPORT​

  • 类型: bool
  • 默认值: True
  • 描述: 允许管理员导出系统设置。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

ENABLE_ADMIN_IMPORT​

  • 类型: bool
  • 默认值: True
  • 描述: 允许管理员导入系统设置。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

其他环境变量​

云存储​

Open WebUI 支持兼容 S3 的云存储提供商以持久化文件。配置后，文件将存储在云端存储桶中，而不是本地文件系统。一次只能激活一个云存储提供商。

CLOUD_STORAGE_PROVIDER​

  • 类型: str
  • 默认值: None
  • 选项:
    • s3 - 使用 Amazon S3 或兼容 S3 的提供商。
    • gcs - 使用 Google Cloud Storage。
    • azure - 使用 Microsoft Azure Storage。
  • 描述: 指定要使用的云存储提供商。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

Amazon S3 存储​

要使用兼容 S3 的提供商（例如 MinIO、Cloudflare R2），请配置以下环境变量：

CLOUD_STORAGE_S3_ENDPOINT_URL​
  • 类型: str
  • 默认值: None
  • 描述: 指定兼容 S3 服务的端点 URL。在连接到官方 AWS S3 之外的提供商（例如 MinIO、Cloudflare R2）时使用此项。
  • 示例: https://my-minio-server.com:9000 或 https://<accountid>.r2.cloudflarestorage.com
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_S3_ACCESS_KEY_ID​
  • 类型: str
  • 默认值: None
  • 描述: 指定用于向兼容 S3 的服务进行身份验证的 Access Key ID。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_S3_SECRET_ACCESS_KEY​
  • 类型: str
  • 默认值: None
  • 描述: 指定用于向兼容 S3 的服务进行身份验证的 Secret Access Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_S3_BUCKET_NAME​
  • 类型: str
  • 默认值: None
  • 描述: 指定用于存储文件的存储桶（Bucket）名称。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_S3_REGION_NAME​
  • 类型: str
  • 默认值: None
  • 描述: 指定 S3 存储桶的区域名称。
  • 示例: us-east-1，auto（常用于 Cloudflare R2）
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_S3_SECURE​
  • 类型: bool
  • 默认值: True
  • 描述: 切换与 S3 端点通信时是否使用安全的 HTTPS 连接。当设置为 False 时，将使用 HTTP。出于安全考虑，建议保持为 True，本地自托管部署（例如本地 MinIO）除外。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_S3_SIGNATURE_VERSION​
  • 类型: str
  • 默认值: None
  • 描述: 指定用于请求签名的 AWS 签名版本。例如 s3v4（标准）或 s3（旧版）。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

Google Cloud Storage​

要使用 Google Cloud Storage，请配置以下变量：

CLOUD_STORAGE_GCS_BUCKET_NAME​
  • 类型: str
  • 默认值: None
  • 描述: 指定用于存储文件的 GCS 存储桶（Bucket）名称。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_GCS_PROJECT_ID​
  • 类型: str
  • 默认值: None
  • 描述: 指定与 GCS 存储桶关联的 Google Cloud 项目 ID。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_GCS_CREDS_JSON​
  • 类型: str (JSON 字符串或 JSON 文件路径)
  • 默认值: None
  • 描述: 配置 GCS 凭证。可以是内联 JSON 凭证字符串，也可以是主机容器上 GCP 服务账号凭证 JSON 文件的绝对路径。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

Microsoft Azure Storage​

要使用 Microsoft Azure Blob 存储，请配置以下变量：

CLOUD_STORAGE_AZURE_ACCOUNT_NAME​
  • 类型: str
  • 默认值: None
  • 描述: 指定 Azure 存储账号名称。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_AZURE_ACCOUNT_KEY​
  • 类型: str
  • 默认值: None
  • 描述: 指定 Azure 存储账号的 Access Key。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_AZURE_CONTAINER_NAME​
  • 类型: str
  • 默认值: None
  • 描述: 指定 Azure 存储账号中用于存储文件的容器名称。
  • 持久化: 此环境变量是一个 PersistentConfig 变量。
CLOUD_STORAGE_AZURE_CONNECTION_STRING​
  • 类型: str
  • 默认值: None
  • 描述: 指定 Azure 存储账号的连接字符串。当设置时，这将覆盖 CLOUD_STORAGE_AZURE_ACCOUNT_NAME 和 CLOUD_STORAGE_AZURE_ACCOUNT_KEY。
  • 示例: DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net
  • 持久化: 此环境变量是一个 PersistentConfig 变量。

OpenTelemetry 配置​

Open WebUI 支持用于监控和追踪的 OpenTelemetry。启用时，它可以将追踪数据发送给 OpenTelemetry 收集器。

ENABLE_OTEL​

  • 类型: bool
  • 默认值: False
  • 描述: 针对后端追踪启用 OpenTelemetry 埋点（Instrumentation）。启用时，追踪遥测数据将被导出到配置的收集器。

OTEL_EXPORTER_OTLP_ENDPOINT​

  • 类型: str
  • 默认值: http://localhost:4317
  • 描述: 指定用于发送遥测数据的 OTLP gRPC 端点 URL。
  • 示例: http://otel-collector:4317

OTEL_SERVICE_NAME​

  • 类型: str
  • 默认值: open-webui
  • 描述: 设置用于在 OpenTelemetry 后端中识别此 Open WebUI 实例的服务名称。

数据库连接池​

Open WebUI 使用数据库连接池来管理与 PostgreSQL/Postgres 以及 MySQL 数据库的连接。使用连接池可以通过重用现有连接，而不是为每个查询都建立新连接，从而提高性能。

DATABASE_POOL_SIZE​

  • 类型: int
  • 默认值: None
  • 描述: 设置连接池大小（要保持打开的数据库连接的最大数量）。如果未设置，将使用 SQLAlchemy 的默认连接池大小 5。

DATABASE_POOL_MAX_OVERFLOW​

  • 类型: int
  • 默认值: None
  • 描述: 指定最大连接溢出数量（在高峰流量期间，可以超出 DATABASE_POOL_SIZE 打开的额外连接数量）。如果未设置，将使用 SQLAlchemy 的默认溢出上限值 10。

DATABASE_POOL_TIMEOUT​

  • 类型: int
  • 默认值: None
  • 描述: 指定在抛出错误之前，等待获取连接池中可用连接的超时时间（以秒为单位）。如果未设置，将使用 SQLAlchemy 的默认超时时间 30 秒。

DATABASE_POOL_RECYCLE​

  • 类型: int
  • 默认值: None
  • 描述: 设置连接回收时间（以秒为单位）。重用数据库连接时间过长可能会导致连接陈旧、防火墙超时断开或数据库服务器上的内存泄漏问题。超过此限制的连接将被关闭，并在下一次查询时被新连接替换。如果未设置，将使用 SQLAlchemy 的默认值 -1（不回收）。
  • 示例: 将此项设置为 3600 将每小时回收一次数据库连接。

使用 SQLCipher 加密的 SQLite​

Open WebUI 支持针对 SQLite 数据库使用 SQLCipher 进行数据库加密。这使你能够加密静态状态下的数据库文件，以增强安全性。

注意

要使用 SQLCipher，你必须在 Python 环境中安装了 pysqlcipher3 或其兼容库。在基于 Docker 安装的 Open WebUI 中，此依赖项已预先安装。然而在 Conda/Pip 安装中，你必须手动在主机系统上安装 SQLCipher 依赖项。

SQLCIPHER_KEY​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于 SQLCipher 数据库加密的加密密码/密钥。当设置时，Open WebUI 将使用此密钥加密 SQLite 数据库。
危险

切勿丢失你的密钥！

如果你丢失了此密钥或稍后配置错误，你将无法读取你的 SQLite 数据库文件。这将导致应用程序无法启动或数据丢失。请务必安全备份此密钥。

Redis​

对于生产环境部署，强烈建议使用 Redis，尤其是在负载均衡器后方运行多个 Open WebUI 实例（副本/Worker）时。它实现了共享缓存和会话同步，从而防止在用户请求被路由到不同副本时发生间歇性登出或看到不一致数据的问题。

REDIS_URL​

  • 类型: str
  • 默认值: None
  • 描述: 指定 Redis 服务器 URL。配置后，Open WebUI 将使用 Redis 作为缓存存储和会话管理的共享后端。
  • 示例: redis://localhost:6379/0 或 redis://:mypassword@redis-server:6379/0

Uvicorn 设置​

这些变量允许微调托管 Open WebUI 的 Uvicorn ASGI Web 服务器。

UVICORN_WORKERS​

  • 类型: int
  • 默认值: 1
  • 描述: 指定要启动的 Uvicorn Worker 进程数量。增加 Worker 数量可以提高多核系统上的并发能力和吞吐量。
  • 用法: 对于高并发生产环境部署，建议将此项设置为匹配可用 CPU 核心数的值（例如 2 或 4）。
注意

当使用多个 Uvicorn Worker 时，你必须配置像 Redis（REDIS_URL）这样的共享缓存后端，并设置共享密钥（WEBUI_SECRET_KEY 和 OAUTH_SESSION_TOKEN_ENCRYPTION_KEY）。如果保持未设置状态，每个 Worker 将生成其自己的内存中缓存和加密密钥，从而在用户请求跨不同进程进行负载均衡时，导致身份验证和会话失败。

缓存设置​

这些变量配置后端应用程序中的缓存行为。

CACHE_DIR​

  • 类型: str
  • 默认值: ${DATA_DIR}/cache
  • 描述: 指定用于存储本地缓存文件（如已下载的模型文件、搜索结果片段和临时媒体资源）的文件系统目录。

代理设置​

这些变量配置 Open WebUI 在进行传出外部 API 调用（例如获取 Web 搜索结果、检查更新、连接远程 LLM 提供商）时应使用的 HTTP/HTTPS 代理。

HTTP_PROXY​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于传出 HTTP 请求的代理服务器。
  • 示例: http://10.10.1.10:3128 或 http://user:password@proxy.example.com:8080

HTTPS_PROXY​

  • 类型: str
  • 默认值: None
  • 描述: 指定用于传出 HTTPS 请求的代理服务器。
  • 示例: http://10.10.1.10:3128

NO_PROXY​

  • 类型: str
  • 默认值: None
  • 描述: 应绕过代理设置的主机名或 IP 地址的逗号分隔列表。通常包含本地环回（localhost,127.0.0.1）以及内部服务地址（例如本地 Ollama 容器，如 ollama）。
  • 示例: localhost,127.0.0.1,ollama,.internal.company.com

安装所需的 Python 包​

Open WebUI 允许在运行时动态安装自定义 Pipelines、Functions 或 Tools 所需的 Python 包。

ENABLE_PIP_INSTALL​

  • 类型: bool
  • 默认值: False
  • 描述: 切换是否允许应用程序在运行时执行动态 pip install 命令。

当设置为 True 时，声明了外部依赖项的 Function 或 Tool（使用形如 # pip install <package> 的注释）在导入时会自动触发 pip 进行安装。

危险

安全风险

在多用户环境中，启用 ENABLE_PIP_INSTALL 会带来巨大的安全风险。如果允许不受信任的用户上传或运行自定义 Function/Tool，他们可能会利用此设置在主机系统上安装恶意包或执行任意代码。

仅在你可以完全控制已上传代码的安全、受信任或单用户环境中启用此变量。在企业或公共部署中，强烈建议将此项保持为 False，并改为预先将依赖项安装到容器镜像中。

提示

预先安装包 (推荐)

如果你希望将 ENABLE_PIP_INSTALL 保持为 False，但仍然需要用于自定义 Function/Tool 的特定包，你应该预先在容器内部安装它们。

你可以通过编写一个扩展官方 Open WebUI 镜像的自定义 Dockerfile 来实现这一点：

FROM ghcr.io/open-webui/open-webui:main

RUN pip install --no-cache-dir python-docx requests beautifulsoup4

禁用时，导入缺失包的 Function 和 Tool 将在加载时失败，并抛出 ModuleNotFoundError，从而清晰地指示需要预先安装哪些包。

PIP_OPTIONS​

  • 类型: str
  • 描述: 指定 pip 在安装包时应使用的附加命令行选项。例如，你可以包含诸如 --upgrade、--user 或 --no-cache-dir 等标志来控制安装过程。

PIP_PACKAGE_INDEX_OPTIONS​

  • 类型: str
  • 描述: 为 pip 定义自定义的包索引行为。这可以包含指定附加或备用索引 URL（例如 --extra-index-url）、身份验证凭据，或管理如何从不同位置检索包的其他参数。
This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.