作者：nTokenX｜发布日期：2026-10-11｜更新日期：2026-10-11
OpenWebUI配置自定义OpenAI接口教程的核心，就是把服务商提供的 Base URL、API Key 和模型 ID 填入 Open WebUI 的外部连接设置。只要接口遵循 OpenAI 兼容协议，就能在同一个界面调用云端或自建模型。
什么是 Open WebUI 自定义 OpenAI 接口
Open WebUI 的“自定义 OpenAI 接口”并不限定为 OpenAI 官方服务，而是指向一个兼容 OpenAI API 格式的模型服务。官方文档显示，Open WebUI 主要通过 OpenAI 兼容协议连接不同模型服务，配置入口通常位于 设置 → 管理员设置 → 外部连接。(docs.openwebui.com)
这意味着你可以接入官方 API、企业网关、本地模型服务，或提供统一接口的多模型 API 聚合平台。常见必需信息如下：
| 配置项 | 作用 | 示例 |
|---|---|---|
| Base URL | 指定 API 服务地址 | https://example.com/v1 |
| API Key | 完成接口鉴权 | sk-xxxx |
| Model ID | 指定可调用模型 | gpt-xxx |
| API Type | 选择调用协议 | Chat Completions |
需要注意，Base URL 通常应填写到 /v1 层级，但最终仍以服务商文档为准。Open WebUI 官方兼容接口说明中，聊天功能至少需要支持 /v1/chat/completions；如果希望自动读取模型列表，还应支持 /v1/models。(docs.openwebui.com)
OpenWebUI配置自定义OpenAI接口教程：标准配置步骤
第一步：进入外部连接设置
登录 Open WebUI 后，依次打开：
- 点击左下角用户头像；
- 进入 管理员设置；
- 打开 设置 → 外部连接；
- 找到 管理 OpenAI API 连接；
- 点击添加连接。
不同版本的界面名称可能略有变化，但核心位置都是管理员连接管理区域。
第二步：填写 Base URL 与 API Key
在连接窗口中填写：
URL：
https://你的服务商域名/v1
API Key：
你的接口密钥
如果使用 nTokenX 这类统一 API，可先在平台创建或获取 API Key，再将平台提供的兼容接口地址填入 URL。nTokenX 的使用方式是申请一个 API Key 后，通过统一接口调用 GPT、Claude、Gemini、Grok 等多个模型，具体可用模型以账户和接口返回结果为准。
对于 OpenAI 官方接口，官方示例地址为 https://api.openai.com/v1。对于其他兼容服务，不要机械复制这个地址，而要确认服务商是否要求额外路径、版本号或特殊请求头。(docs.openwebui.com)
第三步：处理模型列表
保存连接后，Open WebUI 通常会请求 /v1/models 自动读取模型。如果模型列表为空，可以在高级设置中的 Model IDs 手动填写模型 ID。
建议先只填写一个已确认可用的模型，例如：
model-a
确认单模型能够正常对话后，再逐步加入其他模型。这样可以避免模型名称错误、权限不足和接口未开放等问题同时出现。
如果服务端不支持 /models 自动发现，Open WebUI 官方建议使用模型白名单手动指定模型 ID。(docs.openwebui.com)
Docker 部署时最容易出错的三个参数
1. 不要把 localhost 当成宿主机地址
如果 Open WebUI 运行在 Docker 容器内，而模型服务运行在宿主机，容器里的 localhost 指向的是容器自身，不是宿主机。官方文档建议在此场景尝试使用：
http://host.docker.internal:端口/v1
Linux 环境是否默认支持该域名，取决于 Docker 配置；必要时需要通过 extra_hosts 映射宿主机地址。(docs.openwebui.com)
2. 不要重复拼接 /v1
常见错误是服务商地址本身已经包含 /v1，用户又在 Open WebUI 中重复填写，最终形成：
https://example.com/v1/v1
出现 404 或路由不存在时，优先检查 Base URL 的路径层级。
3. 区分连接地址与模型名称
Base URL 是服务器地址，Model ID 是模型标识，两者不能互换。比如：
Base URL： https://example.com/v1
Model ID： claude-model-name
不要把完整聊天接口地址 /chat/completions 填进 Base URL，Open WebUI 会自行拼接请求路径。
一套更可靠的接口验收方法
仅看到模型出现在下拉菜单，并不代表接口完全兼容。针对 Open WebUI 接入，我建议使用“四层验收框架”：
- 发现层：能否成功读取
/v1/models； - 对话层：能否完成普通非流式请求；
- 流式层：回复是否持续输出，而不是长时间等待后一次性返回；
- 能力层：工具调用、图片、嵌入或语音等功能是否确实被服务端支持。
Open WebUI 官方列出的兼容接口中，聊天补全是核心能力；嵌入、语音转文字、文字转语音和图像生成则属于可选接口。(docs.openwebui.com)
这个框架的价值在于：模型能聊天，不等于 RAG、语音或工具调用也能用。如果你只需要文本对话，完成前两层即可；如果要搭建知识库，还应确认 /v1/embeddings 是否可用。
常见错误与排查顺序
| 现象 | 常见原因 | 优先处理方式 |
|---|---|---|
| 模型列表为空 | 不支持 /models 或模型 ID 错误 |
手动填写 Model IDs |
| 401 / 403 | API Key 无效或权限不足 | 重新生成密钥并确认权限 |
| 404 | Base URL 路径错误 | 检查是否重复 /v1 |
| 连接超时 | Docker 网络、域名或服务端响应慢 | 先用浏览器或命令行测试地址 |
| 能看到模型但无法回复 | 模型名称映射错误或聊天接口不兼容 | 核对 /chat/completions 与 Model ID |
| 回复中途停止 | 流式响应格式不兼容 | 检查 SSE 流式返回和网关配置 |
如果模型列表请求长时间卡住，Open WebUI 官方还提供了模型列表超时配置选项，例如通过 AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST 调整请求等待时间。(docs.openwebui.com)
对于希望在多个客户端复用同一接口的团队，可以进一步参考 Cherry Studio 配置第三方服务商 API 的参数与排错指南；如果主要使用 NextChat，则可查看 NextChat 配置自定义服务商接口教程。
Open WebUI 连接官方 API、网关和统一 API 有什么区别
三类连接在填写方式上相似，但责任边界不同：
- 官方 API：由模型厂商直接提供，模型名称、计费和权限由官方账户控制；
- 正规 API 聚合或网关：用户绑定自己的模型厂商 Key，平台负责统一转发、计费、监控或路由；
- 第三方模型中转：平台采购或代理模型额度，再向用户提供统一 API。
选择时不要只看“能否连通”，还要核对授权来源、数据处理方式、故障响应、模型映射和账单记录。对于企业场景，建议优先选择能够提供清晰接口文档、账户隔离和用量记录的服务，并将生产 Key 与测试 Key 分开管理。
如果你需要多个模型共用一个调用入口，可阅读 多模型 API 聚合服务的统一接入指南，重点比较协议兼容、模型路由与运维责任，而不是单纯比较模型数量。
常见问题
Open WebUI 可以接入非 OpenAI 模型吗？
可以。只要服务端实现了 OpenAI 兼容接口，通常就能通过 OpenAI 连接类型接入。模型是否可用，取决于服务端支持的协议、模型 ID 和权限。
Base URL 应该填写到哪一级？
通常填写到 API 根路径，例如 /v1，不要直接填写 /chat/completions。但部分服务商有自定义路径，最终应以其接口文档为准。
为什么保存后看不到模型？
优先检查 API Key、/v1/models 是否可访问，以及服务商是否要求手动指定 Model IDs。如果 Docker 中部署，还应检查容器是否能访问目标域名或宿主机端口。
Open WebUI 能同时配置多个接口吗？
可以。Open WebUI 支持管理多个 OpenAI 兼容连接，使用时再从模型选择器中选择对应模型。多连接场景下，建议使用不同的连接名称或模型前缀，减少模型名称冲突。
配置后能否继续使用本地 Ollama？
可以。Open WebUI 可以同时管理本地模型与外部 OpenAI 兼容接口，具体显示效果取决于当前版本和连接配置。官方文档也将 Ollama、OpenRouter、vLLM 等兼容服务归入自定义 Base URL 的连接方式。(github.com)