Open WebUI 安装与 OmniProxy 配置

Open WebUI 是一个可以自己部署的聊天界面，安装在自己的电脑或服务器上，也能完全离线运行。它不绑定某一家模型：既可以连接 Ollama 这类在本机运行模型的工具，也可以连接兼容 OpenAI 格式的接口，也就是使用相同请求格式提供模型服务的地址。这样，本地模型和云端模型就能放在同一个窗口里切换。

它适合团队和组织长期使用。更新更快的能力会先出现在 Computer，也就是 Open WebUI 用来尝试新功能的产品中。

安装前准备

Open WebUI 可以在 macOS、Linux 和 Windows 上使用。你可以通过 Docker、Python 或 Kubernetes 安装。Docker 会把应用和运行环境装在一个相对独立的容器里，是推荐方式；没有 Docker 时，也可以使用下面实测过的 Python 命令。Kubernetes 是用来部署和管理容器的系统，对应步骤见文末的 Quick Start。

官方推荐

Docker

一条 docker run
浏览器打开 3000
数据在数据卷里

只想聊天

slim 镜像

下载体积更小
标签改成 :slim
聊天功能还在

这篇不展开

另两条路

Python 手动安装
Kubernetes 部署
看官方 Quick Start

先装 Docker，再按官方推荐命令启动。只通过接口聊天时，可以把镜像标签改成 slim。

开始前准备好：

已经安装并能运行的 Docker。
一个只给你自己使用的密钥串。执行 openssl rand -hex 32 生成，然后填入 WEBUI_SECRET_KEY。这个值要固定保存；容器重建时如果换了它，已经登录的人会被登出。
正在运行的 OmniProxy，以及它当前模型列表里的模型 ID。模型 ID 就是选择具体模型时使用的完整名称。

安装并首次启动

打开终端，执行 Quick Start 里的命令。先把 your-secret-key 换成刚才生成的那串密钥：

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data -e WEBUI_SECRET_KEY=your-secret-key --name open-webui --restart always ghcr.io/open-webui/open-webui:main

这条命令中的几项分别负责：

-p 3000:8080：让你通过这台电脑的 3000 端口打开界面。3000 被占用时，改左边的数字。
-v open-webui:/app/backend/data：把聊天、用户和设置放进数据卷。数据卷是容器之外长期保存数据的位置，更新容器后内容还在，所以不要去掉这一项。
--add-host=host.docker.internal:host-gateway：让容器能够访问这台电脑上运行的其他服务。
--restart always：电脑重新开机后，容器会再次启动。

命令执行后，在浏览器打开 http://localhost:3000，按照页面提示建立第一个账号。

如果只是通过接口聊天，可以把镜像标签从 :main 改成 :slim。slim 是体积更小的镜像，不包含容器内的本地语音和嵌入模型，但聊天界面仍然可用。需要这些本地能力时，继续使用 :main。

更新时，手动步骤是先执行 docker rm -f open-webui，再执行 docker pull ghcr.io/open-webui/open-webui:main，然后使用同一条 docker run 命令重新启动。数据卷和 WEBUI_SECRET_KEY 都要保持原样。

没有 Docker 时

Quick Start 也提供了 Python 安装方式。2026-10-09 在 macOS 上使用下面的命令安装到 Open WebUI v0.11.4，并完成了一次对话。当时这台电脑没有 Docker Desktop。

DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve

启动后，在浏览器打开 http://localhost:8080。这是 Python 安装方式使用的端口，不是 Docker 的 3000。

第一次启动会下载一个嵌入模型，可能需要几分钟。嵌入模型会把文字转换成便于搜索和匹配的数据。等登录页出现后再继续；第一个注册的账号会成为管理员。界面语言跟随系统，这次看到的是简体中文。

DATA_DIR 要指向一个会长期保留的目录，用来存放 Open WebUI 的数据。不设置时，数据可能落在临时目录里，关闭后就会丢失。没有设置 WEBUI_SECRET_KEY 时，程序会在当前目录写下 .webui_secret_key。请从打算保留的目录启动，或自己设置这个变量。

从 OmniProxy 取得连接参数

从你自己的 OmniProxy 复制下面三项：

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: 从 OmniProxy 当前模型列表复制

URL 是 Open WebUI 连接接口时使用的地址，要写到 /v1 结束。不要在后面再加 /chat/completions，这一段会由 Open WebUI 自己接上。

模型 ID 要从 OmniProxy 当前列表完整复制。如果 ID 中带有来源前缀和斜杠，也要一起保留。下面两个短名字只是 2026-10-09 供应商文档中的对照；当前列表里没有时，不要使用：

Claude Sonnet 5.5 的 Claude API ID：claude-sonnet-5-5
Gemini 3.8 Flash 的接口名：gemini-3.8-flash

