环境变量配置
概述
Open WebUI 提供了大量的环境变量，允许你定制和配置应用程序的各个方面。本页面作为所有可用环境变量的综合参考，提供它们的类型、默认值和描述。 随着新变量的引入，本页面将不断更新，以反映日益增加的配置选项。
信息
本页面与 Open WebUI 发布版本 v0.9.6 保持同步，但仍在完善中，后续将包含更准确的描述、列出环境变量的可用选项、默认值以及改进的描述。
关于 ConfigVar 环境变量的重要说明
备注
首次启动 Open WebUI 时，所有环境变量都被同等对待，可用于配置应用程序。但是，对于标记为 ConfigVar 的环境变量，它们的值会被持久化并存储在内部。
初始启动后，如果你重新启动容器，ConfigVar 环境变量将不再使用外部环境变量的值。相反，它们将使用内部存储的值。
相比之下，常规环境变量将在随后的每次重启时继续更新并应用。
你可以直接从 Open WebUI 内部更新 ConfigVar 环境变 量的值，这些更改将存储在内部。这使你可以独立于外部环境变量来管理这些配置设置。
请注意，ConfigVar 环境变量在下面的文档中已明确标记，以便你了解它们的行为方式。
要禁用此行为并强制 Open WebUI 始终使用你的环境变量（忽略数据库），请将 ENABLE_PERSISTENT_CONFIG 设置为 False。
CRITICAL WARNING（严重警告）： 当 ENABLE_PERSISTENT_CONFIG 为 False 时，你可能仍然能够在管理界面中编辑设置。然而，这些更改不会永久保存。它们仅在当前会话中持续有效，并在你重新启动容器时丢失，因为系统将恢复为环境变量中定义的值。
排查被忽略的环境变量 🛠️
如果你更改了环境变量（例如 ENABLE_SIGNUP=True）但在 UI 中未看到更改反映出来（例如，"注册"按钮仍然缺失），这很可能是因为之前运行的值或持久化的 Docker 卷中的值已经持久化在数据库中。
选项 1：使用 ENABLE_PERSISTENT_CONFIG（临时修复）
在你的环境中设置 ENABLE_PERSISTENT_CONFIG=False。这会强制 Open WebUI 直接读取你的变量。请注意，在此模式下，基于 UI 的设置更改不会在重启后持久保留。
选项 2：通过管理界面更新（推荐）
更改 ConfigVar 设置的最简单、最安全的方法是直接通过 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：重置以进行全新安装
如果你正在执行全新安装并希望确保所有环境变量都是全新的：
- 停止容器。
- 删除持久卷：
docker volume rm open-webui。 - 重新启动容器。
危险
警告： 删除卷将删除所有用户数据，包括聊天和账户。
应用程序/后端
以下环境变量被 backend/open_webui/config.py 使用以提供 Open WebUI 启动
配置。请注意，某些变量的默认值可能会根据
你是直接运行 Open WebUI 还是通过 Docker 运行而有所不同。有关日志记录
环境变量的更多信息，请参阅我们的 日志文档。
常规
WEBUI_URL
- 类型：
str - 默认值：
http://localhost:3000 - 描述：指定实例可访问的 URL；OAuth/SSO 和搜索引擎支持都需要它。
- 持久化：这是一个
ConfigVar变量。
注意
首次使用 OAuth/SSO 之前必须先设置 WEBUI_URL。由于它是持久化配置，建议通过 ENABLE_PERSISTENT_CONFIG 或管理面板修改；否则登录会失败。
ENABLE_SIGNUP
- 类型：
bool - 默认值：
True - 描述：控制是否允许创建新用户账户。
- 持久化：这是一个
ConfigVar变量。
ENABLE_SIGNUP_PASSWORD_CONFIRMATION
- 类型：
bool - 默认值：
False - 描述：为注册页添加“确认密码”字段，减少输错密码。
WEBUI_ADMIN_EMAIL
- 类型：
str - 默认值：空字符串（
''） - 描述：首次启动且数据库中没有用户时自动创建管理员账号的邮箱。
信息
只有在数据库为空且同时配置了 WEBUI_ADMIN_EMAIL 和 WEBUI_ADMIN_PASSWORD 时，才会创建管理员账号。创建后会自动禁用注册。
WEBUI_ADMIN_PASSWORD
- 类型：
str - 默认值：空字符串（
''） - 描述：自动创建的管理员账号密码，需与
WEBUI_ADMIN_EMAIL一起使用。
危险
安全注意事项
- 生产环境请使用强且唯一的密码
- 建议使用 secrets 管理，不要明文保存
- 初始设置后建议通过 UI 更改管理员密码
- 不要提交到版本控制
WEBUI_ADMIN_NAME
- 类型：
str - 默认值：
Admin - 描述：自动创建管理员账号的显示名称。
ENABLE_LOGIN_FORM
- 类型：
bool - 默认值：
True - 描 述：控制登录表单、邮箱/密码字段及“或”分隔元素的显示。
- 持久化：这是一个
ConfigVar变量。
ENABLE_PASSWORD_CHANGE_FORM
- 类型：
bool - 默认值：
True - 描述：控制 设置 > 账户 中密码修改界面的可见性。
- 持久化：这是一个
ConfigVar变量。
ENABLE_PASSWORD_AUTH
- 类型：
bool - 默认值：
True - 描述：控制密码认证是否可用。关闭后只允许 SSO/OAuth。
提示
如果你只使用 SSO/OAuth 登录并公开部署 Open WebUI，建议将此项设为 False 以避免基于密码的登录。
危险
只有在同时启用 ENABLE_OAUTH_SIGNUP 时才应关闭此项；否则会导致无法登录。
DEFAULT_LOCALE
- 类型：
str - 默认值：
en - 描述：设置应用程序的默认语言环境。
- 持久化：这是一个
ConfigVar变量。
DEFAULT_MODELS
- 类型：
str - 默认值：空字符串（
''） - 描述：设置默认模型列表。
- 持久化：这是一个
ConfigVar变量。
DEFAULT_PINNED_MODELS
- 类型：
str - 默认值：空字符串（
''） - 描述：为新用户预置默认置顶模型的 ID 列表，使用逗号分隔。
- 示例：
gpt-4,claude-3-opus,llama-3-70b - 持久化：这是一个
ConfigVar变量。
DEFAULT_MODEL_METADATA
- 类型：
dict(JSON object) - 默认值：
{} - 描述：为所有模型设置全局默认元数据；模型自己的设置始终优先。
- 持久化：这是一个
ConfigVar变量。存储在配置键models.default_metadata。
DEFAULT_MODEL_PARAMS
- 类型：
dict(JSON object) - 默认值：
{} - 描述：为所有模型设置全局默认参数（temperature、top_p、max_tokens、seed 等）。
- 持久化：这是一个
ConfigVar变量。存储在配置键models.default_params。
信息
DEFAULT_MODEL_PARAMS 会在启动时以 JSON 字符串从环境变量读取；解析失败时会回退到 {}。
DEFAULT_USER_ROLE
- 类型：
str - 选项：
pending、user、admin - 默认值：
pending - 描述：设置新用户默认角色。
- 持久化：这是一个
ConfigVar变量。
DEFAULT_GROUP_ID
- 类型：
str - 默认值：空字符串（
''） - 描述：设置新用户默认加入的组 ID。
- 持久化：这是一个
ConfigVar变量。
DEFAULT_GROUP_SHARE_PERMISSION
- 类型：
str - 选项：
members、true、false - 默认值：
members - 描述：控制新建用户组的默认共享权限。
PENDING_USER_OVERLAY_TITLE
- 类型：
str - 默认值：空字符串（
''） - 描述：为待处理用户遮罩设置自定义标题。
- 持久化：这是一个
ConfigVar变量。
PENDING_USER_OVERLAY_CONTENT
- 类型：
str - 默认值：空字符串（
''） - 描述：为待处理用户遮罩设置自定义文本内容。
- 持久化：这是一个
ConfigVar变量。
ENABLE_CALENDAR
- 类型：
bool - 默认值：
True - 描述：用于启用或禁用日历功能，支持创建、管理和共享日历。
- 持久化：这是一个
ConfigVar变量。
ENABLE_CHANNELS
- 类型：
bool - 默认值：
False - 描述：用于启用或禁用频道支持。
- 持久化：这是一个
ConfigVar变量。
ENABLE_FOLDERS
- 类型：
bool - 默认值：
True - 描述：用于启用或禁用文件夹功能，允许用户在侧边栏中整理聊天。
- 持久化：这是一个
ConfigVar变量。
FOLDER_MAX_FILE_COUNT
- 类型：
int - 默认值：空字符串（无限制）
- 描述：设置每个文件夹允许处理的最大文件数。
- 持久化：这是一个
ConfigVar变量。可在 Admin Panel > Settings > General > Folder Max File Count 中配置。
ENABLE_AUTOMATIONS
- 类型：
bool - 默认值：
True - 描述：用于全局启用或禁用自动化功能。
- 持久化：这是一个
ConfigVar变量。
AUTOMATION_MAX_COUNT
- 类型：
int - 默认值：空字符串（无限制）
- 描述：限制非管理员用户可创建的自动化数量。
- 持久化：这是一个
ConfigVar变量。
AUTOMATION_MIN_INTERVAL
- 类型：
int(seconds) - 默认值：空字符串（无最小值）
- 描述：限制非管理员用户自动化重复执行的最小间隔（秒）。
- 持久化：这是一个
ConfigVar变量。
Common values for AUTOMATION_MIN_INTERVAL
| 数值 | 含义 |
|---|---|
60 | 两次运行之间最少 1 分钟 |
300 | 两次运行之间最少 5 分钟 |
900 | 两次运行之间最少 15 分钟 |
3600 | 两次运行之间最少 1 小时 |
SCHEDULER_POLL_INTERVAL
- 类型：
int(seconds) - 默认值：
10 - 描述：设置调度器轮询间隔，统一调度器同时处理自动化执行和日历提醒。
CALENDAR_ALERT_LOOKAHEAD_MINUTES
- 类型：
int(minutes) - 默认值：
10 - 描述：日历提醒的默认提前窗口（分钟），窗口内的事件会触发通知。
ENABLE_NOTES
- 类型：
bool - 默认值：
True - 描述：用于启用或禁用笔记功能。
- 持久化：这是一个
ConfigVar变量。
ENABLE_MEMORIES
- 类型：
bool - 默认值：
True - 描述：用于启用或禁用记忆功能，让模型存储和检索长期信息。
- 持久化：这是一个
ConfigVar变量。
WEBHOOK_URL
- 类型：
str - 描述：设置用于与 Discord/Slack/Microsoft Teams 集成的 webhook。
- 持久化：这是一个
ConfigVar变量。
ENABLE_ADMIN_EXPORT
- 类型：
bool - 默认值：
True - 描述：控制管理员是否可以导出数据、聊天记录和数据库。
ENABLE_ADMIN_CHAT_ACCESS
- 类型：
bool - 默认值：
True - 描述：允许管理员直接访问其他用户的聊天记录。
ENABLE_ADMIN_ANALYTICS
- 类型：
bool - 默认值：
True - 描述：控制管 理面板中的 Analytics 选项卡是否可见且可访问。
BYPASS_ADMIN_ACCESS_CONTROL
- 类型：
bool - 默认值：
True - 描述：控制管理员是否绕过工作区访问控制，访问所有项目和模型。
ENABLE_USER_WEBHOOKS
- 类型：
bool - 默认值：
False - 描述：启用或禁用用户 webhook（每个用户可设置一个 URL，其通知会以 POST 方式推送到该 URL）。出于 SSRF 安全考虑，凡是解析到私有或保留 IP 的 webhook URL 一律拒绝，除非
ENABLE_RAG_LOCAL_WEB_FETCH被设为true。 - 持久化：这是一个
ConfigVar变量。
RESPONSE_WATERMARK
- 类型：
str - 默认值：空字符串（
''） - 描述：设置复制消息时附加的自定义文本。
- 持久化：这是一个
ConfigVar变量。
IFRAME_CSP
- 类型：
str - 默认值：空字符串（不注入 CSP）
- 描述：为 UI 中所有渲染的
srcdociframe 设置统一的 Content-Security-Policy —— 包括 Artifacts、代码/HTML 预览、文件预览、引用弹窗。设置后会在 iframe 文档顶部注入一个<meta http-equiv="Content-Security-Policy">标签，限制 LLM 生成或用户上传的 HTML 能够加载和执行的内容（网络连接、脚本、样式、字体、frame）。iframe 上的sandbox属性仍然提供基础隔离；这里的 CSP 是为需要限制渲染 HTML 出站请求的部署提供的额外纵深防御。示例值：default-src 'self' 'unsafe-inline' 'unsafe-eval' data: blob:; connect-src 'none'。不设置则保持现有行为（仅 sandbox）。
THREAD_POOL_SIZE
- 类型：
int - 默认值：
0（未设置——使用 AnyIO 默认上限 40） - 描述：设置 AnyIO 工作线程池中同时可运行的阻塞操作上限。Open WebUI 通过
run_in_threadpool把同步/阻塞工作（多数 DB 调用、文件 I/O、同步路由处理器、部分库调用）卸载到这个池子中。该值是并发上限（token 上限），不是一组预生成的 OS 线程，也不是 CPU 核心/线程数：工作线程按需懒加载并复用，因此较高的值不会凭空创建那么多线程、消耗 CPU，或在空闲时引起 争用。它只提升了能同时进行的阻塞操作数量，超出的请求必须排队。
在任何真实服务器上将其调高（2000+）；永远不要调低
AnyIO 的默认值 40 对生产环境来说远不够。当同时需要的阻塞操作数超过 THREAD_POOL_SIZE（许多用户同时操作，或少量用户各自触发多次阻塞调用）时，每一个新增请求都得等待空闲槽位。症状是整个应用在高负载下看起来挂起/冻结/停止响应，但 CPU 和内存看起来都正常——这是线程池饥饿，不是资源耗尽。
- 普通服务器/生产环境：
2000或更高。2000对超大型多用户实例来说只是下限——调得更高也没问题，而且不会带来 CPU 或争用风险（它是上限，不是预分配）。 - 永远不要低于默认值。 空闲的高上限几乎不消耗资源；低上限才会导致冻结。
- 例外——弱硬件（Raspberry Pi、小型 VPS、CPU 配额约 250m / 内存很低的容器）：不要在这里设
2000。每个真正并发的阻塞操作仍会占用一个真正的 OS 线程（栈内存），所以在极小设备上超大的上限会让流量突增时产生足够多的线程耗尽内存。保持默认值，或按设备实际承受能力设置为几百的较小值。该例外只适用于受限单板/微型部署——任何正常服务器都应该用2000+。 - 持久化：这是一个
ConfigVar变量。
ENABLE_CUSTOM_MODEL_FALLBACK
- 类型：
bool - 默认值：
False - 描述：当自定义模型的基础模型缺失时，是否回退到默认模型。
SHOW_ADMIN_DETAILS
- 类型：
bool - 默认值：
True - 描述：切换是否在界面中显示管理员用户详情。
- 持久化：这是一个
ConfigVar变量。
ENABLE_PUBLIC_ACTIVE_USERS_COUNT
- 类型：
bool - 默认值：
True - 描述：控制活跃用户数量对所有用户可见，还是仅管理员可见。
- 持久化：这是一个
ConfigVar变量。
ENABLE_USER_STATUS
- 类型：
bool - 默认值：
True - 描述：全局启用或禁用用户状态功能；关闭后状态 UI 与相关 API 会被隐藏/限制。
- 持久化：这是一个
ConfigVar变量。可在 Admin Panel > Settings > General > User Status 中切换。
ENABLE_EASTER_EGGS
- 类型：
bool - 默认值：
True - 描述：启用或禁用 UI 中的彩蛋功能，例如特殊主题（如 “Her” 主题）。
ADMIN_EMAIL
- 类型：
str - 描述：
SHOW_ADMIN_DETAILS显示的管理员邮箱。 - 持久化：这是一个
ConfigVar变量。
ENV
- 类型：
str - 选项：
dev- 启用/docs上的 FastAPI API 文档prod- 自动配置若干环境变量
- 默认值：
- 后端默认值：
dev - Docker 默认值：
prod
- 后端默认值：
- 描述：环境设置。
ENABLE_PERSISTENT_CONFIG
- 类型：
bool - 默认值：
True - 描述：控制数据库配置与环境变量的优先级。
True（默认值）： 数据库中保存的值优先。False： 环境变量优先；启动时不会再从数据库加载该配置。- 严重警告： 在 UI 中看似修改成功的设置，重启后会丢失。
- 使用场景： 如果你希望完全通过
docker-compose.yaml或.env管理配置，可设为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这会让 Open WebUI 运行在 9999 端口。此模式下会忽略 PORT 环境变量。
ENABLE_REALTIME_CHAT_SAVE
- 类型：
bool - 默认值：
False - 描述：启用后，系统会把流式聊天的每个分块实时写入数据库。
EXTREME PERFORMANCE RISK: DO NOT ENABLE IN PRODUCTION
强烈建议不要在生产或多用户环境中启用此项。
启用后，LLM 生成的每个 token 都会触发一次单独的数据库写入。在多用户环境中，这会：
- 耗尽数据库连接池：快速写入会很快耗尽所有可用连接，导致
QueuePool limit reached错误和全局卡死。 - 严重拖慢性能：每分钟成千上万次数据库事务会给所有用户带来巨大延迟。
- 增加硬件压力：会对存储系统造成极大的 I/O 压力。
请保持为 False（默认值）。 对话仍会在生成完成后自动保存；此设置只适用于极端调试或单用户环境。
ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION
- 类型：
bool - 默 认值：
False - 描述：启用后，会自动把 Markdown 中超过 1KB 的 base64 图片上传并转换为图片 URL，以减小响应文本体积。
ENABLE_IMAGE_CONTENT_TYPE_EXTENSION_FALLBACK
- 类型：
bool - 默认值：
False - 描述：当系统 MIME 数据库和文件元数据都无法识别图片类型时，使用扩展名到 MIME 的硬编码兜底映射。
ENABLE_PROFILE_IMAGE_URL_FORWARDING
- 类型：
bool - 默认值：
True - 描述：控制用户和模型头像端点是否会对存储在
profile_image_url中的外部http(s)://URL 做302 Found重定向到原始来源。设为False时不再重定向，端点会回退到内置的默认头像。设为False可以避免客户端在加载攻击者控制的头像 URL 时把 IP、User-Agent、Referer 泄漏给攻击者（data URI 以及同源/静态图片仍然正常加载）。如果你的部署确实依赖外部头像 URL（例如上游身份提供方返回的 Gravatar 重定向），应保留默认值。该变量只在启动时读取一次——它不是ConfigVar，无法在管理面板中修改。
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 前缀校验，因此在这里新增一个类型既会在读取路径上提供它，也会在写入路径上接受它。该变量只在启动时读取一次——它不是ConfigVar，无法在管理面板中修改。
PROFILE_IMAGE_MAX_DATA_URI_SIZE
- 类型：
int（字节） - 默认值：未设置（无限制）
- 描述：内联
data:image/...;base64,...头像的最大字节长度。该共享的头像校验器会在保存时拒绝更长的 data URI，适用于用户头像和模型图标。可用它来限制超大内联图片导致的 Postgres/Redis 膨胀（以及更慢的模型列表响应）。仅限制data:URI；http(s)头像 URL 和内建静态路径不受影响。限制按 base64 编码后的字符串长度计算（比原始图片大约大三分之一），因此262144（256 KiB）大约对应 190 KiB 的实际图片。未设置（默认）时内联图片无上限。启动时读取一次——不是ConfigVar，无法在管理面板中修改。
CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE
- 类型：
int - 默认值：
1 - 描述：设置流式响应向客户端发送前的最小 token 批量大小。
CHAT_STREAM_RESPONSE_CHUNK_MAX_BUFFER_SIZE
- 类型：
int - 默认值：Empty string (' '), which disables the limit (equivalent to None)
- 描述：设置处理流式响应分块的最大缓冲区大小。超过该值时会跳过过大的数据块。
信息
如果你在高并发、多用户、且模型流式速度很快的场景下运行 Open WebUI，建议将其设为较大的个位数或两位数值。
CHAT_RESPONSE_MAX_TOOL_CALL_ITERATIONS
- 类型：
int - 默认值：
256 - 描述：在启用 Native Function Calling 时，限制单次助手响应中代理循环可以连续执行的工具调用轮数。每当模型发出一或多个工具调用计为一轮（同一轮中分组的多个工具调用仍计为一轮）；计数器在每条新消息处重置，不跨对话轮次延续。它不是对失败工具调用的重试预算——成功的调用和失败的调用各消耗一次，完全相同。设为
-1表示无限制（无上限）。启动时读取一次；不是ConfigVar，无法在管理面板中修改。空值或非法值会回退到256。v0.9.6 之前名为CHAT_RESPONSE_MAX_TOOL_CALL_RETRIES（旧默认值30）的旧名称仍作为回退被兼容识别；请优先使用新名称。
ENABLE_RESPONSES_API_STATEFUL
- 类型：
bool - 默认值：
False - 描述：通过向上游传递
previous_response_id启用有状态的 Responses API 会话。
Experimental
只有在上游 Responses API 端点明确支持有状态会话时才启用此项。 大多数代理和第三方端点是无状态的，启用后会出问题。
BYPASS_MODEL_ACCESS_CONTROL
- 类型：
bool - 默认值：
False - 描述：控制是否绕过模型访问控制。启用后，所有用户都能访问所有模型。
BYPASS_RETRIEVAL_ACCESS_CONTROL
- 类型：
bool - 默认值：
False - 描述：控制是否绕过检索访问控制。启用后，RAG 检索将忽略知识库上的访问控制列表，访问该实例的所有用户都能命中所有知识库的内容。
ENABLE_RETRIEVAL_UNSCOPED_COLLECTIONS
- 类型：
bool - 默认值：
True - 描述：控制检索时是否同时考虑未限定范围的知识库集合（即不属于任何显式访问控制范围的集合）。设为
False时，检索只考虑通过访问控制范围限定到当前用户的集合。适合希望让所有 RAG 命中都遵循访问控制策略的部署。
WEBUI_BUILD_HASH
- 类型：
str - 默认值：
dev-build - 描述：用于标识发布构建对应的 Git SHA。
WEBUI_BANNERS
- 类型：
listofdict - 默认值：
[] - 描述：要向用户显示的横幅列表，格式如下：
[{"id": "string", "type": "string [info, success, warning, error]", "title": "string", "content": "string", "dismissible": false, "timestamp": 1000}]- 持久化：这是一个
ConfigVar变量。
信息
在 .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 支持，为本地 Whisper 和 embeddings 提供 GPU 加速。
DOCKER
- 类型：
bool - 默认值：
False - 描述：表示 Open WebUI 是否 运行在 Docker 容器中，用于内部环境检测。
USE_CUDA
- 类型：
bool - 默认值：
False - 描述：控制是否为本地模型使用 CUDA 加速。设为
true时会尝试检测并使用可用的 NVIDIA GPU。
DEVICE_TYPE
- 类型：
str - 默认值：
cpu - 描述：指定模型执行所用的设备类型；若 CUDA 可用且启用，则自动设为
cuda，Apple Silicon 则为mps。
EXTERNAL_PWA_MANIFEST_URL
- 类型：
str - 默认值：Empty string (' '), since
Noneis set as default. - 描述：当设置为完整 URL（例如
https://path/to/manifest.webmanifest）时，发往/manifest.json的请求会使用外部 manifest；否则使用默认 manifest.json。
ENABLE_TITLE_GENERATION
- 类型：
bool - 默认值：
True - 描述：启用或禁用聊天标题生成。
- 持久化：这是一个
ConfigVar变量。
LICENSE_KEY
- 类型：
str - 默认值：
None - 描述：指定要使用的许可证密钥（仅限 Enterprise 用户）。
- 持久化：这是一个
ConfigVar变量。
SSL_ASSERT_FINGERPRINT
- 类型：
str - 默认值：Empty string (' '), since
Noneis set as default. - 描述：指定要使用的 SSL assert fingerprint。
- 持久化：这是一个
ConfigVar变量。
ENABLE_COMPRESSION_MIDDLEWARE
- 类型：
bool - 默认值：
True - 描述：为 HTTP 响应启用 gzip 压缩中间件，从而减少带宽占用并提升加载速度。
DEFAULT_PROMPT_SUGGESTIONS
- 类型：
listofdict - 默认值：
[]（表示使用内置的默认提示词建议） - 描述：设置用户在新建对话时看到的全局默认提示词建议。当没有配置模型级提示词建议时，会使用这里的值。提示词建议也可以在模型编辑器中按模型配置（见 提示词建议），或通过 全局模型默认值 功能对所有模型统一设置。格式如下：
[{"title": ["Title part 1", "Title part 2"], "content": "prompt"}]AIOHTTP 客户端
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 - 描述：设置执行 tool server API 调用的超时时间（秒）。
信息
如果此变量未 设置或无效，Open WebUI 会回退到 AIOHTTP_CLIENT_TIMEOUT。
AIOHTTP_CLIENT_SESSION_SSL
- 类型：
bool - 默认值：
True - 描述：控制连接外部 API 时 AIOHTTP 客户端会话的 SSL/TLS 验证。
AIOHTTP_CLIENT_ALLOW_REDIRECTS
- 类型：
bool - 默认值：
False - 描述：控制应用范围内的出站 HTTP 请求是否跟随
3xx重定向。False（自 v0.9.5 起的默认值）下不跟随重定向——这关闭了一类 SSRF 攻击：攻击者把一个通过白名单校验的公网 URL302-重定向到内部地址（RFC 1918、回环地址127.0.0.1、云元数据169.254.169.254），从而绕过原本的 allowlist 检查。受影响的调用方包括 RAG 网页加载器、图片加载与 base64 转换、OAuth 预检、code-interpreter 登录、tool-server 执行。只有当你的部署确实需要跟随重定向（例如短链 URL）且已经部署了其他 SSRF 防护（通常是出站防火墙或覆盖了内网范围的WEB_FETCH_FILTER_LIST），才将其设为True。
USER_AGENT
- 类型：
str - 默认值：未设置（使用底层 HTTP 客户端默认值；通常类似
Python-urllib/3.x或python-requests/2.x） - 描述：Open WebUI 在所有出站 HTTP 请求中使用的
User-Agent头，包括 Web Search 结果抓取、网页内容加载（fetch_url工具）、远程文档加载器和文件下载。许多大型发布商（Wikipedia、Cloudflare 保护站点、Reddit、新闻媒体）会按 UA 过滤请求，剥离被识别为 bot/默认 Python UA 的流量，导致结果为空或返回 403。设置成真实浏览器 UA（例如Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36）可以显著提升成功率。
AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA
- 类型：
int - 默认值：
10 - 描述：设置获取 tool server 元数据/配置的超时时间（秒）。
AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL
- 类型：
bool - 默认值：
True - 描述：控制通过 AIOHTTP 客户端连接 tool server 时的 SSL/TLS 验证。
MCP_INITIALIZE_TIMEOUT
- 类型：
int - 默认值：
30 - 描述：与 MCP 服务器进行初始化握手（
initialize+notifications/initialized）的超时时间（秒）。一些网络受限或资源较少的 MCP 服务器在该窗口内无法完成握手；调高这个值可以避免误判为失败。
AIOHTTP_POOL_CONNECTIONS
- 类型：
int - 默认值：未设置（无限制）
- 描述：共享 AIOHTTP 客户端池中总并发连接数上限。
AIOHTTP_POOL_CONNECTIONS_PER_HOST
- 类型：
int - 默认值：未设置（无限制）
- 描述：共享 AIOHTTP 池中单个主机的并发连接数上限。
AIOHTTP_POOL_DNS_TTL
- 类型：
int - 默认值：
300 - 描述：共享 AIOHTTP 池的 DNS 缓存 TTL（秒）。
信息
Open WebUI 会复用一个长期存在的 AIOHTTP 客户端会话来处理外发 HTTP 流量，以便复用 TCP/TLS 连接、共享 DNS 缓存并限制并发。上面这三个变量用于调优该连接池；在常规部署中通常无需设置。
REQUESTS_VERIFY
- 类型：
bool - 默认值：
True - 描述：控制同步
requests的 SSL/TLS 验证。
Directories
DATA_DIR
- 类型：
str - 默认值：
./data - 描述：指定数据存储的基础目录，包括上传、缓存、向量数据库等。
FONTS_DIR
- 类型：
str - 描述：指定字体目录。
FRONTEND_BUILD_DIR
- 类型：
str - 默认值：
../build - 描述：指定前端构建产物目录。
STATIC_DIR
- 类型：
str - 默认值：
./static - 描述：指定静态文件目录，例如 favicon。
Logging
GLOBAL_LOG_LEVEL
- 类型：
str - 默认值：
INFO - 描述：设置所有 Open WebUI 组件的全局日志级别。
LOG_FORMAT
- 类型：
str - 默认值：未设置（纯文本日志）
- 描述：控制日志输出格式。设为
json时，所有 stdout 日志都会变成单行 JSON 对象。
ENABLE_AUDIT_STDOUT
- 类型：
bool - 默认值：
False - 描述：控制审计日志是否输出到 stdout（控制台）。
ENABLE_AUDIT_LOGS_FILE
- 类型：
bool - 默认值：
True - 描述：控制审计日志是否写入文件。
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 - 描述：设置审计日志轮转前的最大文件大小。
AUDIT_UVICORN_LOGGER_NAMES
- 类型：
str - 默认值：
uvicorn.access - 描述：要纳入审计日志的 logger 名称列表，以逗号分隔。
AUDIT_LOG_LEVEL
- 类型：
str - 默认值：
NONE - Options:
NONE,METADATA,REQUEST,REQUEST_RESPONSE - 描述：控制审计日志的详细程度。
MAX_BODY_LOG_SIZE
- 类型：
int - 默认值：
2048 - 描述：设置审计日志中请求/响应 body 的最大字节数。
AUDIT_EXCLUDED_PATHS
- 类型：
str - 默认值：
/chats,/chat,/folders - 描述：从审计日志中排除的 URL 路径列表，逗号分隔。
AUDIT_INCLUDED_PATHS
- 类型：
str - 默认值：空字符串（禁用）
- 描述：要包含在审计日志中的 URL 路径列表，逗号分隔。
白名单与黑名单
默认情况下审计日志使用黑名单模式；如果设置了 AUDIT_INCLUDED_PATHS，则切换为白名单模式。若两者都设置，白名单优先。
Ollama 配置
ENABLE_OLLAMA_API
- 类型：
bool - 默认值：
True - 描述：启用 Ollama API。
- 持久化：这是一个
ConfigVar变量。
OLLAMA_BASE_URL (OLLAMA_API_BASE_URL is deprecated)
- 类型：
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。 - 示例：
http://host-one:11434;http://host-two:11434 - 持久化：这是一个
ConfigVar变量。
USE_OLLAMA_DOCKER
- 类型：
bool - 默认值：
False - 描述：构建包含内置 Ollama 实例的 Docker 镜像。
K8S_FLAG
- 类型：
bool - 默认值：
False - 描述：如果启用，则按 Helm 部署处理，并将
OLLAMA_BASE_URL指向集群内的 Ollama 服务。
OpenAI
ENABLE_OPENAI_API
- 类型：
bool - 默认值：
True - 描述：启用 OpenAI API。
- 持久化：这是一个
ConfigVar变量。
OPENAI_API_BASE_URL
- 类型：
str - 默认值：
https://api.openai.com/v1 - 描述：配置 OpenAI API 基础 URL。
- 持久化：这是一个
ConfigVar变量。
OPENAI_API_BASE_URLS
- 类型：
str - 描述：支持负载均衡的 OpenAI 基础 API URL，使用分号分隔。
- 示例：
http://host-one:11434;http://host-two:11434 - 持久化：这是一个
ConfigVar变量。
OPENAI_API_KEY
- 类型：
str - 描述：设置 OpenAI API 密钥。
- 示例：
sk-124781258123 - 持久化：这是一个
ConfigVar变量。
Provider Key Scope (Important)
对于兼容 OpenAI 的后端和代理（包括 LiteLLM），请尽可能为普通用户流量配置最小权限的密钥。
除非你的部署明确需要更高信任级别，否则不要使用提供商的管理/主密钥。
OPENAI_API_KEYS
- 类型：
str - 描述：支持多个 OpenAI API 密钥，使用分号分隔。
- 示例：
sk-124781258123;sk-4389759834759834 - 持久化：这是一个
ConfigVar变量。
ENABLE_OPENAI_API_PASSTHROUGH
- 类型：
bool - 默认值：
False - 描述：启用后，OpenAI 代理的兜底端点（
/{path:path}）会使用管理员配置的 API 密钥转发请求，且不再额外做访问控制。
危险
除非你明确需要，否则请保持关闭。 该兜底代理会使用管理员密钥直通上游 API，且不做模型级访问控制。
任务模板
TASK_MODEL
- 类型：
str - 描述：在使用 Ollama 模型时 ，用于标题和网页搜索查询生成等任务的默认模型。
- 持久化：这是一个
ConfigVar变量。
TASK_MODEL_EXTERNAL
- 类型：
str - 描述：在使用兼容 OpenAI 的端点时，用于标题和网页搜索查询生成等任务的默认模型。
- 持久化：这是一个
ConfigVar变量。
TITLE_GENERATION_PROMPT_TEMPLATE
- 类型：
str - 描述：生成聊天标题时使用的提示词模板。
- 默认值：
DEFAULT_TITLE_GENERATION_PROMPT_TEMPLATE环境变量的值。
DEFAULT_TITLE_GENERATION_PROMPT_TEMPLATE:
### 任务：
生成一个简洁的 3-5 个词的标题，并配上表情符号，用来概括聊天历史。
### 指南：
- 标题应清楚反映对话的主要主题或内容。
- 使用有助于理解主题的表情符号，但避免引号或特殊格式。
- 标题应使用聊天的主要语言；如果是多语言内容，则默认使用英语。
- 优先保证准确性，而不是过度追求创意；保持清晰、简洁。
### 输出：
JSON 格式：{ "title": "your concise title here" }
### 示例：
- { "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>
{{MESSAGES:END:2}}
</chat_history>
- 持久化：这是一个
ConfigVar变量。
ENABLE_FOLLOW_UP_GENERATION
- 类型：
bool - 默认值：
True - 描述：启用或禁用后续问题生成。
- 持久化：这是一个
ConfigVar变量。
FOLLOW_UP_GENERATION_PROMPT_TEMPLATE
- 类型：
str - 描述 ：用于生成多个相关后续问题的提示词模板。
- 默认值：
DEFAULT_FOLLOW_UP_GENERATION_PROMPT_TEMPLATE环境变量的值。
DEFAULT_FOLLOW_UP_GENERATION_PROMPT_TEMPLATE:
### 任务：
建议 3-5 个相关的后续问题或提示，这些问题应当是用户在这段对话中下一步可能自然提出的“用户视角”问题，用来延续或深化讨论，并基于聊天历史进行生成。
### 指南：
- 所有后续问题都要从用户的角度撰写，并直接指向助手。
- 问题应简洁、清晰，并与正在讨论的主题直接相关。
- 只建议在聊天内容下合理、且不会重复已讨论内容的后续问题。
- 如果对话很短或不够具体，则可以建议更通用但仍相关的后续问题。
- 使用对话的主要语言；如果是多语言内容，则默认使用英语。
- 回复必须是由字符串组成的 JSON 数组，不要有任何额外文本或格式。
### 输出：
JSON 格式：{ "follow_ups": ["问题 1?", "问题 2?", "问题 3?"] }
### 聊天历史：
<chat_history>
{{MESSAGES:END:6}}
</chat_history>"
- 持久化：这是一个
ConfigVar变量。
TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE
- 类型：
str - 描述：调用工具时使用的提示词模板。
- 默认值：
DEFAULT_TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE环境变量的值。
DEFAULT_TOOLS_FUNCTION_CALLING_PROMPT_TEMPLATE:
可用工具：{{TOOLS}}
你的任务是根据查询，从可用工具列表中选择并返回正确的工具。请遵循以下指南：
- 仅返回 JSON 对象，不要附加任何额外文本或解释。
- 如果没有工具匹配查询，请返回一个空数组：
{
"tool_calls": []
}
- 如果有一个或多个工具匹配查询，请构造一个 JSON 响应，其中包含一个 "tool_calls" 数组，数组里的对象应包含：
- "name"：工具名称。
- "parameters"：所需参数及其对应值的字典。
JSON 响应的严格格式如下：
{
"tool_calls": [
{"name": "toolName1", "parameters": {"key1": "value1"}},
{"name": "toolName2", "parameters": {"key2": "value2"}}
]
}
- 持久化：这是一个
ConfigVar变量。
Code Execution
ENABLE_CODE_EXECUTION
- 类型：
bool - 默认值：
True - 描述：启用或禁用代码执行。
- 持久化：这是一个
ConfigVar变量。
CODE_EXECUTION_ENGINE
- 类型：
str - 默认值：
pyodide - 描述：指定要使用的代码执行引擎。
- 持久化：这是一个
ConfigVar变量。
CODE_EXECUTION_JUPYTER_URL
- 类型：
str - 默认值：
None - 描述：指定代码执行要使用的 Jupyter URL。
- 持久化：这是一个
ConfigVar变量。
CODE_EXECUTION_JUPYTER_AUTH
- 类型：
str - 默认值：
None - 描述：指定代码执行要使用的 Jupyter 认证方式。
- 持久化：这是一个
ConfigVar变量。
CODE_EXECUTION_JUPYTER_AUTH_TOKEN
- 类型：
str - 默认值：
None - 描述：指定代码执行要使用的 Jupyter 认证 token。
- 持久化：这是一个
ConfigVar变量。
CODE_EXECUTION_JUPYTER_AUTH_PASSWORD
- 类型：
str - 默认值：
None - 描述：指定代码执行要使用的 Jupyter 认证密码。
- 持久化：这是一个
ConfigVar变量。
CODE_EXECUTION_JUPYTER_TIMEOUT
- 类型：
str - 默认值：Empty string (' '), since
Noneis set as default. - 描述：指定 Jupyter 代码执行的超时时间。
- 持久化：这是一个
ConfigVar变量。
Code Interpreter
ENABLE_CODE_INTERPRETER
- 类型：
bool - 默认值：
True - 描述：启用或禁用代码解释器。
- 持久化：这是一个
ConfigVar变量。
CODE_INTERPRETER_ENGINE
- 类型：
str - 默认值：
pyodide - 描述：指定要使用的代码解释器引擎。
- 持久化：这是一个
ConfigVar变量。
CODE_INTERPRETER_BLACKLISTED_MODULES
- 类型：
str(comma-separated list of module names) - 默认值：None
- 描述：指定代码解释器中禁止导入或使用的 Python 模块列表，以逗号分隔。
CODE_INTERPRETER_PROMPT_TEMPLATE
- 类型：
str - 默认值：
None - 描述：指定代码解释器使用的提示词模板。
- 持久化：这是一个
ConfigVar变量。
CODE_INTERPRETER_JUPYTER_URL
- 类型：
str - 默认值：Empty string (' '), since
Noneis set as default. - 描述：指定代码解释器要使用的 Jupyter URL。
- 持久化：这是一个
ConfigVar变量。
CODE_INTERPRETER_JUPYTER_AUTH
- 类型：
str - 默认值：Empty string (' '), since
Noneis set as default. - 描述：指定代码解释器要使用的 Jupyter 认证方式。
- 持久化：这是一个
ConfigVar变量。
CODE_INTERPRETER_JUPYTER_AUTH_TOKEN
- 类型：
str - 默认值：Empty string (' '), since
Noneis set as default. - 描述：指定代码解释器要使用的 Jupyter 认证 token。
- 持久化：这是一个
ConfigVar变量。
CODE_INTERPRETER_JUPYTER_AUTH_PASSWORD
- 类型：
str - 默认值：Empty string (' '), since
Noneis set as default. - 描述：指定代码解释器要使用的 Jupyter 认证密码。
- 持久化：这是一个
ConfigVar变量。
CODE_INTERPRETER_JUPYTER_TIMEOUT
- 类型：
str - 默认值：Empty string (' '), since
Noneis set as default. - 描述：指定 Jupyter 代码解释器的超时时间。
- 持久化：这是一个
ConfigVar变量。
Direct Connections (OpenAPI/MCPO Tool Servers)
ENABLE_DIRECT_CONNECTIONS
- 类型：
bool - 默认值：
True - 描述：启用或禁 用直接连接。
- 持久化：这是一个
ConfigVar变量。
TOOL_SERVER_CONNECTIONS
- 类型：
str(JSON array) - 默认值：
[] - 描述：指定 tool server 连接配置的 JSON 数组；格式无效时会回退为空数组。
- 字段说明：
url：服务器基础 URL。path：服务器暴露的具体工具路由。auth_type：连接使用的认证方式。key：所选认证方式使用的 API key 或 token。config：单个连接的配置对象，例如{ "enable": true }。info：显示在 UI 中的可选元数据，如连接名称和描述。spec_type/spec：当连接基于 OpenAPI spec URL 或文件时，用于描述 spec 位置。
- 示例：
[
{
"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."
}
}
]- 持久化：这是一个
ConfigVar变量。
注意
The JSON data structure of TOOL_SERVER_CONNECTIONS might evolve over time as new features are added.
Terminal Server
TERMINAL_SERVER_CONNECTIONS
- 类型：
str(JSON array) - 默认值：
[] - 描述：指定终端服务器连接配置的 JSON 数组。每个连接定义了连接 Open Terminal 实例或 Terminals orchestrator 所需的参数。与用户级 tool server 不同，这些连接由管理员配置并通过 Open WebUI 代理，因此终端 URL 和 API key 不会暴露给浏览器。支持通过
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 orchestrator）：
[
{
"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"}
]
}
}
]- 持久化：这 是一个
ConfigVar变量。
Helm chart auto-configuration
当使用 Open WebUI Helm chart 在 Kubernetes 上部署并设置 terminals.enabled: true 时，该变量会自动指向集群内的 orchestrator 服务。详情请参阅 Terminals（Orchestrator）指南。
注意
TERMINAL_SERVER_CONNECTIONS 的 JSON 数据结构可能会随着新功能的加入而变化。
TERMINAL_PROXY_HEADERS
-
类型：
str（JSON 对象） -
默认值：
{} -
描述：终端代理在返回响应时注入的自定义 HTTP 响应头。终端代理会从上游响应中剥离一组固定的逐跳头和安全敏感头；该对象中的条目会在剥离之后合并进去，冲突时优先生效。这样管理员就可以在不修改应用代码的前提下，为代理后的终端内容设置部署特定的响应头。无效 JSON 会回退到
{}，即不添加任何头。安全说明。 默认值
{}意味着代理会在 Open WebUI 的同源下原样转发上游内容（HTML、JS，无论什么）。这是有意为之——很多合法的 open-terminal 用例（开发服务器、内部工具、管理员通过终端跑的 Web UI）都依赖代理响应中的 JavaScript 真正执行。对于互相信任的多用户共用一条终端服务器连接的部署来说，这没有问题。如果同一信任组内的用户还需要互相隔离对方的代理内容（或者你在已记载的多用户部署等级之上把终端服务器功能开放给信任程度更低的用户），可以把它设置成一个 sandbox CSP，把代理过来的 JS 锁进一个 opaque origin，但仍然允许它为合法工作流执行：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。该关键字会使 sandbox 的源隔离失效，从而无法防止localStorage被窃取。上面的示例特意未加。
自动补全
ENABLE_AUTOCOMPLETE_GENERATION
- 类型：
bool - 默认值：
True - 描述：启用或禁用自动补全生成。
- 持久化：这是一个
ConfigVar变量。
信息
启用 ENABLE_AUTOCOMPLETE_GENERATION 时，请同时正确配置 AUTOCOMPLETE_GENERATION_INPUT_MAX_LENGTH 和 AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE。
AUTOCOMPLETE_GENERATION_INPUT_MAX_LENGTH
- 类型：
int - 默认值：
-1 - 描述：设置自动补全生成的最大输入长度。
- 持久化：这是一个
ConfigVar变量。
AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE
- 类型：
str - 默认值：环境变量
DEFAULT_AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE的值。
DEFAULT_AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE:
### 任务：
你是一套自动补全系统。请根据 `<type>` 中的**补全类型**以及给定语言，继续 `<text>` 中的文本。
### **说明**：
1. 分析 `<text>` 的上下文和含义。
2. 使用 `<type>` 指导你的输出：
- **General**：提供自然、简洁的续写。
- **Search Query**：按生成真实搜索查询的方式完成。
3. 将自己视为正在直接续写 `<text>`。不要重复、释义或以模型身份回复。只需补全文本。
4. 确保续写内容：
- 与 `<text>` 自然衔接。
- 避免重复、过度解释或无关内容。
5. 如果不确定，请返回：`{ "text": "" }`。
### **输出规则**：
- 仅以 JSON 格式返回：`{ "text": "<your_completion>" }`。
### **示例**：
#### 示例 1：
输入：
<type>General</type>
<text>The sun was setting over the horizon, painting the sky</text>
输出：
{ "text": "with vibrant shades of orange and pink." }
#### 示例 2：
输入：
<type>Search Query</type>
<text>Top-rated restaurants in</text>
输出：
{ "text": "New York City for Italian cuisine." }
---
### 上下文：
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
<type>{{TYPE}}</type>
<text>{{PROMPT}}</text>
#### 输出：
- 描述：设置自动补全生成的提示词模板。
- 持久化：这是一个
ConfigVar变量。
评测竞技场模型
ENABLE_EVALUATION_ARENA_MODELS
- 类型：
bool - 默认值：
True - 描述：启用或禁用评测竞技场模型。
- 持久化：这是一个
ConfigVar变量。
ENABLE_MESSAGE_RATING
- 类型：
bool - 默认值：
True - 描述：启用消息评分功能。
- 持久化：这是一个
ConfigVar变量。
ENABLE_COMMUNITY_SHARING
- 类型：
bool - 默认值：
True - 描述：控制用户是否可以与 Open WebUI Community 共享内容并访问社区资源。启用后，该设置会在整个应用中显示以下 UI 元素：
- Prompts 工作区：显示“Open WebUI 社区制作”区域，附带发现社区提示词的链接，以及提示词菜单下拉中的“分享”按钮
- Tools 工作区：显示“Open WebUI 社区制作”区域，附带发现社区工具的链 接，以及工具菜单下拉中的“分享”按钮
- Models 工作区：显示“Open WebUI 社区制作”区域，附带发现社区模型预设的链接，以及模型菜单下拉中的“分享”按钮
- Functions 管理页：显示“Open WebUI 社区制作”区域，附带发现社区函数的链接
- Share Chat 弹窗：在分享聊天会话时显示“分享到 Open WebUI Community”按钮
- Evaluation Feedbacks：用于将反馈历史贡献到社区排行榜的“分享到 Open WebUI Community”按钮
- Stats Sync 弹窗：启用与社区同步使用统计数据
- 持久化：这是一个
ConfigVar变量。
信息
当 ENABLE_COMMUNITY_SHARING 设为 False 时，所有社区共享按钮和社区资源发现区块都会从 UI 中隐藏。用户仍然可以将内容导出到本地，但无法再直接分享到 Open WebUI Community。
标签生成
ENABLE_TAGS_GENERATION
- 类型：
bool - 默认值：
True - 描述：启用或禁用标签生成。
- 持久化：这是一个
ConfigVar变量。
TAGS_GENERATION_PROMPT_TEMPLATE
- 类型：
str - 默认值：环境变量
DEFAULT_TAGS_GENERATION_PROMPT_TEMPLATE的值。
DEFAULT_TAGS_GENERATION_PROMPT_TEMPLATE:
### 任务：
生成 1-3 个概括聊天历史主要主题的宽泛标签，并额外给出 1-3 个更具体的子主题标签。
### 指南：
- 以高层领域开头（例如：科学、技术、哲学、艺术、政治、商业、健康、体育、娱乐、教育）
- 如果整段对话中有明显体现相关子领域/子学科，可一并包含
- 如果内容过短（少于 3 条消息）或过于分散，则只使用 ["General"]
- 使用聊天的主要语言；如果是多语言内容则默认使用英语
- 优先保证准确性，而非过度追求细粒度
### 输出：
JSON 格式：{ "tags": ["tag1", "tag2", "tag3"] }
### 聊天历史：
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
- 描述：设置标签生成的提示词模板。
- 持久化：这是一个
ConfigVar变量。
API Key 端点限制
ENABLE_API_KEYS
- 类型：
bool - 默认值：
False - 描述：启用 API Key 创建功能，允许用户生成 API Key 以程序化访问 Open WebUI。
- 持久化：这是一个
ConfigVar变量。
信息
此变量取代了已弃用的 ENABLE_API_KEY 环境变量。
信息
要让 API Key 创建功能（以及 API Key 本身）正常工作：
- 使用此设置（
ENABLE_API_KEYS）全局启用 API Key - 对于非管理员用户，通过默认权限或用户组授予“API Keys”权限
注意： 只要启用了 ENABLE_API_KEYS，管理员即使没有 features.api_keys 也可以生成 API Key。
ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS
- 类型：
bool - 默认值：
False - 描述：启用 API Key 端点限制，以增强安全性和可配置性，允许管理员限制 API Key 可访问的端点。
- 持久化：这是一个
ConfigVar变量。
信息
此变量取代了已弃用的 ENABLE_API_KEY_ENDPOINT_RESTRICTIONS 环境变量。
API_KEYS_ALLOWED_ENDPOINTS
- 类型：
str - 描述：在启用 API Key 端点限制时，指定允许访问的 API 端点逗号分隔列表。
- 示例：
/api/v1/messages,/api/v1/channels,/api/v1/chat/completions - 持久化：这是一个
ConfigVar变量。
备注
API_KEYS_ALLOWED_ENDPOINTS 的值应为以逗号分隔的端点 URL 列表，例如 /api/v1/messages, /api/v1/channels。
信息
此变量取代了已弃用的 API_KEY_ALLOWED_ENDPOINTS 环境变量。
CUSTOM_API_KEY_HEADER
- 类型：
str - 默认值：
x-api-key - 描述：认证中间件用于查找 API key 凭据的 HTTP 头名称。当 Open WebUI 位于反向代理或 API 网关之后、而后者会消费
Authorization头做自己的认证时非常有用——把它设置成一个独立的头名（例如X-OpenWebUI-Key），客户端就可以传 Open WebUI 的 API key 而不会与代理自身的认证冲突。 - 在启动时从进程环境变量读取（不是
ConfigVar）。
认证中间件按以下顺序识别凭据：
Authorization: Bearer <token>（最常见——API key 或 JWT）tokencookie（Bearer——WebUI 自身使用）CUSTOM_API_KEY_HEADER指定的头（默认x-api-key）
三者都不存在时，请求按匿名处理。
位于会消费
Authorization 的代理之后？许多企业网关（basic auth、双向 TLS 适配器、SSO sidecar）会消费 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 调用，尤其适合用户较多或模型端点连接较慢的部署。也可以在
Admin Panel > Settings > Connections > "Cache Base Model List"中配置。 - 持久化：这是一个
ConfigVar变量。
缓存的工作方式：
- 初始化：启用后，基础模型会在应用启动时获取并缓存。
- 存储：缓存存放在应用内存中（
app.state.BASE_MODELS）。 - 缓存命中：后续模型请求会直接返回缓存列表，而不会联系外部端点。
- 缓存刷新：缓存会在以下情况刷新：
- 应用重启
- 在 Admin Panel > Settings > Connections 中保存连接设置（点击右下角的 Save 按钮会触发刷新，并用新获取的模型更新缓存）
- 无 TTL：没有基于时间的自动过期机制。
性能考量
建议在模型列表相对稳定的生产环境中启用此设置。对于开发环境，或在 Ollama 中频繁增删模型的场景，你可能更希望保持关闭，以便实时发现模型。
MODELS_CACHE_TTL
- 类型：
int - 默认值：
1 - 描述：为 OpenAI 和 Ollama 端点返回的模型列表设置缓存存活时间（秒）。它会在指定时长内缓 存可用模型列表，从而减少 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表示不过期。 - 持久化：这是一个
ConfigVar变量。
注意
将 JWT_EXPIRES_IN 设为 -1 会禁用 JWT 过期，让签发的令牌永久有效。这在生产环境中极其危险，如果令牌泄露或被盗用，会给系统带来严重安全风险。
在生产环境中务必设置合理的过期时间（例如 3600s、1h、7d 等），以限制认证令牌的有效期。
切勿在生产环境中使用 -1。
如果你已经以 JWT_EXPIRES_IN=-1 部署，可以轮换或修改 WEBUI_SECRET_KEY，立即让所有现有令牌失效。
安全变量
ENABLE_FORWARD_USER_INFO_HEADERS
- 类型：
bool - 默认值：
False - 描述：将用户和会话信息作为 HTTP 标头转发到 OpenAI API、Ollama API、MCP 服务器和 Tool 服务器。
如果启用，会转发以下标头：
X-OpenWebUI-User-NameX-OpenWebUI-User-IdX-OpenWebUI-User-EmailX-OpenWebUI-User-RoleX-OpenWebUI-Chat-IdX-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-IdFORWARD_USER_INFO_HEADER_JWT_SECRET
- 类型：
str - 默认值：未设置
- 描述：用于签发/验证在转发用户/会话信息时携带的 JWT 头所采用的共享密钥。下游代理（Open WebUI 之外的工具服务器或中间件）会用同一密钥验证该 JWT，从而在不直接信任标头值的前提下确认请求者身份。生成方式：使用
openssl rand -hex 32或同等强度的随机源；长度建议 ≥ 32 字节。仅当确实有下游消费者需要校验时再设置，未配置时该 JWT 头会被忽略。该变量只在启动时读取一次——它不是ConfigVar，无法在管理面板中修改。
FORWARD_USER_INFO_HEADER_JWT
- 类型：
str - 默认值：未设置
- 描述：承载已签名 JWT 的 HTTP 标头名称（用于转发用户/会话信息）。如果设置，则在每个出站请求中携带一份用
FORWARD_USER_INFO_HEADER_JWT_SECRET签名的 JWT，载荷中包含当前用户 ID、角色和（可选的）会话上下文；下游服务可以独立校验其真实性，而不必信任透传过来的标头值。仅当确实有下游消费者需要 JWT 校验时再设置。该变量只在启动时读取一次——它不是ConfigVar，无法在管 理面板中修改。
FORWARD_USER_INFO_HEADER_JWT_EXPIRES_SECONDS
- 类型：
int - 默认值：
3600（1 小时） - 描述：转发用户信息 JWT 的有效期（秒）。过期后该 JWT 在下一次请求时被重新签发；过短的值会浪费签名开销，过长则会让被截获的 token 在更长时间内可用。建议与下游服务的 token 校验窗口相匹配。该变量只在启动时读取一次——它不是
ConfigVar，无法在管理面板中修改。
ENABLE_WEB_LOADER_SSL_VERIFICATION
- 类型：
bool - 默认值：
True - 描述：为网站上的 RAG 绕过 SSL 验证。
- 持久化：这是一个
ConfigVar变量。
WEBUI_SESSION_COOKIE_SAME_SITE
- 类型：
str - 选项：
lax- 将SameSite属性设 置为 lax，允许第三方网站发起的请求携带 session cookies。strict- 将SameSite属性设置为 strict，阻止第三方网站发起的请求携带 session cookies。none- 将SameSite属性设置为 none，允许第三方网站发起的请求携带 session cookies，但仅限 HTTPS。
- 默认值：
lax - 描述：为 session cookies 设置
SameSite属性。
注意
当启用 ENABLE_OAUTH_SIGNUP 时，将 WEBUI_SESSION_COOKIE_SAME_SITE 设为 strict 可能会导致登录失败。这是因为 Open WebUI 使用 session cookie 来验证来自 OAuth 提供方的回调，从而帮助防止 CSRF 攻击。
但是，strict session cookie 不会随回调请求发送，这会导致潜在的登录问题。如果遇到此问题，请改用默认的 lax 值。
WEBUI_SESSION_COOKIE_SECURE
- 类型：
bool - 默认值：
False - 描述：如果设为
True，为 session cookies 设置Secure属性。
WEBUI_AUTH_COOKIE_SAME_SITE
- 类型：
str - 选项：
lax- 将SameSite属性设置为 lax，允许认证 cookie 随第三方网站发起的请求发送。strict- 将SameSite属性设置为 strict，阻止认证 cookie 随第三方网站发起的请求发送。none- 将SameSite属性设置为 none，允许认证 cookie 随第三方网站发起的请求发送，但仅限 HTTPS。
- 默认值：
lax - 描述：为认证 cookie 设置
SameSite属性。
信息
如果未设置该值，将回退使用 WEBUI_SESSION_COOKIE_SAME_SITE。
WEBUI_AUTH_COOKIE_SECURE
- 类型：
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定义的复杂度要求。这有助于在整个应用中执行更强的密码策略。
信息
密码校验适用于：
- 新用户注册（signup）
- 通过用户设置修改密码
- 管理员创建用户
- 密码重置
现有用户如果密码不符合新要求，不会被自动强制更新密码；但在下一次修改密码时必须满足这些要求。
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 (JWTs) 以及在静态存储时加密敏感数据的密钥（包括 MCP 的 OAuth token）。可以通过
WEBUI_SECRET_KEY环境变量或旧版WEBUI_JWT_SECRET_KEY变量（已弃用）进行设置。
密钥生成方式
你不需要为了安全安装而手动设置此变量——所有标准启动方式都会在首次启动时自动生成并持久化一个密码学随机密钥：
| 启动方式 | 是否自动生成？ | 持久化到 |
|---|---|---|
Docker (start.sh) | ✅ 是 | 容器内的 .webui_secret_key 文件 |
pip install (open-webui serve) | ✅ 是 | 工作目录中的 .webui_secret_key 文件 |
开发模式 (open-webui dev、直接 uvicorn) | ❌ 否 | 不适用——使用代码级回退值 |
代码级回退值（t0p-s3cr3t）仅用于开发方便，在通过标准 Docker 或 open-webui serve 方式启动 Open WebUI 时绝不会使用。这两种方式都会先检查环境变量；如果未设置，就会生成安全随机密钥、将其保存到文件中，并注入到环境变量里——整个过程都在应用启动之前完成。
推荐：设置显式且持久的值
虽然自动生成的密钥是安全的，但它绑定在容器或工作目录中的某个文件上。如果容器被重新创建（而不只是重启），并且该密钥文件没有放在持久化卷中，就会生成新的密钥，这会导致：
- 所有现有用户会话失效（用户会被登出）。
- 所有 OAuth 会话失效。
- MCP Tools 会失效（错误：
Error decrypting tokens），因为使用旧密钥加密的 token 无法再解密。
为避免这种情况，请显式将 WEBUI_SECRET_KEY 设置为一个安全、持久且能在容器重建后继续保留的值：
# 生成一个安全密钥
openssl rand -hex 32然后把它作为环境变量传入 Docker Compose 或部署配置中。
注意
多 Worker 与多节点部署必需，且在单 Worker 环境中也强烈推荐
当你以 UVICORN_WORKERS > 1 部署 Open WebUI，或者在带负载均衡器的多节点/多 Worker 集群中部署（例如 helm/kubectl/kubernetes/k8s）时，必须将此变量设置为所有副本相同的值。否则会出现以下问题：
- 会话管理在各 worker 之间失效
- 不同实例之间的应用状态不一致
- 分布式环境中的 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 Hub 下载嵌入模型
- 如果你在启用
OFFLINE_MODE之前没有下载过嵌入模型，任何 RAG、web search 和文档分析功能都可能无法正常工作
- 如果你在启用
- UI 中的更新通知（参见
ENABLE_VERSION_UPDATE_CHECK）
仍然可用：
- 外部 LLM API 连接（OpenAI 等）
- OAuth 身份验证提供方
- 使用外部 API 的 web search 和 RAG
有关 offline mode 的更多信息，请参阅 离线模式指南。
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 - 默认值：
* - 描述：设置 Cross-Origin Resource Sharing (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 - 默认值：
""（空字符串） - 描述：设置额外允许的 Cross-Origin Resource Sharing (CORS) scheme 列表。你可以指定除标准
http和https之外的自定义 URL scheme，作为有效的 CORS 来源。
信息
这在以下场景中特别有用：
- 集成使用自定义协议的桌面应用（例如
app://、custom-app-scheme://）。 - 使用非标准 scheme 的本地开发环境或测试环境（例如在适用时使用
file://，或electron://）。
请提供不带 :// 的 scheme 名称，并以分号分隔。例如：app;file;electron;my-custom-scheme。
配置后，这些自定义 scheme 会与 http 和 https 一起被验证，用于 CORS_ALLOW_ORIGIN 中指定的任何来源。
RAG_EMBEDDING_MODEL_TRUST_REMOTE_CODE
- 类型：
bool - 默认值：
False - 描述：决定是否允许 Hub 上定义的自定义模型在其自己的模型文件中使用远程代码。
RAG_RERANKING_MODEL_TRUST_REMOTE_CODE
- 类型：
bool - 默认值：
False - 描述：决定是否允许 Hub 上定义的自定义模型在其自己的模型文件中用于重排序时使用远程代码。
RAG_EMBEDDING_MODEL_AUTO_UPDATE
- 类型：
bool - 默认值：
True - 描述：切换 Sentence-Transformer 模型的自动更新。
RAG_RERANKING_MODEL_AUTO_UPDATE
- 类型：
bool - 默认值：
True - 描述：切换重排序模型的自动更新。
向量数据库
VECTOR_DB
- 类型：
str - 选项：
chroma,elasticsearch,mariadb-vector,milvus,opensearch,pgvector,qdrant,pinecone,s3vector,oracle23ai,weaviate- 默认值：
chroma - 描述：指定要使用的向量数据库系统。此设置决定用于管理 embeddings 的向量存储系统。
ChromaDB（默认）不适用于多 Worker 或多副本部署
默认的 ChromaDB 配置使用基于 SQLite 的本地 PersistentClient。SQLite 不是 fork-safe 的——当 uvicorn fork 出多个 worker 进程（UVICORN_WORKERS > 1）时，每个 worker 都会继承同一条 SQLite 连接的副本。来自这些 fork 出来的进程的并发写入会立即导致崩溃（Child process died）或数据库损坏。
这同样适用于多副本部署（Kubernetes、Docker Swarm），当多个容器指向同一个 ChromaDB 数据目录时也会发生。
如果你需要多个 worker 或副本，必须二选一：
- 切换到客户端/服务器模式的向量数据库，例如 PGVector、MariaDB Vector、Milvus 或 Qdrant（推荐）。
- 将 ChromaDB 作为单独的 HTTP 服务器运行，并配置
CHROMA_HTTP_HOST/CHROMA_HTTP_PORT，让 Open WebUI 使用HttpClient而不是本地PersistentClient。
更多详情请参阅 扩展与高可用指南。
备注
PostgreSQL 依赖
要使用 pgvector，请确保已安装 PostgreSQL 相关依赖：
pip install open-webui[all]信息
只有 PGVector 和 ChromaDB 会由 Open WebUI 团队持续维护。 其他向量存储均为社区添加的向量数据库。
ChromaDB
本地模式与 HTTP 模式
默认情况下（未设置 CHROMA_HTTP_HOST 时），ChromaDB 会作为使用 SQLite 存储的本地 PersistentClient 运行。此模式仅适用于单 worker、单实例部署（UVICORN_WORKERS=1，一个副本）。
对于多 worker 或多副本部署，你必须配置 CHROMA_HTTP_HOST 和 CHROMA_HTTP_PORT，将其指向独立的 ChromaDB 服务器，或者直接切换到其他向量数据库。请参阅上面的 VECTOR_DB 警告。
CHROMA_TENANT
- 类型：
str - 默认值：
chromadb模块中chromadb.DEFAULT_TENANT的值 - 描述：设置 ChromaDB 用于 RAG embeddings 的 tenant。
CHROMA_DATABASE
- 类型：
str - 默认值：
chromadb模块中chromadb.DEFAULT_DATABASE的值 - 描述：设置 ChromaDB tenant 中用于 RAG embeddings 的数据库。
CHROMA_HTTP_HOST
- 类型：
str - 描述：指定远程 ChromaDB Server 的主机名。如果未设置，则使用本地 ChromaDB 实例。多 worker 或多副本部署必须设置此变量——它会将 ChromaDB 从本地 SQLite-backed
PersistentClient切换为 fork-safe 的HttpClient。
CHROMA_HTTP_PORT
- 类型：
int - 默认值：
8000 - 描述：指定远程 ChromaDB Server 的端口。
CHROMA_HTTP_HEADERS
- 类型：
str - 描述：要随每个 ChromaDB 请求一起发送的 HTTP 标头逗号分隔列表。
- 示例：
Authorization=Bearer heuhagfuahefj,User-Agent=OpenWebUI
CHROMA_HTTP_SSL
- 类型：
bool - 默认值：
False - 描述：控制是否在连接 ChromaDB Server 时使用 SSL。
CHROMA_CLIENT_AUTH_PROVIDER
- 类型：
str - 描述：指定远程 ChromaDB Server 的认证提供方。
- 示例：
chromadb.auth.basic_authn.BasicAuthClientProvider
CHROMA_CLIENT_AUTH_CREDENTIALS
- 类型：
str - 描述：指定远程 ChromaDB Server 的认证凭据。
- 示例：
username:password
Elasticsearch
ELASTICSEARCH_API_KEY
- 类型：
str - 默认值：空字符串（
''），因为默认值设为None - 描述：指定 Elasticsearch API key。
- 持久化：这是一个
ConfigVar变量。
ELASTICSEARCH_CA_CERTS
- 类型：
str - 默认值：空字符串（
''），因为默认值设为None - 描述：指定 Elasticsearch 的 CA 证书路径。
- 持久化：这是一个
ConfigVar变量。
ELASTICSEARCH_CLOUD_ID
- 类型：
str - 默认值：空字符串（
''），因为默认值设为None - 描述：指定 Elasticsearch 的 cloud ID。
- 持久化：这是一个
ConfigVar变量。
ELASTICSEARCH_INDEX_PREFIX
- 类型：
str - 默认值：
open_webui_collections - 描述：指定 Elasticsearch 索引的前缀。
- 持久化：这是一个
ConfigVar变量。
ELASTICSEARCH_PASSWORD
- 类型：
str - 默认值：空字符串（
''），因为默认值设为None - 描述：指定 Elasticsearch 的密码。
- 持久化：这是一个
ConfigVar变量。
ELASTICSEARCH_URL
- 类型：
str - 默认值：
https://localhost:9200 - 描述：指定 Elasticsearch 实例的 URL。
- 持久化：这是一个
ConfigVar变量。
ELASTICSEARCH_USERNAME
- 类型：
str - 默认值：空字符串（
''），因为默认值设为None - 描述：指定 Elasticsearch 的用户名。
- 持久化：这是一个
ConfigVar变量。
Milvus
注意
Milvus 目前并未由 Open WebUI 团队积极维护。它是社区添加的功能，由社区维护。 如果你要使用 Milvus，请在升级 Open WebUI 时格外小心（请为回滚创建备份和快照），以防 Open WebUI 的内部变更导致故障。
MILVUS_URI (Required)
- 类型：
str - 默认值：
${DATA_DIR}/vector_db/milvus.db - 示例（远程）：
http://your-server-ip:19530 - 描述：指定连接 Milvus 向量数据库的 URI。根据部署配置，它可以指向本地或远程 Milvus 服务器。
MILVUS_DB
- 类型：
str - 默认值：
default - 示例：
default - 描述：指定 Milvus 实例中要连接的数据库。
MILVUS_TOKEN (Required for remote connections with authentication)
- 类型：
str - 默认值：
None - 示例：
root:password（格式：username:password） - 描述：指定 Milvus 的可选连接 token。连接启用认证的远程 Milvus 服务器时必须提供。格式为
username:password。
MILVUS_INDEX_TYPE
- 类型：
str - 默认值：
HNSW - 选项：
AUTOINDEX、FLAT、IVF_FLAT、HNSW、DISKANN - 描述：指定在 Milvus 中创建新集合时使用 的索引类型。对于 Milvus standalone，通常推荐
AUTOINDEX。HNSW可能提供更好的性能，但需要集群化的 Milvus 部署，不适合 standalone 部署。 - 持久化：这是一个
ConfigVar变量。
MILVUS_METRIC_TYPE
- 类型：
str - 默认值：
COSINE - 选项：
COSINE、IP、L2 - 描述：指定 Milvus 中向量相似度搜索所使用的指标类型。
- 持久化：这是一个
ConfigVar变量。
MILVUS_HNSW_M
- 类型：
int - 默认值：
16 - 描述：指定 Milvus 中 HNSW 索引类型的
M参数。这会影响在构建过程中为每个新元素创建的双向链接数量。仅当MILVUS_INDEX_TYPE为HNSW时适用。 - 持久化：这是一个
ConfigVar变量。
MILVUS_HNSW_EFCONSTRUCTION
- 类型：
int - 默认值：
100 - 描述：指定 Milvus 中 HNSW 索引类型的
efConstruction参数。这会影响索引构建期间最近邻动态列表的大小。仅当MILVUS_INDEX_TYPE为HNSW时适用。 - 持久化：这是一个
ConfigVar变量。
MILVUS_IVF_FLAT_NLIST
- 类型：
int - 默认值：
128 - 描述：指定 Milvus 中 IVF_FLAT 索引类型的
nlist参数，也就是聚类单元的数量。仅当MILVUS_INDEX_TYPE为IVF_FLAT时适用。 - 持久化：这是一个
ConfigVar变量。
MILVUS_DISKANN_MAX_DEGREE
- 类型：
int - 默认值：
56 - 描述：在 Milvus 处于 DISKANN 索引模式时设置最大度数。通常建议保持默认值。
MILVUS_DISKANN_SEARCH_LIST_SIZE
- 类型：
int - 默认值：
100 - 描述：设置 Milvus DISKANN 的搜索列表大小。通常建议保持默认值。
ENABLE_MILVUS_MULTITENANCY_MODE
- 类型：
bool - 默认值：
false - 描述：为 Milvus 集合管理启用多租户模式，通过合并相似的向量数据结构显著降低内存使用和计算开销。控制 Milvus 是否使用多租户集合架构。启用后，所有向量数据都会合并到 5 个共享集合中（memories、knowledge、files、web_search、hash_based），而不是为每个资源创建独立集合。数据隔离通过
resource_id字段实现，而不是通过集合级别的分离。
信息
多租户模式的优势：
- 显著降低 RAM 占用（5 个集合，而不是潜在的数百个）
- 通过集合管理降低计算开销
- 更快的冷启动时间
- 减少索引维护负担
技术实现：
- 所有 memories 都进入
{prefix}_memories - 所有知识库都进入
{prefix}_knowledge - 所有上传文件都进入
{prefix}_files - web search 结果都进入
{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 | 其他所有情况（默认回退）。 | 存储显式创建的知识库。 |
信息
从旧模式迁移到多租户模式
当你在已有普通 Milvus 数据库且其中已有数据时启用多租户模式，会发生什么：
- 现有集合（模式：
open_webui_{collection_name}）仍会保留在 Milvus 中，但会对 Open WebUI 变得不可访问 - 新数据会写入这 5 个共享的多租户集合
- 在重新索引之前，应用会将知识库视为空的
- 文件和记忆不会自动迁移到新的集合架构中，因此看起来会像丢失了一样
从普通 Milvus 迁移到多租户 Milvus 的清理迁移路径：
- 在启用多租户之前，尽可能先从 UI 导出任何关键知识内容
- 设置
ENABLE_MILVUS_MULTITENANCY_MODE=true并重启 Open WebUI - 前往
Admin Settings > Documents，然后点击Reindex Knowledge Base
这只会将知识库向量重建到新的多租户集合中 文件、用户记忆和 web search 历史不会被此次操作迁移
验证知识库是否可访问且功能正常
- 如果基于文件的检索很关键，请重新上传文件（文件元数据会保留，但向量不会迁移）
- 用户聊天记忆需要通过新的对话重新生成
清理旧集合： 在成功迁移（从 milvus 到多租户 milvus ）后，旧集合仍会继续占用资源。请手动移除它们：
- 使用原生客户端（pymilvus 或 Attu UI）连接到 Milvus
- 删除所有旧集合
当前 UI 的限制：
- 没有一键“迁移并清理”的按钮
- UI 中的向量数据库重置（Admin Settings > Documents > Reset Vector Storage/Knowledge）只会影响当前模式的集合
- 旧集合需要使用 Milvus 客户端工具手动清理
注意
关键注意事项
在已有安装上启用多租户之前：
- 数据丢失风险：文件向量和用户记忆向量不会自动迁移。只有知识库内容可以重新索引（迁移）。
- 集合命名依赖：多租户依赖 Open WebUI 内部的集合命名约定（user-memory-、file-、web-search-、hash 模式）。如果 Open WebUI 在未来更新中更改这些约定，多租户路由就可能失效，导致隔离资源之间出现数据损坏或错误的数据检索。
- 无自动回滚：在数据写入后禁用多租户不会恢复对共享集合的访问。数据需要手动导出并重新导入。
对于全新安装，不存在迁移顾虑。
对于已有且包含重要数据的安装：
- 如果你不想处理迁移和数据丢失风险，就不要迁移到 多租户模式
- 了解文件和记忆都需要重新上传/重新生成
- 先在备份/预发布环境中测试迁移
- 评估 RAM 节省是否值得你为此付出的迁移成本
要执行完整重置并切换到多租户：
- 在外部备份任何关键知识库内容
- 前往
Admin Settings > Documents - 点击
Reset Vector Storage/Knowledge（这会删除所有当前模式集合以及已存储的知识元数据） - 设置
ENABLE_MILVUS_MULTITENANCY_MODE=true - 重启 Open WebUI
- 从头重新上传/创建知识库
注意
多租户映射依赖于 Open WebUI 当前的集合命名约定。
如果 Open WebUI 更改了它生成集合名称的方式（例如 user-memory- 前缀、file- 前缀、web search 模式或哈希格式），此映射就会失效，并把数据路由到错误的集合。
这可能导致严重的数据损坏、数据一致性问题，以及数据库内错误的数据映射。
如果你使用多租户模式，在升级前务必检查集合名称和数据映射是否有任何变化，并谨慎升级（请准备快照和备份以便回滚）！
MILVUS_COLLECTION_PREFIX
- 类型：
str - 默认值：
open_webui - 描述：设置 Milvus 集合名称的前缀。在多租户模式下，集合会变成
{prefix}_memories、{prefix}_knowledge等；在旧模式下，集合会变成{prefix}_{collection_name}。修改此值会创建一个完全独立的命名空间——旧前缀的现有集合会对 Open WebUI 变得不可见，但仍会在 Milvus 中占用资源。它适用于在共享 Milvus 服务器上实现真正的多实例隔离，而不是用于模式迁移。Milvus 只接受下划线，不支持连字符/破折号，后者会导致错误。
MariaDB Vector
注意
MariaDB Vector 目前并未由 Open WebUI 团队积极维护。它是社区添加的功能，由社区维护。 如果你要使用 MariaDB Vector，请在升级 Open WebUI 时格外小心（请为回滚创建备份和快照），以防 Open WebUI 的内部变更导致故障。
备注
MariaDB 依赖
mariadb Python 连接器默认不包含——它已经从捆绑依赖中移除。要使用 mariadb-vector，你必须显式安装：
pip install open-webui[mariadb]官方 Docker 镜像包含编译连接器所需的系统级 C 库（libmariadb-dev），因此在容器内执行 pip install open-webui[mariadb] 无需额外系统包即可工作。对于非 Docker 部署，你必须先安装 MariaDB C 连接器库（Debian/Ubuntu 上为 libmariadb-dev），再安装 Python 驱动。
信息
MariaDB Vector 需要使用官方 MariaDB 连接器（mariadb+mariadbconnector://...）作为连接 scheme。这是强制要求，因为官方驱动提供了正确的 qmark paramstyle，以及对 VECTOR(n) float32 负载的正确二进制绑定。其他兼容 MySQL 的驱动都无法工作。
你的 MariaDB 服务器必须支持 VECTOR 和 VECTOR INDEX 功能（MariaDB 11.7+）。
MARIADB_VECTOR_DB_URL
- 类型：
str - 默认值：空字符串（
""） - 描述：设置 MariaDB Vector 存储的数据库 URL。必须使用
mariadb+mariadbconnector://scheme（官方 MariaDB 驱动）。 - 示例：
mariadb+mariadbconnector://user:password@localhost:3306/openwebui
MARIADB_VECTOR_INITIALIZE_MAX_VECTOR_LENGTH
- 类型：
int - 默认值：
1536 - 描述：指定
VECTOR(n)列允许的最大向量长度（维度数）。它必须与嵌入模型的维度一致。表创建后，修改此值需要进行数据迁移——如果配置维度与已存储的列维度不一致，后端会拒绝启动。
MARIADB_VECTOR_DISTANCE_STRATEGY
- 类型：
str - 选项：
cosine- 使用vec_distance_cosine()进行相似度测量。euclidean- 使用vec_distance_euclidean()进行相似度测量。
- 默认值：
cosine - 描述：控制
VECTOR INDEX和相似度搜索查询所使用的距离函数。
MARIADB_VECTOR_INDEX_M
- 类型：
int - 默认值：
8 - 描述：HNSW 索引参数，用于控制索引构建期间每层最大双向连接数（MariaDB
VECTOR INDEX定义中的M=<int>）。值越大召回率越高，但索引大小和构建时间也会增加。
MARIADB_VECTOR_POOL_SIZE
- 类型：
int - 默认值：
None - 描述：设置 MariaDB Vector 数据库连接池中要维护的连接数。如果未设置，则使用 SQLAlchemy 默认值。将其设为
0会完全禁用连接池（使用NullPool）。
MARIADB_VECTOR_POOL_MAX_OVERFLOW
- 类型：
int - 默认值：
0 - 描述：指定连接池耗尽时，除了
MARIADB_VECTOR_POOL_SIZE之外还能创建的最大连接数。
MARIADB_VECTOR_POOL_TIMEOUT
- 类型：
int - 默认值：
30 - 描述：设置从 MariaDB Vector 连接池获取连接的超时时间（秒）。
MARIADB_VECTOR_POOL_RECYCLE
- 类型：
int - 默认值：
3600 - 描述：指定 MariaDB Vector 连接池中连接在多久之后会被回收，以防止连接变旧。
OpenSearch
OPENSEARCH_CERT_VERIFY
- 类型：
bool - 默认值：
False - 描述：启用或禁用 OpenSearch 证书验证。
OPENSEARCH_PASSWORD
- 类型：
str - 默认值：
None - 描述：设置 OpenSearch 的密码。
OPENSEARCH_SSL
- 类型：
bool - 默认值：
True - 描述：启用或禁用 OpenSearch 的 SSL。
OPENSEARCH_URI
- 类型：
str - 默认值：
https://localhost:9200 - 描述：设置 OpenSearch 的 URI。
OPENSEARCH_USERNAME
- 类型：
str - 默认值：
None - 描述：设置 OpenSearch 的用户名。
PGVector
备注
PostgreSQL 依赖
要使用 pgvector，请确保已安装 PostgreSQL 相关依赖：
pip install open-webui[all]PGVECTOR_DB_URL
- 类型：
str - 默认值：
DATABASE_URL环境变量的值 - 描述：设置用于模型存储的数据库 URL。
PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH
- 类型：
str - 默认值：
1536 - 描述：指定 PGVector 初始化时的最大向量长度。
PGVECTOR_CREATE_EXTENSION
- 类型：
str - 默认值：
true - 描述：在数据库中创建 vector 扩展。
信息
如果设为 false，open-webui 会假定存储 embeddings 的 PostgreSQL 数据库已预先配置好 vector 扩展。这也允许 open-webui 以非超级用户数据库账户运行。
PGVECTOR_INDEX_METHOD
- 类型：
str - 选项：
ivfflat- 使用扁平压缩的倒排文件 ，对高维数据集更友好。hnsw- 使用 Hierarchical Navigable Small World 图，通常能提供更好的查询性能。
- 默认值：未指定（pgvector 会使用其默认值）
- 描述：指定 pgvector 的索引方法。该选择会影响查询性能和索引构建时间。
- 持久化：这是一个
ConfigVar变量。
信息
选择索引方法时，请考虑数据集大小和查询模式。HNSW 通常查询性能更好，但会消耗更多内存；而 IVFFlat 对更大的数据集通常更节省内存。
PGVECTOR_HNSW_M
- 类型：
int - 默认值：
16 - 描述：HNSW 索引参数，用于控制索引构建期间每层最大双向连接数。值越大召回率越高，但索引大小和构建时间也会增加。仅当
PGVECTOR_INDEX_METHOD设为hnsw时适用。 - 持久化：这是一个
ConfigVar变量。
PGVECTOR_HNSW_EF_CONSTRUCTION
- 类型：
int - 默认值：
64 - 描述：HNSW 索引参数，用于控制索引构建期间动态候选列表的大小。值越大索引质量越高，但构建时间也会增加。仅当
PGVECTOR_INDEX_METHOD设为hnsw时适用。 - 持久化：这是一个
ConfigVar变量。
PGVECTOR_IVFFLAT_LISTS
- 类型：
int - 默认值：
100 - 描述：IVFFlat 索引参数，指定要创建的倒排列表（聚类）数量。对于最多 100 万行的数据，一个不错的起点是
rows / 1000；超过 100 万行时，则可考虑sqrt(rows)。仅当PGVECTOR_INDEX_METHOD设为ivfflat时适用。 - 持久化：这是一个
ConfigVar变量。
信息
对于 IVFFlat 索引，选择合适的列表数量对查询性能至关重要。列表太少会导致查询变慢，而列表太多则会增加索引大小，却不会带来明显的性能提升。
PGVECTOR_USE_HALFVEC
- 类型：
bool - 默认值：
False - 描述：启用使用
halfvec数据类型代替vector来存储 embeddings。当PGVECTOR_INITIALIZE_MAX_VECTOR_LENGTH超过 2000 维时必须启用，因为vector类型有 2000 维限制。
PGVECTOR_PGCRYPTO
- 类型：
bool - 默认值：
False - 描述：为 PGVector 启用 pgcrypto 扩展，用于加密敏感数据。启用后必须设置
PGVECTOR_PGCRYPTO_KEY。
PGVECTOR_PGCRYPTO_KEY
- 类型：
str - 默认值：
None - 描述：在启用
PGVECTOR_PGCRYPTO时，为 pgcrypto 指定加密密钥。该密钥必须安全且随机生成。
PGVECTOR_POOL_SIZE
- 类型：
int - 默认值：
None - 描述：设置 PGVector 数据库连接池中要维护的连接数。如果未设置，则使用 SQLAlchemy 默认值。
PGVECTOR_POOL_MAX_OVERFLOW
- 类型：
int - 默认值：
0 - 描述：指定连接池耗尽时，除了
PGVECTOR_POOL_SIZE之外还能创建的最大连接数。
PGVECTOR_POOL_TIMEOUT
- 类型：
int - 默认值：
30 - 描述：设置从 PGVector 连接池获取连接的超时时间（秒）。
PGVECTOR_POOL_RECYCLE
- 类型：
int - 默认值：
3600 - 描述：指定 PGVector 连接池中连接在多久之后会被回收，以防止连接变旧。
Qdrant
注意
Qdrant 目前并未由 Open WebUI 团队积极维护。它是社区添加的功能，由社区维护。 如果你要使用 Qdrant，请在升级 Open WebUI 时格外小心（请为回滚创建备份和快照），以防 Open WebUI 的内部变更导致故障。
QDRANT_API_KEY
- 类型：
str - 描述：设置 Qdrant 的 API key。
QDRANT_URI
- 类型：
str - 描述：设置 Qdrant 的 URI。
QDRANT_ON_DISK
- 类型：
bool - 默认值：
False - 描述：启用 memmap（也称为 on-disk）存储。
QDRANT_PREFER_GRPC
- 类型：
bool - 默认值：
False - 描述：尽可能使用 gRPC 接口。
信息
如果将其设为 True，并且 QDRANT_URI 指向一个启用了 TLS 且证书由私有 CA 签名的自托管服务器，请将环境变量 GRPC_DEFAULT_SSL_ROOTS_FILE_PATH 设置为你的 PEM 编码 CA 证书文件路径。更多信息请参阅 gRPC Core Docs。
QDRANT_GRPC_PORT
- 类型：
int - 默认值：
6334 - 描述：设置 Qdrant 的 gRPC 端口号。
QDRANT_TIMEOUT
- 类型：
int - 默认值：
5 - 描述：设置对 Qdrant 服务器发出的所有请求的超时时间（秒），以防长时间运行的查询阻塞应用。
QDRANT_HNSW_M
- 类型：
int - 默认值：
16 - 描述：控制 HNSW（Hierarchical Navigable Small World）索引构建。在标准模式下，这会设置
m参数；在多租户模式下，该值会用于payload_m参数，在 payload 上构建索引，因为全局m会因性能原因被禁用，这符合 Qdrant 的最佳实践。
ENABLE_QDRANT_MULTITENANCY_MODE
- 类型：
bool - 默认值：
True - 描述：为 Qdrant 集合管理启用多租户模式，通过合并相似的向量数据结构显著降低 RAM 使用和计算开销。建议开启。
信息
这会断开所有先前非多租户模式下创建的 Qdrant 集合。前往 Admin Settings > Documents > Reindex Knowledge Base 迁移现有知识。
之前模式下创建的 Qdrant 集合仍会继续占用资源。
目前 UI 中没有仅重置向量数据库的按钮。如果你想迁移知识到多租户模式：
- 使用原生 Qdrant 客户端移除所有带有
open_webui-knowledge前缀的集合（或者移除带有open_webui前缀的所有集合，以删除所有与 Open WebUI 相关的集合） - 前往
Admin Settings>Documents>Reindex Knowledge Base迁移现有知识库
Reindex Knowledge Base 只会迁移知识库
危险
如果你决定将多租户模式作为默认模式，并且不需要迁移旧知识，请前往 Admin Settings > Documents 重置向量与知识，这会删除所有带有 open_webui 前缀的集合以及所有已存储的知识。
注意
多租户映射依赖于 Open WebUI 当前的集合命名约定。
如果 Open WebUI 更改了它生成集合名称的 方式（例如 user-memory- 前缀、file- 前缀、web search 模式或哈希格式），此映射就会失效，并把数据路由到错误的集合。
这可能导致严重的数据损坏、数据一致性问题，以及数据库内错误的数据映射。
如果你使用多租户模式，在升级前务必检查集合名称和数据映射是否有任何变化，并谨慎升级（请准备快照和备份以便回滚）！
QDRANT_COLLECTION_PREFIX
- 类型：
str - 默认值：
open-webui - 描述：设置 Qdrant 集合名称的前缀。它有助于为集合提供命名空间或隔离，尤其在多租户模式下。修改此值会让应用在 Qdrant 中使用另一组集合。现有使用不同前缀的集合不会受到影响。
Pinecone
当使用 Pinecone 作为向量存储时，以下环境变量用于控制其行为。请确保在你的 .env 文件或部署环境中设置这些变量。
PINECONE_API_KEY
- 类型：
str - 默认值：
None - 描述：设置用于与 Pinecone 服务认证的 API key。
PINECONE_ENVIRONMENT
- 类型：
str - 默认值：
None - 描述：指定要连接的 Pinecone 环境（例如
us-west1-gcp、gcp-starter等）。
PINECONE_INDEX_NAME
- 类型：
str - 默认值：
open-webui-index - 描述：定义用于存储和查询向量嵌入的 Pinecone 索引名称。
PINECONE_DIMENSION
- 类型：
int - 默认值：
1536 - 描述：向量嵌入的维度。必须与索引预期的维度一致（通常基于所用模型为 768、1024、1536 或 3072）。
PINECONE_METRIC
- 类型：
str - 默认值：
cosine - 选项：
cosine、dotproduct、euclidean - 描述：指定 Pinecone 索引中用于向量比较的相似度指标。
PINECONE_CLOUD
- 类型：
str - 默认值：
aws - 选项：
aws、gcp、azure - 描述：指定 Pinecone 索引所在的云提供商。
Weaviate
信息
自托管与云部署
Open WebUI 在 Weaviate 连接中使用 connect_to_custom，它同时支持本地部署和远程 Weaviate 实例。这对于自托管部署尤其重要，因为 HTTP 和 gRPC 端点可能位于不同的 ingress 或主机名上，这在 Kubernetes 或 Azure Container Apps 等容器编排平台中很常见。
WEAVIATE_HTTP_HOST
- 类型：
str - 默认值：空字符串（
' '） - 描述：指定 Weaviate 服务器用于 HTTP 连接的主机名。对于自托管部署，这通常就是你的 Weaviate HTTP 端点主机名。
WEAVIATE_GRPC_HOST
- 类型：
str - 默认值：空字符串（
' '） - 描述：指定 Weaviate 服务器用于 gRPC 连接的主机名。当 HTTP 和 gRPC 分别通过不同的 ingress 提供时，它可以不同于
WEAVIATE_HTTP_HOST，这在容器编排环境中很常见。
WEAVIATE_HTTP_PORT
- 类型：
int - 默认值：
8080 - 描述：指定连接 Weaviate 服务器时使用的 HTTP 端口。
WEAVIATE_GRPC_PORT
- 类型：
int - 默认值：
50051 - 描述：指定连接 Weaviate 服务器时使用的 gRPC 端口。
WEAVIATE_HTTP_SECURE
- 类型：
bool - 默认值：
False - 描述：为与 Weaviate 服务器的 HTTP 连接启用 HTTPS。连接 HTTP 端点已启用 TLS 的 Weaviate 实例时，请将其设为
true。
WEAVIATE_GRPC_SECURE
- 类型：
bool - 默认值：
False - 描述：为与 Weaviate 服务器的 gRPC 连接启用 TLS。连接 gRPC 端点已启用 TLS 的 Weaviate 实例时，请将其设为
true。
WEAVIATE_API_KEY
- 类型：
str - 默认值：
None - 描述：设置用于与 Weaviate 服务器认证的 API key。
WEAVIATE_SKIP_INIT_CHECKS
- 类型：
bool - 默认值：
False - 描述：在连接时跳过 Weaviate 初始化检查。在某些网络配置下，检查可能失败但连接本身正常，这时该选项会很有用。
Oracle 23ai 向量搜索（oracle23ai）
ORACLE_DB_USE_WALLET
- 类型：
bool - 默认值：
false - 描述：决定与 Oracle Database 的连接方式。
- 设为
false时，使用ORACLE_DB_DSN中的主机、端口和服务名进行直连（例如 Oracle Database 23ai Free 或 DBCS 实例）。 - 设为
true时，使用基于 wallet 的连接（例如 Oracle Autonomous Database（ADW/ATP））。此时还必须配置ORACLE_WALLET_DIR和ORACLE_WALLET_PASSWORD。
- 设为
ORACLE_DB_USER
- 类型：
str - 默认值：
DEMOUSER - 描述：指定用于连接 Oracle Database 的用户名。
ORACLE_DB_PASSWORD
- 类型：
str - 默认值：
Welcome123456 - 描述：指定
ORACLE_DB_USER的密码。
ORACLE_DB_DSN
- 类型：
str - 默认值：
localhost:1521/FREEPDB1 - 描述：定义 Oracle Database 连接的 Data Source Name。
- 如果
ORACLE_DB_USE_WALLET为false，则应采用hostname:port/service_name格式（例如localhost:1521/FREEPDB1）。 - 如果
ORACLE_DB_USE_WALLET为true，则可以是 TNS 别名（例如 ADW/ATP 的medium），也可以是完整连接字符串。
- 如果
ORACLE_WALLET_DIR
- 类型：
str - 默认值：空字符串（
' '） - 描述：在
ORACLE_DB_USE_WALLET为true时必需。指定包含 Oracle Cloud Wallet 文件（例如cwallet.sso、sqlnet.ora、tnsnames.ora）的目录绝对路径。
ORACLE_WALLET_PASSWORD
- 类型：
str - 默认值：空字符串（
' '） - 描述：在
ORACLE_DB_USE_WALLET为true时必需。指定 Oracle Cloud Wallet 的密码。
ORACLE_VECTOR_LENGTH
- 类型：
int - 默认值：
768 - 描述：设置存储在 Oracle Database 中的向量嵌入的预期维度或长度。这必须与所用嵌入模型匹配。
ORACLE_DB_POOL_MIN
- 类型：
int - 默认值：
2 - 描述：Oracle Database 连接池中要维护的最小连接数。
ORACLE_DB_POOL_MAX
- 类型：
int - 默认值：
10 - 描述：Oracle Database 连接池允许的最大连接数。
ORACLE_DB_POOL_INCREMENT
- 类型：
int - 默认值：
1 - 描述：当连接池需要扩容时创建的连接数。
S3 向量桶
当使用 S3 Vector Bucket 作为向量存储时，以下环境变量用于控制其行为。请确保在你的 .env 文件或部署环境中设置这些变量。
信息
注意：此配置假定 AWS 凭据可在你的 Open WebUI 环境中使用。这可以通过 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 等环境变量提供，也可以通过 IAM 角色权限提供。
S3_VECTOR_BUCKET_NAME
- 类型：
str - 描述：指定要存储向量的 S3 Vector Bucket 名称。
S3_VECTOR_REGION
- 类型：
str - 描述：指定 S3 Vector Bucket 所在的 AWS 区域。
Valkey
Valkey 是 Redis 的开源分叉，可以作为 Open WebUI 的向量数据库后端（仅支持支持向量索引的 Valkey 8+）。
VALKEY_URL
- 类型：
str - 默认值：
redis://localhost:6379/0 - 描述：用于向量存储的 Valkey 实例的连接 URL。和
REDIS_URL不同——REDIS_URL用于缓存/WebSocket，而本变量专用于向量数据。
VALKEY_COLLECTION_PREFIX
- 类型：
str - 默认值：
open-webui - 描述：所有 Valkey 集合（collection）名称的前缀。用于在同一 Valkey 实例上区分多个 Open WebUI 部署。
VALKEY_INDEX_TYPE
- 类型：
str - 可选值：
HNSW - 默认值：
HNSW - 描述：Valkey 使用的向量索引类型。HNSW 在召回率和速度上提供了良好的平衡。
VALKEY_DISTANCE_METRIC
- 类型：
str - 可选值：
COSINE、L2、IP - 默认值：
COSINE - 描述：Valkey 用于向量相似度计算的距离度量。
COSINE（余弦相似度）适合绝大多数 embedding 模型；L2（欧氏距离）适合归一化向量；IP（内积）等价于负余弦距离。
VALKEY_HNSW_M
- 类型：
int - 默认值：
16 - 描述：HNSW 索引中每个节点的最大出度。更大的值带来更高的召回率，但写入更慢、内存占用更高。16 是常见折中。
VALKEY_HNSW_EF_CONSTRUCTION
- 类型：
int - 默认值：
200 - 描述：构建 HNSW 索引时搜索的候选数量。更大的值带来更高质量的索引，但索引构建更慢。
VALKEY_HNSW_EF_RUNTIME
- 类型：
int - 默认值：
10 - 描述：HNSW 索引运行时搜索的候选数量。更大的值带来更高的召回率，但查询更慢。
RAG（检索增强生成）内容提取引擎配置
CONTENT_EXTRACTION_ENGINE
- 类型：
str - 可选值：
- 留空以使用默认值
external- 使用外部加载器tika- 使用本地 Apache Tika 服务器docling- Use Docling enginedocument_intelligence- Use Document Intelligence enginemistral_ocr- Use Mistral OCR enginemineru
- 描述：Sets the content extraction engine to use for document ingestion.
- 持久化：这是一个
ConfigVar变量。
MISTRAL_OCR_API_KEY
- 类型：
str - 默认值：
None - 描述：Specifies the Mistral OCR API key to use.
- 持久化：这是一个
ConfigVar变量。
MISTRAL_OCR_API_BASE_URL
- 类型：
str - 默认值：
https://api.mistral.ai/v1 - 描述：Configures custom Mistral OCR API endpoints for flexible deployment options, allowing users to point to self-hosted or alternative Mistral OCR instances.
- 持久化：这是一个
ConfigVar变量。
EXTERNAL_DOCUMENT_LOADER_URL
- 类型：
str - 默认值：
None - 描述：Sets the URL for the external document loader service.
- 持久化：这是一个
ConfigVar变量。
EXTERNAL_DOCUMENT_LOADER_API_KEY
- 类型：
str - 默认值：
None - 描述：Sets the API key for authenticating with the external document loader service.
- 持久化：这是一个
ConfigVar变量。
TIKA_SERVER_URL
- 类型：
str - 默认值：
http://localhost:9998 - 描述：Sets the URL for the Apache Tika server.
- 持久化：这是一个
ConfigVar变量。
DOCLING_SERVER_URL
- 类型：
str - 默认值：
http://docling:5001 - 描述：Specifies the URL for the Docling server. Requires Docling version 2.0.0 or later for full compatibility with the new parameter-based configuration system.
- 持久化：这是一个
ConfigVar变量。
注意
Docling 2.0.0+ Required
The Docling integration has been refactored to use server-side parameter passing. If you are using Docling:
- Upgrade to Docling server version 2.0.0 or later
- Migrate all individual
DOCLING_*configuration variables to theDOCLING_PARAMSJSON object - Remove all deprecated
DOCLING_*environment variables from your configuration - Add
DOCLING_API_KEYif your server requires authentication
The old individual environment variables (DOCLING_OCR_ENGINE, DOCLING_OCR_LANG, etc.) are no longer supported and will be ignored.
DOCLING_API_KEY
- 类型：
str - 默认值：
None - 描述：Sets the API key for authenticating with the Docling server. Required when the Docling server has authentication enabled.
- 持久化：这是一个
ConfigVar变量。
DOCLING_PARAMS
-
类型：
str(JSON) -
默认值：
{} -
描述：Specifies all Docling processing parameters in JSON format. This is the primary configuration method for Docling processing options. All previously individual Docling settings are now configured through this single JSON object.
Supported Parameters:
do_ocr(bool): Enable OCR processing.force_ocr(bool): Force OCR even when text layer exists.ocr_engine(str): OCR engine to use. Options:tesseract,easyocr,ocrmac,rapidocr,tesserocr.ocr_lang(list[str]): OCR language codes. Note: Format depends on engine (e.g.,["eng", "fra"]for Tesseract;["en", "fr"]for EasyOCR).pdf_backend(str): PDF processing backend. Options:dlparse_v1,dlparse_v2,dlparse_v4,pypdfium2.table_mode(str): Table extraction mode. Options:fast,accurate.pipeline(str): Processing pipeline to use. Options:fast,standard.do_picture_description(bool): Enable image description generation.picture_description_mode(str): Mode for picture descriptions. Options:local,api.picture_description_local(str): Local model configuration object for picture descriptions.picture_description_api(str): API endpoint configuration object for picture descriptions.vlm_pipeline_model_api(str): Vision-language model API configuration. (e.g.,openai://gpt-4o).
-
Example:
{
"do_ocr": true,
"ocr_engine": "tesseract",
"ocr_lang": ["eng", "fra", "deu", "spa"],
"force_ocr": false,
"pdf_backend": "dlparse_v4",
"table_mode": "accurate",
"do_picture_description": true,
"picture_description_mode": "api",
"vlm_pipeline_model_api": "openai://gpt-4o"
}提示
dlparse vs dbparse: Note that the backend names use dlparse (Deep Learning Parse), not dbparse. For modern Docling (v2+), dlparse_v4 is generally recommended for the best balance of features.
- 持久化：这是一个
ConfigVar变量。
信息
Migration from Individual Docling Variables
If you were previously using individual DOCLING_* environment variables (such as DOCLING_OCR_ENGINE, DOCLING_OCR_LANG, etc.), these are now deprecated. You must migrate to using DOCLING_PARAMS as a single JSON configuration object.
Example Migration:
# Old configuration (deprecated)
DOCLING_OCR_ENGINE=tesseract
DOCLING_OCR_LANG=eng,fra
DOCLING_DO_OCR=true
# New configuration (required)
DOCLING_PARAMS='{"do_ocr": true, "ocr_engine": "tesseract", "ocr_lang": "eng,fra"}'注意
When setting this environment variable in a .env file, ensure proper JSON formatting and escape quotes as needed:
DOCLING_PARAMS="{\"do_ocr\": true, \"ocr_engine\": \"tesseract\", \"ocr_lang\": \"eng,fra,deu,spa\"}"
MINERU_API_TIMEOUT
- 类型：
str - 默认值：
300 - 描述：Sets the timeout in seconds for MinerU API requests during document processing.
- 持久化：这是一个
ConfigVar变量。
MINERU_FILE_EXTENSIONS
- 类型：
str（逗号分隔的扩展名） - 默认值：空（处理所有文件类型，不做扩展名过滤）
- 描述：当
CONTENT_EXTRACTION_ENGINE=mineru时，要通过 MinerU 处理的扩展名列表（不含点号）。MinerU 是为 PDF/扫描文档/复杂布局设计的 OCR 引擎，对纯文本文档或代码文件是浪费；只把它应用于它擅长的格式。扩展名以逗号分隔，不区分大小写，并匹配文件名后缀（不是 MIME 类型）。空值表示不过滤，对所有文件都调用 MinerU——这通常会拖慢文本/代码导入。典型配置：pdf,png,jpg,jpeg,tiff,bmp,webp。
PADDLEOCR_VL_BASE_URL
- 类型：
str - 默认值：
http://localhost:8080 - 描述：当
CONTENT_EXTRACTION_ENGINE=paddleocr_vl时所使用的 PaddleOCR-vl 服务器 Base URL。文档和图片会以 POST 方式提交到{base_url}/layout-parsing，并按页读取响应中的layoutParsingResults[].markdown.text。 - 持久化：这是一个
ConfigVar变量。
PADDLEOCR_VL_TOKEN
- 类型：
str - 默认值：
""（空） - 描述：PaddleOCR-vl 服务器的认证 token。每次 layout-parsing 请求会以
Authorization: token <value>形式发送。该值为空时，运行期会跳过 PaddleOCR-vl 引擎——即便设置了CONTENT_EXTRACTION_ENGINE=paddleocr_vl，加载器仍会对当前文档回退到默认的 PyPDFLoader。设置此值以激活该引擎。 - 持久化：这是一个
ConfigVar变量。
支持的文件类型
PaddleOCR-vl 同时处理文档和图片。被视为图片并以 fileType=1 发送的扩展名包括：png、jpg、jpeg、bmp、tiff、webp。其余以 fileType=0（文档，如 PDF）发送。输出为按页 Markdown，因此下游分块行为与其他引擎一致。
Retrieval Augmented Generation (RAG)
Core Configuration
RAG_EMBEDDING_ENGINE
- 类型：
str - Options:
- Leave empty for
Default (SentenceTransformers)- Uses SentenceTransformers for embeddings. ollama- Uses the Ollama API for embeddings.openai- Uses the OpenAI API for embeddings.azure_openai- Uses Azure OpenAI Services for embeddings.
- Leave empty for
- 描述：Selects an embedding engine to use for RAG.
- 持久化：这是一个
ConfigVar变量。
RAG_EMBEDDING_MODEL
- 类型：
str - 默认值：
sentence-transformers/all-MiniLM-L6-v2 - 描述：Sets a model for embeddings. Locally, a Sentence-Transformer model is used.
- 持久化：这是一个
ConfigVar变量。
RAG_TOP_K
- 类型：
int - 默认值：
3 - 描述：Sets the default number of results to consider for the embedding when using RAG.
- 持久化：这是一个
ConfigVar变量。
RAG_TOP_K_RERANKER
- 类型：
int - 默认值：
3 - 描述：Sets the default number of results to consider for the reranker when using RAG.
- 持久化：这是一个
ConfigVar变量。
RAG_RELEVANCE_THRESHOLD
- 类型：
float - 默认值：
0.0 - 描述：Sets the relevance threshold to consider for documents when used with reranking.
- 持久化：这是一个
ConfigVar变量。
ENABLE_RAG_HYBRID_SEARCH
- 类型：
bool - 默认值：
False - 描述：Enables the use of ensemble search with
BM25+ChromaDB, with reranking usingsentence_transformersmodels. When enabled, this applies to both the standard RAG retrieval pipeline and the native knowledge tools used in agentic mode. - 持久化：这是一个
ConfigVar变量。
RAG_HYBRID_BM25_WEIGHT
- 类型：
float - 默认值：
0.5 - 描述：Sets the weight given to the keyword search (BM25) during hybrid search. 1 means only keyword search, 0 means only vector search.
- 持久化：这是一个
ConfigVar变量。
ENABLE_RAG_HYBRID_SEARCH_ENRICHED_TEXTS
- 类型：
bool - 默认值：
False - 描述：Enhances BM25 hybrid search by enriching indexed text with document metadata including filenames, titles, sections, and snippets. This improves keyword recall for metadata-based queries, allowing searches to match on document names and structural elements in addition to content.
- 持久化：这是一个
ConfigVar变量。
信息
Enabling this feature increases the text volume indexed by BM25, which may impact storage requirements and indexing performance. However, it significantly improves search results when users query based on document names, titles, or structural elements rather than just content.
ENABLE_KB_EXEC
- 类型：
bool - 默认值：
False - 描述：为支持原生函数调用的模型启用代理式（agentic）知识库检索。它会给模型一组类 shell 的工具（
ls、tree、grep、cat、按行读取），让模型以迭代、面向探索的方式访问知识库；能力强的模型会用它替代一次性的相似度检索，召回率和精确率都更好。只在启用 Native Function Calling 时生效；在 Default 模式下没有任何效果。建议搭配在 管理面板 > 设置 > 模型 > Builtin Tools 中显式开启知识库工具类别的模型使用。详见 类文件系统访问：kb_exec。 - 持久化：这是一个
ConfigVar变量。
RAG_TEMPLATE
- 类型：
str - 默认值：The value of
DEFAULT_RAG_TEMPLATEenvironment variable.
DEFAULT_RAG_TEMPLATE:
### 任务：
使用提供的上下文回答用户查询，仅当 `<source>` 标签包含显式的 id 属性（例如 `<source id="1">`）时，才以 `[id]` 的格式加入行内引用。
### 指南：
- 如果你不知道答案，请明确说明。
- 如果不确定，请向用户请求澄清。
- 用与用户查询相同的语言回复。
- 如果上下文不可读或质量较差，请告知用户，并尽可能给出最佳答案。
- 如果答案不在上下文中，但你掌握相关知识，请向用户说明这一点，并基于你的理解给出答案。
- **只有当 `<source>` 标签包含 id 属性时，才使用 `[id]`（例如 `[1]`、`[2]`）这种行内引用。**
- 如果 `<source>` 标签不包含 id 属性，则不要引用。
- 回复中不要使用 XML 标签。
- 确保引用简洁，并且与所提供的信息直接相关。
### 引用示例：
如果用户询问某个具体主题，而信息来自带有 id 属性的来源，则回复应像 下面这样包含引用：
* “根据该研究，所提出的方法将效率提高了 20% [1]。”
### 输出：
请给出清晰、直接的回复，并且仅在上下文中的 `<source>` 标签带有 id 属性时，才以 `[id]` 的格式加入行内引用。
<context>
{{CONTEXT}}
</context>
<user_query>
{{QUERY}}
</user_query>
- 描述：Template to use when injecting RAG documents into chat completion.
- 持久化：这是一个
ConfigVar变量。
Document Processing
CHUNK_SIZE
- 类型：
int - 默认值：
1000 - 描述：Sets the document chunk size for embeddings.
- 持久化：这是一个
ConfigVar变量。
CHUNK_OVERLAP
- 类型：
int - 默认值：
100 - 描述：Specifies how much overlap there should be between chunks.
- 持久化：这是一个
ConfigVar变量。
CHUNK_MIN_SIZE_TARGET
- 类型：
int - 默认值：
0 - 描述：Chunks smaller than this threshold will be intelligently merged with neighboring chunks when possible. This helps prevent tiny, low-quality fragments that can hurt retrieval performance and waste embedding resources. This feature only works when
ENABLE_MARKDOWN_HEADER_TEXT_SPLITTERis enabled. Set to0to disable merging. For more information on the benefits and configuration, see the RAG guide. - 持久化：这是一个
ConfigVar变量。
RAG_TEXT_SPLITTER
- 类型：
str - Options:
charactertoken
- 默认值：
character - 描述：Sets the text splitter for RAG models. Use
characterfor RecursiveCharacterTextSplitter ortokenfor TokenTextSplitter (Tiktoken-based). - 持久化：这是一个
ConfigVar变量。
ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER
- 类型：
bool - 默认值：
True - 描述：Enables markdown header text splitting as a preprocessing step before character or token splitting. When enabled, documents are first split by markdown headers (h1-h6), then the resulting chunks are further processed by the configured text splitter (
RAG_TEXT_SPLITTER). This helps preserve document structure and context across chunks. - 持久化：这是一个
ConfigVar变量。
信息
Migration from markdown_header TEXT_SPLITTER
The markdown_header option has been removed from RAG_TEXT_SPLITTER. Markdown header splitting is now a preprocessing step controlled by ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER. If you were using RAG_TEXT_SPLITTER=markdown_header, switch to character or token and ensure ENABLE_MARKDOWN_HEADER_TEXT_SPLITTER is enabled (it is enabled by default).
TIKTOKEN_CACHE_DIR
- 类型：
str - 默认值：
{CACHE_DIR}/tiktoken - 描述：Sets the directory for TikToken cache.
TIKTOKEN_ENCODING_NAME
- 类型：
str - 默认值：
cl100k_base - 描述：Sets the encoding name for TikToken.
- 持久化：这是一个
ConfigVar变量。
PDF_EXTRACT_IMAGES
- 类型：
bool - 默认值：
False - 描述：Extracts images from PDFs using OCR when loading documents.
- 持久化：这是一个
ConfigVar变量。
PDF_LOADER_MODE
- 类型：
str - Options:
page- Creates one document per page (default).single- Combines all pages into one document for better chunking across page boundaries.
- 默认值：
page - 描述：Controls how PDFs are loaded and split into documents when using the default content extraction engine (PyPDFLoader). Page mode creates one document per page, while single mode combines all pages into one document, which can improve chunking quality when content spans across page boundaries. This setting has no effect when using external content extraction engines like Tika, Docling, Document Intelligence, MinerU, or Mistral OCR, as those engines have their own document handling logic.
- 持久化：这是一个
ConfigVar变量。
RAG_FILE_MAX_SIZE
- 类型：
int - 描述：Sets the maximum size of a file in megabytes that can be uploaded for document ingestion.
- 持久化：这是一个
ConfigVar变量。
RAG_FILE_MAX_COUNT
- 类型：
int - 描述 ：Sets the maximum number of files that can be uploaded at once for document ingestion.
- 持久化：这是一个
ConfigVar变量。
RAG_ALLOWED_FILE_EXTENSIONS
- 类型：
listofstr - 默认值：
[](which means all supported file types are allowed) - 描述：Specifies which file extensions are permitted for upload.
["pdf,docx,txt"]- 持久化：这是一个
ConfigVar变量。
信息
When configuring RAG_FILE_MAX_SIZE and RAG_FILE_MAX_COUNT, ensure that the values are reasonable to prevent excessive file uploads and potential performance issues.
FILE_IMAGE_COMPRESSION_WIDTH
- 类型：
int - 默认值：空（不调整宽度）
- 描述：把上传的图片在嵌入到知识库/聊天之前压缩到的最大宽度（像素）。
0或空值表示不调整宽度。等比例缩放，纵横比始终保留；超过此宽度的图会被等比缩小，小于此宽度的图保持原样。把它和FILE_IMAGE_COMPRESSION_HEIGHT一起设置可以控制上限尺寸；与RAG_FILE_MAX_SIZE不同，这个值作用于像素，不是文件字节数。通常需要配合调小 embedding 成本、限制上下文占用、或对齐多模态模型的最大尺寸。低于 100 的值通常没有实际意义（图片太小反而丢失关键信息）。 - 持久化：这是一个
ConfigVar变量。
FILE_IMAGE_COMPRESSION_HEIGHT
- 类型：
int - 默认值：空（不调整高度）
- 描述：把上传的图片在嵌入到知识库/聊天之前压缩到的最大高度（像素）。
0或空值表示不调整高度。等比例缩放，纵横比始终保留。把它和FILE_IMAGE_COMPRESSION_WIDTH一起设置可以控制上限尺寸。详见FILE_IMAGE_COMPRESSION_WIDTH上的说明。 - 持久化：这是一个
ConfigVar变量。
Embedding Engine Configuration
常规 Embedding Settings
RAG_EMBEDDING_BATCH_SIZE
- 类型：
int - 默认值：
1 - 描述：Controls how many text chunks are embedded in a single API request when using external embedding providers (Ollama, OpenAI, or Azure OpenAI). Higher values (20-100+; max 16000 (not recommended)) may process documents faster by sending less, but larger API requests. Some external APIs do not support batching or sending more than 1 chunk per request. In such casey you must leave this at
1. Default is 1 (safest option if the API does not support batching / more than 1 chunk per request). This setting only applies to external embedding engines, not the default SentenceTransformers engine. - 持久化：这是一个
ConfigVar变量。
信息
Check if your API and embedding model supports batched processing. Only increase this variable's value if it does - otherwise you might run into unexpected issues.
ENABLE_ASYNC_EMBEDDING
- 类型：
bool - 默认值：
true - 描述：Runs embedding tasks asynchronously (parallelized) for maximum performance. Only works for Ollama, OpenAI and Azure OpenAI, does not affect sentence transformer setups.
- 持久化：这是一个
ConfigVar变量。
提示
It may be needed to increase the value of THREAD_POOL_SIZE if many other users are simultaneously using your Open WebUI instance while having async embeddings turned on to prevent
注意
Enabling this will potentially send thousands of requests per minute. If you are embedding locally, ensure that you can handle this amount of requests, otherwise turn this off to return to sequential embedding (slower but will always work). If you are embedding externally via API, ensure your rate limits are high enough to handle parallel embedding. (Usually, OpenAI can handle thousands of embedding requests per minute, even on the lowest API tier).
RAG_EMBEDDING_CONCURRENT_REQUESTS
- 类型：
int - 默认值：
0 - 描述：Limits the number of concurrent embedding API requests when async embedding is enabled. Uses an asyncio semaphore to throttle parallel requests. Set to
0for unlimited concurrency (default behavior), or set to a positive integer to cap simultaneous requests. Useful for respecting rate limits on external embedding APIs or reducing load on local embedding servers. - 持久化：这是一个
ConfigVar变量。
提示
If you are hitting rate limits from your embedding provider (e.g., 429 errors), set this to a value that keeps you within your API tier's rate limit (e.g., 5 or 10). This is especially helpful when uploading large documents that generate many embedding batches.
RAG_EMBEDDING_TIMEOUT
- 类型：
int(seconds) - 默认值：
None(no timeout) - 描述：Sets an optional timeout in seconds for embedding operations during document upload. When set, embedding requests that exceed this duration will be aborted with a timeout error. When unset (default), embedding operations run without a time limit. This setting is primarily relevant for deployments using the default SentenceTransformers embedding engine, where embeddings run locally and can take longer on slower hardware. External embedding engines (Ollama, OpenAI, Azure OpenAI) have their own timeout mechanisms and are generally not affected by this setting.
信息
This variable was introduced alongside a fix for uvicorn worker death during document uploads. Previously, local embedding operations could block the worker thread long enough to trigger uvicorn's health check timeout (default: 5 seconds), causing the worker process to be killed. The underlying fix uses run_coroutine_threadsafe to keep the main event loop responsive to health checks regardless of this timeout setting. The timeout is purely a safety net for aborting abnormally long embedding operations — it does not affect worker health check behavior.
RAG_EMBEDDING_CONTENT_PREFIX
- 类型：
str - 默认值：
None - 描述：Sets the prefix string prepended to document content before generating embeddings. Some embedding models (e.g., nomic-embed-text) require task-specific prefixes to differentiate between content being stored vs. queries being searched. For nomic-embed-text, set this to
search_document:. Only needed if your embedding model's documentation specifies a content/document prefix.
RAG_EMBEDDING_QUERY_PREFIX
- 类型：
str - 默认值：
None - 描述：Sets the prefix string prepended to user queries before generating embeddings for retrieval. This is the counterpart to
RAG_EMBEDDING_CONTENT_PREFIX. For nomic-embed-text, set this tosearch_query:. Only needed if your embedding model's documentation specifies a query prefix.
RAG_EMBEDDING_PREFIX_FIELD_NAME
- 类型：
str - 默认值：
None - 描述：Specifies the JSON field name used to pass the prefix to the embedding API request body. When set along with a prefix value, the prefix is sent as a separate field in the API request rather than being prepended to the text. Required for embedding APIs that accept the prefix as a dedicated parameter instead of inline text.
OpenAI Embeddings
RAG_OPENAI_API_BASE_URL
- 类型：
str - 默认值：
${OPENAI_API_BASE_URL} - 描述：Sets the OpenAI base API URL to use for RAG embeddings.
- 持久化：这是一个
ConfigVar变量。
RAG_OPENAI_API_KEY
- 类型：
str - 默认值：
${OPENAI_API_KEY} - 描述：Sets the OpenAI API key to use for RAG embeddings.
- 持久化：这是一个
ConfigVar变量。
RAG_EMBEDDING_OPENAI_BATCH_SIZE
- 类型：
int - 默认值：
1 - 描述：Sets the batch size for OpenAI embeddings.
Azure OpenAI Embeddings
RAG_AZURE_OPENAI_BASE_URL
- 类型：
str - 默认值：
None - 描述：Sets the base URL for Azure OpenAI Services when using Azure OpenAI for RAG embeddings. Should be in the format
https://{your-resource-name}.openai.azure.com. - 持久化：这是一个
ConfigVar变量。
RAG_AZURE_OPENAI_API_KEY
- 类型：
str - 默认值：
None - 描述：Sets the API key for Azure OpenAI Services when using Azure OpenAI for RAG embeddings.
- 持久化：这是一个
ConfigVar变量。
RAG_AZURE_OPENAI_API_VERSION
- 类型：
str - 默认值：
None - 描述：Sets the API version for Azure OpenAI Services when using Azure OpenAI for RAG embeddings. Common values include
2023-05-15,2023-12-01-preview, or2024-02-01. - 持久化：这是一个
ConfigVar变量。
Ollama Embeddings 配置
RAG_OLLAMA_BASE_URL
- 类型：
str - 描述：Sets the base URL for Ollama API used in RAG models.
- 持久化：这是一个
ConfigVar变量。
RAG_OLLAMA_API_KEY
- 类型：
str - 描述：Sets the API key for Ollama API used in RAG models.
- 持久化：这是一个
ConfigVar变量。
Reranking
RAG_RERANKING_ENGINE
- 类型：
str - Options:
external, or empty for local Sentence-Transformer CrossEncoder - 默认值：Empty string (local reranking)
- 描述：Specifies the reranking engine to use. Set to
externalto use an external reranker API (requiresRAG_EXTERNAL_RERANKER_URL). Leave empty to use a local Sentence-Transformer CrossEncoder model. - 持久化：这是一个
ConfigVar变量。
RAG_RERANKING_MODEL
- 类型：
str - 描述：Sets a model for reranking results. Locally, a Sentence-Transformer model is used.
- 持久化：这是一个
ConfigVar变量。
RAG_RERANKING_BATCH_SIZE
- 类型：
int - 默认值：
32 - 描述：Controls how many query–document pairs are scored in a single batch during local reranking. Higher values use more memory but can be faster on GPUs with sufficient VRAM. This applies to the local ColBERT/CrossEncoder reranking model's
predict()call. - 持久化：这是一个
ConfigVar变量。
SENTENCE_TRANSFORMERS_CROSS_ENCODER_SIGMOID_ACTIVATION_FUNCTION
- 类型：
bool - 默认值：
True - 描述：When enabled (default), applies sigmoid normalization to local CrossEncoder reranking scores to ensure they fall within the 0-1 range. This allows the relevance threshold setting to work correctly with models like MS MARCO that output raw logits.
RAG_EXTERNAL_RERANKER_TIMEOUT
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the timeout in seconds for external reranker API requests during RAG document retrieval. Leave empty to use default timeout behavior.
- 持久化：这是一个
ConfigVar变量。
RAG_EXTERNAL_RERANKER_URL
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the full URL for the external reranking API.
- 持久化：这是一个
ConfigVar变量。
注意
You MUST provide the full URL, including the endpoint path (e.g., https://api.yourprovider.com/v1/rerank). The system does not automatically append /v1/rerank or any other path to the base URL you provide.
RAG_EXTERNAL_RERANKER_API_KEY
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the API key for the external reranking API.
- 持久化：这是一个
ConfigVar变量。
Query Generation
ENABLE_RETRIEVAL_QUERY_GENERATION
- 类型：
bool - 默认值：
True - 描述：Enables or disables retrieval query generation.
- 持久化：这是一个
ConfigVar变量。
ENABLE_QUERIES_CACHE
- 类型：
bool - 默认值：
False - 描述：Enables request-scoped caching of LLM-generated search queries. When enabled, queries generated for web search are cached and automatically reused for file/knowledge base retrieval within the same request. This eliminates duplicate LLM calls when both web search and RAG are active, reducing token usage and latency while maintaining search quality. It is highly recommended to enable this especially in larger setups.
QUERY_GENERATION_PROMPT_TEMPLATE
- 类型：
str - 默认值：The value of
DEFAULT_QUERY_GENERATION_PROMPT_TEMPLATEenvironment variable.
DEFAULT_QUERY_GENERATION_PROMPT_TEMPLATE:
### 任务：
分析聊天历史，以确定是否需要生成搜索查询，并使用给定语言进行回答。默认情况下，**优先生成 1-3 个宽泛且相关的搜索查询**，除非可以绝对确定不需要额外信息。目标是在即使不确定性很低的情况下，也尽可能检索到全面、最新且有价值的信息。如果无需搜索，请返回空列表。
### 指南：
- **仅**以 JSON 对象回复。严格禁止任何形式的额外评论、解释或其他文本。
- 生成搜索查询时，请按如下格式回复：{ "queries": ["query1", "query2"] }，并确保每个查询都独立、简洁且与主题相关。
- 只有在完全确定搜索无法检索到任何有用结果时，才返回：{ "queries": [] }。
- 只要有**任何可能**带来有用或最新信息，就应倾向于建议搜索查询。
- 保持简洁，专注于编写高质量的搜索查询，避免不必要的展开、评论或假设。
- 今天的日期是：{{CURRENT_DATE}}。
- 始终优先提供可执行且足够宽泛、能最大化信息覆盖范围的查询。
### 输出：
仅以 JSON 格式返回：
{
"queries": ["query1", "query2"]
}
### 聊天历史：
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
- 描述：Sets the prompt template for query generation.
- 持久化：这是一个
ConfigVar变量。
Document Intelligence (Azure)
DOCUMENT_INTELLIGENCE_ENDPOINT
- 类型：
str - 默认值：
None - 描述：Specifies the endpoint for document intelligence.
- 持久化：这是一个
ConfigVar变量。
DOCUMENT_INTELLIGENCE_KEY
- 类型：
str - 默认值：
None - 描述：Specifies the key for document intelligence.
- 持久化：这是一个
ConfigVar变量。
DOCUMENT_INTELLIGENCE_MODEL
- 类型：
str - 默认值：
None - 描述：Specifies the model for document intelligence.
- 持久化：这是一个
ConfigVar变量。
Advanced Settings
BYPASS_EMBEDDING_AND_RETRIEVAL
- 类型：
bool - 默认值：
False - 描述：Bypasses the embedding and retrieval process.
- 持久化：这是一个
ConfigVar变量。
RAG_FULL_CONTEXT
- 类型：
bool - 默认值：
False - 描述：Specifies whether to use the full context for RAG.
- 持久化：这是一个
ConfigVar变量。
RAG_SYSTEM_CONTEXT
- 类型：
bool - 默认值：
False - 描述：When enabled, injects RAG context into the system message instead of the user message. This is highly recommended for optimizing performance when using models that support KV prefix caching or Prompt Caching. This includes local engines (like Ollama, llama.cpp, or vLLM) and cloud providers / Model-as-a-Service providers (like OpenAI and Vertex AI). By placing the context in the system message, it remains at a stable position at the start of the conversation, allowing the cache to persist across multiple turns. When disabled (default), context is injected into the user message, which shifts position each turn and invalidates the cache.
ENABLE_RAG_LOCAL_WEB_FETCH
- 类型：
bool - 默认值：
False - 描述：Controls whether RAG web fetch operations can access URLs that resolve to private/local network IP addresses.
- 持久化：这是一个
ConfigVar变量。
When disabled (default), Open WebUI blocks web fetch requests to URLs that resolve to private IP addresses, including:
- IPv4 private ranges (
10.x.x.x,172.16.x.x-172.31.x.x,192.168.x.x,127.x.x.x) - IPv6 private ranges
This is a Server-Side Request Forgery (SSRF) protection. Without this safeguard, a malicious user could provide URLs that appear external but resolve to internal addresses, potentially exposing internal services, cloud metadata endpoints, or other sensitive resources.
注意
Only enable this setting if you need to fetch content from internal network resources (e.g., an internal wiki or intranet) and you trust all users with access to your Open WebUI instance. Enabling this in a multi-tenant or public-facing deployment introduces significant security risk.
Google Drive
ENABLE_GOOGLE_DRIVE_INTEGRATION
- 类型：
bool - 默认值：
False - 描述：Enables or disables Google Drive integration. If set to true, and
GOOGLE_DRIVE_CLIENT_ID&GOOGLE_DRIVE_API_KEYare both configured, Google Drive will appear as an upload option in the chat UI. - 持久化：这是一个
ConfigVar变量。
信息
When enabling GOOGLE_DRIVE_INTEGRATION, ensure that you have configured GOOGLE_DRIVE_CLIENT_ID and GOOGLE_DRIVE_API_KEY correctly, and have reviewed Google's terms of service and usage guidelines.
GOOGLE_DRIVE_CLIENT_ID
- 类型：
str - 描述：Sets the client ID for Google Drive (client must be configured with Drive API and Picker API enabled).
- 持久化：这是一个
ConfigVar变量。
GOOGLE_DRIVE_API_KEY
- 类型：
str - 描述：Sets the API key for Google Drive integration.
- 持久化：这是一个
ConfigVar变量。
OneDrive
信息
For a step-by-step setup guide, check out our tutorial: Configuring OneDrive & SharePoint Integration.
ENABLE_ONEDRIVE_INTEGRATION
- 类型：
bool - 默认值：
False - 描述：Enables or disables the Microsoft OneDrive integration feature globally.
- 持久化：这是一个
ConfigVar变量。
注意
Configuring OneDrive integration is a multi-step process that requires creating and correctly configuring an Azure App Registration. The authentication flow also depends on a browser pop-up window. Please ensure that your browser's pop-up blocker is disabled for your Open WebUI domain to allow the authentication and file selection window to appear.
ENABLE_ONEDRIVE_PERSONAL
- 类型：
bool - 默认值：
True - 描述：Controls whether the "Personal OneDrive" option appears in the attachment menu. Requires
ONEDRIVE_PERSONAL_CLIENT_IDto be configured. - 持久化：这是一个
ConfigVar变量。
ENABLE_ONEDRIVE_BUSINESS
- 类型：
bool - 默认值：
True - 描述：Controls whether the "Work/School OneDrive" option appears in the attachment menu. Requires
ONEDRIVE_CLIENT_IDto be configured. - 持久化：这是一个
ConfigVar变量。
ONEDRIVE_CLIENT_ID
- 类型：
str - 默认值：
None - 描述：Generic environment variable for the OneDrive Client ID. You should rather use the specific
ONEDRIVE_CLIENT_ID_PERSONALorONEDRIVE_CLIENT_ID_BUSINESSvariables. This exists as a legacy option for backwards compatibility.
ONEDRIVE_CLIENT_ID_PERSONAL
- 类型：
str - 默认值：
None - 描述：Specifies the Application (client) ID for the Personal OneDrive integration. This requires a separate Azure App Registration configured to support personal Microsoft accounts. Do not put the business OneDrive client ID here!
ONEDRIVE_CLIENT_ID_BUSINESS
- 类型：
str - 默认值：
None - 描述：Specifies the Application (client) ID for the Work/School (Business) OneDrive integration. This requires a separate Azure App Registration configured to support personal Microsoft accounts. Do not put the personal OneDrive client ID here!
信息
This Client ID (also known as Application ID) is obtained from an Azure App Registration within your Microsoft Entra ID (formerly Azure AD) tenant. When configuring the App Registration in Azure, the Redirect URI must be set to the URL of your Open WebUI instance and configured as a Single-page application (SPA) type for the authentication to succeed.
ONEDRIVE_SHAREPOINT_URL
- 类型：
str - 默认值：
None - 描述：Specifies the root SharePoint site URL for the work/school integration, e.g.,
https://companyname.sharepoint.com. - 持久化：这是一个
ConfigVar变量。
信息
This variable is essential for the work/school integration. It should point to the root SharePoint site associated with your tenant, enabling access to SharePoint document libraries.
ONEDRIVE_SHAREPOINT_TENANT_ID
- Type:
str - Default:
None - Description: Specifies the Directory (tenant) ID for the work/school integration. This is obtained from your business-focused Azure App Registration.
- Persistence: This environment variable is a
ConfigVarvariable.
信息
This Tenant ID (also known as Directory ID) is required for the work/school integration. You can find this value on the main overview page of your Azure App Registration in the Microsoft Entra ID portal.
Web Search
ENABLE_WEB_SEARCH
- 类型：
bool - 默认值：
False - 描述：Enable web search toggle.
- 持久化：这是一个
ConfigVar变量。
ENABLE_SEARCH_QUERY_GENERATION
- 类型：
bool - 默认值：
True - 描述：Only applies to Default Function Calling mode, which is legacy and no longer supported. If True: an LLM generates optimized, distilled search queries from the conversation context. If False: the user's last message is used verbatim as the web search query. Native Mode (the supported mode) uses the model's own
search_webtool call and does not consult this setting. - 持久化：这是一个
ConfigVar变量。
WEB_SEARCH_TRUST_ENV
- 类型：
bool - 默认值：
False - 描述：Enables proxy set by
http_proxyandhttps_proxyduring web search content fetching. - 持久化：这是一个
ConfigVar变量。
WEB_FETCH_FILTER_LIST
- 类型：
string(comma-separated list) - 默认值：
""(empty, but default blocklist is always applied) - 描述：Configures additional URL filtering rules for web fetch operations to prevent Server-Side Request Forgery (SSRF) attacks. The system includes a default blocklist that protects against access to cloud metadata endpoints (AWS, Google Cloud, Azure, Alibaba Cloud). Entries without a ! prefix are treated as an allow list (only these domains are permitted), while entries with a ! prefix are added to the block list (these domains are always denied). The default blocklist includes !169.254.169.254, !fd00:ec2::254, !metadata.google.internal, !metadata.azure.com, and !100.100.100.200. Custom entries are merged with the default blocklist.
信息
Example:
Block additional domains: WEB_FETCH_FILTER_LIST="!internal.company.com,!192.168.1.1" Allow only specific domains: WEB_FETCH_FILTER_LIST="example.com,trusted-site.org"
WEB_SEARCH_DOMAIN_FILTER_LIST
- 类型：
listofstr - 默认值：
[] - 描述：Comma-separated list of domains to filter web search results. Domains prefixed with
!are blocked; domains without prefix create an allowlist (only those domains permitted). - Example:
wikipedia.org,github.com,!malicious-site.com - 持久化：这是一个
ConfigVar变量。
WEB_SEARCH_RESULT_COUNT
- 类型：
int - 默认值：
3 - 描述：Maximum number of web search results to crawl. In Native/Agentic tool calling, this is also the default
search_webresult count when the model omitscount, and the maximum cap when the model providescount. - 持久化：这是一个
ConfigVar变量。
WEB_SEARCH_CONCURRENT_REQUESTS
- 类型：
int - 默认值：
0 - 描述：Limits the number of concurrent search requests to the search engine provider. Set to
0for unlimited concurrency (default). Set to1for sequential execution to prevent rate limiting errors (e.g., Brave Free Tier). - 持久化：这是一个
ConfigVar变量。
WEB_FETCH_MAX_CONTENT_LENGTH
- 类型：
int - 默认值：None (no limit)
- 描述：Maximum number of characters to return from fetched URLs. When set, content exceeding this limit is truncated. Previously hardcoded at 50,000 characters. Leave empty or unset to return full content without truncation. Useful for controlling context window usage with large web pages.
- 持久化：这是一个
ConfigVar变量。
WEB_LOADER_CONCURRENT_REQUESTS
- 类型：
int - 默认值：
10 - 描述：Specifies the number of concurrent requests used by the web loader to fetch content from web pages returned by search results. This directly impacts how many pages can be crawled simultaneously.
- 持久化：这是一个
ConfigVar变量。
信息
"WEB_LOADER_CONCURRENT_REQUESTS" was previously named "WEB_SEARCH_CONCURRENT_REQUESTS". The variable "WEB_SEARCH_CONCURRENT_REQUESTS" has been repurposed to control the concurrency of the search engine requests (see above). To control the web loader concurrency (fetching content from results), you MUST use "WEB_LOADER_CONCURRENT_REQUESTS".
WEB_SEARCH_ENGINE
- 类型：
str - Options:
searxng- Uses the SearXNG search engine.google_pse- Uses the Google Programmable Search Engine.brave- Uses the Brave search engine.kagi- Uses the Kagi search engine.mojeek- Uses the Mojeek search engine.bocha- Uses the Bocha search engine.serpstack- Uses the Serpstack search engine.serper- Uses the Serper search engine.serply- Uses the Serply search engine.searchapi- Uses the SearchAPI search engine.serpapi- Uses the SerpApi search engine.duckduckgo- Uses the DuckDuckGo search engine.tavily- Uses the Tavily search engine.jina- Uses the Jina search engine.bing- Uses the Bing search engine.exa- Uses the Exa search engine.perplexity- Uses the Perplexity API to access perplexity's AI models. Calls their AI models, which execute a search and also return a full response.perplexity_search- Uses the Perplexity Search API search engine. In contrast to theperplexityoption, this uses Perplexity's web search API for searching the web and retrieving results.sougou- Uses the Sougou search engine.ollama_cloud- Uses the Ollama Cloud search engine.azure_ai_searchyacyyandex- Uses the Yandex Search API.youcom- Uses the You.com YDC Index API for web search.
- 持久化：这是一个
ConfigVar变量。
DDGS_BACKEND
- 类型：
str - 默认值：
auto - Options:
auto(Random),bing,brave,duckduckgo,google,grokipedia,mojeek,wikipedia,yahoo,yandex. - 描述：Specifies the backend to be used by the DDGS engine.
- 持久化：这是一个
ConfigVar变量。 It can be configured in the Admin Panel > Settings > Web Search > DDGS Backend when DDGS is selected as the search engine.
BYPASS_WEB_SEARCH_EMBEDDING_AND_RETRIEVAL
- 类型：
bool - 默认值：
False - 描述：Bypasses the web search embedding and retrieval process.
- 持久化：这是一个
ConfigVar变量。
BYPASS_WEB_SEARCH_WEB_LOADER
- 类型：
bool - 默认值：
False - 描述：Bypasses the web loader when performing web search. When enabled, only snippets from the search engine are used, and the full page content is not fetched.
- 持久化：这是一个
ConfigVar变量。
SEARXNG_QUERY_URL
- 类型：
str - 描述：The SearXNG search API URL supporting JSON output.
<query>is replaced with the search query. Example:http://searxng.local/search?q=<query> - 持久化：这是一个
ConfigVar变量。
SEARXNG_LANGUAGE
- 类型：
str - 默认值：
all - 描述：This variable is used in the request to searxng as the "search language" (arguement "language").
- 持久化：这是一个
ConfigVar变量。
GOOGLE_PSE_API_KEY
- 类型：
str - 描述：Sets the API key for the Google Programmable Search Engine (PSE) service.
- 持久化：这是一个
ConfigVar变量。
GOOGLE_PSE_ENGINE_ID
- 类型：
str - 描述：The engine ID for the Google Programmable Search Engine (PSE) service.
- 持久化：这是一个
ConfigVar变量。
BRAVE_SEARCH_API_KEY
- 类型：
str - 描述：Sets the API key for the Brave Search API.
- 持久化：这 是一个
ConfigVar变量。
信息
Brave's free tier enforces a rate limit of 1 request per second. Open WebUI automatically retries requests that receive HTTP 429 rate limit errors after a 1-second delay. For free tier users, set WEB_SEARCH_CONCURRENT_REQUESTS to 1 to ensure sequential request processing. See the Brave web search documentation for more details.
BRAVE_SEARCH_CONTEXT_TOKENS
- 类型：
int - 默认值：
8192 - 描述：当
WEB_SEARCH_ENGINE=brave_llm_context时，每次查询所拉取的最大 token 总数。会以maximum_number_of_tokens发送给 Brave 的 LLM Context API。有效范围1024–32768。值越大获取的提取段落越丰富，相应消耗的 API 配额也越多；值越小响应越精简。可在 管理面板 → 设置 → 网页搜索 → Context Tokens 中配置（仅在选择brave_llm_context引擎时显示）。 - 持久化：这是一个
ConfigVar变量。存储于配置键rag.web.search.brave_search_context_tokens。
KAGI_SEARCH_API_KEY
- 类型：
str - 描述：Sets the API key for Kagi Search API.
- 持久化：这是一个
ConfigVar变量。
MOJEEK_SEARCH_API_KEY
- 类型：
str - 描述：Sets the API key for Mojeek Search API.
- 持久化：这是一个
ConfigVar变量。
SERPSTACK_API_KEY
- 类型：
str - 描述：Sets the API key for Serpstack search API.
- 持久化：这是一个
ConfigVar变量。
SERPSTACK_HTTPS
- 类型：
bool - 默认值：
True - 描述：Configures the use of HTTPS for Serpstack requests. Free tier requests are restricted to HTTP only.
- 持久化：这是一个
ConfigVar变量。
SERPER_API_KEY
- 类型：
str - 描述：Sets the API key for Serper search API.
- 持久化：这是一个
ConfigVar变量。
SERPLY_API_KEY
- 类型：
str - 描述：Sets the API key for Serply search API.
- 持久化：这是一个
ConfigVar变量。
SEARCHAPI_API_KEY
- 类型：
str - 描述：Sets the API key for SearchAPI.
- 持久化：这是一个
ConfigVar变量。
SEARCHAPI_ENGINE
- 类型：
str - 描述：Sets the SearchAPI engine.
- 持久化：这是一个
ConfigVar变量。
TAVILY_API_KEY
- 类型：
str - 描述：Sets the API key for Tavily search API.
- 持久化：这是一个
ConfigVar变量。
LINKUP_API_KEY
- 类型：
str - 描述：Sets the API key for Linkup search API.
- 持久化：这是一个
ConfigVar变量。
LINKUP_SEARCH_PARAMS
- 类型：
str(JSON) - 默认值：
{} - 描述：传递给 Linkup 搜索 API 的额外参数（以 JSON 对象形式）。用于覆盖默认搜索行为，例如深度、域名限制、是否包含原始内容等。空对象
{}表示全部使用 Linkup 默认值。任何未通过此参数覆盖的字段，Open WebUI 都会回退到内置默认。 - 持久化：这是一个
ConfigVar变量。
JINA_API_KEY
- 类型：
str - 描述：Sets the API key for Jina.
- 持久化：这是一个
ConfigVar变量。
JINA_API_BASE_URL
- 类型：
str - 默认值：
https://s.jina.ai/ - 描述：Sets the Base URL for Jina Search API. Useful for specifying custom or regional endpoints (e.g.,
https://eu-s-beta.jina.ai/). - 持久化：这是一个
ConfigVar变量。 It can be configured in the Admin Panel > Settings > Web Search > Jina API Base URL.
BING_SEARCH_V7_ENDPOINT
- 类型：
str - 描述：Sets the endpoint for Bing Search API.
- 持久化：这是一个
ConfigVar变量。
BING_SEARCH_V7_SUBSCRIPTION_KEY
- 类型：
str - 默认值：
https://api.bing.microsoft.com/v7.0/search - 描述：Sets the subscription key for Bing Search API.
- 持久化：这是一个
ConfigVar变量。
BOCHA_SEARCH_API_KEY
- 类型：
str - 默认值：
None - 描述：Sets the API key for Bocha Search API.
- 持久化：这是一个
ConfigVar变量。
EXA_API_KEY
- 类型：
str - 默认值：
None - 描述：Sets the API key for Exa search API.
- 持久化：这是一个
ConfigVar变量。
SERPAPI_API_KEY
- 类型：
str - 默认值：
None - 描述：Sets the API key for SerpAPI.
- 持久化：这是一个
ConfigVar变量。
SERPAPI_ENGINE
- 类型：
str - 默认值：
None - 描述：Specifies the search engine to use for SerpAPI.
- 持久化：这是一个
ConfigVar变量。
AZURE_AI_SEARCH_API_KEY
- 类型：
str - 默认值：
None - 描述：API key (query key or admin key) for authenticating with Azure AI Search service. Required for using Azure AI Search as a web search provider.
- 持久化：这是一个
ConfigVar变量。
AZURE_AI_SEARCH_ENDPOINT
- 类型：
str - 默认值：
None - 描述：Azure Search service endpoint URL. Specifies which Azure Search service instance to connect to.
- Example:
https://myservice.search.windows.net,https://company-search.search.windows.net - 持久化：这是一个
ConfigVar变量。
AZURE_AI_SEARCH_INDEX_NAME
- 类型：
str - 默认值：
None - 描述：Name of the search index to query within your Azure Search service. Different indexes can contain different types of searchable content.
- Example:
my-search-index,documents-index,knowledge-base - 持久化：这是一个
ConfigVar变量。
SOUGOU_API_SID
- 类型：
str - 默认值：
None - 描述：Sets the Sogou API SID.
- 持久化：这是一个
ConfigVar变量。
SOUGOU_API_SK
- 类型：
str - 默认值：
None - 描述：Sets the Sogou API SK.
- 持久化：这是一个
ConfigVar变量。
OLLAMA_CLOUD_WEB_SEARCH_API_KEY
- 类型：
str - 默认值：
None - 描述：Sets the Ollama Cloud Web Search API Key.
- 持久化：这是一个
ConfigVar变量。
TAVILY_EXTRACT_DEPTH
- 类型：
str - 默认值：
basic - 描述：Specifies the extract depth for Tavily search results.
- 持久化：这是一个
ConfigVar变量。
YACY_QUERY_URL
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the query URL for YaCy search engine integration. Should point to a YaCy instance's search API endpoint.
- 持久化：这是一个
ConfigVar变量。
YACY_USERNAME
- 类型：
str - 默认值：Empty string (' ')
- 描述：Specifies the username for authenticated access to YaCy search engine.
- 持久化：这是一个
ConfigVar变量。
YACY_PASSWORD
- 类型：
str - 默认值：Empty string (' ')
- 描述：Specifies the password for authenticated access to YaCy search engine.
- 持久化：这是一个
ConfigVar变量。
EXTERNAL_WEB_SEARCH_URL
- 类型：
str - 默认值：Empty string (' ')
- 描述：Specifies the URL of an external web search service API endpoint for custom search integrations.
- 持久化：这是一个
ConfigVar变量。
EXTERNAL_WEB_SEARCH_API_KEY
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the API key for authenticating with the external web search service.
- 持久化：这是一个
ConfigVar变量。
EXTERNAL_WEB_LOADER_URL
- 类型：
str - 默认值：Empty string (' ')
- 描述：Specifies the URL of an external web content loader service for fetching and processing web pages.
- 持久化：这是一个
ConfigVar变量。
EXTERNAL_WEB_LOADER_API_KEY
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the API key for authenticating with the external web loader service.
- 持久化：这是一个
ConfigVar变量。
YANDEX_WEB_SEARCH_URL
- 类型：
str - 默认值：
https://searchapi.api.cloud.yandex.net/v2/web/search - 描述：Specifies the URL of the Yandex Web Search service API endpoint.
- 持久化：这是一个
ConfigVar变量。
YANDEX_WEB_SEARCH_API_KEY
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the API key for authenticating with the Yandex Web Search service.
- 持久化：这是一个
ConfigVar变量。
YANDEX_WEB_SEARCH_CONFIG
- 类型：
str - 默认值：Empty string (' ')
- 描述：Optional JSON configuration string for Yandex Web Search. Can be used to set parameters like
searchTypeorregionas per the Yandex API documentation. - 持久化：这是一个
ConfigVar变量。
PERPLEXITY_API_KEY
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the API key for Perplexity API.
- 持久化：这是一个
ConfigVar变量。
PERPLEXITY_SEARCH_API_URL
- 类型：
str - 默认值：
https://api.perplexity.ai/search - 描述：Configures the API endpoint for Perplexity Search. Allows using custom or self-hosted Perplexity-compatible API endpoints (such as LiteLLM's
/searchendpoint) instead of the hardcoded default for the official Perplexity API. This enables flexibility in routing search requests to alternative providers or internal proxies. Note: If using LiteLLM, append the specific provider name to the URL path. - Example:
http://my-litellm-server.com/search/perplexity-search - 持久化：这是一个
ConfigVar变量。
PERPLEXITY_MODEL
- 类型：
str - 默认值：
sonar - 描述：Specifies the Perplexity AI model to use for search queries when using
Perplexityas the web search engine. - 持久化：这是一个
ConfigVar变量。
信息
Perplexity is different from perplexity_search.
If you use perplexity_search, this variable is not relevant to you.
PERPLEXITY_SEARCH_CONTEXT_USAGE
- 类型：
str - 默认值：
medium - 描述：Controls the amount of search context used by Perplexity AI. Options typically include
low,medium,high. - 持久化：这是一个
ConfigVar变量。
信息
Perplexity is different from perplexity_search.
If you use perplexity, this variable is not relevant to you.
YOUCOM_API_KEY
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the API key for You.com YDC Index API web search. Required when
WEB_SEARCH_ENGINEis set toyoucom. Obtain an API key from You.com API. - 持久化：这是一个
ConfigVar变量。
Web Loader Configuration
WEB_LOADER_ENGINE
- 类型：
str - 默认值：
(empty) - 描述：Specifies the loader to use for retrieving and processing web content.
- Options:
safe_web(default) - Uses internal fetching with enhanced error handling.playwright- Uses Playwright for rendering pages with JavaScript support.firecrawl- Uses Firecrawl service.tavily- Uses Tavily service.external- Uses an external web loader API.
- 持久化：这是一个
ConfigVar变量。
信息
When using playwright, you have two options:
- If
PLAYWRIGHT_WS_URIis not set, Playwright with Chromium dependencies will be automatically installed in the Open WebUI container on launch. - If
PLAYWRIGHT_WS_URIis set, Open WebUI will connect to a remote browser instance instead of installing dependencies locally.
PLAYWRIGHT_WS_URL
- 类型：
str - 默认值：
None - 描述：Specifies the WebSocket URI of a remote Playwright browser instance. When set, Open WebUI will use this remote browser instead of installing browser dependencies locally. This is particularly useful in containerized environments where you want to keep the Open WebUI container lightweight and separate browser concerns. Example:
ws://playwright:3000 - 持久化：这是一个
ConfigVar变量。
提示
Using a remote Playwright browser via PLAYWRIGHT_WS_URL can be beneficial for:
- Reducing the size of the Open WebUI container
- Using a different browser other than the default Chromium
- Connecting to a non-headless (GUI) browser
FIRECRAWL_API_BASE_URL
- 类型：
str - 默认值：
https://api.firecrawl.dev - 描述：Sets the base URL for Firecrawl API.
- 持久化：这是一个
ConfigVar变量。
FIRECRAWL_API_KEY
- 类型：
str - 默认值：
None - 描述：Sets the API key for Firecrawl API.
- 持久化：这是一个
ConfigVar变量。
FIRECRAWL_TIMEOUT
- 类型：
int - 默认值：
None - 描述：Specifies the timeout in milliseconds for Firecrawl requests. If not set, the default Firecrawl timeout is used.
- 持久化：这是一个
ConfigVar变量。 It can be configured in the Admin Panel > Settings > Web Search > Firecrawl Timeout.
PLAYWRIGHT_TIMEOUT
- 类型：
int - 默认值：Empty string (' '), since
Noneis set as default. - 描述：Specifies the timeout for Playwright requests.
- 持久化：这是一个
ConfigVar变量。
WEB_LOADER_TIMEOUT
- 类型：
float - 默认值：Empty string (' '), since
Noneis set as default. - 描述：Specifies the request timeout in seconds for the SafeWebBaseLoader when scraping web pages. Without this setting, web scraping operations can hang indefinitely on slow or unresponsive pages. Recommended values are 10–30 seconds depending on your network conditions.
- 持久化：这是一个
ConfigVar变量。
注意
This timeout only applies when WEB_LOADER_ENGINE is set to safe_web or left empty (the default). It has no effect on Playwright or Firecrawl loader engines, which have their own timeout configurations (PLAYWRIGHT_TIMEOUT and Firecrawl's internal settings respectively).
YouTube Loader
YOUTUBE_LOADER_PROXY_URL
- 类型：
str - 描述：Sets the proxy URL for YouTube loader.
- 持久化：这是一个
ConfigVar变量。
YOUTUBE_LOADER_LANGUAGE
- 类型：
str - 默认值：
en - 描述：Comma-separated list of language codes to try when fetching YouTube video transcriptions, in priority order.
- Example: If set to
es,de, Spanish transcriptions will be attempted first, then German if Spanish was not available, and lastly English.
备注
Note: If none of the specified languages are available and en was not in your list, the system will automatically try English as a final fallback.
- 持久化：这是一个
ConfigVar变量。
Audio
BYPASS_PYDUB_PREPROCESSING
- 类型：
bool - 默认值：
False - 描述：When enabled, skips pydub-based preprocessing (format conversion to MP3, compression, and chunked splitting by size) before audio is sent to the Speech-to-Text engine. Useful when the upstream provider already handles these steps, when ffmpeg is unavailable on the host, or when you want to pass audio through untouched. Applies to all STT engines.
Whisper Speech-to-Text (Local)
WHISPER_MODEL
- 类型：
str - 默认值：
base - 描述：Sets the Whisper model to use for Speech-to-Text. The backend used is faster_whisper with quantization to
int8. - 持久化：这是一个
ConfigVar变量。
WHISPER_MODEL_DIR
- 类型：
str - 默认值：
${DATA_DIR}/cache/whisper/models - 描述：Specifies the directory to store Whisper model files.
WHISPER_COMPUTE_TYPE
- 类型：
str - 默认值：
int8(CPU),float16(CUDA) - 描述：Sets the compute type for Whisper model inference. Defaults to
int8for CPU andfloat16for CUDA (with fallback toint8/int8_float16).
WHISPER_VAD_FILTER
- 类型：
bool - 默认值：
False - 描述：Specifies whether to apply a Voice Activity Detection (VAD) filter to Whisper Speech-to-Text.
WHISPER_MODEL_AUTO_UPDATE
- 类型：
bool - 默认值：
False - 描述：Toggles automatic update of the Whisper model.
WHISPER_LANGUAGE
- 类型：
str - 默认值：
None - 描述：Specifies the ISO 639-1 language Whisper uses for STT (ISO 639-2 for Hawaiian and Cantonese). Whisper predicts the language by default.
WHISPER_MULTILINGUAL
- 类型：
bool - 默认值：
False - 描述：Toggles whether to use the multilingual Whisper model. When set to
False, the system will use the English-only model for better performance in English-centric tasks. WhenTrue, it supports multiple languages.
Speech-to-Text (OpenAI)
AUDIO_STT_ENGINE
- 类型：
str - Options:
""(empty string) - Uses the built-in local Whisper engine for Speech-to-Text. This runs Whisper on the backend server.openai- Uses an OpenAI-compatible API for Speech-to-Text.deepgram- Uses Deepgram engine for Speech-to-Text.azure- Uses Azure Cognitive Services for Speech-to-Text.mistral- Uses Mistral API for Speech-to-Text.
- 描述：Specifies the Speech-to-Text engine to use. When left as an empty string (the default), the backend runs a local Whisper instance. Note: The "Web API" option seen in User Settings is a frontend-only setting that uses the browser's built-in speech recognition and does not call this backend endpoint at all.
- 持久化：这是一个
ConfigVar变量。
AUDIO_STT_MODEL
- 类型：
str - 默认值：
whisper-1 - 描述：Specifies the Speech-to-Text model to use for OpenAI-compatible endpoints.
- 持久化：这是一个
ConfigVar变量。
AUDIO_STT_OPENAI_API_BASE_URL
- 类型：
str - 默认值：
${OPENAI_API_BASE_URL} - 描述：Sets the OpenAI-compatible base URL to use for Speech-to-Text.
- 持久化：这是一个
ConfigVar变量。
AUDIO_STT_OPENAI_API_KEY
- 类型：
str - 默认值：
${OPENAI_API_KEY} - 描述：Sets the OpenAI API key to use for Speech-to-Text.
- 持久化：这是一个
ConfigVar变量。
Speech-to-Text (Azure)
AUDIO_STT_AZURE_API_KEY
- 类型：
str - 默认值：
None - 描述：Specifies the Azure API key to use for Speech-to-Text.
- 持久化：这是一个
ConfigVar变量。
AUDIO_STT_AZURE_REGION
- 类型：
str - 默认值：
None - 描述：Specifies the Azure region to use for Speech-to-Text.
- 持久化：这是一个
ConfigVar变量。
AUDIO_STT_AZURE_LOCALES
- 类型：
str - 默认值：
None - 描述：Specifies the locales to use for Azure Speech-to-Text.
- 持久化：这是一个
ConfigVar变量。
AUDIO_STT_AZURE_BASE_URL
- 类型：
str - 默认值：
None - 描述：Specifies a custom Azure base URL for Speech-to-Text. Use this if you have a custom Azure endpoint.
- 持久化：这是一个
ConfigVar变量。
AUDIO_STT_AZURE_MAX_SPEAKERS
- 类型：
int - 默认值：
3 - 描述：Sets the maximum number of speakers for Azure Speech-to-Text diarization.
- 持久化：这是一个
ConfigVar变量。
Speech-to-Text (Deepgram)
DEEPGRAM_API_KEY
- 类型：
str - 默认值：
None - 描述：Specifies the Deepgram API key to use for Speech-to-Text.
- 持久化：这是一个
ConfigVar变量。
Speech-to-Text (Mistral)
AUDIO_STT_MISTRAL_API_KEY
- 类型：
str - 默认值：
None - 描述：Specifies the Mistral API key to use for Speech-to-Text.
- 持久化：这是一个
ConfigVar变量。
AUDIO_STT_MISTRAL_API_BASE_URL
- 类型：
str - 默认值：
https://api.mistral.ai/v1 - 描述：Specifies the Mistral API base URL to use for Speech-to-Text.
- 持久化：这是一个
ConfigVar变量。
AUDIO_STT_MISTRAL_USE_CHAT_COMPLETIONS
- 类型：
bool - 默认值：
False - 描述：When enabled, uses the chat completions endpoint for Mistral Speech-to-Text instead of the dedicated transcription endpoint.
- 持久化：这是一个
ConfigVar变量。
Speech-to-Text (General)
AUDIO_STT_SUPPORTED_CONTENT_TYPES
- 类型：
str - 默认值：
None - 描述：Comma-separated list of supported audio MIME types for Speech-to-Text (e.g.,
audio/wav,audio/mpeg,video/*). Leave empty to use defaults. - 持久化：这是一个
ConfigVar变量。
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 类型校验）。可在 Admin Settings → Audio → STT 中配置。 - 持久化：这是一个
ConfigVar变量。
Text-to-Speech
AUDIO_TTS_API_KEY
- 类型：
str - 描述：Sets the API key for Text-to-Speech.
- 持久化：这是一个
ConfigVar变量。
AUDIO_TTS_ENGINE
- 类型：
str - Options:
""(empty string) - Disables backend TTS. When empty, TTS requests do not reach the backend. All TTS is handled client-side using the browser's Web Speech API or the user-configurable "Browser Kokoro" option in User Settings.openai- Uses an OpenAI-compatible API for Text-to-Speech.mistral- Uses Mistral's Text-to-Speech API.elevenlabs- Uses ElevenLabs engine for Text-to-Speech.azure- Uses Azure Cognitive Services for Text-to-Speech.transformers- Uses a local SentenceTransformers-based model for Text-to-Speech (runs on the backend).
- 描述：Specifies the Text-to-Speech engine to use on the backend. When left as an empty string (the default), no backend TTS service is configured, and audio playback relies entirely on the user's browser capabilities or frontend options like "Browser Kokoro".
- 持久化：这是一个
ConfigVar变量。
AUDIO_TTS_MODEL
- 类型：
str - 默认值：
tts-1 - 描述：Specifies the OpenAI text-to-speech model to use.
- 持久化：这是一个
ConfigVar变量。
AUDIO_TTS_VOICE
- 类型：
str - 默认值：
alloy - 描述：Sets the OpenAI text-to-speech voice to use.
- 持久化：这是一个
ConfigVar变量。
AUDIO_TTS_SPLIT_ON
- 类型：
str - 默认值：
punctuation - 描述：Sets the OpenAI text-to-speech split on to use.
- 持久化：这是一个
ConfigVar变量。
Azure Text-to-Speech
AUDIO_TTS_AZURE_SPEECH_REGION
- 类型：
str - 描述：Sets the region for Azure Text to Speech.
- 持久化：这是一个
ConfigVar变量。
AUDIO_TTS_AZURE_SPEECH_OUTPUT_FORMAT
- 类型：
str - 默认值：
audio-24khz-160kbitrate-mono-mp3 - 描述：Sets the output format for Azure Text to Speech.
- 持久化：这是一个
ConfigVar变量。
AUDIO_TTS_AZURE_SPEECH_BASE_URL
- 类型：
str - 默认值：
None - 描述：Specifies a custom Azure Speech base URL for Text-to-Speech. Use this if you have a custom Azure endpoint.
- 持久化：这是一个
ConfigVar变量。
Voice Mode
ENABLE_VOICE_MODE_PROMPT
- 类型：
bool - 默认值：
True - 描述：语音模式系统提示词的总开关。设为
True时，语音模式聊天会在前面追加自定义的VOICE_MODE_PROMPT_TEMPLATE（若已设置）或DEFAULT_VOICE_MODE_PROMPT_TEMPLATE。设为False时不注入任何语音专用系统提示——模型只使用常规系统提示和聊天历史。可在 Admin Settings → Interface → Voice Mode Custom Prompt 中通过开关配置。 - 持久化：这是一个
ConfigVar变量。存储于配置键task.voice.prompt.enable。
VOICE_MODE_PROMPT_TEMPLATE
- 类型：
str - 默认值：The value of
DEFAULT_VOICE_MODE_PROMPT_TEMPLATEenvironment variable. - 描述：Configures a custom system prompt for voice mode interactions. Allows administrators to control how the AI responds in voice conversations (style, length, tone). Leave empty to use the default prompt optimized for voice conversations, or provide custom instructions to tailor the voice assistant's behavior. Only applied when
ENABLE_VOICE_MODE_PROMPTisTrue. - 持久化：这是一个
ConfigVar变量。
OpenAI Text-to-Speech
AUDIO_TTS_OPENAI_API_BASE_URL
- 类型：
str - 默认值：
${OPENAI_API_BASE_URL} - 描述：Sets the OpenAI-compatible base URL to use for text-to-speech.
- 持久化：这是一个
ConfigVar变量。
AUDIO_TTS_OPENAI_API_KEY
- 类型：
str - 默认值：
${OPENAI_API_KEY} - 描述：Sets the API key to use for text-to-speech.
- 持久化：这是一个
ConfigVar变量。
AUDIO_TTS_OPENAI_PARAMS
- 类型：
str(JSON) - 默认值：
{} - 描述：Additional parameters for OpenAI-compatible TTS API in JSON format. Allows customization of API-specific settings.
- Example:
{"speed": 1.0} - 持久化：这是一个
ConfigVar变量。
Mistral Text-to-Speech
AUDIO_TTS_MISTRAL_API_KEY
- 类型：
str - 默认值：
None - 描述：Sets the API key used for Mistral Text-to-Speech.
- 持久化：这是一个
ConfigVar变量。
AUDIO_TTS_MISTRAL_API_BASE_URL
- 类型：
str - 默认值：
https://api.mistral.ai/v1 - 描述：Sets the base URL used for Mistral Text-to-Speech.
- 持久化：这是一个
ConfigVar变量。
信息
When AUDIO_TTS_ENGINE=mistral, Open WebUI uses mistral-tts-latest when AUDIO_TTS_MODEL is empty.
Elevenlabs Text-to-Speech
ELEVENLABS_API_BASE_URL
- 类型：
str - 默认值：
https://api.elevenlabs.io - 描述：Configures custom ElevenLabs API endpoints, enabling support for EU residency API requirements and other regional deployments.
- 持久化：这是一个
ConfigVar变量。
Image Generation
常规 Settings
ENABLE_IMAGE_GENERATION
- 类型：
bool - 默认值：
False - 描述：Enables or disables image generation features.
- 持久化：这是一个
ConfigVar变量。
ENABLE_IMAGE_PROMPT_GENERATION
- 类型：
bool - 默认值：
True - 描述：Enables or disables automatic enhancement of user prompts for better image generation results.
- 持久化：这是一个
ConfigVar变量。
IMAGE_PROMPT_GENERATION_PROMPT_TEMPLATE
- 类型：
str - 默认值：
None - 描述：指定用于生成图片提示词的模板。
- 持久化：这是一个
ConfigVar变量。
DEFAULT_IMAGE_PROMPT_GENERATION_PROMPT_TEMPLATE:
### 任务：
根据给定的语言和上下文，为图片生成任务写出一段详细的提示词。请像在向一个看不见图片的人描述它一样来说明图像内容。包括相关细节、颜色、形状以及任何其他重要元素。
### 指南：
- 描述要充分且具体，重点放在图像最重要的方面。
- 不要做任何假设，也不要添加图片中不存在的信息。
- 使用聊天的主要语言；如果是多语言内容，则默认使用英语。
- 如果图像过于复杂，请聚焦最显著的元素。
### 输出：
严格以 JSON 格式返回：
{
"prompt": "Your detailed description here."
}
### 聊天历史：
<chat_history>
{{MESSAGES:END:6}}
</chat_history>
Image Creation
IMAGE_GENERATION_ENGINE
- 类型：
str - Options:
openai- Uses OpenAI DALL-E for image generation.comfyui- Uses ComfyUI engine for image generation.automatic1111- Uses AUTOMATIC1111 engine for image generation.gemini- Uses Gemini for image generation.
- 默认值：
openai - 描述：Specifies the engine to use for image generation.
- 持久化：这是一个
ConfigVar变量。
IMAGE_GENERATION_MODEL
- 类型：
str - 默认值：``
- 描述：Default model to use for image generation (e.g.,
dall-e-3,gemini-2.0-flash-exp). - 持久化：这是一个
ConfigVar变量。
IMAGE_SIZE
- 类型：
str - 默认值：
512x512 - 描述：Sets the default output dimensions for generated images in WIDTHxHEIGHT format (e.g.,
1024x1024). Set toautoto let the model determine the appropriate size (only supported by models matchingIMAGE_AUTO_SIZE_MODELS_REGEX_PATTERN). - 持久化：这是一个
ConfigVar变量。
IMAGE_AUTO_SIZE_MODELS_REGEX_PATTERN
- 类型：
str - 默认值：
^gpt-image - 描述：A regex pattern to match model names that support
IMAGE_SIZE = "auto". When a model matches this pattern, theautosize option becomes available, allowing the model to determine the appropriate output dimensions. By default, only models starting withgpt-image(e.g.,gpt-image-1) are matched.
IMAGE_URL_RESPONSE_MODELS_REGEX_PATTERN
- 类型：
str - 默认值：
^gpt-image - 描述：A regex pattern to match model names that return image URLs directly instead of base64-encoded data. Models matching this pattern will not include
response_format: b64_jsonin API requests. By default, only models starting withgpt-imageare matched. For other models, Open WebUI requests base64 responses and handles the conversion internally.
IMAGE_STEPS
- 类型：
int - 默认值：
50 - 描述：Sets the default iteration steps for image generation. Used for ComfyUI and AUTOMATIC1111 engines.
- 持久化：这是一个
ConfigVar变量。
Image Editing
ENABLE_IMAGE_EDIT
- 类型：
boolean - 默认值：
true - 描述：When disabled, Image Editing will not be used and instead, images will be created only using the image generation engine.
- 持 久化：这是一个
ConfigVar变量。
IMAGE_EDIT_ENGINE
- 类型：
str - Options:
openai- Uses OpenAI DALL-E for image editing.gemini- Uses Gemini for image editing.comfyui- Uses ComfyUI engine for image editing.
- 默认值：
openai - 描述：Configures the engine used for image editing operations, enabling modification of existing images using text prompts.
- 持久化：这是一个
ConfigVar变量。
IMAGE_EDIT_MODEL
- 类型：
str - 默认值：``
- 描述：Specifies the model to use for image editing operations within the selected engine (e.g.,
dall-e-2,gemini-2.5-flash). - 持久化：这是一个
ConfigVar变量。
IMAGE_EDIT_SIZE
- 类型：
str - 默认值：``
- 描述：Defines the output dimensions for edited images in WIDTHxHEIGHT format (e.g.,
1024x1024). Leave empty to preserve original dimensions. - 持久化：这是一个
ConfigVar变量。
OpenAI DALL-E
Image Generation
IMAGES_OPENAI_API_BASE_URL
- 类型：
str - 默认值：
${OPENAI_API_BASE_URL} - 描述：Sets the OpenAI-compatible base URL to use for DALL-E image generation.
- 持久化：这是一个
ConfigVar变量。
IMAGES_OPENAI_API_VERSION
- 类型：
str - 默认值：
${OPENAI_API_VERSION} - 描述：Optional setting. If provided it sets the
api-versionquery parameter when calling the image generation endpoint. Required for Azure OpenAI deployments. - 持久化：这是一个
ConfigVar变量。
IMAGES_OPENAI_API_KEY
- 类型：
str - 默认值：
${OPENAI_API_KEY} - 描述：Sets the API key to use for DALL-E image generation.
- 持久化：这是一个
ConfigVar变量。
IMAGES_OPENAI_API_PARAMS
- 类型：
str(JSON) - 默认值：
{} - 描述：Additional parameters for OpenAI image generation API in JSON format. Allows customization of API-specific settings such as quality parameters for DALL-E models (e.g.,
{"quality": "hd"}for dall-e-3). - Example:
{"quality": "hd", "style": "vivid"} - 持久化：这是一个
ConfigVar变量。
Image Editing
IMAGES_EDIT_OPENAI_API_BASE_URL
- 类型：
str - 默认值：
${OPENAI_API_BASE_URL} - 描述：Configures the OpenAI API base URL specifically for image editing operations, allowing separate endpoints from image generation.
- 持久化：这是一个
ConfigVar变量。
IMAGES_EDIT_OPENAI_API_VERSION
- 类型：
str - 默认值：``
- 描述：Specifies the OpenAI API version for image editing, enabling support for Azure OpenAI deployments with versioned endpoints.
- 持久化：这是一个
ConfigVar变量。
IMAGES_EDIT_OPENAI_API_KEY
- 类型：
str - 默认值：
${OPENAI_API_KEY} - 描述：Provides authentication for OpenAI image editing API requests, with support for separate keys from image generation.
- 持久化：这是一个
ConfigVar变量。
Gemini
提示
For a detailed setup guide and example configuration, please refer to the Gemini Image Generation Guide.
Image Generation
IMAGES_GEMINI_API_BASE_URL
- 类型：
str - 默认值：
${GEMINI_API_BASE_URL} - 描述：Specifies the URL to Gemini's image generation API.
- 持久化：这是一个
ConfigVar变量。
IMAGES_GEMINI_API_KEY
- 类型：
str - 默认值：
${GEMINI_API_KEY} - 描述：Sets the Gemini API key for image generation.
- 持久化：这是一个
ConfigVar变量。
IMAGES_GEMINI_ENDPOINT_METHOD
- 类型：
str - Options:
predict- Uses the predict endpoint (default for Imagen models).generateContent- Uses the generateContent endpoint (for Gemini 2.5 Flash and newer models).
- 默认值：``
- 描述：Specifies the Gemini API endpoint method for image generation, supporting both legacy Imagen models and newer Gemini models with image generation capabilities.
- 持久化：这是一个
ConfigVar变量。
Image Editing
IMAGES_EDIT_GEMINI_API_BASE_URL
- 类型：
str - 默认值：
${GEMINI_API_BASE_URL} - 描述：Configures the Gemini API base URL for image editing operations with Gemini models.
- 持久化：这是一个
ConfigVar变量。
IMAGES_EDIT_GEMINI_API_KEY
- 类型：
str - 默认值：
${GEMINI_API_KEY} - 描述：Provides authentication for Gemini image editing API requests.
- 持久化：这是一个
ConfigVar变量。
ComfyUI
Image Generation
COMFYUI_BASE_URL
- 类型：
str - 默认值：``
- 描述：Specifies the URL to the ComfyUI image generation API (e.g.,
http://127.0.0.1:8188). - 持久化：这是一个
ConfigVar变量。
COMFYUI_API_KEY
- 类型：
str - 默认值：``
- 描述：Sets the API key for ComfyUI authentication.
- 持久化：这是一个
ConfigVar变量。
COMFYUI_WORKFLOW
- 类型：
str(JSON) - Default:
{
"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"
}
}
}- 描述：Defines the ComfyUI workflow configuration in JSON format. Export from ComfyUI using "Save (API Format)" to ensure compatibility.
- 持久化：这是一个
ConfigVar变量。
COMFYUI_WORKFLOW_NODES
- 类型：
list[dict] - 默认值：
[] - 描述：Specifies the ComfyUI workflow node mappings for image generation, defining which nodes handle prompt, model, dimensions, and other parameters. Configured automatically via the admin UI.
- 持久化：这是一个
ConfigVar变量。
Image Editing
IMAGES_EDIT_COMFYUI_BASE_URL
- 类型：
str - 默认值：``
- 描述：Configures the ComfyUI base URL for image editing operations, enabling self-hosted ComfyUI workflows for image manipulation.
- 持久化：这是一个
ConfigVar变量。
IMAGES_EDIT_COMFYUI_API_KEY
- 类型：
str - 默认值：``
- 描述：Provides authentication for ComfyUI image editing API requests when the ComfyUI instance requires API key authentication.
- 持久化：这是一个
ConfigVar变量。
IMAGES_EDIT_COMFYUI_WORKFLOW
- 类型：
str(JSON) - 默认值：``
- 描述：Defines the ComfyUI workflow configuration in JSON format for image editing operations. Must include nodes for image input, prompt, and output. Export from ComfyUI using "Save (API Format)".
- 持久化：这是一个
ConfigVar变量。
IMAGES_EDIT_COMFYUI_WORKFLOW_NODES
- 类型：
list[dict] - 默认值：
[] - 描述：Specifies the ComfyUI workflow node mappings for image editing, defining which nodes handle image input, prompt, model, dimensions, and other parameters. Configured automatically via the admin UI.
- 持久化：这是一个
ConfigVar变量。
AUTOMATIC1111
AUTOMATIC1111_BASE_URL
- 类型：
str - 默认值：``
- 描述：Specifies the URL to AUTOMATIC1111's Stable Diffusion API (e.g.,
http://127.0.0.1:7860). - 持久化：这是一个
ConfigVar变量。
AUTOMATIC1111_API_AUTH
- 类型：
str - 默认值：``
- 描述：Sets the AUTOMATIC1111 API authentication credentials if required.
- 持久化：这是一个
ConfigVar变量。
AUTOMATIC1111_PARAMS
- 类型：
str(JSON) - 默认值：
{} - 描述：Additional parameters in JSON format to pass to AUTOMATIC1111 API requests (e.g.,
{"cfg_scale": 7, "sampler_name": "Euler a", "scheduler": "normal"}). - 持久化：这是一个
ConfigVar变量。
OAuth
信息
You can only configure one OAUTH provider at a time. You cannot have two or more OAUTH providers configured simultaneously.
ENABLE_OAUTH_SIGNUP
- 类型：
bool - 默认值：
False - 描述：Enables account creation when signing up via OAuth. Distinct from
ENABLE_SIGNUP. - 持久化：这是一个
ConfigVar变量。
危险
ENABLE_LOGIN_FORM must be set to False when ENABLE_OAUTH_SIGNUP is set to True. Failure to do so will result in the inability to login.
OAUTH_AUTO_REDIRECT
- 类型：
bool - 默认值：
False - 描述：启用后，访问登录页面的已注销用户会被自动重定向到已配置的 OAuth 提供方，而不再看到本地登录表单。仅当只启用了一个 OAuth 提供方，且希望登录流尽量单步直达时使用——它依赖
ENABLE_OAUTH_SIGNUP=True、且ENABLE_LOGIN_FORM=False才能避免与本地登录冲突。多个 OAuth 提供方并存时此项被忽略（用户需要先选择要使用哪一个）。该变量只在启动时读取一次——它不是ConfigVar，无法在管理面板中修改。
ENABLE_OAUTH_PERSISTENT_CONFIG
- 类型：
bool - 默认值：
True - 描述：Controls whether OAuth-related settings are persisted in the database after the first launch.
信息
By default, OAuth configurations are stored in the database and managed via the Admin Panel after the initial setup. Set this variable to False to force Open WebUI to always read OAuth settings from the environment variables on every restart. This is ideal for environments using GitOps or immutable infrastructure where configuration is managed exclusively through external files (e.g., Docker Compose, Kubernetes ConfigMaps).
OAUTH_SUB_CLAIM
- 类型：
str - 默认值：
None - 描述：Overrides the default claim used to identify a user's unique ID (
sub) from the OAuth/OIDC provider's user info response. By default, Open WebUI attempts to infer this from the provider's configuration. This variable allows you to explicitly specify which claim to use. For example, if your identity provider uses 'employee_id' as the unique identifier, you would set this variable to 'employee_id'. - 持久化：这是一个
ConfigVar变量。
OAUTH_MERGE_ACCOUNTS_BY_EMAIL
- 类型：
bool - 默认值：
False - 描述：If enabled, merges OAuth accounts with existing accounts using the same email address. This is considered unsafe as not all OAuth providers will verify email addresses and can lead to potential account takeovers.
- 持久化：这是一个
ConfigVar变量。
ENABLE_OAUTH_WITHOUT_EMAIL
- 类型：
bool - 默认值：
False - 描述：Enables authentication with OpenID Connect (OIDC) providers that do not support or expose an email scope. When enabled, Open WebUI will create and manage user accounts without requiring an email address from the OAuth provider.
- 持久化：这是一个
ConfigVar变量。
注意
Use with Caution
Enabling this option bypasses email-based user identification, which is the standard method for uniquely identifying users across authentication systems. When enabled:
- User accounts will be created using the
subclaim (or the claim specified inOAUTH_SUB_CLAIM) as the primary identifier - Email-based features such as password recovery, email notifications, and account merging via
OAUTH_MERGE_ACCOUNTS_BY_EMAILwill not function properly - Ensure your OIDC provider's
subclaim is stable and unique to prevent authentication conflicts
Only enable this if your identity provider does not support email scope and you have alternative user identification mechanisms in place.
This setting is designed for enterprise environments using identity providers that:
- Use employee IDs, usernames, or other non-email identifiers as the primary user claim
- Have privacy policies that prevent sharing email addresses via OAuth
- Operate in air-gapped or highly restricted networks where email-based services are unavailable
For most standard OAuth providers (Google, Microsoft, GitHub, etc.), this setting should remain False.
OAUTH_UPDATE_PICTURE_ON_LOGIN
- 类型：
bool - 默认值：
False - 描述：If enabled, updates the local user profile picture with the OAuth-provided picture on login.
- 持久化：这是一个
ConfigVar变量。
信息
If the OAuth picture claim is disabled by setting OAUTH_PICTURE_CLAIM to '' (empty string), then setting this variable to true will not update the user profile pictures.
ENABLE_OAUTH_ID_TOKEN_COOKIE
- 类型：
bool - 默认值：
True - 描述：Controls whether the legacy
oauth_id_tokencookie (unsafe, not recommended, token can go stale/orphaned) is set in the browser upon a successful OAuth login. This is provided for backward compatibility with custom tools or older versions that might rely on scraping this cookie. The new, recommended approach is to use the server-side session management. - Usage: For new and secure deployments, it is recommended to set this to
Falseto minimize the information exposed to the client-side. Keep it asTrueonly if you have integrations that depend on the old cookie-based method.
ENABLE_OAUTH_TOKEN_EXCHANGE
- 类型：
bool - 默认值：
False - 描述：Enables the OAuth token exchange endpoint, allowing external applications to exchange an OAuth provider's access token for an Open WebUI JWT session token. This enables programmatic authentication for external tools and services that already have OAuth tokens from your identity provider.
- Usage: Set to
trueto enable the token exchange endpoint at/api/v1/oauth/{provider}/token/exchange. When enabled, external applications can POST to this endpoint with an OAuth access token to obtain an Open WebUI session token.
注意
Security Note: This feature should only be enabled when you have external applications that need to authenticate with Open WebUI using OAuth tokens from your identity provider. Ensure proper access controls are in place for any external applications using this endpoint.
Request Example:
curl -X POST "http://localhost:8080/api/v1/oauth/google/token/exchange" \
-H "Content-Type: application/json" \
-d '{"token": "ya29.a0AfH6SMB..."}'Response:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_at": 1735682400,
"id": 1,
"email": "user@example.com",
"name": "John Doe",
"role": "user",
"profile_image_url": "https://...",
"permissions": {...}
}Requirements:
- The user must already exist in Open WebUI (they must have signed in via the web interface at least once)
- The OAuth provider must be properly configured
- The token exchange uses the same user lookup logic as regular OAuth login (by OAuth
subclaim first, then by email ifOAUTH_MERGE_ACCOUNTS_BY_EMAILis enabled)
ENABLE_OAUTH_BACKCHANNEL_LOGOUT
- 类型：
bool - 默认值：
False - 描述：Enables OpenID Connect Back-Channel Logout support. When enabled, Open WebUI exposes
POST /oauth/backchannel-logoutso your identity provider can trigger server-side logout without browser redirects. - Usage: Set to
trueto enable the endpoint. Your identity provider should send a form-encodedlogout_tokenthat follows the OpenID Connect Back-Channel Logout 1.0 specification.
注意
Redis Requirement for JWT Revocation
Back-channel logout revokes existing Open WebUI JWT sessions through Redis-based revocation keys. Without Redis, Open WebUI can still remove stored OAuth sessions, but already-issued JWTs remain valid until they naturally expire.
For production SSO deployments, especially with multiple workers or replicas, configure REDIS_URL when enabling this feature.
信息
Behavior Notes
- The endpoint returns
200with an empty body for valid requests, including cases where no matching user is found. - Invalid or malformed
logout_tokenrequests return400withinvalid_requestdetails. - Back-channel logout revokes users by provider +
subclaim matching.sid-only logout matching is not currently supported.
OAUTH_CLIENT_INFO_ENCRYPTION_KEY
- 类型：
str - 默认值：Falls back to the value of
WEBUI_SECRET_KEY. - 描述：Specifies the secret key used to encrypt and decrypt OAuth client tokens stored server-side in the database. This is a critical security component for OAuth client tokens. If not set, it defaults to using the main
WEBUI_SECRET_KEY, but it is highly recommended to set it to a unique, securely generated value for production environments.OAUTH_CLIENT_INFO_ENCRYPTION_KEYis used in conjunction with OAuth 2.1 MCP server authentication.
OAUTH_SESSION_TOKEN_ENCRYPTION_KEY
- 类型：
str - 默认值：Falls back to the value of
WEBUI_SECRET_KEY. - 描述：Specifies the secret key used to encrypt and decrypt OAuth tokens stored server-side in the database. This is a critical security component for protecting user credentials at rest. If not set, it defaults to using the main
WEBUI_SECRET_KEY, but it is highly recommended to set it to a unique, securely generated value for production environments.
注意
Required for Multi-Replica Deployments In any production environment running more than one instance of Open WebUI (e.g., Docker Swarm, Kubernetes), this variable MUST be explicitly set to a persistent, shared secret. If left unset, each replica will generate or use a different key, causing session decryption to fail intermittently as user requests are load-balanced across instances.
OAUTH_MAX_SESSIONS_PER_USER
- 类型：
int - 默认值：
10 - 描述：Maximum number of concurrent OAuth sessions allowed per user per provider. When a user logs in and the number of existing sessions for that user/provider combination meets or exceeds this limit, the oldest sessions are pruned to make room for the new one. This prevents unbounded session growth while allowing multi-device usage (e.g., logging in from a desktop and a mobile device without invalidating either session).
OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE
- 类型：
bool - 默认值：
False - 描述：Ensures the full OAuth scope is included during refresh token requests instead of relying on provider defaults. When enabled, the configured scope (e.g.
MICROSOFT_OAUTH_SCOPE) is passed to the identity provider during token refresh. This is required for providers like Microsoft where missing scopes can cause refresh failures, especially when using custom API scopes.
WEBUI_AUTH_TRUSTED_EMAIL_HEADER
- 类型：
str - 描述：Defines the trusted request header for authentication. See SSO docs.
WEBUI_AUTH_TRUSTED_NAME_HEADER
- 类型：
str - 描述：Defines the trusted request header for the username of anyone registering with the
WEBUI_AUTH_TRUSTED_EMAIL_HEADERheader. See SSO docs.
WEBUI_AUTH_TRUSTED_GROUPS_HEADER
- 类型：
str - 描述：Defines the trusted request header containing a comma-separated list of group memberships for the user when using trusted header authentication. See SSO docs.
WEBUI_AUTH_TRUSTED_ROLE_HEADER
- 类型：
str - 描述：Defines the trusted request header that determines the user's role (
admin,user, orpending) when using trusted header authentication. When set, the user's role is updated to match the header value on every sign-in. Invalid values are ignored with a warning. See SSO docs.
Google
See https://support.google.com/cloud/answer/6158849?hl=en
信息
You must also set OPENID_PROVIDER_URL or otherwise logout may not work.
GOOGLE_CLIENT_ID
- 类型：
str - 描述：Sets the client ID for Google OAuth.
- 持久化：这是一个
ConfigVar变量。
GOOGLE_CLIENT_SECRET
- 类型：
str - 描述：Sets the client secret for Google OAuth.
- 持久化：这是一个
ConfigVar变量。
GOOGLE_OAUTH_SCOPE
- 类型：
str - 默认值：
openid email profile - 描述：Sets the scope for Google OAuth authentication.
- 持久化：这是一个
ConfigVar变量。
GOOGLE_REDIRECT_URI
- 类型：
str - 默认值：
<backend>/oauth/google/callback - 描述：Sets the redirect URI for Google OAuth.
- 持久化：这是一个
ConfigVar变量。
GOOGLE_OAUTH_AUTHORIZE_PARAMS
- 类型：
str(JSON object) - 默认值：
{} - 描述：Adds Google-specific parameters to the OAuth
/authorizerequest. Useful for Google flows that require extra parameters such asprompt,login_hint, orhd.
# Example (.env)
GOOGLE_OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com","hd":"example.com"}注意
GOOGLE_OAUTH_AUTHORIZE_PARAMS must be valid JSON and must be a JSON object. If parsing fails, Open WebUI ignores it and logs a warning.
Microsoft
See https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app
信息
You must also set OPENID_PROVIDER_URL or otherwise logout may not work.
MICROSOFT_CLIENT_ID
- 类型：
str - 描述：Sets the client ID for Microsoft OAuth.
- 持久化：这是一个
ConfigVar变量。
MICROSOFT_CLIENT_SECRET
- 类型：
str - 描述：Sets the client secret for Microsoft OAuth.
- 持久化：这是一个
ConfigVar变量。
MICROSOFT_CLIENT_TENANT_ID
- 类型：
str - 描述：Sets the tenant ID for Microsoft OAuth.
- 持久化：这是一个
ConfigVar变量。
MICROSOFT_OAUTH_SCOPE
- 类型：
str - 默认值：
openid email profile - 描述：Sets the scope for Microsoft OAuth authentication. This scope is also included in refresh token requests when
OAUTH_REFRESH_TOKEN_INCLUDE_SCOPEis enabled, which is required by Azure AD to avoidAADSTS90009errors. If you use custom API scopes, include them here (e.g.,openid email profile offline_access api://<Application ID URI>/<custom_scope>). - 持久化：这是一个
ConfigVar变量。
MICROSOFT_REDIRECT_URI
- 类型：
str - 默认值：
<backend>/oauth/microsoft/callback - 描述：Sets the redirect URI for Microsoft OAuth.
- 持久化：这是一个
ConfigVar变量。
MICROSOFT_CLIENT_LOGIN_BASE_URL
- 类型：
str - 默认值：
https://login.microsoftonline.com - 描述：Sets the base login URL for Microsoft OAuth authentication. Allows configuration of alternative login endpoints for government clouds or custom deployments.
- 持久化：这是一个
ConfigVar变量。
MICROSOFT_CLIENT_PICTURE_URL
- 类型：
str - 默认值：
https://graph.microsoft.com/v1.0/me/photo/$value - 描述：Specifies the Microsoft Graph API endpoint for retrieving user profile pictures during OAuth authentication.
- 持久化：这是一个
ConfigVar变量。
GitHub
See https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps
信息
You must also set OPENID_PROVIDER_URL or otherwise logout may not work.
GITHUB_CLIENT_ID
- 类型：
str - 描述：Sets the client ID for GitHub OAuth.
- 持久化：这是一个
ConfigVar变量。
GITHUB_CLIENT_SECRET
- 类型：
str - 描述：Sets the client secret for GitHub OAuth.
- 持久化：这是一个
ConfigVar变量。
GITHUB_CLIENT_SCOPE
- 类型：
str - 默认值：
user:email - 描述：Specifies the scope for GitHub OAuth authentication.
- 持久化：这是一个
ConfigVar变量。
GITHUB_CLIENT_REDIRECT_URI
- 类型：
str - 默认值：
<backend>/oauth/github/callback - 描述：Sets the redirect URI for GitHub OAuth.
- 持久化：这是一个
ConfigVar变量。
Feishu
See https://open.feishu.cn/document/sso/web-application-sso/login-overview
FEISHU_CLIENT_ID
- 类型：
str - 描述：Sets the client ID for Feishu OAuth.
- 持久化：这是一个
ConfigVar变量。
FEISHU_CLIENT_SECRET
- 类型：
str - 描述：Sets the client secret for Feishu OAuth.
- 持久化：这是一个
ConfigVar变量。
FEISHU_OAUTH_SCOPE
- 类型：
str - 默认值：
contact:user.base:readonly - 描述：Specifies the scope for Feishu OAuth authentication.
- 持久化：这是一个
ConfigVar变量。
FEISHU_REDIRECT_URI
- 类型：
str - 描述：Sets the redirect URI for Feishu OAuth.
- 持久化：这是一个
ConfigVar变量。
OpenID (OIDC)
OAUTH_CLIENT_ID
- 类型：
str - 描述：Sets the client ID for OIDC.
- 持久化：这是一个
ConfigVar变量。
OAUTH_CLIENT_SECRET
- 类型：
str - 描述：Sets the client secret for OIDC.
- 持久化：这是一个
ConfigVar变量。
OPENID_PROVIDER_URL
- 类型：
str - 描述：Path to the
.well-known/openid-configurationendpoint - 持久化：这是一个
ConfigVar变量。
危险
The environment variable OPENID_PROVIDER_URL MUST be configured, otherwise the logout functionality will not work for most providers.
Even when using Microsoft, GitHub or other providers, you MUST set the OPENID_PROVIDER_URL environment variable.
Alternatively, if your provider does not support standard OIDC discovery (e.g., AWS Cognito), you can set OPENID_END_SESSION_ENDPOINT to a custom logout URL instead.
OPENID_END_SESSION_ENDPOINT
- 类型：
str - 默认值：Empty string (
"") - 描述：Sets a custom end-session (logout) endpoint URL. When configured, Open WebUI will redirect to this URL on logout instead of attempting OIDC discovery via
OPENID_PROVIDER_URL. This is useful for OAuth providers that do not support standard OIDC discovery for logout, such as AWS Cognito. - 持久化：这是一个
ConfigVar变量。
OPENID_REDIRECT_URI
- 类型：
str - 默认值：
<backend>/oauth/oidc/callback - 描述：Sets the redirect URI for OIDC
- 持久化：这是一个
ConfigVar变量。
OAUTH_SCOPES
- 类型：
str - 默认值：
openid email profile - 描述：Sets the scope for OIDC authentication.
openidandemailare required. - 持久化：这是一个
ConfigVar变量。
OAUTH_CODE_CHALLENGE_METHOD
- 类型：
str - Options:
S256- Hashcode_verifierwith SHA-256.
- 默认值：Empty string (' '), since
Noneis set as default. - 描述：Specifies the code challenge method for OAuth authentication. Set to
S256when PKCE is required by the provider. - 持久化：这是一个
ConfigVar变量。
OAUTH_PROVIDER_NAME
- 类型：
str - 默认值：
SSO - 描述：Sets the name for the OIDC provider.
- 持久化：这是一个
ConfigVar变量。
OAUTH_USERNAME_CLAIM
- 类型：
str - 默认值：
name - 描述：Set username claim for OpenID.
- 持久化：这是一个
ConfigVar变量。
OAUTH_EMAIL_CLAIM
- 类型：
str - 默认值：
email - 描述：Set email claim for OpenID.
- 持久化：这是一个
ConfigVar变量。
OAUTH_PICTURE_CLAIM
- 类型：
str - 默认值：
picture - 描述：Set picture (avatar) claim for OpenID.
- 持久化：这是一个
ConfigVar变量。
信息
If OAUTH_PICTURE_CLAIM is set to '' (empty string), then the OAuth picture claim is disabled and the user profile pictures will not be saved.
OAUTH_GROUP_CLAIM
- 类型：
str - 默认值：
groups - 描述：Specifies the group claim for OAuth authentication.
- 持久化：这是一个
ConfigVar变量。
ENABLE_OAUTH_ROLE_MANAGEMENT
- 类型：
bool - 默认值：
False - 描述：Enables role management for OAuth delegation.
- 持久化：这是一个
ConfigVar变量。
ENABLE_OAUTH_GROUP_MANAGEMENT
- 类型：
bool - 默认值：
False - 描述：Enables or disables OAuth group management.
- 持久化：这是一个
ConfigVar变量。
ENABLE_OAUTH_GROUP_CREATION
- 类型：
bool - 默认值：
False - 描述：When enabled, groups from OAuth claims that don't exist in Open WebUI will be automatically created.
- 持久化：这是一个
ConfigVar变量。
OAUTH_GROUP_DEFAULT_SHARE
- 类型：
str - 默认值：
true - Options:
true— Groups created via OAuth will have sharing enabled for anyone.members— Groups created via OAuth will only allow sharing with group members.false— Groups created via OAuth will have sharing disabled (no one can share).
- 描述：Controls the default sharing permission for groups that are automatically created via OAuth group management. Only applies when
ENABLE_OAUTH_GROUP_CREATIONis enabled. Existing groups are not affected by this setting. - 持久化：这是一个
ConfigVar变量。
OAUTH_BLOCKED_GROUPS
- 类型：
str - 默认值：
[] - 描述：JSON array of group names that are blocked from accessing the application. Users belonging to these groups will be denied access even if they have valid OAuth credentials.
- 持久化：这是一个
ConfigVar变量。
OAUTH_ROLES_CLAIM
- 类型：
str - 默认值：
roles - 描述：Sets the roles claim to look for in the OIDC token.
- 持久化：这是一个
ConfigVar变量。
OAUTH_ALLOWED_ROLES
- 类型：
str - 默认值：
user,admin - 描述：Sets the roles that are allowed access to the platform.
- 持久化：这是一个
ConfigVar变量。
OAUTH_ADMIN_ROLES
- 类型：
str - 默认值：
admin - 描述：Sets the roles that are considered administrators.
- 持久化：这是一个
ConfigVar变量。
OAUTH_ROLES_SEPARATOR
- 类型：
str - 默认值：
, - 描述：Allows custom role separators for for splitting the
OAUTH_*_ROLESvariables. Meant for OAuth roles that contain commas; useful for roles specified in LDAP syntax or other systems where commas are part of role names. If the claim is a string and contains the separator, it will be also split by that separator.
OAUTH_GROUPS_SEPARATOR
- 类型：
str - 默认值：
; - 描述：Specifies the delimiter used to parse multiple group names from the OAuth group claim. This separator is used when the identity provider returns group memberships as a delimited string rather than an array. Useful when integrating with systems that use non-standard separators or when group names themselves contain commas.
OAUTH_ALLOWED_DOMAINS
- 类型：
str - 默认值：
* - 描述：Specifies the allowed domains for OAuth authentication. (e.g., "example1.com,example2.com").
- 持久化：这是一个
ConfigVar变量。
OAUTH_AUDIENCE
- 类型：
str - 默认值：Empty string (' ')
- 描述：Specifies an audience parameter passed to the OAuth provider's authorization endpoint during login. Some providers (such as Auth0 and Ory) use this value to determine the type of access token returned—without it, providers typically return an opaque token, while with it, they return a JWT that can be decoded and validated. This parameter is not part of the official OAuth/OIDC spec for authorization endpoints but is widely supported by some providers.
信息
This is useful when you need a JWT access token for downstream validation or when your OAuth provider requires an audience hint for proper token generation. For Auth0, this is typically your API identifier (e.g., https://your-api.auth0.com/api/v2/). For Ory, specify the resource server you want to access.
OAUTH_AUTHORIZE_PARAMS
- 类型：
str(JSON object) - 默认值：
{} - 描述：Passes extra parameters directly to the OAuth provider's authorization endpoint during login. Use this when your provider requires custom authorize-time parameters that are not covered by dedicated variables.
Common examples include parameters like prompt, login_hint, domain_hint, resource, audience, or provider-specific flags.
# 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 must be valid JSON and must be a JSON object (key/value map). If parsing fails, Open WebUI ignores it and logs a warning.
信息
If you set both OAUTH_AUDIENCE and OAUTH_AUTHORIZE_PARAMS containing an audience key, the value from OAUTH_AUTHORIZE_PARAMS takes precedence.
OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE
- 类型：
bool - 默认值：
False - 描述：When enabled, includes the configured OAuth scope in refresh token requests. Some OAuth providers, notably Microsoft Azure AD, require the scope to be explicitly provided when refreshing a token. Without it, Azure AD treats the request as the application requesting a token for itself, resulting in
AADSTS90009errors. Enable this if you encounter token refresh failures with your OAuth provider. - 持久化：这是一个
ConfigVar变量。
信息
This setting is compliant with RFC 6749 Section 6, where the scope parameter is optional during refresh token requests. Only enable this for providers that require it, such as certain Azure AD configurations.
LDAP
ENABLE_LDAP
- 类型：
bool - 默认值：
False - 描述：Enables or disables LDAP authentication.
- 持久化：这是一个
ConfigVar变量。
LDAP_SERVER_LABEL
- 类型：
str - 描述：Sets the label of the LDAP server.
- 持久化：这是一个
ConfigVar变量。
LDAP_SERVER_HOST
- 类型：
str - 默认值：
localhost - 描述：Sets the hostname of the LDAP server.
- 持久化：这是一个
ConfigVar变量。
LDAP_SERVER_PORT
- 类型：
int - 默认值：
389 - 描述：Sets the port number of the LDAP server.
- 持久化：这是一个
ConfigVar变量。
LDAP_ATTRIBUTE_FOR_MAIL
- 类型：
str - 描述：Sets the attribute to use as mail for LDAP authentication.
- 持久化：这是一个
ConfigVar变量。
LDAP_ATTRIBUTE_FOR_USERNAME
- 类型：
str - 描述：Sets the attribute to use as a username for LDAP authentication.
- 持久化：这是一个
ConfigVar变量。
LDAP_APP_DN
- 类型：
str - 描述：Sets the distinguished name for the LDAP application.
- 持久化：这是一个
ConfigVar变量。
LDAP_APP_PASSWORD
- 类型：
str - 描述：Sets the password for the LDAP application.
- 持久化：这是一个
ConfigVar变量。
LDAP_SEARCH_BASE
- 类型：
str - 描述：Sets the base to search for LDAP authentication.
- 持久化：这是一个
ConfigVar变量。
LDAP_SEARCH_FILTER
- 类型：
str - 默认值：
None - 描述：Sets additional filter conditions for LDAP user search. This filter is appended to the automatically-generated username filter. Open WebUI automatically constructs the username portion of the filter using
LDAP_ATTRIBUTE_FOR_USERNAME, so you should not include user placeholders like%(user)sor%s— these are not supported. Use this for additional conditions such as group membership restrictions (e.g.,(memberOf=cn=allowed-users,ou=groups,dc=example,dc=com)). Alternative toLDAP_SEARCH_FILTERS. - 持久化：这是一个
ConfigVar变量。
LDAP_SEARCH_FILTERS
- 类型：
str - 描述：Sets additional filter conditions for LDAP user search. This is an alias for
LDAP_SEARCH_FILTER. The filter is appended to the automatically-generated username filter — do not include user placeholders like%(user)sor%s. - 持久化：这是一个
ConfigVar变量。
LDAP_USE_TLS
- 类型：
bool - 默认值：
True - 描述：Enables or disables TLS for LDAP connection.
- 持久化：这是一个
ConfigVar变量。
LDAP_CA_CERT_FILE
- 类型：
str - 描述：Sets the path to the LDAP CA certificate file.
- 持久化：这是一个
ConfigVar变量。
LDAP_VALIDATE_CERT
- 类型：
bool - 描述：Sets whether to validate the LDAP CA certificate.
- 持久化：这是一个
ConfigVar变量。
LDAP_CIPHERS
- 类型：
str - 默认值：
ALL - 描述：Sets the ciphers to use for LDAP connection.
- 持久化：这是一个
ConfigVar变量。
ENABLE_LDAP_GROUP_MANAGEMENT
- 类型：
bool - 默认值：
False - 描述：Enables the group management feature.
- 持久化：这是一个
ConfigVar变量。
ENABLE_LDAP_GROUP_CREATION
- 类型：
bool - 默认值：
False - 描述：If a group from LDAP does not exist in Open WebUI, it will be created automatically.
- 持久化：这是一个
ConfigVar变量。
LDAP_ATTRIBUTE_FOR_GROUPS
- 类型：
str - 默认值：
memberOf - 描述：Specifies the LDAP attribute that contains the user's group memberships.
memberOfis a standard attribute for this purpose in Active Directory environments. - 持久化：这是一个
ConfigVar变量。
SCIM
SCIM_ENABLED
- 类型：
bool - 默认值：
False - 描述：Enables or disables SCIM 2.0 (System for Cross-domain Identity Management) support for automated user and group provisioning from identity providers like Okta, Azure AD, and Google Workspace.
- 持久化：这是一个
ConfigVar变量。
SCIM_TOKEN
- 类型：
str - 默认值：
"" - 描述：Sets the bearer token for SCIM authentication. This token must be provided by identity providers when making SCIM API requests. Generate a secure random token (e.g., using
openssl rand -base64 32) and configure it in both Open WebUI and your identity provider. - 持久化：这是一个
ConfigVar变量 。
SCIM_AUTH_PROVIDER
- 类型：
str - 默认值：
"" - 描述：Specifies the OAuth provider name to associate with SCIM
externalIdvalues (e.g.,microsoft,oidc). When set, SCIM operations store and look upexternalIdunder this provider key in the user'sscimJSON field, enabling account linking between SCIM-provisioned identities and OAuth logins. A warning is logged on startup if SCIM is enabled but this variable is not set.
User Permissions
Chat Permissions
USER_PERMISSIONS_CHAT_CONTROLS
- 类型：
bool - 默认值：
True - 描述：Acts as a master switch to enable or disable the main "Controls" button and panel in the chat interface. If this is set to False, users will not see the Controls button, and the granular permissions below will have no effect.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_VALVES
- 类型：
bool - 默认值：
True - 描述：When
USER_PERMISSIONS_CHAT_CONTROLSis enabled, this setting specifically controls the visibility of the "Valves" section within the chat controls panel.
USER_PERMISSIONS_CHAT_SYSTEM_PROMPT
- 类型：
bool - 默认值：
True - 描述：When
USER_PERMISSIONS_CHAT_CONTROLSis enabled, this setting specifically controls the visibility of the customizable "System Prompt" section within the chat controls panel, folders and the user settings.
USER_PERMISSIONS_CHAT_PARAMS
- 类型：
bool - 默认值：
True - 描述：When
USER_PERMISSIONS_CHAT_CONTROLSis enabled, this setting specifically controls the visibility of the "Advanced Parameters" section within the chat controls panel.
USER_PERMISSIONS_CHAT_FILE_UPLOAD
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to upload files to chats.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_WEB_UPLOAD
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to attach web pages (URLs) in chats via the "Attach Webpage" option. When set to
False, the "Attach Webpage" button is hidden for non-admin users. Also configurable per-group in Admin Panel → Users → Groups → Permissions → Chat Permissions → Allow Web Upload.
USER_PERMISSIONS_CHAT_DELETE
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to delete chats.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_EDIT
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to edit chats.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_DELETE_MESSAGE
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to delete individual messages within chats. This provides granular control over message deletion capabilities separate from full chat deletion.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_CONTINUE_RESPONSE
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to continue AI responses. When disabled, users cannot use the "Continue Response" button, which helps prevent potential system prompt leakage through response continuation manipulation.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_REGENERATE_RESPONSE
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to regenerate AI responses. Controls access to both the standard regenerate button and the guided regeneration menu.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_RATE_RESPONSE
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to rate AI responses using the thumbs up/down feedback system. This controls access to the response rating functionality for evaluation and feedback collection.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_STT
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to use Speech-to-Text in chats.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_TTS
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to use Text-to-Speech in chats.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_CALL
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to make calls in chats.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_MULTIPLE_MODELS
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to use multiple models in chats.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_TEMPORARY
- 类型：
bool - 默认值：
True - 描述：Enables or disables user permission to create temporary chats. Note: Temporary chats disable backend document parsing for privacy.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_TEMPORARY_ENFORCED
- 类型：
str - 默认值：
False - 描述：Enables or disables enforced temporary chats for users.
- 持久化：这是一个
ConfigVar变量。
Feature Permissions
USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS
- 类型：
str - 默认值：
False - 描述：Enables or disables user permission to access direct tool servers.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_FEATURES_WEB_SEARCH
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to use the web search feature.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_FEATURES_IMAGE_GENERATION
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to use the image generation feature.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_FEATURES_CODE_INTERPRETER
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to use code interpreter feature.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_FEATURES_MEMORIES
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to use the memory feature.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_FEATURES_AUTOMATIONS
- 类型：
str - 默认值：
False - 描述：Enables or disables Automations access for non-admin users. When enabled, users can access
/automationsand manage their own scheduled automations. - 持久化：这是一个
ConfigVar变量。
信息
This setting maps to Features > Automations in RBAC permissions.
- Non-admin users need this permission to access and use Automations.
- Admin users are exempt from this specific permission check.
See Permissions for role/permission behavior.
USER_PERMISSIONS_FEATURES_CALENDAR
- 类型：
str - 默认值：
True - 描述：Enables or disables Calendar access for non-admin users. When enabled, users can access the Calendar feature to create calendars, manage events, and view shared calendars.
- 持久化：这是一个
ConfigVar变量。
信息
This setting maps to Features > Calendar in RBAC permissions.
- Non-admin users need this permission to access and use Calendar.
- Admin users are exempt from this specific permission check.
See Permissions for role/permission behavior.
USER_PERMISSIONS_FEATURES_FOLDERS
- 类型：
str - 默认值：
True - 描述：Enables or disables the visibility of the Folders feature (chat sidebar) to users.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_FEATURES_NOTES
- 类型：
str - 默认值：
True - 描述：Enables or disables the visibility of the Notes feature to users.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_FEATURES_CHANNELS
- 类型：
str - 默认值：
True - 描述：Enables or disables the ability for users to create their own group channels.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_FEATURES_API_KEYS
- 类型：
bool - 默认值：
False - 描述：Sets the permission for API key creation feature for users. When enabled, users will have the ability to create and manage API keys for programmatic access.
- 持久化：这是一个
ConfigVar变量。
信息
For API Key creation (and the API keys themselves):
- This setting controls API key creation permission for non-admin users (directly or via User Groups)
- API keys must also be globally enabled using
ENABLE_API_KEYS
Note: 当 ENABLE_API_KEYS 启用时，管理员即使没有 features.api_keys 权限也可以生成 API key。详细设置说明请参见监控指南。
Workspace Permissions
USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS
- 类型：
bool - 默认值 ：
False - 描述：Enables or disables user permission to access workspace models.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS
- 类型：
bool - 默认值：
False - 描述：Enables or disables user permission to access workspace knowledge.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS
- 类型：
bool - 默认值：
False - 描述：Enables or disables user permission to access workspace prompts.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS
- 类型：
bool - 默认值：
False - 描述：Enables or disables user permission to access workspace tools.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_SKILLS_ACCESS
- 类型：
bool - 默认值：
False - 描述：Enables or disables user permission to access workspace skills.
- 持久化：这是一个
ConfigVar变量。
Sharing (Private)
These settings control whether users can share workspace items with other users privately (non-public sharing).
USER_PERMISSIONS_WORKSPACE_MODELS_ALLOW_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables private sharing of workspace models.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ALLOW_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables private sharing of workspace knowledge.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_PROMPTS_ALLOW_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables private sharing of workspace prompts.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_TOOLS_ALLOW_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables private sharing of workspace tools.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_SKILLS_ALLOW_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables private sharing of workspace skills.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_NOTES_ALLOW_SHARING
- 类型：
str - 默认值：
True - 描述：Enables or disables private sharing of notes.
- 持久化：这是一个
ConfigVar变量。
Sharing (Public)
These settings control whether users can share workspace items publicly.
USER_PERMISSIONS_WORKSPACE_MODELS_ALLOW_PUBLIC_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables public sharing of workspace models.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ALLOW_PUBLIC_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables public sharing of workspace knowledge.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_PROMPTS_ALLOW_PUBLIC_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables public sharing of workspace prompts.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_TOOLS_ALLOW_PUBLIC_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables public sharing of workspace tools.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_SKILLS_ALLOW_PUBLIC_SHARING
- 类型：
str - 默认值：
False - 描述：Enables or disables public sharing of workspace skills.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_NOTES_ALLOW_PUBLIC_SHARING
- 类型：
str - 默认值：
True - 描述：Enables or disables public sharing of notes.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CHAT_ALLOW_PUBLIC_SHARING
- 类型：
bool - 默认值：
False - 描述：启用或禁用聊天对话的公开分享。禁用后，非管理员用户在聊天分享弹窗中的访问控制选择器里看不到 "Public" 选项——他们仍可以创建限定特定用户或用户组的分享链接，但无法让聊天对所有人都可访问。管理员始终保留公开分享的权限。需要用户启用
USER_PERMISSIONS_CHAT_SHARE（Share Chat）权限。可在 管理面板 → 用户 → 用户组 → 权限 → Chats Public Sharing 中按组配置。 - 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_CALENDAR_ALLOW_PUBLIC_SHARING
- 类型：
bool - 默认值：
False - 描述：启用或禁用日历的公开分享。禁用后，非管理员所有者在创建或更新日历时无法附加通配的
read或write访问授权——公共主体会被静默从访问授权列表中过滤掉，因此日历无法在未经管理员授权的前提下被所有具备 Calendar 功能的用户读取或写入。按用户和按组的授权不受影响。管理员始终保留公开分享的权限。可在 管理面板 → 用户 → 用户组 → 权限 → Calendars Public Sharing 中按组配置。 - 持久化：这是一个
ConfigVar变量。
Access Grants
USER_PERMISSIONS_ACCESS_GRANTS_ALLOW_USERS
- 类型：
bool - 默认值：
True - 描述：Controls whether non-admin users can share resources (knowledge bases, models, prompts, notes, skills, and tools) with specific individual users. When set to
False, individual user grants are silently stripped from access grant lists — group sharing and public sharing remain unaffected. Admins always retain the ability to share with individual users regardless of this setting. Also configurable per-group in Admin Panel → Users → Groups → Permissions → Access Grants → Allow Sharing With Users.
Import / Export
USER_PERMISSIONS_WORKSPACE_MODELS_IMPORT
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to import workspace models.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_MODELS_EXPORT
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to export workspace models.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_PROMPTS_IMPORT
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to import workspace prompts.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_PROMPTS_EXPORT
- 类型：
str - 默认值：
True - 描述：Enables or disables user permission to export workspace prompts.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_TOOLS_IMPORT
- 类型：
str - 默认值：
False - 描述：Enables or disables user permission to import workspace tools.
- 持久化：这是一个
ConfigVar变量。
USER_PERMISSIONS_WORKSPACE_TOOLS_EXPORT
- 类型：
str - 默认值：
False - 描述：Enables or disables user permission to export workspace tools.
- 持久化：这是一个
ConfigVar变量。
Settings Permissions
USER_PERMISSIONS_SETTINGS_INTERFACE
- 类型：
bool - 默认值：
True - 描述：Enables or disables user / group permissions for the interface settings section in the Settings Modal.
- 持久化：这是一个
ConfigVar变量。
Misc Environment Variables
These variables are not specific to Open WebUI but can still be valuable in certain contexts.
Cloud Storage
STORAGE_PROVIDER
- 类型：
str - Options:
s3- uses the S3 client library and related environment variables mentioned in Amazon S3 Storagegcs- uses the GCS client library and related environment variables mentioned in Google Cloud Storageazure- uses the Azure client library and related environment variables mentioned in Microsoft Azure Storage
- 默认值：empty string (' '), which defaults to
local - 描述：Sets the storage provider.
STORAGE_LOCAL_CACHE
- 类型：
bool - 默认值：
True - 描述：Controls whether a local copy of a file is retained after it has been uploaded to a cloud storage provider (S3, GCS, Azure). When
True(the default), the local cache copy inUPLOAD_DIRis preserved — matching previous behavior. WhenFalse, the local copy is removed automatically once processing completes, so files live only in cloud storage. Has no effect whenSTORAGE_PROVIDER=local.
Amazon S3 Storage
S3_ACCESS_KEY_ID
- 类型：
str - 描述：Sets the access key ID for S3 storage.
S3_ADDRESSING_STYLE
- 类型：
str - 默认值：
None - 描述：Specifies the addressing style to use for S3 storage (e.g., 'path', 'virtual').
S3_BUCKET_NAME
- 类型：
str - 描述：Sets the bucket name for S3 storage.
S3_ENDPOINT_URL
- 类型：
str - 描述：Sets the endpoint URL for S3 storage.
信息
If the endpoint is an S3-compatible provider like MinIO that uses a TLS certificate signed by a private CA, set the environment variable AWS_CA_BUNDLE to the path of your PEM-encoded CA certificates file. See the Amazon SDK Docs for more information.
S3_KEY_PREFIX
- 类型：
str - 描述：Sets the key prefix for a S3 object.
S3_REGION_NAME
- 类型：
str - 描述：Sets the region name for S3 storage.
S3_SECRET_ACCESS_KEY
- 类型：
str - 描述：Sets the secret access key for S3 storage.
S3_USE_ACCELERATE_ENDPOINT
- 类型：
str - 默认值：
False - 描述：Specifies whether to use the accelerated endpoint for S3 storage.
S3_ENABLE_TAGGING
- 类型：
str - 默认值：
False - 描述：Enables S3 object tagging after uploads for better organization, searching, and integration with file management policies. Always set to
Falsewhen using Cloudflare R2, as R2 does not support object tagging.
Google Cloud Storage
GOOGLE_APPLICATION_CREDENTIALS_JSON
- 类型：
str - 描述：Contents of Google Application Credentials JSON file.
- Optional - if not provided, credentials will be taken from the environment. User credentials if run locally and Google Metadata server if run on a Google Compute Engine.
- A file can be generated for a service account following this guide.
GCS_BUCKET_NAME
- 类型：
str - 描述：Sets the bucket name for Google Cloud Storage. Bucket must already exist.
Microsoft Azure Storage
AZURE_STORAGE_ENDPOINT
- 类型：
str - 描述：Sets the endpoint URL for Azure Storage.
AZURE_STORAGE_CONTAINER_NAME
- 类型：
str - 描述：Sets the container name for Azure Storage.
AZURE_STORAGE_KEY
- 类型：
str - 描述：Set the access key for Azure Storage.
- Optional - if not provided, credentials will be taken from the environment. User credentials if run locally and Managed Identity if run in Azure services.
OpenTelemetry Configuration
Additional Dependencies May Be Required
OpenTelemetry support requires additional Python dependencies that may not be included by default depending on your installation method (e.g., standard pip install open-webui versus Docker images).
If you encounter ImportError or missing module errors related to OpenTelemetry, you may need to install them manually:
pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlpENABLE_OTEL
- 类型：
bool - 默认值：
False - 描述：Enables or disables OpenTelemetry for observability. When enabled, tracing, metrics, and logging data can be collected and exported to an OTLP endpoint.
ENABLE_OTEL_TRACES
- 类型：
bool - 默认值：
False - 描述：Enables or disables OpenTelemetry traces collection and export. This variable works in conjunction with
ENABLE_OTEL.
ENABLE_OTEL_METRICS
- 类型：
bool - 默认值：
False - 描述：Enables or disables OpenTelemetry metrics collection and export. This variable works in conjunction with
ENABLE_OTEL.
ENABLE_OTEL_LOGS
- 类型：
bool - 默认值：
False - 描述：Enables or disables OpenTelemetry logging export. When enabled, application logs are sent to the configured OTLP endpoint. This variable works in conjunction with
ENABLE_OTEL.
OTEL_EXPORTER_OTLP_ENDPOINT
- 类型：
str - 默认值：
http://localhost:4317 - 描述：Specifies the default OTLP (OpenTelemetry Protocol) endpoint for exporting traces, metrics, and logs. This can be overridden for metrics if
OTEL_METRICS_EXPORTER_OTLP_ENDPOINTis set, and for logs ifOTEL_LOGS_EXPORTER_OTLP_ENDPOINTis set.
OTEL_METRICS_EXPORTER_OTLP_ENDPOINT
- 类型：
str - 默认值：Value of
OTEL_EXPORTER_OTLP_ENDPOINT - 描述：Specifies the dedicated OTLP endpoint for exporting OpenTelemetry metrics. If not set, it defaults to the value of
OTEL_EXPORTER_OTLP_ENDPOINT. This is useful when separate endpoints for traces and metrics are used.
OTEL_LOGS_EXPORTER_OTLP_ENDPOINT
- 类型：
str - 默认值：Value of
OTEL_EXPORTER_OTLP_ENDPOINT - 描述：Specifies the dedicated OTLP endpoint for exporting OpenTelemetry logs. If not set, it defaults to the value of
OTEL_EXPORTER_OTLP_ENDPOINT. This is useful when separate endpoints for logs, traces, and metrics are used.
OTEL_EXPORTER_OTLP_INSECURE
- 类型：
bool - 默认值：
False - 描述：If set to
True, the OTLP exporter will use an insecure connection (e.g., HTTP for gRPC) for traces. For metrics, its behavior is governed byOTEL_METRICS_EXPORTER_OTLP_INSECURE, and for logs byOTEL_LOGS_EXPORTER_OTLP_INSECURE.
OTEL_METRICS_EXPORTER_OTLP_INSECURE
- 类型：
bool - 默认值：Value of
OTEL_EXPORTER_OTLP_INSECURE - 描述：If set to
True, the OTLP exporter will use an insecure connection for metrics. If not specified, it uses the value ofOTEL_EXPORTER_OTLP_INSECURE.
OTEL_LOGS_EXPORTER_OTLP_INSECURE
- 类型：
bool - 默认值：Value of
OTEL_EXPORTER_OTLP_INSECURE - 描述：If set to
True, the OTLP exporter will use an insecure connection for logs. If not specified, it uses the value ofOTEL_EXPORTER_OTLP_INSECURE.
OTEL_SERVICE_NAME
- 类型：
str - 默认值：
open-webui - 描述：Sets the service name that will be reported to your OpenTelemetry collector or observability platform. This helps identify your Open WebUI instance.
OTEL_RESOURCE_ATTRIBUTES
- 类型：
str - 默认值：Empty string (' ')
- 描述：Allows you to define additional resource attributes to be attached to all telemetry data, in a comma-separated
key1=val1,key2=val2format.
OTEL_TRACES_SAMPLER
- 类型：
str - Options:
parentbased_always_on,always_on,always_off,parentbased_always_off, etc. - 默认值：
parentbased_always_on - 描述：Configures the sampling strategy for OpenTelemetry traces. This determines which traces are collected and exported to reduce data volume.
OTEL_BASIC_AUTH_USERNAME
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the username for basic authentication with the default OTLP endpoint. This applies to traces, and by default, to metrics and logs unless overridden by their specific authentication variables.
OTEL_BASIC_AUTH_PASSWORD
- 类型：
str - 默认值：Empty string (' ')
- 描述：Sets the password for basic authentication with the default OTLP endpoint. This applies to traces, and by default, to metrics and logs unless overridden by their specific authentication variables.
OTEL_METRICS_EXPORT_INTERVAL_MILLIS
- 类型：
int - 默认值：
10000(10 seconds) - 描述：Controls how often OpenTelemetry metrics are exported, in milliseconds. The default of 10 seconds produces approximately 6 data points per minute. Lower this value for higher resolution, or increase it to reduce cost on platforms that charge per data point (e.g. Grafana Cloud recommends staying below 1 DPM — set to
60000for one export per minute).
OTEL_METRICS_BASIC_AUTH_USERNAME
- 类型：
str - 默认值：Value of
OTEL_BASIC_AUTH_USERNAME - 描述：Sets the username for basic authentication specifically for the OTLP metrics endpoint. If not specified, it uses the value of
OTEL_BASIC_AUTH_USERNAME.
OTEL_METRICS_BASIC_AUTH_PASSWORD
- 类型：
str - 默认值：Value of
OTEL_BASIC_AUTH_PASSWORD - 描述：Sets the password for basic authentication specifically for the OTLP metrics endpoint. If not specified, it uses the value of
OTEL_BASIC_AUTH_PASSWORD.
OTEL_LOGS_BASIC_AUTH_USERNAME
- 类型：
str - 默认值：Value of
OTEL_BASIC_AUTH_USERNAME - 描述：Sets the username for basic authentication specifically for the OTLP logs endpoint. If not specified, it uses the value of
OTEL_BASIC_AUTH_USERNAME.
OTEL_LOGS_BASIC_AUTH_PASSWORD
- 类型：
str - 默认值：Value of
OTEL_BASIC_AUTH_PASSWORD - 描述：Sets the password for basic authentication specifically for the OTLP logs endpoint. If not specified, it uses the value of
OTEL_BASIC_AUTH_PASSWORD.
OTEL_OTLP_SPAN_EXPORTER
- 类型：
str - Options:
grpc,http - 默认值：
grpc - 描述：Specifies the default protocol for exporting OpenTelemetry traces (gRPC or HTTP). This can be overridden for metrics if
OTEL_METRICS_OTLP_SPAN_EXPORTERis set, and for logs ifOTEL_LOGS_OTLP_SPAN_EXPORTERis set.
OTEL_METRICS_OTLP_SPAN_EXPORTER
- 类型：
str - Options:
grpc,http - 默认值：Value of
OTEL_OTLP_SPAN_EXPORTER - 描述：Specifies the protocol for exporting OpenTelemetry metrics (gRPC or HTTP). If not specified, it uses the value of
OTEL_OTLP_SPAN_EXPORTER.
OTEL_LOGS_OTLP_SPAN_EXPORTER
- 类型：
str - Options:
grpc,http - 默认值：Value of
OTEL_OTLP_SPAN_EXPORTER - 描述：Specifies the protocol for exporting OpenTelemetry logs (gRPC or HTTP). If not specified, it uses the value of
OTEL_OTLP_SPAN_EXPORTER.
Database Pool
DATABASE_URL
- 类型：
str - 默认值：
sqlite:///${DATA_DIR}/webui.db - 描述：Specifies the complete database connection URL, following SQLAlchemy's URL scheme. This variable takes precedence over individual database connection parameters if explicitly set.
信息
For PostgreSQL support, ensure you installed with pip install open-webui[all] instead of the basic installation.
Supports SQLite, Postgres, and encrypted SQLite via SQLCipher.
Changing the URL does not migrate data between databases.
Documentation on the URL scheme is available here.
If your database password contains special characters, please ensure they are properly URL-encoded. For example, a password like p@ssword should be encoded as p%40ssword.
For configuration using individual parameters or encrypted SQLite, see the relevant sections below.
Single-user / single-replica on local disk? The default is fine.
The default sqlite:///${DATA_DIR}/webui.db is a perfectly good choice for personal use, evaluation, home-lab setups, and small single-replica deployments — as long as DATA_DIR lives on a locally-attached SSD/NVMe. No migration needed. The rest of this callout is for operators running on network storage or scaling out.
SQLite is only supported on locally-attached SSD/NVMe
Running SQLite on NFS, CIFS/SMB, Azure Files, GlusterFS, CephFS, or any Kubernetes PersistentVolumeClaim backed by network storage is not supported — this is SQLite upstream's own position (SQLite FAQ #5), and under the async backend (0.9.0+) it will produce pool-timeout errors (QueuePool limit of size N overflow M reached), multi-minute stalls, WAL deadlocks, and potential database corruption.
For multi-replica, multi-worker, Kubernetes, Docker Swarm, or any deployment where DATA_DIR is on shared/network storage, set DATABASE_URL to a PostgreSQL URL:
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/openwebui
See Performance → Disk I/O Latency for the full mechanism (fsync + async pool saturation) and Scaling → Step 1 for migration guidance.
Multi-replica / multi-worker deployments REQUIRE PostgreSQL
For multi-replica or high-availability deployments (Kubernetes, Docker Swarm), you must use an external database (PostgreSQL) instead of SQLite. SQLite does not support concurrent writes from multiple instances and will result in database corruption or data inconsistency. A shared SQLite file on NFS does not count as "supported" — it will still corrupt or deadlock. See the scaling guide linked above.
ENABLE_DB_MIGRATIONS
- 类型：
bool - 默认值：
True - 描述：Controls whether database migrations are automatically run on startup. In multi-pod or multi-worker deployments, set this to
Falseon all pods except one to designate a "master" pod responsible for migrations, preventing race conditions or schema corruption.
注意
Required for Multi-Replica Setups For multi-replica or high-availability deployments (Kubernetes, Docker Swarm), you MUST use an external database (PostgreSQL) instead of SQLite. SQLite does not support concurrent writes from multiple instances and will result in database corruption or data inconsistency.
DATABASE_TYPE
- 类型：
str - 默认值：
None(automatically set tosqliteifDATABASE_URLuses default SQLite path) - 描述：Specifies the database type (e.g.,
sqlite,postgresql,sqlite+sqlcipher). This is used in conjunction with other individual parameters to construct theDATABASE_URLif a completeDATABASE_URLis not explicitly defined. - Persistence: No
DATABASE_USER
- 类型：
str - 默认值：
None - 描述：Specifies the username for database authentication. This is used to construct the
DATABASE_URLwhen a completeDATABASE_URLis not explicitly defined. - Persistence: No
DATABASE_PASSWORD
- 类型：
str - 默认值：
None - 描述：Specifies the password for database authentication. This is used to construct the
DATABASE_URLwhen a completeDATABASE_URLis not explicitly defined. If your password contains special characters, please ensure they are properly URL-encoded. - Persistence: No
DATABASE_HOST
- 类型：
str - 默认值：
None - 描述：Specifies the hostname or IP address of the database server. This is used to construct the
DATABASE_URLwhen a completeDATABASE_URLis not explicitly defined. - Persistence: No
DATABASE_PORT
- 类型：
int - 默认值：
None - 描述：Specifies the port number of the database server. This is used to construct the
DATABASE_URLwhen a completeDATABASE_URLis not explicitly defined. - Persistence: No
DATABASE_NAME
- 类型：
str - 默认值：
None - 描述：Specifies the name of the database to connect to. This is used to construct the
DATABASE_URLwhen a completeDATABASE_URLis not explicitly defined. - Persistence: No
信息
When DATABASE_URL is not explicitly set, Open WebUI will attempt to construct it using a combination of DATABASE_TYPE, DATABASE_USER, DATABASE_PASSWORD, DATABASE_HOST, DATABASE_PORT, and DATABASE_NAME. For this automatic construction to occur, all of these individual parameters must be provided. If any are missing, the default DATABASE_URL (SQLite file) or any explicitly set DATABASE_URL will be used instead.
DATABASE_USER_ACTIVE_STATUS_UPDATE_INTERVAL
- 类型：
float - 默认值：
None - 描述：Sets the minimum time interval in seconds between user active status updates in the database. Helps reduce write operations for high-traffic instances. Set to
0.0to update on every activity.
DATABASE_ENABLE_SESSION_SHARING
- 类型：
bool - 默认值：
False - 描述：Controls database session sharing behavior. When enabled (
True),get_db_contextreuses existing database sessions, which can improve performance and scalability in high-concurrency environments. When disabled (False), new sessions are always created.
Recommendations by Database Type
- SQLite: Keep this setting disabled (default
False). Enabling session sharing on SQLite with limited hardware resources may cause performance issues. - PostgreSQL: Consider enabling this setting (
True) for improved performance, especially in multi-user or high-concurrency deployments.
This setting is very deployment-specific. Users are encouraged to experiment based on their hardware specs and database choice to find the optimal configuration.
注意
Enabling this on low-spec hardware (e.g., Raspberry Pi, containers with limited CPU allocation) may cause significant slowdowns or timeouts. If you experience slow admin page loads or API timeouts after upgrading, ensure this setting is disabled.
Encrypted SQLite with SQLCipher
For enhanced security, Open WebUI supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed.
Additional Dependencies Required
SQLCipher encryption requires additional dependencies that are not included by default. Before using this feature, you must install:
- The SQLCipher system library (e.g.,
libsqlcipher-devon Debian/Ubuntu,sqlcipheron macOS via Homebrew) - The
sqlcipher3-wheelsPython package (pip install sqlcipher3-wheels)
For Docker users, this means building a custom image with these dependencies included.
To enable encryption, you must configure two environment variables:
- Set
DATABASE_TYPE="sqlite+sqlcipher". - Set
DATABASE_PASSWORD="your-secure-password".
When these are set and a full DATABASE_URL is not explicitly defined, Open WebUI will automatically create and use an encrypted database file at ./data/webui.db.
危险
- The
DATABASE_PASSWORDenvironment variable is required when usingsqlite+sqlcipher. - The
DATABASE_TYPEvariable tells Open WebUI which connection logic to use. Setting it tosqlite+sqlcipheractivates the encryption feature.
Ensure the database password is kept secure, as it is needed to decrypt and access all application data.
Migrating Existing Data to SQLCipher
Open WebUI does not support automatic migration from an unencrypted SQLite database to an encrypted SQLCipher database. If you enable SQLCipher on an existing installation, the application will fail to read your existing unencrypted data.
To use SQLCipher with existing data, you must either start fresh (with users exporting/re-importing chats), manually migrate the database using external SQLite/SQLCipher tools, use filesystem-level encryption (LUKS/BitLocker) instead, or switch to PostgreSQL.
DATABASE_SCHEMA
- 类型：
str - 默认值：
None - 描述：Specifies the database schema to connect to.
DATABASE_POOL_SIZE
- 类型：
int - 默认值：
None - 描述：Specifies the pooling strategy and size of the database pool. By default SQLAlchemy will automatically chose the proper pooling strategy for the selected database connection. A value of
0disables pooling. A value larger0will set the pooling strategy toQueuePooland the pool size accordingly.
High-Concurrency Deployments
For deployments with many concurrent users, consider increasing both DATABASE_POOL_SIZE and DATABASE_POOL_MAX_OVERFLOW. A good starting point is DATABASE_POOL_SIZE=15 and DATABASE_POOL_MAX_OVERFLOW=20.
Important: The combined total (DATABASE_POOL_SIZE + DATABASE_POOL_MAX_OVERFLOW) should remain well below your database server's max_connections limit. PostgreSQL defaults to 100 max connections, so keeping the combined total under 50-80 per Open WebUI instance is recommended to leave room for other clients and maintenance connections.
Pool Size Multiplies with Concurrency
Each Open WebUI process maintains its own independent connection pool. This applies whether you're running multiple Uvicorn workers (UVICORN_WORKERS > 1), multiple Kubernetes pods, Docker Swarm replicas, or any other multi-instance deployment.
The actual maximum number of database connections is:
Total connections = (DATABASE_POOL_SIZE + DATABASE_POOL_MAX_OVERFLOW) × Number of processes/instances
For example, with DATABASE_POOL_SIZE=15, DATABASE_POOL_MAX_OVERFLOW=20, and 4 instances (whether workers, pods, or replicas), you could open up to 140 connections (35 × 4).
When calculating pool settings, always account for this multiplier to avoid exhausting your database's max_connections limit. This is a fundamental limitation—connection pools cannot be shared across separate processes or containers.
SQLite on NFS / network storage — increasing the pool does not help
If you are seeing QueuePool limit of size N overflow M reached, connection timed out errors on SQLite and the database file lives on NFS, CephFS, Azure Files, an SMB mount, or any network-backed Kubernetes PVC, increasing this value will not fix it. The root cause is slow fsync on the network filesystem, which keeps each connection checked out far longer than on local disk; more pool slots just means more concurrent slow fsyncs against the same slow storage. The async backend saturates any size pool you give it.
The only real fixes are:
- Migrate to PostgreSQL (
DATABASE_URL=postgresql+asyncpg://...) — strongly recommended. - Move
webui.dbto a locally-attached SSD/NVMe. - Temporary workaround:
DATABASE_POOL_SIZE=1+DATABASE_SQLITE_PRAGMA_BUSY_TIMEOUT=30000— serializes DB access, not a supported long-term config.
See Performance → Disk I/O Latency for the mechanism, and Scaling → Step 1 for migration guidance.
DATABASE_POOL_MAX_OVERFLOW
- 类型：
int - 默认值：
0 - 描述：Specifies the database pool max overflow. This allows additional connections beyond
DATABASE_POOL_SIZEduring traffic spikes.
信息
More information about this setting can be found here.
DATABASE_POOL_TIMEOUT
- 类型：
int - 默认值：
30 - 描述：Specifies the database pool timeout in seconds to get a connection.
信息
More information about this setting can be found here.
DATABASE_POOL_RECYCLE
- 类型：
int - 默认值：
3600 - 描述：Specifies the database pool recycle time in seconds.
信息
More information about this setting can be found here.
DATABASE_ENABLE_SQLITE_WAL
- 类型：
bool - 默认值：
False - 描述：Enables or disables SQLite WAL (Write-Ahead Logging) mode. When enabled, SQLite transactions can be managed more efficiently, allowing multiple readers and one writer concurrently, which can improve database performance, especially under high concurrency. This setting only applies to SQLite databases.
DATABASE_SQLITE_PRAGMA_SYNCHRONOUS
- 类型：
str - 默认值：
NORMAL - 描述：Sets the SQLite
PRAGMA synchronousvalue.NORMAL(1) is safe with WAL mode and avoids an fsync per transaction, improving write throughput. Valid values:OFF(0),NORMAL(1),FULL(2),EXTRA(3). Set to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.
DATABASE_SQLITE_PRAGMA_BUSY_TIMEOUT
- 类型：
str - 默认值：
5000 - 描述：Sets the SQLite
PRAGMA busy_timeoutvalue in milliseconds. Controls how long a connection waits for a write lock before raisingSQLITE_BUSY. Higher values reduce lock contention errors under concurrent writes. Set to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.
DATABASE_SQLITE_PRAGMA_CACHE_SIZE
- 类型：
str - 默认值：
-65536 - 描述：Sets the SQLite
PRAGMA cache_sizevalue. Negative values specify the cache size in KiB — the default-65536allocates approximately 64 MB of page cache. Larger caches reduce disk I/O for read-heavy workloads. Set to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.
DATABASE_SQLITE_PRAGMA_TEMP_STORE
- 类型：
str - 默认值：
MEMORY - 描述：Sets the SQLite
PRAGMA temp_storevalue.MEMORY(2) keeps temporary tables and indices in RAM, which improves performance for queries using temporary storage. Valid values:DEFAULT(0),FILE(1),MEMORY(2). Set to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.
DATABASE_SQLITE_PRAGMA_MMAP_SIZE
- 类型：
str - 默认值：
268435456 - 描述：Sets the SQLite
PRAGMA mmap_sizevalue in bytes. The default268435456enables approximately 256 MB of memory-mapped I/O, which can significantly improve read performance by avoiding syscall overhead. Set to0to disable mmap, or to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.
DATABASE_SQLITE_PRAGMA_JOURNAL_SIZE_LIMIT
- 类型：
str - 默认值：
67108864 - 描述：Sets the SQLite
PRAGMA journal_size_limitvalue in bytes. Caps the WAL file size after checkpoint — without this, the WAL file can grow unbounded during write bursts. The default67108864caps it at approximately 64 MB. Set to-1for no limit (SQLite default), or to an empty string to skip this PRAGMA entirely. This setting only applies to SQLite databases.
Redis
REDIS_URL
- 类型：
str - 描述：Specifies the URL of the Redis instance or cluster host for storing application state.
- Examples:
redis://localhost:6379/0rediss://:password@localhost:6379/0(with password and TLS)rediss://redis-cluster.redis.svc.cluster.local:6379/0?ssl_cert_reqs=required&ssl_certfile=/tls/redis/tls.crt&ssl_keyfile=/tls/redis/tls.key&ssl_ca_certs=/tls/redis/ca.crt(with mTLS)
注意
Required for Multi-Worker and Multi-Node Deployments
When deploying Open WebUI with UVICORN_WORKERS > 1 or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you must set the REDIS_URL value. Without it, the following issues will occur:
- Session management will fail across workers
- Application state will be inconsistent between instances
- Websocket connections will not function properly in distributed setups
- Users may experience intermittent authentication failures
Redis serves as the central state store that allows multiple Open WebUI instances to coordinate and share critical application data.
信息
Single Instance Deployments
If you're running Open WebUI as a single instance with UVICORN_WORKERS=1 (the default), Redis is not required for basic functionality. However, without Redis, signing out and password changes do not invalidate existing JWT tokens — they remain valid until they expire (default: 4 weeks). For production deployments, either configure Redis or shorten JWT_EXPIRES_IN. See Token Revocation for details.
危险
Critical Redis Server Configuration — Prevent Connection Exhaustion
Open WebUI uses Redis for token validation, WebSocket management, and session storage. Each user action can create Redis connections. If your Redis server is misconfigured, connections will accumulate over time until the limit is reached, causing 500 Internal Server Errors and preventing all users from logging in.
You must configure these settings in your redis.conf (not Open WebUI environment variables):
| Setting | Bad Default | Recommended | Why |
|---|---|---|---|
maxclients | 1000 (some distros) | 10000 or higher | Low limits cause "max number of clients reached" errors |
timeout | 0 (never close) | 1800 (30 minutes) | Without timeout, idle connections accumulate forever |
Example redis.conf settings:
maxclients 10000
timeout 1800
Symptoms of this misconfiguration:
- Works fine for days/weeks, then suddenly all logins fail with 500 errors
redis.exceptions.ConnectionError: max number of clients reachedin logs- Problem appears to "fix itself" temporarily, then returns
Why this happens:
With timeout 0, every Redis connection stays open indefinitely. Over days or weeks, connections from token checks, WebSocket events, and session validations accumulate. Once maxclients is reached, no new connections can be made, and authentication fails completely.
To check your current connection count:
redis-cli INFO clients | grep connected_clientsTo verify your settings:
redis-cli CONFIG GET maxclients
redis-cli CONFIG GET timeoutREDIS_SENTINEL_HOSTS
- 类型：
str - 描述：Comma-separated list of Redis Sentinels for app state. If specified, the "hostname" in
REDIS_URLwill be interpreted as the Sentinel service name.
REDIS_SENTINEL_PORT
- 类型：
int - 默认值：
26379 - 描述：Sentinel port for app state Redis.
REDIS_CLUSTER
- 类型：
bool - 默认值：
False - 描述：Connect to a Redis Cluster instead of a single instance or using Redis Sentinels. If
True,REDIS_URLmust also be defined. This mode is compatible with AWS Elasticache Serverless and other Redis Cluster implementations.
信息
This option has no effect if REDIS_SENTINEL_HOSTS is defined.
OpenTelemetry Support
Redis Cluster mode is fully compatible with OpenTelemetry instrumentation. When ENABLE_OTEL is enabled, Redis operations are properly traced regardless of whether you're using a single Redis instance or Redis Cluster mode.
REDIS_KEY_PREFIX
- 类型：
str - 默认值：
open-webui - 描述：Customizes the Redis key prefix used for storing configuration values. This allows multiple Open WebUI instances to share the same Redis instance without key conflicts. When operating in Redis cluster mode, the prefix is formatted as
{prefix}:(e.g.,{open-webui}:config:*) to enable multi-key operations on configuration keys within the same hash slot.
REDIS_SOCKET_CONNECT_TIMEOUT
- 类型：
float(seconds) or empty string for None - 默认值：None (no timeout, uses redis-py library default)
- 描述：Sets the socket connection timeout in seconds for all Redis client connections, including Sentinel, Cluster, and plain URL modes. This timeout applies to the initial TCP connection establishment. When set, it prevents indefinite blocking when attempting to connect to unreachable Redis nodes.
危险
Critical for Redis Sentinel Deployments
Without a socket connection timeout, Redis Sentinel failover can cause the application to hang indefinitely when a master node goes offline. The application may become completely unresponsive and even fail to restart.
For Sentinel deployments, it is strongly recommended to set this value (e.g., REDIS_SOCKET_CONNECT_TIMEOUT=5).
注意
Interaction with WEBSOCKET_REDIS_OPTIONS
If you explicitly set WEBSOCKET_REDIS_OPTIONS, this variable will not apply to the AsyncRedisManager used for websocket communication. In that case, you must include socket_connect_timeout directly within WEBSOCKET_REDIS_OPTIONS:
WEBSOCKET_REDIS_OPTIONS='{"socket_connect_timeout": 5}'If WEBSOCKET_REDIS_OPTIONS is not set, REDIS_SOCKET_CONNECT_TIMEOUT will be applied to websocket connections automatically.
REDIS_SOCKET_KEEPALIVE
- 类型：
bool - 默认值：
False - 描述：Enables TCP
SO_KEEPALIVEon all Redis client sockets (plain, cluster, and sentinel connections, both sync and async). When enabled, the operating system kernel sends TCP keepalive probes on idle connections, detecting half-closed sockets (e.g., after a silent firewall/load balancer reset or a NIC flap) before the next Redis command lands on them.
When to enable
Enable this setting in environments where:
- A firewall or load balancer sits between the application and Redis and may silently drop idle connections
- Network instability can cause connections to become half-open without notification
- You want an additional layer of dead-connection detection alongside
REDIS_HEALTH_CHECK_INTERVAL
REDIS_SOCKET_KEEPALIVE operates at the TCP level (kernel-driven probes), while REDIS_HEALTH_CHECK_INTERVAL operates at the application level (redis-py PING commands). They are complementary and can be used together for maximum reliability.
REDIS_SENTINEL_MAX_RETRY_COUNT
- 类型：
int - 默认值：
2 - 描述：Sets the maximum number of retries for Redis operations when using Sentinel fail-over. This is a critical high-availability setting that allows the application time for master election and promotion. If your Sentinel
down-after-millisecondsis high, you should tune this value accordingly to ensure the service survives the failover window without dropping connections.
REDIS_RECONNECT_DELAY
- 类型：
float(milliseconds) - 默认值：None
- 描述：Optional reconnect delay in milliseconds for Redis Sentinel retry logic, applied consistently across both synchronous and asynchronous Redis operations. This improves stability during Sentinel failover by preventing tight retry loops. When unset or invalid, retry behavior remains unchanged.
REDIS_HEALTH_CHECK_INTERVAL
- 类型：
int(seconds) - 默认值：None (disabled)
- 描述：How often (in seconds) redis-py should PING an idle pooled connection before reusing it. When set to a positive integer, redis-py will PING any pooled connection that has been idle longer than this interval before handing it back to a caller. This detects stale/dead connections before a real command lands on them, preventing
ConnectionError: Connection reset by peererrors. Set to0or leave empty to disable.
Recommended for production
Set REDIS_HEALTH_CHECK_INTERVAL to a value shorter than both:
- Your Redis server's
timeoutsetting (e.g.,timeout 1800) - Any firewall or load balancer idle timeout on the path to Redis
A typical value is 60 (seconds). This keeps actively-used pooled connections warm (the PING resets the server's idle timer) while still allowing the Redis server to reap truly orphaned connections via its timeout setting.
How it works
When enabled, redis-py performs a lightweight PING on checkout for any connection that has been idle longer than the configured interval. This serves two purposes:
- Detects dead connections — stale sockets are identified and replaced before your application code runs a command on them
- Keeps active connections alive — the PING resets the Redis server's per-connection idle timer, preventing the server from reaping connections that are still in the pool
Without this setting, if your Redis server has a timeout configured (recommended to prevent connection exhaustion), the first request that grabs a reaped socket from the pool will fail with a ConnectionError.
WEBSOCKET_REDIS_LOCK_TIMEOUT
- 类型：
int - 默认值：
60 - 描述：Sets the timeout in seconds for Redis locks used by the websocket manager.
ENABLE_WEBSOCKET_SUPPORT
- 类型：
bool - 默认值：
True - 描述：Enables websocket support in Open WebUI.
注意
Required for Multi-Worker and Multi-Node Deployments
When deploying Open WebUI with UVICORN_WORKERS > 1 or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you must set this variable. Without it, the following issues will occur:
- Session management will fail across workers
- Application state will be inconsistent between instances
- Websocket connections will not function properly in distributed setups
- Users may experience intermittent authentication failures
WEBSOCKET_MANAGER
- 类型：
str - 默认值：
"" (empty string) - 描述：Specifies the websocket manager to use. Allowed values include:
redis
注意
Required for Multi-Worker and Multi-Node Deployments
When deploying Open WebUI with UVICORN_WORKERS > 1 or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you must set this variable. Without it, the following issues will occur:
- Session management will fail across workers
- Application state will be inconsistent between instances
- Websocket connections will not function properly in distributed setups
- Users may experience intermittent authentication failures
WEBSOCKET_REDIS_URL
- 类型：
str - 默认值：
${REDIS_URL} - 描述：Specifies the URL of the Redis instance or cluster host for websocket communication. It is distinct from
REDIS_URLand in practice, it is recommended to set both.
注意
Required for Multi-Worker and Multi-Node Deployments
When deploying Open WebUI with UVICORN_WORKERS > 1 or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you must set this variable. Without it, the following issues will occur:
- Session management will fail across workers
- Application state will be inconsistent between instances
- Websocket connections will not function properly in distributed setups
- Users may experience intermittent authentication failures
WEBSOCKET_SENTINEL_HOSTS
- 类型：
str - 描述：Comma-separated list of Redis Sentinels for websocket. If specified, the "hostname" in
WEBSOCKET_REDIS_URLwill be interpreted as the Sentinel service name.
WEBSOCKET_SENTINEL_PORT
- 类型：
int - 默认值：
26379 - 描述：Sentinel port for websocket Redis.
WEBSOCKET_REDIS_CLUSTER
- 类型：
bool - 默认值：
${REDIS_CLUSTER} - 描述：Specifies that websocket should communicate with a Redis Cluster instead of a single instance or using Redis Sentinels. If
True,WEBSOCKET_REDIS_URLand/orREDIS_URLmust also be defined.
信息
This option has no effect if WEBSOCKET_SENTINEL_HOSTS is defined.
WEBSOCKET_REDIS_OPTIONS
- 类型：
str - 默认值：
{}(empty, which allowsREDIS_SOCKET_CONNECT_TIMEOUTto apply if set) - 描述：A string representation of a dictionary containing additional Redis connection options for the websocket Redis client (AsyncRedisManager). This allows you to specify advanced connection parameters such as SSL settings, timeouts, or other Redis client configurations that are not covered by the standard
WEBSOCKET_REDIS_URL. The string should be formatted as valid JSON. For example:{"retry_on_timeout": true, "socket_connect_timeout": 5, "socket_timeout": 5, "max_connections": 8}. All JSON encodable options listed here can be used.
注意
AWS SSM and Docker compose cannot ingest raw JSON, as such you need to escape any double quotes like the following:
{\"retry_on_timeout\": true, \"socket_connect_timeout\": 5, \"socket_timeout\": 5, \"max_connections\": 8}
信息
Precedence with REDIS_SOCKET_CONNECT_TIMEOUT
When this variable is left empty (default), REDIS_SOCKET_CONNECT_TIMEOUT is automatically applied to websocket connections if set. However, if you explicitly set WEBSOCKET_REDIS_OPTIONS to any value, REDIS_SOCKET_CONNECT_TIMEOUT will not be injected—you must include socket_connect_timeout manually within this JSON if needed.
WEBSOCKET_SERVER_LOGGING
- 类型：
bool - 默认值：
false - 描述：Controls logging for SocketIO server related to websocket operations.
注意
This can be very verbose, it is only recommended to use this flag when debugging Redis related issues.
WEBSOCKET_SERVER_ENGINEIO_LOGGING
- 类型：
bool - 默认值：Falls back to
WEBSOCKET_SERVER_LOGGINGif not set, otherwisefalse - 描述：Controls logging for Engine.IO server related to websocket operations. If not explicitly set, this inherits the value from
WEBSOCKET_SERVER_LOGGING.
注意
This can be very verbose, it is only recommended to use this flag when debugging Redis related issues.
WEBSOCKET_SERVER_PING_TIMEOUT
- 类型：
int - 默认值：
20 - 描述：The timeout for a ping to Redis in seconds.
WEBSOCKET_SERVER_PING_INTERVAL
- 类型：
int - 默认值：
25 - 描述：The frequency for a ping to Redis in seconds.
WEBSOCKET_EVENT_CALLER_TIMEOUT
- 类型：
int - 默认值：
300 - 描述：Sets the timeout in seconds for the
sio.call()used inevent_callevents. This controls how long the server waits for a user to respond to interactive prompts, forms, or dropdowns generated by tools and actions usingevent_call(e.g.,execute()type events). Increase this value if users need more time to fill out forms or make decisions presented by event calls.
ENABLE_STAR_SESSIONS_MIDDLEWARE
- 类型：
bool - 默认值：
False - 描述：Enables Redis-based session storage for OAuth authentication flows using the StarSessions middleware. When enabled, OAuth session state is stored in Redis instead of browser cookies, which can help resolve CSRF errors in multi-replica deployments where session data needs to be shared across pods. Experimental feature that enables Redis-based session storage for OAuth flows using StarSessions middleware, helping resolve CSRF errors in multi-replica deployments.
- Persistence: This is an experimental environment variable.
注意
Experimental Feature - Known Limitations
This feature is currently experimental and has known compatibility issues:
- Redis Sentinel and Redis Cluster configurations are not yet supported and will cause authentication failures if this setting is enabled
- Only basic Redis setups (single instance or standard Redis URL) are currently compatible
- This feature was introduced to address CSRF "mismatching_state" errors in multi-pod deployments, but it is disabled by default due to ongoing compatibility work
Only enable this setting if:
- You are experiencing persistent CSRF errors during OAuth login in a multi-replica deployment
- You are using a basic Redis setup (not Sentinel or Cluster)
- You have confirmed that
WEBUI_SECRET_KEYis set to the same value across all replicas - You understand this is an experimental feature that may change or be removed in future releases
For most deployments, the default browser cookie-based session management is sufficient and more stable.
Uvicorn Settings
UVICORN_WORKERS
- 类型：
int - 默认值：
1 - 描述：Controls the number of worker processes that Uvicorn spawns to handle requests. Each worker runs its own instance of the application in a separate process.
信息
When deploying in orchestrated environments like Kubernetes or using Helm charts, it's recommended to keep UVICORN_WORKERS set to 1. Container orchestration platforms already provide their own scaling mechanisms through pod replication, and using multiple workers inside containers can lead to resource allocation issues and complicate horizontal scaling strategies.
If you use UVICORN_WORKERS, you also need to ensure that related environment variables for scalable multi-worker setups are set accordingly.
ChromaDB Not Compatible with Multiple Workers
The default vector database (ChromaDB) uses a local SQLite-backed PersistentClient. SQLite connections are not fork-safe — when uvicorn forks multiple workers, each process inherits the same SQLite connection, and concurrent writes will crash workers instantly (Child process died).
If you set UVICORN_WORKERS > 1, you must either switch to a client-server vector database (PGVector, Milvus, Qdrant) via VECTOR_DB, or run ChromaDB as a separate server and set CHROMA_HTTP_HOST.
Database Migrations with Multiple Workers / Multi-Pod Deployments
When UVICORN_WORKERS > 1 or when running multiple replicas, starting the application can trigger concurrent database migrations from multiple processes, potentially causing database schema corruption or inconsistent states.
Recommendation: To handle migrations safely in multi-process/multi-pod environments, you can:
- Designate a Master (Recommended): Set
ENABLE_DB_MIGRATIONS=Falseon all but one instance/worker. The instance withENABLE_DB_MIGRATIONS=True(default) will handle the migration, while others will wait or skip it. - Scale Down: Temporarily scale down to a single instance/worker to let migrations finish before scaling back up.
For Kubernetes, Helm, and Orchestrated Setups:
It is recommended to use the ENABLE_DB_MIGRATIONS variable to designate a specific pod for migrations, or use an init container/job to handle migrations before scaling up the main application pods. This ensures schema updates are applied exactly once.
Cache Settings
CACHE_CONTROL
- 类型：
str - 默认值：Not set (no Cache-Control header added)
- 描述：Sets the Cache-Control header for all HTTP responses. Supports standard directives like
public,private,no-cache,no-store,must-revalidate,max-age=seconds, etc. If an invalid value is provided, defaults to"no-store, max-age=0"(no caching). - Examples:
"private, max-age=86400"- Cache privately for 24 hours"public, max-age=3600, must-revalidate"- Cache publicly for 1 hour, then revalidate"no-cache, no-store, must-revalidate"- Never cache
Proxy Settings
Open WebUI supports using proxies for HTTP and HTTPS retrievals. To specify proxy settings, Open WebUI uses the following environment variables:
http_proxy
- 类型：
str - 描述：Sets the URL for the HTTP proxy.
https_proxy
- 类型：
str - 描述：Sets the URL for the HTTPS proxy.
no_proxy
- 类型：
str - 描述：Lists domain extensions (or IP addresses) for which the proxy should not be used, separated by commas. For example, setting no_proxy to '.mit.edu' ensures that the proxy is bypassed when accessing documents from MIT.
Install Required Python Packages
Open WebUI provides environment variables to customize the pip installation process. Below are the environment variables used by Open WebUI for adjusting package installation behavior:
ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS
- 类型：
bool - 默认值：
True - 描述：Controls whether Open WebUI automatically runs
pip installfor Python packages declared in function and toolrequirementsfrontmatter. When enabled, dependencies are installed at runtime — both on startup (for all active functions and admin tools) and when saving a function or tool with new requirements.
Security Hardening for Production
Strongly recommended: set ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS=False in production. Runtime pip installs allow any admin-uploaded function or tool to install arbitrary Python packages into the running process. Disabling this:
- Prevents arbitrary package installation from user-uploaded code
- Eliminates race conditions that crash workers when
UVICORN_WORKERS > 1or multiple replicas attempt concurrent pip installs - Ensures reproducible deployments — all dependencies are baked into the container image
Pre-install required packages in your Dockerfile instead:
FROM ghcr.io/open-webui/open-webui:main
RUN pip install --no-cache-dir python-docx requests beautifulsoup4When disabled, functions and tools that import missing packages will fail with a ModuleNotFoundError at load time, clearly indicating which packages need to be pre-installed.
PIP_OPTIONS
- 类型：
str - 描述：Specifies additional command-line options that pip should use when installing packages. For example, you can include flags such as
--upgrade,--user, or--no-cache-dirto control the installation process.
PIP_PACKAGE_INDEX_OPTIONS
- 类型：
str - 描述：Defines custom package index behavior for pip. This can include specifying additional or alternate index URLs (e.g.,
--extra-index-url), authentication credentials, or other parameters to manage how packages are retrieved from different locations.