Open WebUI OpenAI API base URL：Flatkey 设置指南

Open WebUI OpenAI API base URL 设置是一个小字段，它决定了 Open WebUI 是将聊天流量发送到单个上游提供商、本地模型服务器，还是像 Flatkey 这样的路由器。对于团队部署，该字段不应被视为简单的复制粘贴细节。应与 API 密钥、模型 ID、模型发现行为、聊天补全、流式传输和使用日志一起进行检查。

本指南专为希望使用 Open WebUI 将 Flatkey 作为 OpenAI 兼容模型路由器的开发人员、AI 产品团队、自动化构建者、平台工程师、财务运营商和采购审核员编写。它展示了当前的 Open WebUI 连接路径、需要验证的 Flatkey base URL、何时使用模型过滤器、如何运行 curl 预检，以及在向更多用户推广设置之前需要记录的内容。

来源说明：本文于 2026 年 6 月 29 日根据官方 Open WebUI OpenAI 兼容文档、实时 Flatkey 主页以及实时 Flatkey 定价页面进行了核对。在此运行时中没有可用的实时 Flatkey API 密钥或 Open WebUI 实例，因此以下命令是模板，需要使用您自己的密钥、模型别名和 Open WebUI 部署来运行。

快速解答：用于 Flatkey 的 Open WebUI OpenAI API base URL

对于 Flatkey 路由，请将 Open WebUI OpenAI API base URL 设置为您账户中当前的 Flatkey 提供商 base URL。本文查阅的 Flatkey 公开主页指出，应将 OpenAI 兼容的客户端指向 https://console.flatkey.ai/v1。在 Open WebUI 中，使用该 base URL，粘贴 Flatkey API 密钥，如果模型发现有问题或失败，则添加确切的 Flatkey 模型 ID，然后保存连接。

简而言之：配置 URL、密钥和模型过滤器，然后测试聊天请求并确认该请求出现在 Flatkey 使用记录中。本 Open WebUI OpenAI API base URL 指南的其余部分将其转化为一个可重复的设置和故障排除清单。

当前的 Open WebUI 文档确认了什么

Open WebUI 的官方 OpenAI 兼容指南指出，Open WebUI 可以连接到任何实现 OpenAI 兼容 API 的服务器或提供商。该文档将集成构建在标准协议之上，特别是 OpenAI 聊天补全协议，而不是为每个提供商都使用自定义模块。这使得 Flatkey 的配置成为一项关于 base URL、密钥和模型选择的任务。

同一指南给出了当前的管理员路径：打开 Open WebUI，进入 Admin Settings，然后是 Connections，接着是 OpenAI，然后点击 Add Connection。在那里，填写提供商 URL 和 API 密钥。如果自动模型发现不起作用，请将模型 ID 添加到 Model IDs (Filter) 并保存。

Open WebUI 的一个警告对于路由器设置尤其重要。添加连接时，Open WebUI 会通过提供商的 /models 端点使用标准不记名令牌进行验证。文档中说，一些提供商没有实现 /models，使用非标准行为，或者返回一个庞大而笨拙的模型列表。模型列表错误并不自动意味着聊天补全不兼容。这意味着您可能需要手动添加模型 ID 并直接测试聊天端点。

为了完全兼容，Open WebUI 将 /v1/models 列为推荐端点，将 /v1/chat/completions 列为必需的核心聊天端点。它还传递常见的 OpenAI 参数，例如 temperature、top_p、max_tokens 或 max_completion_tokens、stop、seed 和 logit_bias。当模型和服务器支持 tools 和 tool_choice 时，支持工具使用。

在更改 Open WebUI 之前需要验证的 Flatkey 值

于 2026 年 6 月 29 日查阅的 Flatkey 主页标题为 One API gateway for production AI teams，并描述了统一的模型访问、路由、计费、使用分析和操作控制。它还指出，团队应将 OpenAI 兼容的客户端指向 https://console.flatkey.ai/v1，并保留现有的 SDK 或客户端模式。

