Open WebUI

• 官方主页：openwebui.com
• 安装文档：docs.openwebui.com/getting-started/quick-start
• 网关对接文档：OpenAI 连接指南
• 协议类型：OpenAI 兼容（/v1/chat/completions）

安装

官方提供 Docker、Python（pip / uv）、Helm 等多种方式，完整清单见 官方安装文档。以下列出最常用的两种。

系统要求：Python 安装方式要求 Python 3.11；Docker 方式无额外要求。需要 GPU 本地推理时另见官方 GPU 章节，对接 TokenBay 不需要 GPU。

方式一：Docker（官方推荐）

docker run -d \
  -p 3000:8080 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

启动后访问 http://localhost:3000，首次进入会要求创建管理员账号。

方式二：Python（pip）

pip install open-webui
open-webui serve

默认监听 http://localhost:8080。

版本校验

# Docker 安装：查看镜像与运行状态
docker ps --filter name=open-webui
docker exec open-webui pip show open-webui | grep Version
 
# pip 安装
pip show open-webui | grep Version

也可登录后在 ⚙️ Admin Settings → About 页面查看当前版本号。

对接 TokenBay

对接机制

Open WebUI 内置「OpenAI 连接」，只要把连接的 URL 指向 TokenBay 网关、填入 TokenBay API Key 即可。凭证以 Authorization: Bearer <sk-...> 形式随请求发送，Open WebUI 会自动向该 Base URL 追加 /models、/chat/completions 等路径。

提供两种配置入口：

• 管理面板 UI（推荐）：运行时生效，无需重启容器。
• 环境变量：启动时预置，适合自动化部署。

Base URL 注意：TokenBay 网关 Base URL 为 https://api.tokenbay.com（不带路径、不带结尾斜杠）。但 Open WebUI 需要你填写带 /v1 的形式，即 https://api.tokenbay.com/v1，因为它会在此基础上自动拼接 /models 与 /chat/completions。若漏掉 /v1，模型列表会拉取失败。

1. 获取 API Key

进入 TokenBay 控制台 → API 密钥 → 创建密钥（直达链接），复制 sk- 开头的密钥。

明文仅显示一次：密钥创建后只完整显示这一次，请立即妥善保存；遗失只能重新创建。

2. 方式 A：通过管理面板（推荐）

以管理员登录后，进入 ⚙️ Admin Settings → Connections → OpenAI → Manage（扳手图标）→ ➕ Add New Connection，按下表填写：

点击 Save ✅。回到聊天首页的模型下拉框，应能看到 TokenBay 透传过来的模型列表。

Model IDs (Filter)：留空 = 自动发现全部模型；填写 = 白名单，只显示你列出的模型 ID，可用来隐藏不需要或较贵的模型。 Prefix ID：当你同时配置多个上游、且存在同名模型时，填一个前缀（如 tokenbay/）以区分。

3. 方式 B：通过环境变量

用环境变量在启动时预置连接。变量对应关系：

docker run 时追加：

docker run -d \
  -p 3000:8080 \
  -e OPENAI_API_BASE_URLS="https://api.tokenbay.com/v1" \
  -e OPENAI_API_KEYS="sk-XXXXXXX" \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

复数形式：OPENAI_API_BASE_URLS / OPENAI_API_KEYS 支持多个端点，用 ; 分隔，两个数组按下标一一对应。只接一个端点时也可用单数 OPENAI_API_BASE_URL / OPENAI_API_KEY。变量名拼错时 Open WebUI 不会报错，只是 UI 里不会预填值。

持久化优先级：通过 Admin Settings UI 保存的连接会写入数据库，优先级高于环境变量。若想让环境变量始终生效，可设 ENABLE_PERSISTENT_CONFIG=false；若想用环境变量重置数据库配置，可在下次启动时设 RESET_CONFIG_ON_START=true。

4. 推荐模型

模型 ID 由 Open WebUI 原样透传给 TokenBay，请直接使用 TokenBay 的模型 ID。完整清单见 模型清单 或控制台模型广场。

模型名格式：TokenBay 的版本号只接受小数点形式，如 claude-sonnet-4.6、gpt-5.5，不接受连字符形式（如 claude-sonnet-4-6）。 模型未授权：若下拉框看不到某个模型，可能是该模型在 控制台 → 分组设置 中尚未授权，需先开通。

5. 进阶配置

对长任务（如长上下文推理、复杂编码）建议调大超时，避免请求被提前中断。可与上面的连接变量合并写入 docker run：

docker run -d \
  -p 3000:8080 \
  -e OPENAI_API_BASE_URLS="https://api.tokenbay.com/v1" \
  -e OPENAI_API_KEYS="sk-XXXXXXX" \
  -e AIOHTTP_CLIENT_TIMEOUT=600 \
  -e AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=30 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main