Open WebUI 安装与配置教程（2026 最新 v0.12）：uv / Docker 部署、接入 OpenAI 兼容 API、地址怎么填

本文按 2026 年 10 月 25 日发布的 v0.12.4 写，用 uv 安装、接 API、发消息都在 Mac 上实测过，Docker 命令按官方文档整理。接 API 那一节，我们读了 Open WebUI 的源码，把「地址要不要带 /v1」讲清楚。

Open WebUI 能做什么

它是一个网页版客户端，自己不提供模型，接什么服务就用什么模型：

• 像 ChatGPT 一样聊天：对话记录、文件上传、代码高亮、语音输入，一个对话里可以随时换模型。
• 接多家模型：任何 OpenAI 兼容的 API，以及本地的 Ollama。可以同时接好几家，模型都出现在同一个下拉框里。
• 知识库：把文档传进去，让模型基于你的资料回答。
• 多账号：第一个注册的是管理员，可以开放注册给家人或同事用，分别管理权限。
• 数据在你自己手上：对话、账号、设置都存在你部署的机器上。

和 Cherry Studio 这类桌面软件比，Open WebUI 的优势是装一次，任何设备打开浏览器就能用，也适合部署在服务器上给几个人共用；代价是要自己装和维护。

安装

官方支持三种装法。个人在自己电脑上用，推荐 uv；部署到服务器上长期跑，推荐 Docker。

方法一：uv（推荐个人电脑用）

uv 是一个 Python 工具管理器，它会自己下载合适版本的 Python，不用你先装 Python。

先装 uv（Mac / Linux）：

curl -LsSf https://astral.sh/uv/install.sh | sh

然后启动 Open WebUI：

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

Windows 在 PowerShell 里：

$env:DATA_DIR="C:\open-webui\data"; uvx --python 3.12 open-webui@latest serve

• DATA_DIR 一定要写：它决定对话和设置存在哪个文件夹，不写的话以后升级可能找不到旧数据。
• 第一次运行要下载软件本身（我们实测装完约 1.9GB），加上下面说的嵌入模型，要耐心等一会儿。
• 看到日志不再滚动后，打开 http://localhost:8080。
• 关掉终端窗口，Open WebUI 就停了；下次再运行同一条命令即可。

方法二：Docker（推荐服务器用）

docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY=换成一串随机字符 \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

• 打开 http://localhost:3000（左边的 3000 可以改成别的空闲端口）。
• -v open-webui:/app/backend/data 把数据存在 Docker 卷里，升级不会丢。
• WEBUI_SECRET_KEY 用 openssl rand -hex 32 生成一串，固定下来，换了它所有人都要重新登录。
• 如果电脑上也装了 Ollama，官方命令里还会加 --add-host=host.docker.internal:host-gateway，让容器能访问本机的 Ollama。

方法三：pip

pip install open-webui
open-webui serve

要求 Python 3.11 或 3.12（3.13 还不支持）。这种方式最容易碰到 Python 版本和证书问题，不熟悉 Python 的话用方法一。

第一次启动为什么很慢

我们实测第一次启动等了两分钟左右，日志里能看到它在从 Hugging Face 下载 sentence-transformers/all-MiniLM-L6-v2，一共约 913MB。这是知识库默认用的嵌入模型，只下载一次，第二次启动不到一分钟。

如果你的网络连不上 Hugging Face，启动会卡在这里。可以在启动命令前加 OFFLINE_MODE=true 跳过下载（Docker 用 -e OFFLINE_MODE=true），聊天不受影响，只是知识库要另外配置嵌入模型才能用。

第一次打开：创建管理员账号

打开网页后点「开始使用」，填名字、邮箱、密码，点「创建管理员账号」。

• 这个账号只存在你自己部署的 Open WebUI 里，不会发到任何外部网站，邮箱不需要验证。
• 第一个账号就是管理员。管理员建好后，注册入口默认关闭；想让别人也能用，见下文「让家人、同事一起用」。
• 界面语言跟着浏览器走，中文浏览器打开就是中文；也可以在「设置 → 通用 → 语言」里改。

接入 OpenAI 兼容 API

在界面里添加连接

1. 点左下角头像 → 设置，在弹窗左栏的「管理员」下面找到「外部连接」。
2. 在「管理 OpenAI 接口连接」右边点「+」。
3. URL：服务商的 API 地址，填到 /v1 为止，比如 https://api.foo/v1。
4. 认证方式保持 Bearer，右边粘贴 API 密钥。
5. 接口类型保持 Chat Completions。
6. 点 URL 右边的刷新图标（验证连接）。显示「已验证服务器连接」就对了。
7. 点「保存」，回到外部连接页面再点一次右下角的「保存」。

回到新对话，点顶部的模型名，就能看到这个服务商的模型。选一个，发一句「你好」试试。