当天查看的 Flatkey 定价页面显示，其公共目录包含来自 23 个提供商的 633 个已启用的模型。它还公开了端点系列，包括 /v1/chat/completions、/v1/responses、/v1/messages、/v1/images/generations 和 /v1/video/generations。对于 Open WebUI 聊天，请从一个可通过聊天补全路径获得且已为您计划使用的密钥批准的模型开始。

不要假设每个目录模型都是一个好的 Open WebUI 模型。Open WebUI OpenAI API 基础 URL 指向一个路由器，但用户体验取决于所选的模型别名、端点支持、延迟、上下文行为、工具支持，以及模型是否能在 Open WebUI 的模型选择器中清晰地显示。

分步指南：将 Flatkey 添加为 OpenAI 连接

1. 选择 Open WebUI 范围。决定这是一个管理员范围的连接、一个测试实例，还是一个通过环境变量管理的自托管部署。
2. 创建或选择一个 Flatkey 密钥。为 Open WebUI 测试使用一个专用密钥，以便可以归因和限制使用量。
3. 选择一个起始模型。从 Flatkey 定价、Flatkey 控制台或您账户可见的模型列表中复制确切的模型别名。
4. 打开连接屏幕。在 Open WebUI 中，转到 Admin Settings > Connections > OpenAI > Add Connection。
5. 粘贴 Flatkey URL。如果您的账户确认，请使用 https://console.flatkey.ai/v1。该值应包含 /v1，但不应包含 /chat/completions。
6. 粘贴 Flatkey 密钥。使用为此 Open WebUI 部署创建的密钥，而不是个人提供商密钥或不相关的上游提供商密钥。
7. 在需要时添加模型 ID。如果模型发现失败、返回过多选项或公开了策略之外的模型，请将确切的已批准别名添加到 Model IDs (Filter)。
8. 保存并保留先前的路由。Open WebUI 允许启用或禁用连接，因此在测试时保留一个回滚路由。
9. 运行一个低风险提示。在 Open WebUI 中使用一个简单的提示，然后通过时间戳、密钥、模型、令牌计数和成本在 Flatkey 使用情况中确认请求。
10. 记录所有者。在扩大访问权限之前，记录谁拥有密钥、谁可以轮换密钥、批准了哪些模型以及适用什么配额。

可选的环境变量模板

如果您的部署是通过环境变量管理的，请使用您的 Open WebUI 版本和部署方法支持的名称。Open WebUI 的提供商示例显示了用于 OpenAI 兼容后端的 OPENAI_API_BASE_URL 和 OPENAI_API_KEY 模式，但管理面板也可以管理连接。请将其视为一个部署模板，并根据您的版本进行验证。

OPENAI_API_BASE_URL=https://console.flatkey.ai/v1
OPENAI_API_KEY=fk_replace_with_flatkey_key

如果您还通过 Open WebUI 路由嵌入、图像生成、语音或其他 OpenAI 风格的功能，请仅在确认 Flatkey 和所选模型支持该端点系列后，才配置那些特定于功能的基础 URL 和密钥变量。对于首次 Open WebUI OpenAI API 基础 URL 的部署，请将测试重点放在聊天补全上。

在归咎于 Open WebUI 之前，先对 Flatkey 路由进行预检

curl 预检可以将路由器和凭据问题与 Open WebUI UI 问题分离开来。请从与 Open WebUI 服务器相当的网络位置运行此命令。

export FLATKEY_API_KEY="fk_replace_me"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1"
export FLATKEY_OPEN_WEBUI_MODEL="replace-with-flatkey-model-alias"

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_OPEN_WEBUI_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "返回单词 ok。"
      }
    ],
    "stream": false,
    "max_tokens": 16
  }'

如果该请求失败，请在再次更改 Open WebUI 之前，修复 Flatkey 密钥、URL、模型别名、账户权限或网络路由。如果成功，请通过 Open WebUI 重复该操作，并比较 Flatkey 使用日志。