不要把供应商密钥填进 Open WebUI。网关不校验密钥时，API 密钥可以留空，不要另外编一串密钥。

浏览器

本机 3000

打开聊天页面
先完成注册
再进设置

容器里

Open WebUI

不要写 localhost
改用宿主机名
URL 以 /v1 结束

同一台电脑

OmniProxy

密钥留在网关
模型列表以网关为准
再看调用记录

Open WebUI 在 Docker 里、OmniProxy 在宿主机上时，不要把地址写成容器里的 localhost。

如果模型服务运行在宿主机上，而 Open WebUI 运行在 Docker 容器里，请把 URL 中的 localhost 换成 host.docker.internal。宿主机就是直接运行 Docker 的这台电脑。OmniProxy 如果只监听这台电脑，URL 可以写成 http://host.docker.internal:端口/v1，其中的端口要换成 OmniProxy 实际使用的端口。

如果 Open WebUI 通过上一节的 Python 命令运行在本机，OmniProxy 也在本机，地址使用 127.0.0.1 或 localhost。这时不要写成 host.docker.internal。

填写工具配置

2026-10-09 的 v0.11.4 简体中文界面，与英文说明中的 Settings > Admin > Connections 名称不同。按照实际看到的中文选项操作：

展开左侧边栏。
点底部的用户菜单。
点设置。
在下方管理员分组里点 外部连接。
打开 OpenAI 接口。
在 管理 OpenAI 接口连接 右侧点 +。
在弹出的 编辑连接 中，把 URL 填到 /v1。接口类型保持 Chat Completions。
认证方式保持 密钥（Bearer）。Bearer 是把 API 密钥放进请求中进行身份验证的方式。OmniProxy 发给你密钥时，将它填进 API 密钥。网关不校验密钥时，这一栏留空。2026-10-09 留空后，验证和一次对话都成功了。
点 URL 旁边的 验证连接。OmniProxy 提供 /models 时，这里会取得模型列表。
打开高级。模型 ID 留空时，会使用该地址 /models 返回的全部模型。验证失败时，才在 添加模型 ID 里填入列表中的完整 ID，再点添加。每个 ID 只添加一次，前后空格会被去掉。
点这个窗口的保存，再点外部连接页右下角的保存。

只保存配置不能代替验证。验证连接请求的是对方的 /models，也就是用于列出可用模型的接口。有的服务没有这个接口，验证会报错，但聊天仍可能可用。这时再手动添加模型 ID。

验证一个真实任务

回到聊天页，打开输入框旁边的模型菜单，选择 OmniProxy 列表中的完整 ID。发送一句很短的话，例如让它只回复一个词。聊天框里需要实际出现回复。

2026-10-09 使用 v0.11.4 的 Python 安装完成了这次对话。Docker 仍是推荐方式，但这次没有在 Docker 里重做。

接着打开 OmniProxy 的调用记录，确认这次请求的来源和模型 ID。只看到保存成功，或者只看到模型出现在菜单里，都还不算完成。

界面

模型能选到

Connections 已保存
模型出现在列表
发出一句短问题

聊天框有答案

不是空白消息
不是连接报错
换一个模型再试一次

记录

网关看得到

来源是这次连接
模型 ID 一致
没有密钥进页面

三处都对上，才算这条连接可用。

常见错误

容器里写了 localhost 或 127.0.0.1：这两个地址指向容器自己，不是宿主机。改成 host.docker.internal，并确认启动命令中有 --add-host=host.docker.internal:host-gateway。Open WebUI 不在容器里时则相反，应使用本机地址。
浏览器打不开：Docker 查看 3000，Python 查看 8080。第一次启动要等待嵌入模型下载完成。docker ps 可以确认容器是否正在运行。3000 被占用时，修改 -p 左边的端口。
模型菜单里的 ID 比供应商短名字更长：使用菜单里的完整 ID，包括其中的斜杠。
更新后全部登出：WEBUI_SECRET_KEY 变了。使用第一次生成的那串密钥重新启动。
验证连接失败：先在高级中手动添加模型 ID，再用一句真实聊天确认。有的服务没有 /models，验证报错时聊天仍可能可用。
模型不存在：从 OmniProxy 当前列表重新复制 ID，不要继续使用过期名称。

官方参考

安装命令见 Open WebUI Quick Start。连接步骤见 OpenAI-compatible 连接说明。举例使用的模型 ID 见 Claude 模型总览和 Gemini 模型列表。

用你自己的 OmniProxy 配置替换每个占位符。不要发布真实密钥。

保存成功或 HTTP 200 不单独等同完整 Agent 兼容。请在 OmniProxy 调用记录中确认来源和模型。

官方来源 · Open WebUI ↗