跳到主要内容

Open WebUI Integration

概述​

Open WebUI v0.6+ 支持通过 OpenAPI 服务器与外部工具进行无缝集成——这意味着您可以使用自定义或社区驱动的工具服务器轻松扩展您的 LLM 工作流 🧰。

在本指南中，您将学习如何启动一个兼容 OpenAPI 的工具服务器，并通过直观的用户界面将其连接到 Open WebUI。让我们立即开始吧！ 🚀

步骤 1：启动 OpenAPI 工具服务器​

首先，您需要启动 openapi-servers 仓库 中可用的参考工具服务器之一。为了快速测试，我们将以 time（时间）工具服务器为例。

🛠️ 示例：在本地启动 time 服务器

git clone https://github.com/open-webui/openapi-servers
cd openapi-servers

# 进入 time 服务器目录
cd servers/time

# 安装所需依赖
pip install -r requirements.txt

# 启动服务器
uvicorn main:app --host 0.0.0.0 --reload

启动后，这将在 http://localhost:8000 托管一个本地 OpenAPI 服务器，您可以将 Open WebUI 指向该地址。

Time Server

步骤 2：在 Open WebUI 中连接工具服务器​

接下来，将您正在运行的工具服务器连接到 Open WebUI：

  1. 在浏览器中打开 Open WebUI。
  2. 打开 ⚙️ Settings（设置）。
  3. 点击 ➕ Tools（工具）来添加一个新的工具服务器。
  4. 输入您的 OpenAPI 工具服务器正在运行的 URL（例如 http://localhost:8000）。
  5. 点击 "Save"（保存）。

Settings Page

🧑‍💻 用户工具服务器与 🛠️ 全局工具服务器​

在 Open WebUI 中有两种注册工具服务器的方法：

1. 用户工具服务器（通过常规设置添加）​

  • 仅对注册该工具服务器的用户可访问。
  • 连接由用户直接从浏览器（客户端）发起。
  • 非常适合个人工作流或测试自定义/本地工具。

2. 全局工具服务器（通过管理员设置添加）​

管理员可以管理在整个部署中对所有或选定用户可用的共享工具服务器：

  • 前往 🛠️ Admin Settings > Tools（管理员设置 > 工具）。
  • 像在用户设置中一样添加工具服务器 URL。
  • 这些工具的处理方式与 Open WebUI 的内置工具类似。

主要区别：请求是从哪里发起的？​

用户工具服务器与全局工具服务器的主要区别在于 API 连接和请求实际发起的物理位置：

  • 用户工具服务器

    • 发往工具服务器的请求是直接从您的浏览器（客户端）执行的。
    • 这意味着您可以安全地连接到 localhost URL（如 http://localhost:8000）——甚至暴露私有或仅限开发使用的端点（如本地文件系统或开发工具）——而无需冒着暴露给更广泛互联网或其他用户的风险。
    • 您的连接是隔离的；只有您的浏览器可以访问该工具服务器。

  • 全局工具服务器

    • 请求是从 Open WebUI 后端/服务器（而不是您的浏览器）发送的。
    • 后端必须能够访问您指定的工具服务器 URL——因此 localhost 指的是后端服务器的 localhost，不是您个人电脑的 localhost。
    • 使用此方式与整个部署中的其他用户共享工具，但请注意：由于后端发起请求，您无法通过此方法访问您的个人本地资源（如您自己的文件系统）。
    • 注意安全！仅暴露安全且旨在被多个用户访问的远程/全局端点。

总结表格：

工具服务器类型请求发起端是否允许使用 Localhost？使用场景示例
用户工具服务器用户的浏览器（客户端）是（对您私有）个人工具、本地开发/测试
全局工具服务器Open WebUI 后端（服务器端）否（除非运行在后端本身上）团队/共享工具、企业级集成
提示

用户工具服务器最适合个人或实验性工具，尤其是运行在您自己机器上的工具；而全局工具服务器则是生产环境或共享环境的理想选择，在这些环境中，每个人都需要访问相同的工具。

👉 可选：将配置文件与 mcpo 一起使用​

如果您通过 mcpo 使用配置文件运行多个工具，请注意：

🧩 每个工具都挂载在自己独特的路径下！

例如，如果您通过 mcpo 同时使用 memory（记忆）和 time（时间）工具，它们将分别在不同的路由下可用：

这意味着：

  • 在 Open WebUI 中连接工具时，您必须输入该特定工具的完整路由——不要只输入根 URL（http://localhost:8000）。
  • 在 Open WebUI 设置中使用它们各自的子路径 URL 分别添加每个工具。

MCPO Config Tools Setting

✅ 正确：

http://localhost:8000/time http://localhost:8000/memory

🚫 无效：

http://localhost:8000

这确保了 Open WebUI 能够正确识别每个工具服务器并与之通信。

步骤 3：确认您的工具服务器已连接 ✅​

一旦您的工具服务器成功连接，Open WebUI 将在消息输入区域直接显示一个 👇 工具服务器指示器：

📍 您现在将在输入框下方看到此图标：

Tool Server Indicator

点击此图标会打开一个弹出窗口，您可以在其中：

  • 查看已连接的工具服务器信息
  • 查看哪些工具可用以及它们由哪个服务器提供
  • 在需要时调试或断开任何工具的连接

