Open WebUI API Key 怎么创建和调用？

更新于 2026-10-30 · gpt.boats

简答：Open WebUI API Key 的最短流程是：管理员开启 API Keys，非管理员获得对应功能权限，然后在 Settings > Account 创建密钥，用 Authorization: Bearer 请求 GET /api/models。返回 HTTP 200 且响应是有效 JSON，才算完成基础验证；401 优先查请求头和密钥，403 优先查权限或端点限制。本文按 2026-10-30 检索到的官方文档整理，菜单名称可能随版本变化。

定义：Open WebUI API Key 是绑定到某个 Open WebUI 用户的程序化访问凭证，外部脚本或客户端可用它调用该用户有权限访问的 Open WebUI API。

先完成三步：开启、创建、验证

本文是第三方 AI API 接入指南，不代表 Open WebUI 官方。假设你已经能打开自己的 Open WebUI 实例，并知道实例访问地址；下面的 https://your-open-webui.example 和 YOUR_API_KEY 都必须替换为实际值。

官方 API Keys 文档将管理员全局开关、非管理员功能权限和 Account 页面创建入口列为不同步骤；官方 API 端点文档则给出 GET /api/models 的 Bearer 调用方式。可分别查看 API Keys 官方文档 与 API Endpoints 官方文档。

使用 curl 时建议同时显示响应头和状态码：

curl -i -w "\nHTTP_STATUS=%{http_code}\n" -H "Authorization: Bearer YOUR_API_KEY" "https://your-open-webui.example/api/models"

判定标准如下：200 + 有效 JSON表示认证和该端点的基本访问闭环成立；200 + 空数组表示请求可能成功，但当前实例或账户没有可返回的模型；401重点检查密钥和请求头；403重点检查账户权限、全局开关和端点限制；返回 HTML 则先核对 Base URL、重定向和路径。

管理员开关与非管理员权限要分开处理

当前官方 API Keys 页面使用的管理员路径是 Settings > Admin > Authentication。打开 API Keys 后点击 Save，这是实例级总开关；官方文档说明，总开关关闭时，现有密钥也会停止认证。

非管理员用户还需要 API Keys 功能权限。官方文档给出两种路径：

1. 给所有普通用户授权：Admin Panel > Users > Groups > Default Permissions，在 Features Permissions 下打开 API Keys，然后保存。
2. 只给指定用户授权：进入 Admin Panel > Users > Groups，选择或创建用户组，在 Permissions > Features Permissions 中打开 API Keys，然后保存。

如果你看到的是旧版界面，菜单文字可能不同；不要把旧版路径当成当前版本固定路径。判断原则是：先找管理员的 Authentication 设置，再找用户组或 Default Permissions 下的 Features Permissions。官方 API Keys 页面同时列出了这两个权限层级，可作为版本差异下的核对依据。

环境变量方面，当前官方参考列出 ENABLE_API_KEYS，默认值为 False，并说明它替代已废弃的 ENABLE_API_KEY。它是 ConfigVar，首次启动后相关值可能被持久化配置覆盖；修改后应检查 Admin UI 当前值，而不是只看容器环境变量。详见 Environment Variable Configuration 官方参考。

在哪里创建 Open WebUI API Key？

登录 Open WebUI 后，点击左下角个人头像，选择 Settings > Account。滚动到 API keys 区域，点击 Secrets 旁边的 Show；该区域默认可能是折叠状态，看到标题但没有密钥输入框时，先点击 Show。然后点击 Create new secret key，使用复制按钮保存密钥。

根据当前官方 API Keys 文档，一个账户只有一个 API Key。再次创建会替换已有密钥，旧密钥立即停止工作；删除则使账户暂时没有可用密钥。官方文档还说明，账户中的 JWT Token 是浏览器会话令牌，不等同于 API Key。密钥轮换后，要同步更新脚本、环境变量、容器 Secret 和 CI/CD 配置。

如果 Account 页面完全没有 API keys 区域，按这个顺序检查：

1. 管理员是否在 Settings > Admin > Authentication 开启 API Keys。
2. 当前账户是否为非管理员；如果是，检查 Default Permissions 或指定用户组中的 API Keys 功能权限。
3. 页面是否只是折叠状态，点击 Show 后再判断。
4. 如果是通过环境变量配置，检查持久化配置是否覆盖了当前环境变量。

