Open WebUI 配置 OpenAI 兼容 API：Base URL、模型与排错步骤

更新于 2026-10-26 · runapi.cfd

简答：Open WebUI 配置 OpenAI 兼容 API，先在 Settings > Admin > Connections 添加连接，再填写服务商提供的完整 Base URL、API Key 和模型 ID。先用 /v1/models 与 /v1/chat/completions 自测；若模型列表接口不可用，可在 Model IDs 中手动添加。具体服务商地址和模型名必须以对应文档或控制台为准。

定义：OpenAI 兼容 API 是按 OpenAI Chat Completions 等通用接口提供服务的后端，Open WebUI 通过 Base URL、API Key 和模型 ID连接它。

先完成这三项：URL、Key、Model ID

Open WebUI 的兼容连接通常至少需要三个值：服务商提供的完整 Base URL、API Key，以及可以实际调用的模型 ID。Open WebUI 文档说明，连接入口位于 Settings > Admin > Connections；添加连接后填写 URL 和 API Key，若服务端不支持模型自动发现，则需要手动加入 Model IDs。参考 Open WebUI 的 OpenAI-Compatible 配置文档。

关于 runapi.cfd：本文不是该域名的官方文档；我没有从本次核验的 Open WebUI 一手资料中确认它当前可用的 Base URL、模型 ID 或密钥格式，因此这些值应以该服务的可核验文档或控制台为准，不要直接套用其他服务的地址。

后台配置步骤：从连接到第一次聊天

1. 登录已经运行的 Open WebUI，并确认当前账号拥有管理员权限。
2. 进入 Settings > Admin > Connections，找到 Manage OpenAI API Connections。
3. 点击添加连接按钮，在 URL 中填写服务商提供的 Base URL，在 API Key 中填写密钥。
4. 如果服务端支持模型列表自动发现，先点击 Verify Connection，再观察模型建议或列表。
5. 如果验证提示 400、401 或 403，但服务商并没有提供可用的 /models 接口，不要立即判断聊天接口不可用；在 Model IDs 中手动输入真实模型 ID，点击加号后保存。
6. 回到聊天页面，从模型选择器中选中刚添加的模型，先发送一句短文本，确认基础对话能够返回。

Open WebUI 的连接验证会调用提供方的 /models 接口，并使用 Bearer Token。文档特别说明，某些服务没有这个接口或认证方式不同，验证失败并不必然代表 Chat Completions 不可用。查看连接验证与手动 Model IDs 说明。

如果你连接的是一个只实现聊天、不实现模型列表的网关，建议直接使用手动模型 ID。Open WebUI 文档也说明，手动添加后，模型仍可以出现在选择器中。

先在终端自测：不要一上来反复点 Verify

自测的目的，是把问题分成三类：Base URL 不对、API Key 或权限不对、模型或聊天请求体不对。Open WebUI 文档列出的核心兼容端点包括 /v1/models 和 /v1/chat/completions；其中前者用于模型发现，后者是聊天必需端点，Embedding 则只在使用 RAG 时需要。查看 Open WebUI 对兼容端点的要求。

Bash 最小自测：

• read -r -p "Base URL: " BASE_URL; read -r -p "Model ID: " MODEL; read -r -s -p "API Key: " API_KEY; printf '\n'
• curl --fail-with-body --max-time 30 -sS -H "Authorization: Bearer ${API_KEY}" -H "Content-Type: application/json" "${BASE_URL%/}/models"
• BODY=$(jq -n --arg model "$MODEL" '{model:$model,messages:[{role:"user",content:"请只回复：连接成功"}],stream:false}'); curl --fail-with-body --max-time 60 -sS -H "Authorization: Bearer ${API_KEY}" -H "Content-Type: application/json" "${BASE_URL%/}/chat/completions" -d "$BODY"

这里假设你填写的是以 /v1 等路径结尾的 Base URL，因此命令会在末尾拼接 /models 和 /chat/completions。如果服务商文档给的是不同层级的地址，不要自行猜测，按其文档调整。--fail-with-body 需要较新的 curl 版本；若本机不支持，可暂时去掉该参数，但要保留 HTTP 状态码输出。

PowerShell 自测：

