文档

文档

Open WebUI

Open WebUI 将任何兼容 OpenAI 的端点视为一个连接。可以在 Admin Settings 中添加连接,也可以在容器启动时设置两个环境变量——两种方式最终都会创建同一个连接。

在 Admin Settings 中添加一个 OpenAI 连接,或在容器启动时设置 OPENAI_API_BASE_URL 和 OPENAI_API_KEY — 两者最终都指向同一个 /v1。

连接,或 docker run
# Settings → Admin Settings → Connections → Manage OpenAI API Connections → +
URL                https://api.kunavo.com/v1
API Key            sk-kn-...
Model IDs (Filter) claude-sonnet-5, claude-opus-5, claude-haiku-4-5, gpt-5-6-terra

# …or at container start, same thing:
docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=https://api.kunavo.com/v1 \
  -e OPENAI_API_KEY=sk-kn-... \
  -v open-webui:/app/backend/data \
  --name open-webui ghcr.io/open-webui/open-webui:main
填写 Model IDs (Filter)。如果留空,选择器会列出整个目录,包括聊天窗口无法调用的图像、视频和音乐模型,用户第一次点击时就可能选中其中之一。如果端点没有 /models 路由,也可以使用此筛选项;Kunavo 提供该路由,因此无论如何都能通过验证。
URL 中保留 /v1。如果 Open WebUI 在 Docker 中运行,而你要指向同一主机上的某个服务,请将 localhost 替换为 host.docker.internal——托管端点不适用这一点,但这是人们解决前一个问题后紧接着遇到的故障。
还没有密钥?创建 Kunavo 账户,创建一个密钥(以 sk-kn- 开头),并充值 $10 起——调用费用从该余额中扣除,失败的调用不会收费。随后,控制台会打开 Open WebUI 设置页面。

分步操作

  1. 在 /app/keys 创建密钥并复制——它只会显示一次。
  2. 在 Open WebUI 中,进入 Settings → Admin → Connections,找到 Manage OpenAI API Connections。
  3. 点击 ➕ Add Connection,然后填写 URL 和 API Key。
  4. 在 Model IDs (Filter) 中添加所需的 ID,然后保存并等待连接验证。
  5. 开始新的聊天——模型会以连接名称为前缀,显示在选择器中。

已于 2026年9月6日对照 Open WebUI 的兼容 OpenAI 提供商指南检查。第三方设置会发生变化;如果这里的字段名称不再与你看到的内容一致,应以该页面为准,而不是本页。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON,则相同的基础 URL 和密钥可以在 Open WebUI 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models,包含价格的目录见模型页面。费率单位为每 1M token 的美元,格式为输入 / 输出。

模型 IDKunavo 输入 / 输出它在 Open WebUI 中的位置
claude-sonnet-5$1.40 / $7.00通用聊天默认模型
claude-opus-5$3.50 / $17.50长篇分析对话
claude-haiku-4-5$0.70 / $3.50快速、便宜,适用于大多数回合
gpt-5-6-terra$0.70 / $4.20粘贴到聊天窗口中的长文档
计费方式是从预付余额中按 token 扣费,无月费——参见 计费。对于重复上下文——这正是编辑器或聊天客户端发送内容的大部分——提示缓存对账单的影响大于模型选择。

常见问题

如何将 Open WebUI 连接到兼容 OpenAI 的 API?

进入 Settings → Admin → Connections,打开“Manage OpenAI API Connections”,点击 Add Connection,然后输入端点 URL(即 /v1 根路径)和 API 密钥。也可以在容器启动时通过 OPENAI_API_BASE_URL 和 OPENAI_API_KEY 环境变量完成相同配置。两种方式都会创建同一个连接。

Open WebUI 中的 Model IDs (Filter) 有什么作用?

它限制该连接的哪些模型 ID 会显示在选择器中;对于未实现 /models 路由的端点,它也可以作为备用方案——你可以手动添加 ID,验证会失败,但聊天仍可正常使用。对于目录庞大的多模态网关,无论如何都建议设置此项,这样聊天选择器只会列出聊天窗口实际能够调用的模型。

Open WebUI 的 base URL 要包含 /v1 吗?

要包含。Open WebUI 只会将路由追加到你提供的 URL 后面,因此连接 URL 应为 /v1 根路径,例如 https://api.example.com/v1。文档中的示例端点也都带有此后缀。若缺少该后缀,连接可以保存,但每个请求都会返回 404。

Open WebUI 能使用 Claude 和 GPT 模型吗?

可以,只要它们通过兼容 OpenAI 的端点提供服务。Open WebUI 会将模型 ID 原样传递到连接 URL,因此任何供应商的 ID 都会在端点处解析,而不是由 Open WebUI 解析。这也意味着,一个连接和一个密钥就能让 Claude 和 GPT 的 ID 一同显示在模型选择器中。