Open WebUI API Key、提供商 Key、JWT 和 WEBUI_SECRET_KEY 的区别

Open WebUI 快速开始文档把 WEBUI_SECRET_KEY 放在部署环境变量中，并说明固定该实例级密钥与容器重建后的登录状态有关；这不等于它可以替代 Account 页面生成的 API Key。相关部署说明见 Open WebUI Quick Start 官方文档。

Python requests 最小验证示例

下面只请求模型列表，不涉及聊天请求，适合先验证网络、Base URL、认证头和权限。先安装依赖：

python -m pip install requests

保存为 check_open_webui.py：

import os
import requests

base_url = os.environ.get("OPEN_WEBUI_URL", "https://your-open-webui.example").rstrip("/")
api_key = os.environ["OPEN_WEBUI_API_KEY"]

response = requests.get(
    f"{base_url}/api/models",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30,
)

print("HTTP_STATUS=", response.status_code)
print("CONTENT_TYPE=", response.headers.get("content-type"))
print(response.text[:1000])
response.raise_for_status()

Bash 或 zsh：

export OPEN_WEBUI_URL="https://your-open-webui.example"
export OPEN_WEBUI_API_KEY="替换为真实密钥"
python check_open_webui.py

PowerShell：

$env:OPEN_WEBUI_URL = "https://your-open-webui.example"
$env:OPEN_WEBUI_API_KEY = "替换为真实密钥"
python .\check_open_webui.py

不要把真实密钥写进源码、Git、截图、工单或命令历史。若密钥已经暴露，直接在 Account 页面创建新密钥，并立即更新所有调用方。

接入 OpenAI 兼容客户端时，Base URL 怎么判断？

Open WebUI 官方 API 参考明确列出 /api/models，同时说明 API 端点属于可能更新的实验性设置。因此，不能把某个客户端自动拼接的 /v1、/api 或其他路径当作所有工具的固定规则。

配置客户端时先填写三项：

• API Key：填写 Account 页面创建的 Open WebUI API Key，不要填写 WEBUI_SECRET_KEY、JWT 或模型提供商 Key。
• Base URL：填写当前实例实际可访问的地址；是否追加路径取决于客户端如何拼接请求。
• Model：先用 GET /api/models 返回的实际模型标识，不要根据显示名称猜测。

如果客户端请求失败，打开请求日志或使用 curl 复现，重点确认最终请求 URL 是否真的指向 /api/models 或当前版本支持的其他端点。官方端点页面还提醒，Swagger 文档需要在相应环境配置下访问，不要把浏览器前端地址自动等同于每个 API 端点的 Base URL。

反向代理占用 Authorization 时的处理方法

只有在直连请求正常、经过代理请求异常，或代理明确使用了 Authorization 做自身认证时，才考虑自定义请求头。先用 curl 直连 Open WebUI，记录状态码、Content-Type 和最终 URL；再检查代理是否转发了 Authorization 请求头。不要看到普通 401 就直接归因于反向代理。

当前官方环境变量参考显示，CUSTOM_API_KEY_HEADER 默认值为 x-api-key，它在进程启动时从环境变量读取，不是 ConfigVar。若代理确实占用了 Authorization，可以在 Open WebUI 容器中设置：

CUSTOM_API_KEY_HEADER=X-OpenWebUI-Key

重启实例后，用对应请求头验证：

curl -i -w "\nHTTP_STATUS=%{http_code}\n" -H "X-OpenWebUI-Key: YOUR_API_KEY" "https://your-open-webui.example/api/models"

官方认证顺序包括 Bearer Authorization、WebUI 使用的 token Cookie，以及由 CUSTOM_API_KEY_HEADER 指定的请求头。自定义请求头名称必须与容器启动配置和客户端发送的名称一致。

401、403、404 和环境变量不生效的分流表

当前官方环境变量参考明确说明，ENABLE_API_KEYS、ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS 和 API_KEYS_ALLOWED_ENDPOINTS 属于 ConfigVar；CUSTOM_API_KEY_HEADER 则从进程环境启动时读取。旧变量名可能仍出现在旧部署中，但新配置应以当前官方参考为准，不要直接复制旧变量。

端点限制与密钥轮换的安全做法

