
bug: DEFAULT_MODEL_METADATA env not parsed when persistentconfig=false
快速结论:当设置 ENABLE_PERSISTENT_CONFIG=false 时,DEFAULT_MODEL_METADATA 环境变量会被忽略,导致模型的 capabilities 和 builtin tools 无法通过环境变量正确禁用。优先排查 config.py 中是否硬编码了空字典,以及升级到 v0.9.5 或更高版本。
问题场景
用户在 Docker 部署 Open WebUI 时,设置 ENABLE_PERSISTENT_CONFIG: "False" 并传入 DEFAULT_MODEL_METADATA 环境变量以配置默认模型的能力(如禁用 vision、web_search 等)和内置工具。期望这些配置生效后,在 /admin/settings/models 页面中看到对应项被禁用,但实际发现所有 capabilities 和 builtin tools 仍保持启用状态。
报错原文
DEFAULT_MODEL_METADATA: '{"capabilities":{"file_context":true,"vision":true,"file_upload":true,"web_search":false,"image_generation":false,"code_interpreter":false,"terminal":false,"citations":false,"status_updates":true,"usage":true,"builtin_tools":true},"builtinTools":{"time":false,"web_search":false,"calendar":false,"image_generation":false,"memory":false,"chats":false,"code_interpreter":false,"notes":false,"tasks":false,"knowledge":false,"channels":false,"automations":false}}'
观察结果:所有 capabilities + builtin tools 在 /admin/settings/models 中均为启用状态。
原因分析
可能原因:DEFAULT_MODEL_METADATA 在 config.py 中被硬编码为 {}(空字典),从未从环境变量中读取。尽管文档声称该变量可通过环境变量配置,但代码中并未实现从 os.environ 解析的逻辑。该问题在 ENABLE_PERSISTENT_CONFIG=false 模式下尤其明显,因为此模式下配置应完全由环境变量驱动。
环境排查
- Open WebUI 版本:v0.9.2(问题在更早版本也有出现)
- 部署方式:Docker(Git Clone 安装也受影响)
- 操作系统:Linux
- 确认
ENABLE_PERSISTENT_CONFIG是否设置为 “false”(区分大小写) - 确认
DEFAULT_MODEL_METADATAJSON 字符串格式是否正确
解决步骤
- 升级到最新开发版或 v0.9.5+ 版本。 Issue 中提到 “Addressed in dev”,并在 v0.9.5 中经用户验证已修复(enabled 配置现在能正确生效)。
- 如果无法升级,可优先尝试在
config.py中手动添加从环境变量读取的逻辑:
DEFAULT_MODEL_METADATA = json.loads(os.environ.get("DEFAULT_MODEL_METADATA", "{}")) - 确认环境变量传递方式正确:在 Docker 中使用
-e参数,或在 Docker Compose 中正确嵌套 JSON。 - 重启容器/服务后检查 /admin/settings/models 页面。
验证方法
重启容器后,访问 /admin/settings/models 页面,检查在 DEFAULT_MODEL_METADATA 中设置为 false 的 capabilities(如 web_search、vision)是否已显示为禁用状态,且内置工具(如 time、calendar)也正确关闭。如果所有配置如期生效,则问题已解决。