高级设置里的几个选项

在连接弹窗里展开「高级」：

API 地址怎么填：按源码讲清楚

我们读了 v0.12.4 的源码（backend/open_webui/routers/openai.py），Open WebUI 拼地址的方式很简单：在你填的 URL 后面直接接接口名。

• 发消息：你填的 URL + /chat/completions
• 获取模型列表、验证连接：你填的 URL + /models
• 接口类型选 Responses 时：你填的 URL + /responses

它不会自动补 /v1，这一点和 Cherry Studio 不一样。所以：

我们用测试密钥逐个试过 api.foo：

另外两个细节：

• 末尾多一个 / 没关系：界面里保存时会自动去掉。
• Claude 模型也走 OpenAI 格式：源码里只有地址是 Anthropic 官方的 api.anthropic.com 时才切换成 Claude 原生接口。所以用聚合平台时，Claude、Gemini 都通过 OpenAI 兼容接口调用，服务商需要支持这种转换（api.foo 支持）。

用环境变量一次配好

部署到服务器、或者想一条命令就配好时，可以用环境变量：

docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY=换成一串随机字符 \
  -e OPENAI_API_BASE_URL=https://api.foo/v1 \
  -e OPENAI_API_KEY=你的API密钥 \
  -e ENABLE_OLLAMA_API=False \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

uv 方式就把同样的变量写在命令前面：

OPENAI_API_BASE_URL=https://api.foo/v1 OPENAI_API_KEY=你的API密钥 ENABLE_OLLAMA_API=False DATA_DIR=~/.open-webui uvx --python 3.12 open-webui@latest serve

让家人、同事一起用

1. 管理员打开「设置 → 管理员 · 身份验证」，打开「新注册用户」开关。
2. 别人在同一个网址注册。新用户默认是「待激活」，要管理员在「管理员面板 → 用户」里把他的角色改成「用户」才能用。
3. 大家共用你在「外部连接」里配的 API 密钥，用量都算在这把密钥上。

在「设置 → 管理员 · 外部连接」里还有一个「直接连接」开关：打开后，每个用户可以在自己的设置里接自己的 API 密钥。不过官方提示，直接连接要靠浏览器保持请求，更适合测试和临时使用，日常还是用管理员配的连接。

让别的电脑访问，Open WebUI 要监听局域网地址（uv 方式加 --host 0.0.0.0，Docker 默认就是）；放到公网上要配 HTTPS，并且确认已经关掉了「新注册用户」或者只放行认识的人。

常见问题与解决办法

1. 验证连接提示「OpenAI: 无效的令牌」

地址是对的，密钥不对：复制漏了字符、多了空格，或者填成了别家的密钥。重新复制一遍密钥。不同服务商的报错文字不一样，api.foo 显示的是「无效的令牌」。更多报错见 报错排查大全。

2. 验证连接提示「Open WebUI: Server Connection Error」

这表示 Open WebUI 根本没连上你填的地址，看启动 Open WebUI 的终端窗口（或 docker logs open-webui）里的报错：

• CERTIFICATE_VERIFY_FAILED：我们在 Mac 上实测遇到过。用 Python 官网安装包装的 Python 默认不带根证书，任何 HTTPS 地址都连不上。解决办法二选一：
  • 双击「应用程序 → Python 3.12 → Install Certificates.command」；
  • 或者改用 uv 自己下载的 Python：uvx --managed-python --python 3.12 open-webui@latest serve。
• 连接超时、找不到主机：检查地址有没有拼错、这台机器能不能上网；Docker 里还要检查容器能不能访问外网。

3. 404，Invalid URL

你把完整接口路径填进了 URL，比如 …/v1/chat/completions。改成只到 /v1。

4. 模型列表是空的，或者找不到想用的模型

• 先确认「验证连接」能通过，/models 拿不到时模型列表就是空的。
• 外部连接页的「缓存基础模型列表」开着的话，列表只在启动或保存设置时更新，点一下这条连接的保存或重启 Open WebUI 再看。
• 服务商不提供 /models 时，在连接的「高级 → 模型 ID」里手动添加。

5. 改了环境变量不生效

见上文「用环境变量一次配好」的警告：环境变量只在第一次启动时生效，之后到界面里改。

6. 长回答写到一半断了

很长的回答可能超过线路的超时时间。api.foo 的默认线路有 120 秒的超时限制，长任务可以把 URL 换成直连线路 https://dc.api.foo/v1。

数据存在哪、怎么升级

升级前先把数据文件夹（或 Docker 卷）备份一份。Open WebUI 更新很频繁，大版本之间偶尔有不兼容的改动，升级前看一眼 GitHub Releases 的说明。

相关阅读

• Cherry Studio 配置教程：桌面软件，不用部署
• API 中转站是什么？怎么选不踩坑
• 报错排查大全