Open WebUI 配置教程

更新于 2026-09-28

适用范围：Open WebUI 管理员配置的 OpenAI 兼容 Chat Completions 连接；适用于 Docker 自部署实例。

版本与验证：2026-09-28 更新 apizt 专用配置示意图；所有接入地址使用 https://api.apizt.com/v1，模型示例使用 gpt-6-sol。按官方文档核对字段，界面文字可能随版本变化。未使用真实 API Key 验证付费调用。

配置速查

配置项	填写内容	注意事项
URL / Base URL	`https://api.apizt.com/v1`	填写基础地址，不追加 /chat/completions。
API Key	`apizt API Key`	Auth 保留 Bearer，填写自己的令牌。
Model IDs	`gpt-6-sol`	仅为示例，请替换成当前令牌可用模型。
Provider / Provider Type	`Default / OpenAI`	按版本保留普通 OpenAI 兼容连接默认项。

还没有 API Key？注册获取免费体验额度 · 已注册：进入控制台创建 API Key

为此工具单独创建令牌，并设置合理额度和模型权限。截图中的模型仅作示例，以账号当前可用模型为准；不要公开密钥或上传含密钥的配置文件。

本教程通过管理员连接接入 apizt，让 Open WebUI 使用当前令牌可用的聊天模型。先完成一条普通消息，再逐步启用其他功能。

一、安装并打开 Open WebUI

已有安装可直接进入下一步。新用户先安装并启动 Docker，使用下面的本地命令运行独立实例：

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

在浏览器打开 http://localhost:3000，完成首次账号设置后用管理员账号登录。若 3000 端口被占用，可将端口映射左侧改成 3001，再打开对应地址；此命令使用独立容器和数据卷。

二、添加管理员 API 连接

点击头像，进入 Settings（设置）→ Admin（管理）→ Connections（连接）。部分版本显示为「管理员面板 → 设置 → 连接」。
找到 OpenAI API 连接列表，点击 ＋ Add Connection。
按下面的字段表填写 apizt 地址、密钥和模型 ID，确保连接开关已启用。

Open WebUI · 编辑连接，API 地址 https://api.apizt.com/v1，模型 gpt-6-sol；配置示意图 — 图 1：apizt 连接配置示意图。填写本文地址、自己的 API Key 和可用模型 ID。图中的 sk-demo-not-a-real-key 为无效演示密钥；gpt-6-sol 为模型示例，以令牌实际权限为准。点击图片可在页内放大；支持关闭按钮、点击图片外区域和 Esc 关闭。

三、填写 apizt 参数

字段	填写内容	说明
URL / Base URL	`https://api.apizt.com/v1`	填写基础地址，不追加 /chat/completions。
API Key	`apizt API Key`	Auth 保留 Bearer，填写自己的令牌。
Model IDs	`gpt-6-sol`	仅为示例，请替换成当前令牌可用模型。
Provider / Provider Type	`Default / OpenAI`	按版本保留普通 OpenAI 兼容连接默认项。

Open WebUI 的 apizt 配置对照：Base URL、API Key、模型 ID 和提供商默认选项 — 图 2：apizt 参数对照示意图，示例模型为 gpt-6-sol。点击图片可在页内放大；支持关闭按钮、点击图片外区域和 Esc 关闭。

https://api.apizt.com/v1

模型列表能自动读取时选择所需模型；读取不到时，在 Model IDs 中填写当前令牌可用的完整 ID，并点击旁边的加号添加。保持 Prefix ID 为空，先不添加额外 Headers。

四、保存并验证聊天

有 Verify Connection 或刷新图标的版本可先检查连接，再点击 Save。
回到聊天页，刷新模型列表并选中刚添加的模型。
发送「请只回复：连接成功」，确认收到正文，再核对 apizt 控制台对应请求的模型、时间和分组。

验证连接通常只能说明连接或模型列表可读取，不能替代实际聊天测试。实际请求按所选模型计费。

五、切换模型和开放成员使用

要使用第二个模型，在同一连接中添加该模型 ID，保存后从聊天页模型选择器切换。管理员能用而普通成员看不到时，检查模型访问控制和成员所属用户组。

如果出现聊天回复正常但自动标题失败，检查后台任务使用的模型配置，确保它也属于当前令牌可用模型。不要默认沿用其他提供商的任务模型。

常见问题

模型下拉列表为空怎么办？

先检查连接是否启用，再在连接的 Model IDs 中手动添加完整模型 ID；确认普通成员有该模型的访问权限。

配置聊天后就能使用知识库和生图吗？

聊天、嵌入、图像和语音使用不同配置。基础聊天成功后，再配置对应模块与模型，不能只靠聊天连接启用所有能力。

完整场景教程

聊天连接与知识库配置完整流程，包含结果检查、常见错误与对应接口参考。

连接失败时按这几步排查

管理员 Connections 中的 OpenAI 兼容连接填 https://api.apizt.com/v1；该模式从后端发请求。Direct Connections 则从浏览器发请求，应分别排查。

打开 Settings → Admin → Connections，添加 OpenAI 兼容连接并保存 Base URL 和 Key。
刷新列表。若明确选择手动 Model IDs，填写平台真实 ID；手动列表不能证明模型可调用。
后端部署在 Docker 时，从容器所在网络检查连通性；如果是 Direct Connections，则检查浏览器网络与 CORS。

容易混淆的情况

管理员能用而普通用户看不到时，核对模型可见性和用户组权限。
聊天成功但标题生成或 RAG 失败时，分别检查任务模型与 embedding 配置，不能用聊天模型配置代替全部功能。

怎样确认修复成功

分别用管理员和目标用户新建聊天；记录实际回答、模型权限和后台日志。仅浏览器能打开网关首页不代表容器能调用 API。

记录所装客户端版本、模型 ID、请求时间、最终路径与脱敏状态。本节为配置核对指南，未新增客户端付费调用实测；保留原文已有验证记录的适用范围。

打开 Open WebUI 交互排错并下载检查记录 · 官方配置参考

怎样确认配置已生效

在模型列表中能选择配置的模型。
短消息返回正常正文，流式显示能正常结束。
apizt 控制台出现对应模型的调用日志。

接入失败时逐项检查

现象	检查与处理
401 / Unauthorized	重新复制 apizt 令牌，检查是否完整、是否已过期；不要填写工具平台自己的密钥。
403 / 模型无权限	检查令牌允许的模型和所选分组，以响应中的具体错误为准。
404 / 路径错误	本文 Base URL 填 https://api.apizt.com/v1，检查重复的 /v1 或错误的接口路径。
model not found	从价格页复制完整模型 ID，确认当前令牌分组提供该模型。
429 / 额度或速率限制	按错误体区分余额、令牌额度、并发和速率限制；减少并发并稍后重试。
连接超时	检查运行 Open WebUI 后端的服务器或容器是否能访问 API；浏览器能打开网站不等于容器能连通。
管理员可用，成员不可用	检查模型访问权限、用户组以及连接开关。

资料与下一步

遇到问题时保留软件版本、请求时间、模型 ID、错误码和请求 ID，联系支持时先隐藏 API Key。