• $BaseUrl = Read-Host "Base URL"; $Model = Read-Host "Model ID"; $ApiKey = Read-Host "API Key" -AsSecureString; $ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($ApiKey); $PlainKey = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr); [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
• $Headers = @{ Authorization = "Bearer $PlainKey"; "Content-Type" = "application/json" }; Invoke-RestMethod -Method Get -Uri (($BaseUrl.TrimEnd('/')) + '/models') -Headers $Headers
• $Body = @{ model = $Model; messages = @(@{ role = 'user'; content = '请只回复：连接成功' }); stream = $false } | ConvertTo-Json -Depth 5; $Utf8Body = [Text.Encoding]::UTF8.GetBytes($Body); Invoke-RestMethod -Method Post -Uri (($BaseUrl.TrimEnd('/')) + '/chat/completions') -Headers $Headers -Body $Utf8Body

不要把真实 API Key 写进脚本文件、Shell 历史、截图或 URL。Bearer 头在部分系统中可能出现在进程或调试信息里；共享日志前应先脱敏。

模型列表为空、验证失败时怎么处理

Open WebUI 文档明确区分了模型发现和聊天调用：/v1/models 用于发现模型，/v1/chat/completions 是聊天核心接口。也就是说，模型列表为空时，优先验证聊天接口和手动模型配置，而不是反复修改 API Key。参考兼容端点和手动模型配置说明。

Docker 部署：localhost 为什么经常不通

如果 Open WebUI 运行在 Docker 容器中，而兼容 API 运行在宿主机上，容器里的 localhost 指向容器本身，不一定是宿主机。Open WebUI 文档建议此场景将 URL 中的 localhost 替换为 host.docker.internal。查看 Docker 访问宿主机的配置提示。

• API 在宿主机端口 8000：可先测试 http://host.docker.internal:8000/v1 是否符合服务端实际路径。
• API 与 Open WebUI 在同一个 Docker Compose 网络：优先使用服务名和容器端口，例如 http://api-service:8000/v1，具体端口以 Compose 配置为准。
• API 在远程服务器：使用远程服务文档提供的 HTTPS Base URL，并从容器内部测试 DNS 和 TCP 连通性。

不要只在宿主机执行成功的 curl 结果来判断 Open WebUI 已经可用；真正的请求发起位置是 Open WebUI 后端所在的运行环境。

环境变量与管理后台怎么选

单实例、临时配置或需要经常调整时，管理后台更直观；Docker Compose、批量部署或多连接场景，可以使用环境变量。Open WebUI 当前环境变量参考页列出了 OPENAI_API_BASE_URL、OPENAI_API_BASE_URLS、OPENAI_API_KEY、OPENAI_API_KEYS 和 JSON 格式的 OPENAI_API_CONFIGS。查看 Open WebUI 环境变量参考。

环境变量页面还提醒，部分配置变量会在首次启动后持久化到内部数据库；之后只修改容器环境变量，可能看不到界面变化。此时应从 Admin UI 修改，或按文档核对 ENABLE_PERSISTENT_CONFIG 的行为。查看 ConfigVar 持久化和环境变量排查说明。

示例 Compose 配置可以写成：environment: OPENAI_API_BASE_URLS: "https://api.example.com/v1" OPENAI_API_KEYS: "替换为密钥" OPENAI_API_CONFIGS: '{"0":{"enable":true,"model_ids":["替换为真实模型ID"]}}'。这是结构示例，不代表任一具体服务商的真实地址或模型名。

兼容能力边界：聊天能用，不代表所有功能都能用

Open WebUI 采用协议导向设计，核心重点是 OpenAI Chat Completions 协议；官方文档同时将 Open Responses 标为实验性支持。因此，某个服务能完成普通聊天，并不自动说明它支持工具调用、Embedding、RAG、图像、音频或全部高级参数。查看 Open WebUI 的协议与端点说明。

• 普通聊天：优先确认 /v1/chat/completions 和目标模型可用。
• 流式输出：确认服务端支持兼容的流式响应，并在 Open WebUI 中用短消息测试。
• 工具调用：不要只看普通聊天结果；需要单独确认服务端对工具参数和流式工具事件的支持。
• Embedding/RAG：Open WebUI 文档将 /v1/embeddings 列为 RAG 场景所需的可选端点。没有该端点时，聊天可能正常，但知识库功能未必可用。
• 多用户部署：使用权限范围尽量小的 Key，避免把管理密钥直接用于普通用户请求，并检查日志是否记录完整 Authorization 头。

常见问题

Open WebUI 的 Base URL 要不要加 /v1？

不能一概而论。应填写服务商文档给出的完整 Base URL；如果文档明确给出以 /v1 结尾的兼容地址，就按原样填写。不要把 /chat/completions 直接填进 Base URL，也不要因为某个服务使用 /v1 就套到另一个服务上。

Verify Connection 失败，但聊天接口可能正常吗？

可能。Open WebUI 的验证会调用 /models；如果服务端没有该接口，或认证方式不适配，验证可能返回错误，而聊天接口仍可能可用。此时先用终端测试 /chat/completions，再在 Model IDs 中手动添加模型。

模型列表为空时应该改 API Key 还是手动填模型？

先测试 /models。如果返回 404、空列表或服务商明确不提供模型列表接口，优先手动添加真实 Model ID；如果 /models 返回 401 或 403，则先处理密钥和权限问题。

Docker 中填写 localhost 为什么连接超时？

因为 Open WebUI 后端在容器内运行时，localhost 通常指向当前容器。若 API 在宿主机，先按 Open WebUI 文档尝试 host.docker.internal；若 API 与 Open WebUI 在同一个 Compose 网络，则使用对应服务名和容器端口。

普通聊天正常，RAG 或工具调用却不能用，是什么原因？

兼容 API 的能力可能不是完整一致的。聊天主要依赖 chat/completions；RAG 还需要 embeddings，工具调用则需要服务端支持对应参数和响应格式。应按功能逐项测试，不要只用普通聊天结果推断全部能力。

相关阅读

• 继续看 Dify 的 OpenAI 兼容模型配置
• 了解其他客户端如何填写 OpenAI API Base URL
• 排查模型 ID 或请求路径导致的 404
• 查看站内 API 接入文档

参考资料

1. OpenAI-Compatible / Open WebUI（docs.openwebui.com）
2. Environment Variable Configuration / Open WebUI（docs.openwebui.com）
3. Connect Local and Cloud Models / Open WebUI（docs.openwebui.com）
4. OpenAI / Open WebUI（docs.openwebui.com）
5. Open WebUI 文档仓库中的 OpenAI-Compatible 页面源码