摘要

Open WebUI 是很多人本地或服务器上使用的 AI Web 客户端。它支持配置 OpenAI 兼容 API，只要服务端提供兼容接口，就可以通过 Base URL 和 API Key 接入。

本文整理 Open WebUI Docker 环境下配置 OpenAI 兼容 API 的通用流程，包括：

1. Base URL 怎么填
2. API Key 怎么配置
3. 模型列表怎么检查
4. 容器内网络怎么排查
5. 401、404、model not found 怎么处理

示例中的接口可以替换成任意 OpenAI 兼容服务。

一、Open WebUI 配置项

常见配置项：

OpenAI API Base URL OpenAI API Key Model

OpenAI 兼容 API 的 Base URL 通常是：

https://example.com/v1

不要填成完整请求路径：

https://example.com/v1/chat/completions

因为 Open WebUI 会自己拼接请求路径。

二、先在宿主机测试

在配置 Open WebUI 之前，先在宿主机测试接口。

export RELAY_BASE_URL="https://example.com/v1" export RELAY_API_KEY="sk-xxxxxxxxxxxxxxxx"

查询模型：

curl -sS "$RELAY_BASE_URL/models" \ -H "Authorization: Bearer $RELAY_API_KEY"

最小请求：

curl -sS "$RELAY_BASE_URL/chat/completions" \ -H "Authorization: Bearer $RELAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "your-model", "messages": [ { "role": "user", "content": "你好，请回复一句：接口已接通" } ] }'

宿主机能通，说明 API 地址和 Key 大概率没问题。

三、Docker 环境变量配置方式

如果通过 Docker 运行 Open WebUI，可以通过环境变量传入。

示例：

docker run -d \ -p 3000:8080 \ -e OPENAI_API_BASE_URL="https://example.com/v1" \ -e OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx" \ -v open-webui:/app/backend/data \ --name open-webui \ ghcr.io/open-webui/open-webui:main

注意：

1. OPENAI_API_BASE_URL 一般填到 /v1
2. OPENAI_API_KEY 填 Key，不要加 Bearer
3. 不要把完整 /chat/completions 写进 Base URL

不同版本 Open WebUI 的环境变量名可能有差异，具体以当前版本文档或后台设置为准。

四、后台界面配置方式

如果已经启动 Open WebUI，也可以在后台设置里配置连接。

常见填写：

API Base URL：https://example.com/v1 API Key：sk-xxxxxxxxxxxxxxxx Model：your-model

保存后先测试短消息：

你好

不要一开始就用长文本或复杂 Agent 流程测试。

五、容器内网络排查

一个很常见的问题：

宿主机 curl 能通 Open WebUI 里不通

这时要进入容器里测试。

docker exec -it open-webui sh

在容器里执行：

curl -sS "https://example.com/v1/models" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

如果容器内不通，问题可能是：

1. 容器 DNS 问题
2. 服务器网络问题
3. 代理没有传入容器
4. 防火墙或出站限制

这时不是 Open WebUI 配置问题，而是容器网络问题。

六、模型列表不显示怎么办

模型列表不显示，常见原因：

1. /models 接口请求失败
2. API Key 错误
3. Base URL 错误
4. Open WebUI 缓存未刷新
5. 当前服务不返回标准模型列表

排查：

curl -sS "https://example.com/v1/models" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

如果能返回模型列表，可以手动在 Open WebUI 中添加模型名。

七、常见错误

1. 401 Unauthorized

优先检查 API Key。

常见问题：

1. Key 复制不完整
2. Key 前后有空格
3. 错误添加了 Bearer
4. 后台配置没有保存

2. 404 Not Found

优先检查 Base URL。

正确：

https://example.com/v1

错误：

https://example.com/v1/chat/completions

3. model not found

先查模型列表，再复制模型名。

curl -sS "https://example.com/v1/models" \ -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

4. timeout

排查：

1. 宿主机 curl 是否能通
2. 容器内 curl 是否能通
3. 请求内容是否过长
4. 服务端响应是否慢
5. 代理或 DNS 是否正常

八、推荐排查顺序

宿主机 curl 查询 /models -> 宿主机 curl 最小对话 -> 配置 Open WebUI Base URL 和 Key -> 测试短消息 -> 容器内 curl 测试 -> 检查模型列表 -> 再测试真实任务

不要一开始就怀疑模型或客户端，先把网络和基础请求跑通。

九、总结

Open WebUI Docker 配置 OpenAI 兼容 API 时，最容易错的是：

1. Base URL 多写路径
2. API Key 没传进容器
3. 容器网络访问不到接口
4. 模型名和服务端不一致
5. Open WebUI 后台配置覆盖环境变量