🔍 以下是工具信息弹窗展开后的样子：

Tool Info Modal Expanded

🛠️ 全局工具服务器看起来不同——且默认是隐藏的！​

如果您连接了一个全局工具服务器（即管理员配置的服务器），它不会像用户工具服务器那样自动出现在输入区域中。

相反：

  • 全局工具默认是隐藏的，必须针对每个用户显式激活。
  • 要启用它们，您需要点击消息输入区域的 ➕ 按钮（聊天框的左下角），然后手动开启您想要使用的特定全局工具。

它看起来是这样的：

Global Tool Server Message Input

⚠️ 全局工具服务器的重要注意事项：

  • 在从 ➕ 菜单启用之前，它们不会显示在工具指示器弹出窗口中。
  • 必须单独开启每个全局工具，使其在您当前的聊天中处于活动状态。
  • 一旦开启，它们的功能与用户工具相同。
  • 管理员可以通过基于角色的权限来控制对全局工具的访问。

这非常适合团队设置或共享环境，在这些环境中，常用工具（例如文档搜索、记忆或网页查找）应该能够被多个用户集中访问。

（可选）步骤 4：使用“原生”函数调用（ReACT 风格）的工具使用 🧠​

信息

为了使其有效工作，您选择的模型必须支持原生工具调用。某些本地模型声称支持，但效果往往不佳。我们强烈建议使用 GPT-4o 或其他原生支持函数调用的 OpenAI 模型，以获得最佳体验。

想要在您的对话中直接启用 ReACT 风格（Reasoning + Acting，推理 + 行动）的原生函数调用吗？您可以将 Open WebUI 切换为使用原生函数调用（native function calling）。

✳️ 如何启用原生函数调用：

  1. 打开聊天窗口。
  2. 前往 ⚙️ Chat Controls > Advanced Params（聊天控制 > 高级参数）。
  3. 将 Function Calling（函数调用）参数从 Default 更改为 Native。

Native Tool Call

需要更多工具？探索与扩展！​

openapi-servers 仓库 包含各种有用的参考服务器：

  • 📂 文件系统访问
  • 🧠 记忆与知识图谱
  • 🗃️ Git 仓库浏览
  • 🌎 网页搜索（开发中）
  • 🛢️ 数据库查询（开发中）

您可以通过重复上述步骤，以相同的方式运行其中任何一个并将其连接到 Open WebUI。

故障排除与技巧 🧩​

添加 URL 后连接立即失败​

检查协议（HTTP 对比 HTTPS）。 “Add Tool Server”弹窗可能会在 URL 字段中预填 https://。大多数本地工具服务器不使用 TLS，因此您需要使用纯 http://。将 URL 更改为 http://localhost:8000（or 您的服务器使用的其他端口）。

检查端口号。 默认端口因服务器而异。例如，uvicorn 默认端口为 8000，而 Open Terminal 默认端口为 8888。确保 URL 中的端口与您的工具服务器实际监听的端口相匹配。

即使服务器正在运行，连接仍然失败​

理解“localhost”指的是哪台机器。 这是最常见的连接问题，取决于您注册的是哪种类型的工具服务器：

  • 用户工具服务器 — 请求来自您的浏览器。localhost 意味着运行您浏览器的机器。这通常适用于本地开发设置，但有一个例外情况（见下文）。
  • 全局工具服务器 — 请求来自 Open WebUI 后端。localhost 意味着后端服务器，而不是您的个人机器。如果后端在 Docker 中运行，容器内部的 localhost 无法访问您的宿主机——请改用 host.docker.internal 或机器的实际 IP 地址。
⚠️ 用户工具服务器：浏览器 IP 至关重要

即使对于用户工具服务器，仅当您在浏览器中以 http://localhost:... 访问 Open WebUI 时，localhost 才能正常工作。

如果您通过不同的 IP 地址访问 Open WebUI —— 例如，通过 http://10.0.0.5:3000 从局域网（LAN）中的另一台设备连接，或者使用 npm run dev 输出的网络 URL —— 那么相对于工具服务器而言，您的浏览器并不在 localhost 上。浏览器将尝试访问运行它的设备上的 localhost，而不是托管工具服务器的机器。

解决方法： 将 localhost 替换为运行工具服务器的机器 the 实际 IP 地址（例如 http://10.0.0.5:8000），并确保工具服务器绑定到 0.0.0.0（而不仅仅是 127.0.0.1）。

浏览器控制台中的 CORS 错误​

如果您看到 CORS 错误，您的工具服务器需要允许来自 Open WebUI 源地址的请求。关于 FastAPI 的示例，请参阅 关于 CORS 的 FAQ 条目。

通用技巧​

  • 🔒 如果您使用的是远程服务器，请检查防火墙和 HTTPS 配置。
  • 📝 为了让服务器在重启后持久化运行，请考虑在 Docker 中或通过系统服务部署它们。
  • 🔍 遇到疑问时，尝试在用于 Open WebUI 的同一个浏览器中直接打开工具服务器 URL（例如 http://localhost:8000/docs）——如果能够加载，说明浏览器可以正常访问它。

需要帮助？访问 👉 讨论页面 或 提交 Issue。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.