对于流式聊天体验，请单独测试流式传输。非流式响应证明该路由可以应答。但这并不能证明您的反向代理、Open WebUI 部署和客户端浏览器可以在没有缓冲或超时的情况下处理流式传输。

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_OPEN_WEBUI_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "流式传输三个简短的项目符号点。"
      }
    ],
    "stream": true,
    "max_tokens": 96
  }'

模型发现和筛选器清单

最安全的 Open WebUI OpenAI API 基础 URL 设置会有意使用模型筛选器。路由器可以公开许多模型，而一个宽泛的模型列表并不总是管理员希望用户看到的。

首先要调试的故障模式

Open WebUI 加 Flatkey 的生产运行手册

在为更广泛的群体更改 Open WebUI OpenAI API 基础 URL 之前，请记下支持所有权、回滚和成本审查的操作事实。

这在 Flatkey 工具集成集群中的位置

Open WebUI 只是可以使用 OpenAI 兼容路由的一个界面。如果您的团队正在对多个工具进行标准化，请在整个集群中使用相同的模式：一个当前的基础 URL，每个界面一个账户拥有的密钥，确切的模型别名，小范围的冒烟测试，用量证明和回滚说明。

对于相邻的设置，请参阅 Cherry Studio API 设置指南以了解桌面客户端基础 URL 的规范，参阅 CC Switch Claude Code Flatkey 指南以了解开发人员工具的路由，以及更广泛的 OpenAI 兼容 API 迁移手册以了解基础 URL 更改、模型别名验证和回滚。使用 Flatkey 定价来查看当前的模型和端点覆盖范围，然后获取一个密钥，用于拥有首次 Open WebUI 发布的工作区。

常见问题解答

我应该在 Open WebUI OpenAI API 基础 URL 字段中输入什么？

请使用您账户中当前的 Flatkey 提供商基础 URL。截至 2026 年 6 月 29 日检查的 Flatkey 公共主页将 OpenAI 兼容客户端指向 https://console.flatkey.ai/v1。请勿在基础 URL 字段中包含完整的 /chat/completions 路径。

为什么 Open WebUI 会显示模型发现错误？

Open WebUI 通过调用 /models 来验证新的 OpenAI 兼容连接。官方文档警告说，一些提供商没有实现该端点，使用非标准行为，或返回非常大的模型列表。如果聊天补全功能正常，请将确切的模型 ID 添加到过滤器中并再次测试。

我可以将每个 Flatkey 模型都暴露给 Open WebUI 吗？

技术上，一个路由器可以暴露许多模型，但生产环境的管理员应该从一个狭窄的允许列表开始。选择与 Open WebUI 聊天需求、端点支持、延迟预期、使用策略和预算控制相匹配的模型。

Flatkey 会取代 Open WebUI 的设置吗？

不会。Flatkey 提供 OpenAI 兼容的路由、密钥、模型访问、使用情况可见性和计费控制。Open WebUI 仍然控制其自身的连接设置、模型选择器、用户访问、提示行为和部署级网络。

我如何知道设置是否正常工作？

对 /chat/completions 运行 curl 预检请求，保存 Open WebUI 连接，发送一个安全的提示，并确认请求出现在 Flatkey 使用记录中，且包含预期的密钥、模型、时间戳、令牌、状态和成本。

最终检查清单

• 已从当前账户源确认 Flatkey 基本 URL。
• 已为 Open WebUI 部署创建专用的 Flatkey 密钥。
• 首先选择一个已批准的聊天模型别名。
• Open WebUI OpenAI API 基本 URL 设置为提供商的基本 URL，而不是完整的端点。
• 当发现失败或返回过多选项时，手动添加模型 ID。
• 已测试非流式和流式聊天。
• 在第一个 Open WebUI 提示后，已确认 Flatkey 使用记录行。
• 已记录所有者、配额、模型允许列表和回滚路径。

一旦这些检查通过，Open WebUI OpenAI API 基本 URL 就不再仅仅是一个连接字段。它变成了一个受控的 Flatkey 路由，拥有一个密钥、批准的模型、使用情况可见性和清晰的回滚计划。