如果一个集成只需要少数接口，可以由管理员启用 ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS，再用 API_KEYS_ALLOWED_ENDPOINTS 设置逗号分隔的允许路径。官方参考示例包括 /api/v1/messages、/api/v1/channels 和 /api/v1/chat/completions；实际允许路径仍要结合当前版本和实例路由验证，不能把示例路径直接当成你部署中一定存在的端点。

官方 API Keys 文档说明，端点限制是实例级配置，不是每个 API Key 独立配置；因此配置前应先列出所有集成真正需要的路径。若只做模型列表检查，先验证 /api/models 是否在当前实例中可用，再决定是否加入限制。

同一账户只有一个 API Key，多个脚本不应共享管理员账户密钥。更稳妥的方式是给不同集成使用不同的非管理员账户，并分别创建密钥。密钥泄露时选择创建新密钥会立即替换旧密钥；彻底停用某个集成则删除该账户的密钥，并同步清理日志、环境变量和 CI/CD Secret。

版本与文档核对提示

本文按 2026-10-30 检索到的 Open WebUI 官方文档整理。官方页面当前给出了具体菜单路径和环境变量名称，但 Open WebUI 的界面、端点和配置项可能随版本变化；如果你的页面没有完全相同的文字，优先以当前实例的 Admin UI、官方 API Keys 页面和 Environment Variable Configuration 页面为准。

特别是 Settings > Admin > Authentication、Admin Panel > Users > Groups > Default Permissions、Settings > Account 三处分别对应全局开关、非管理员权限和个人密钥创建，不要把它们合并成一个入口。

常见问题

Open WebUI API Key 在哪里创建？

登录后点击左下角头像，进入 Settings > Account，展开 API keys 区域并点击 Show，再选择 Create new secret key。如果完全看不到该区域，先检查管理员是否在 Settings > Admin > Authentication 开启 API Keys；非管理员还要检查用户组或 Default Permissions 中的 API Keys 功能权限。

Open WebUI API Key 和模型提供商 API Key 是一回事吗？

不是。Open WebUI API Key 用于外部脚本或客户端访问当前 Open WebUI 实例；模型提供商 API Key 用于 Open WebUI 后端连接外部模型服务。两者用途、保存位置和认证对象不同。

为什么 Open WebUI API Key 返回 401？

先用 curl -i 检查请求是否使用 Authorization: Bearer YOUR_API_KEY，确认 Base URL 和 /api/models 路径没有拼错，再确认该账户的密钥没有被新密钥替换或删除。如果代理占用了 Authorization，再检查 CUSTOM_API_KEY_HEADER 配置。

为什么返回 403 而不是 401？

403 更应优先检查权限和端点限制：全局 API Keys 开关、非管理员的 API Keys 功能权限、账户或用户组权限，以及 ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS 和 API_KEYS_ALLOWED_ENDPOINTS。不要只重复复制密钥。

创建新密钥后旧密钥还能用吗？

当前官方 API Keys 文档说明，一个账户只有一个 API Key；创建新密钥会替换旧密钥，旧密钥立即停止工作。轮换后要更新所有脚本、环境变量、容器 Secret 和自动化任务。

WEBUI_SECRET_KEY 可以填到客户端的 API Key 字段吗？

不可以。WEBUI_SECRET_KEY 是实例级部署配置，不是外部调用凭证。客户端应填写 Settings > Account 中创建的 Open WebUI API Key。

为什么 GET /api/models 返回 200 但没有模型？

这说明 HTTP 请求可能已经通过基础认证，但不代表模型列表一定有内容。继续检查 Open WebUI 的模型连接、模型同步状态和当前账户可见权限，并区分空列表与 401/403。

相关阅读

• 继续查看 Open WebUI API 文档、端点与 curl/Python 调用示例
• 了解 API Key 的安全保存、环境变量与泄露处理
• 继续按 Key、权限和白名单排查 401 Unauthorized
• 需要接入兼容客户端时查看 LangChain 配置方法

参考资料

1. Open WebUI API Keys 官方文档（docs.openwebui.com）
2. Open WebUI API Endpoints 官方文档（docs.openwebui.com）
3. Open WebUI Environment Variable Configuration 官方参考（docs.openwebui.com）
4. Open WebUI Quick Start 官方文档（docs.openwebui.com）