Open WebUI OpenAI 兼容 API 配置教程
简答：可以。进入 Open WebUI 的“Settings → Admin → Connections”，在 Manage OpenAI API Connections 中新增连接，填写服务商要求的 URL、API Key 和模型 ID。最稳妥的顺序是：先确认 Base URL，再用 /models 和 /chat/completions 测试，最后回到 Open WebUI 保存并选择模型。若连接能保存但模型为空，先看 /models 的响应；若是 401 或 403，优先检查 Key、认证头和权限。本文是第三方接入指南，不代表任何 API 服务商或 Open WebUI 官方。
定义：OpenAI 兼容 API 是采用类似 OpenAI Chat Completions 请求结构的接口，但兼容范围可能只覆盖部分路径、字段、流式格式、工具调用或多模态能力。
先试这三步：URL、模型和最小请求
Open WebUI 官方当前文档将兼容接口配置入口写为 Settings → Admin → Connections，然后在 Manage OpenAI API Connections 中点击添加连接。官方说明连接验证会使用 URL 加上 /models 发起请求，因此 URL 应填写服务商的兼容 API 根地址，而不是完整的 /chat/completions 请求地址。可先查看 Open WebUI 官方 OpenAI-Compatible 文档。
| 字段 | 怎么填 | 不要怎么填 |
|---|---|---|
| URL / Base URL | 服务商文档给出的兼容 API 根地址；是否包含 /v1 以服务商文档和实际请求为准 | 不要直接填完整的 /chat/completions |
| API Key | 具有模型调用权限的 Bearer 密钥 | 不要粘贴管理后台密码、带空格的复制内容或公开截图中的 Key |
| Model IDs | 填写 /models 返回的真实模型 ID，或服务商文档列出的准确 ID | 不要使用模型展示名、别名或自行猜测的 ID |
Open WebUI 官方列出的核心兼容能力是 GET /v1/models 用于模型发现，以及 POST /v1/chat/completions 用于聊天；嵌入、语音、图片和工具调用属于额外能力，是否可用要逐项核对服务商文档。兼容“聊天请求”不等于所有 OpenAI 字段都兼容。
在 Open WebUI 中添加连接：按当前界面核对字段
- 打开已运行的 Open WebUI，登录管理员账号。
- 进入 Settings → Admin → Connections。
- 找到 Manage OpenAI API Connections，点击添加连接按钮。
- 在 URL 中填写服务商兼容接口的 Base URL，在 API Key 中填写调用密钥。
- 点击 Verify Connection。当前官方文档说明，这一步会请求 URL 下的
/models，因此某些没有实现该端点、认证方式不同或返回格式不标准的服务可能验证失败。 - 如果模型未自动出现，在 Model IDs 中输入准确的模型 ID，点击加号后保存。
- 回到新建聊天页面，从模型选择器中选中模型，先发送一条不含敏感资料的短消息。
菜单名称和字段布局可能随 Open WebUI 当前版本、部署方式或界面语言变化。找不到完全相同的文字时，应优先按“管理员设置、连接、OpenAI API、Model IDs”等关键词查找，不要因为菜单不同就修改服务商 URL。Open WebUI 官方快速开始页也明确说明，Open WebUI 本身不提供模型，模型来自用户添加的本地或云端连接。
如果页面出现连接保存成功但模型为空，不要把“保存成功”当作“接口可用”。先执行下面的 curl，分别确认模型列表和聊天请求。
curl 最小验证：先设置变量，再测试两个端点
下面命令需要在与 Open WebUI 后端相同的网络环境中执行。变量中的值必须来自服务商当前文档、控制台或实际 /models 响应；BASE_URL 只放根地址，不要包含 /chat/completions。
export BASE_URL='https://example.com/v1'
export API_KEY='替换为真实调用密钥'
export MODEL_ID='替换为真实模型ID'
先测模型列表：curl -sS "$BASE_URL/models" -H "Authorization: Bearer $API_KEY"
再测非流式聊天：curl -sS "$BASE_URL/chat/completions" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{"model":"'$MODEL_ID'","messages":[{"role":"user","content":"回复 OK"}],"stream":false}'
成功判定不是只看 HTTP 状态码：模型列表应返回可解析的 JSON 和模型信息；聊天请求应返回完成结果或 assistant 消息。若响应是 HTML、404 页面、认证错误或模型不存在，应先修正最终 URL、Key 或模型 ID。
测试流式响应时，可把请求体中的 "stream":false 改为 "stream":true，并使用 curl -N 观察是否持续收到 SSE 数据。流式格式、最后一个 usage 块和结束标记并非所有兼容服务都完全一致，因此只能以服务商文档和实际响应为准。
常见服务配置对照：官方原生、兼容实现与本地服务要分开看
下面只列出接入 Open WebUI 时需要核对的字段，不代表各服务的模型能力、价格、限速或工具调用行为相同。具体模型 ID、认证方式和 URL 可能变化，发布前应再次打开对应官方资料。
| 服务或类型 | URL / Base URL | 模型 ID 来源 | 兼容性注意点 |
|---|---|---|---|
| OpenAI | https://api.openai.com/v1 | 从服务商账号和模型文档核对 | 官方原生 OpenAI 接口；按 Open WebUI 的 OpenAI 连接方式配置 |
| OpenRouter | https://openrouter.ai/api/v1 | 使用模型目录中的作者/模型 ID | 模型数量多，建议在 Model IDs 中建立筛选后的允许列表；官方开发者页确认其提供 OpenAI 兼容 API |
| DeepSeek | 官方 SDK 示例使用 https://api.deepseek.com；Open WebUI 专用页也展示过带 /v1 的连接写法，需以当前实际端点验证 | 从官方模型文档或 /models 响应核对 | 不要机械追加 /v1；先分别测试最终的 /models 和聊天路径 |
| LiteLLM | 按代理实际地址填写；官方快速开始示例代理运行在本机 4000 端口 | 来自 LiteLLM 配置中的模型别名 | 这是兼容网关，模型名可能是自定义别名；Key、预算和路由由网关配置决定 |
| vLLM | 通常是部署地址加 /v1 | 来自 vLLM 服务实际加载的模型 | 官方文档列出 /v1/models 和 /v1/chat/completions，但聊天模板、工具调用和鉴权仍需按启动参数核对 |
| LM Studio | 本地 OpenAI 兼容端点通常使用本机服务地址；官方说明需先在 Developer 页面启动服务器 | 来自本地已加载或可用模型 | Open WebUI 在 Docker 中运行时，容器内的 localhost 不一定指向宿主机 |
| 硅基流动 | 需以当前服务商官方兼容接口文档为准 | 需以当前模型目录或 /models 响应为准 | 本次核验未取得足够的一手页面来确认固定 URL、模型 ID 和全部字段，不写死具体值 |
可核对的官方资料包括：OpenRouter 开发者页面给出了兼容 API 地址；DeepSeek 官方首次调用文档给出了 OpenAI SDK 的 Base URL 和模型字段；LiteLLM 官方快速开始说明其代理可提供 OpenAI 兼容入口；vLLM 官方 OpenAI 兼容服务文档列出了模型和聊天端点；LM Studio 官方本地服务文档说明了 Developer 页面启动方式。
按状态码和响应体排查：不要把所有验证失败都当成同一类问题
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
| 401 | Key 是否正确、是否带 Bearer、是否复制了空格或使用了错误环境的 Key | 用 curl 查看响应体；重新生成或轮换调用 Key，不要把管理密钥放入共享实例 |
| 403 | Key 权限、项目权限、区域或模型访问限制 | 在服务商控制台确认该 Key 是否允许目标模型，不要仅通过更换模型来猜测 |
| 404 | Base URL 是否重复 /v1，是否把完整聊天路径填入 URL，服务是否使用另一种协议 | 打印最终请求地址，确保只拼接一次 /models 或 /chat/completions |
| 连接保存但模型为空 | /models 是否存在、响应格式是否兼容、模型是否被允许列表过滤 | 单独请求 /models；若服务没有该端点，手动加入准确的 Model ID |
| 超时或 TLS 错误 | DNS、证书、代理、容器网络和服务端响应时间 | 从 Open WebUI 所在容器或主机执行 curl；先排网络，再调整模型列表超时 |
| Docker 连接本机服务失败 | 容器与宿主机的地址、监听网卡、端口映射和防火墙 | 不要直接把宿主机的 localhost 当作容器地址；Open WebUI 官方文档提示可按环境尝试 host.docker.internal |
Open WebUI 官方文档明确说明，Verify Connection 主要请求 /models，部分服务不支持该端点时可能出现 400、401 或 403，但聊天接口仍可能单独可用。更严谨的判断方式是：401/403 先查认证和权限；404 或格式错误再查端点；最终以 /chat/completions 的真实响应确认能否聊天。
如果模型列表加载很慢，官方环境变量参考页提供了模型列表请求超时配置。调整前先确认 URL、DNS、TLS 和代理可用，避免用延长超时掩盖错误地址。可查看 Open WebUI 官方环境变量参考。
兼容不等于全部能力兼容：完成基础聊天后再核对字段
OpenAI 兼容通常只说明接口形状相近。完成基础文本聊天后，还应按使用场景核对以下项目：
- 流式：是否支持 SSE，结束标记和 usage 是否与客户端预期一致。
- 工具调用：是否支持
tools、tool_choice、并行工具调用，以及工具调用后的消息字段。 - 视觉和文件：图片 URL、Base64、文件上传和内容数组是否支持。
- 参数名称：
max_tokens、max_completion_tokens、temperature等字段是否被接受或会被忽略。 - 模型列表：模型 ID 是否稳定、是否需要手动允许列表、同名模型是否来自不同连接。
- 额外功能：标题生成、自动补全、联网搜索、嵌入、知识库和语音等可能触发额外请求，是否启用以及是否产生额外用量要按当前版本和部署配置核实。
建议先只验证一条短文本消息，再逐项打开流式、工具、知识库或其他扩展功能。这样可以把“基础聊天失败”和“某个高级字段不兼容”分开定位。
Key 安全与多用户配置：把连接验证和权限控制分开
Open WebUI 的连接可能供实例内多个用户使用，因此 API Key 不应放进公开截图、前端代码、Git 仓库、浏览器脚本或聊天内容。优先使用仅具备模型调用权限的密钥，按服务商提供的控制台设置用量提醒、项目隔离或权限限制。
- 日志只记录请求 ID、状态码、环境名和脱敏后的 URL，不记录完整 Key。
- 发现 Key 泄露时，先在服务商控制台撤销或轮换，再用新的短请求验证旧 Key 已失效。
- 共享 Open WebUI 前，确认哪些用户能看到连接、模型和调用记录；具体权限位置以当前 Open WebUI 版本为准。
- 不要因为连接验证失败就反复粘贴 Key；先检查响应体和最终 URL，避免把密钥暴露到更多日志中。
如果你需要在多个模型服务之间切换，先保持每条连接的 URL、Key 和 Model IDs 独立，完成单条连接验证后再增加第二条连接，便于判断究竟是路由、模型还是权限问题。
常见问题
Open WebUI 的 Base URL 到底要不要加 /v1？
不能一概而论。如果服务商官方文档把兼容端点写在 /v1 下，就保留 /v1；如果官方 SDK 示例使用不带 /v1 的 Base URL，就先按该写法测试。不要把 /chat/completions 填进 Base URL，也不要因为某个服务的写法就套用到所有服务。
为什么 Open WebUI 能保存连接，但模型列表为空？
保存连接不等于模型发现成功。先从 Open WebUI 所在环境请求最终的 /models，查看是否为 404、401、403 或非标准 JSON。如果服务没有可用的模型列表端点，在 Model IDs 中手动加入服务商给出的准确模型 ID。
Verify Connection 返回 401，是不是服务一定不兼容？
不应直接这样判断。401/403 更常见地指向 Key、Bearer 认证头或权限问题；没有 /models 更常见的是 404、格式错误或模型为空。分别测试 /models 和 /chat/completions，并根据响应体分类处理。
Open WebUI 用 Docker 部署时，为什么 localhost 连接不上本地模型？
容器里的 localhost 通常指向容器自身，不一定是宿主机。检查模型服务监听地址、端口映射和 Docker 网络；根据部署环境使用容器可访问的宿主机地址，例如官方文档提到的 host.docker.internal，但 Linux、自定义网络和反向代理仍需本机核对。
OpenRouter、DeepSeek 或本地 vLLM 都能直接接入吗？
只要服务实际提供 OpenAI Chat Completions 兼容接口，通常可以按 URL、Key 和 Model ID 接入；但模型列表、工具调用、流式 usage、视觉和参数支持可能不同。先完成一条非流式短消息，再逐项验证高级能力。
可以把 /chat/completions 直接填到 Open WebUI 的 URL 字段吗？
通常不应该。Open WebUI 会根据连接 URL 拼接模型列表和聊天路径；填入完整聊天路径可能导致重复拼接并产生 404。URL 应填写服务商文档定义的 Base URL，最终以实际请求地址为准。
相关阅读
- Dify OpenAI 兼容 API 配置与 curl 验证
- Continue 的 Base URL、Key 与模型设置
- Cline 接入兼容接口的配置方法
- DeepSeek API 401 的 Key 与请求头排查
参考资料
- Open WebUI 官方：OpenAI-Compatible Providers（docs.openwebui.com）
- Open WebUI 官方：Quick Start（docs.openwebui.com）
- Open WebUI 官方：Environment Variable Configuration（docs.openwebui.com）
- OpenRouter 官方：Developer Platform（openrouter.ai）
- DeepSeek 官方：Your First API Call（api-docs.deepseek.com）
- LiteLLM 官方：Getting Started（docs.litellm.ai）
- vLLM 官方：OpenAI-Compatible Server（docs.vllm.ai）
- LM Studio 官方：Local LLM API Server（lmstudio.ai）