跳到主要内容

Open WebUI 集成

概览​

Open WebUI v0.6+ 支持通过 OpenAPI servers 无缝集成外部工具——这意味着你可以非常方便地使用自定义或社区提供的工具服务器来扩展自己的 LLM 工作流 🧰。

在本指南中，你将学习如何启动一个兼容 OpenAPI 的工具服务器，并通过直观的图形界面将其连接到 Open WebUI。开始吧！🚀

第 1 步：启动一个 OpenAPI 工具服务器​

首先，你需要启动 openapi-servers repo 中提供的某个参考工具服务器。为了便于测试，这里以 time 工具服务器为例。

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

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

# 进入 time server 目录
cd servers/time

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

# 启动 server
uvicorn main:app --host 0.0.0.0 --reload

启动后，它会在 http://localhost:8000 提供一个本地 OpenAPI 服务器，你可以把 Open WebUI 指向该地址。

Time 服务器

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

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

  1. 在浏览器中打开 Open WebUI
  2. 打开 ⚙️ 设置
  3. 点击 ➕ 工具 添加一个新的工具服务器
  4. 输入你的 OpenAPI 工具服务器运行地址（例如 http://localhost:8000）
  5. 点击 “保存”

设置页面

🧑‍💻 用户级工具服务器 vs. 🛠️ 全局工具服务器​

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

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

  • 仅对注册该工具服务器的用户可见
  • 连接由用户浏览器直接发起（client-side）
  • 非常适合个人工作流，或测试自定义 / 本地工具

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

管理员可以把共享工具服务器配置给整个部署中的所有用户或部分用户：

  • 前往 🛠️ 管理员设置 > 工具
  • 按和普通用户设置相同的方式添加工具服务器 URL
  • 这些工具的行为与 Open WebUI 自带工具类似

核心区别：请求是从哪里发出的？​

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

  • 用户级工具服务器

    • 请求由你的浏览器直接发出
    • 这意味着你可以安全地连接 localhost 地址（如 http://localhost:8000）——甚至暴露你自己的本地文件系统或开发环境 endpoint，而不会把它们暴露给外网或其他用户
    • 你的连接是隔离的，只有你的浏览器可以访问该工具服务器

  • 全局工具服务器

    • 请求由 Open WebUI 后端 / 服务器 发出，而不是浏览器
    • 因此这里的 localhost 指的是后端服务器自身，而不是你的个人电脑
    • 适合需要在整个部署中共享的工具，但要注意：由于是后端发请求，所以它不能通过这种方式访问你个人电脑上的本地资源（例如你自己的文件系统）
    • 因此在安全上要格外注意：只暴露那些适合被多个用户访问的远程 / 全局 endpoint

总结表：

工具服务器类型请求来源是否可用 Localhost典型场景
用户级工具服务器用户浏览器（Client-side）可以（仅你可用）个人工具、本地开发 / 测试
全局工具服务器Open WebUI 后端（Server-side）不可以（除非它本身就跑在后端机器上）团队共享工具、企业集成
提示

用户级工具服务器更适合个人或实验性工具，特别是运行在你自己机器上的工具；全局工具服务器则更适合生产环境或共享部署，让所有人都能访问同一组工具。

👉 可选：结合 mcpo 使用配置文件​

如果你通过 mcpo 配置文件同时运行多个工具，需要注意：

🧩 每个工具都会挂载到一个独立路径下！

例如，如果你通过 mcpo 同时运行 memory 和 time 两个工具，它们会分别出现在不同 route 上：

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

这意味着：

  • 在 Open WebUI 中连接工具时，你必须填写该工具的完整路径
  • 不要只填写根 URL（http://localhost:8000）
  • 你需要在 Open WebUI Settings 中用各自的子路径 URL 分别添加每个工具

MCPO 配置工具设置

✅ 正确示例：

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

🚫 错误示例：

http://localhost:8000

这样 Open WebUI 才能正确识别并连接到每个独立的工具服务器。

第 3 步：确认工具服务器已连接成功 ✅​

当工具服务器成功连接后，Open WebUI 会在消息输入区域直接显示一个 👇 工具服务器指示器：

📍 你会在输入框下方看到这个图标：

工具服务器指示器

点击该图标后，会弹出一个窗口，你可以：

  • 查看已连接工具服务器的信息
  • 查看有哪些工具可用，以及它们来自哪个服务器
  • 在需要时调试或断开某个工具

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

工具信息弹窗展开

🛠️ 全局工具服务器的显示方式不同——而且默认隐藏！​

如果你连接的是全局工具服务器（也就是管理员配置的工具），它不会像用户级工具服务器一样自动出现在输入区域。

相反：

  • 全局工具默认是隐藏的，必须按用户手动启用
  • 你需要点击聊天输入框左下角的 ➕ 按钮，并手动打开你想使用的特定全局工具

效果如下：

全局工具服务器消息输入

⚠️ 关于 Global Tool Servers 的重要说明：

  • 在你从 ➕ 菜单启用之前，它们不会显示在工具指示器弹窗中
  • 每个全局工具都必须单独打开，才能在当前聊天中生效
  • 一旦启用，它们的使用方式就和用户级工具一样
  • 管理员可通过基于角色的权限控制来限制全局工具访问

这非常适合团队场景或共享环境：例如文档检索、memory 或 web lookup 这类常用工具，可以集中提供给多个用户使用。

（可选）第 4 步：启用 “Native” Function Calling（ReACT 风格）🧠​

信息

要想让它真正好用，你所选的模型必须支持原生工具调用。某些本地模型虽然声称支持，但实际效果往往较差。为了获得最佳体验，我们强烈建议使用 GPT-4o 或其他原生支持函数调用的 OpenAI 模型。

如果你希望在对话中直接启用 ReACT 风格（Reasoning + Acting）的原生函数调用，可以把 Open WebUI 切换到原生函数调用。

✳️ 启用方式：

  1. 打开聊天窗口
  2. 前往 ⚙️ 聊天控制 > 高级参数
  3. 将 函数调用 参数从 Default 改为 Native

原生工具调用

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

openapi-servers repo 中还提供了多种有用的参考服务器：

  • 📂 文件系统访问
  • 🧠 Memory 与知识图谱
  • 🗃️ Git 仓库浏览
  • 🌎 Web 搜索（WIP）
  • 🛢️ 数据库查询（WIP）

你可以按同样方式运行任意一个，并重复上述步骤把它接入 Open WebUI。

故障排查与建议 🧩​

添加 URL 后立刻连接失败​

先检查协议（HTTP vs HTTPS）。 “添加工具服务器” 弹窗可能会默认填入 https://。但大多数本地工具服务器并未启用 TLS，因此你需要改成普通的 http://。例如改为 http://localhost:8000（或你的实际端口）。

再检查端口号。 默认端口取决于 server 实现。例如 uvicorn 默认是 8000，而 Open Terminal 默认是 8888。请确认你填入的 URL 中端口与实际监听端口一致。

明明 server 在运行，但依然连接失败​

理解 “localhost” 指向的是哪台机器。 这是最常见的问题，而且会随工具服务器类型不同而变化：

  • 用户级工具服务器 —— 请求来自你的浏览器。这里的 localhost 指的是运行浏览器的那台机器
  • 全局工具服务器 —— 请求来自 Open WebUI 后端。这里的 localhost 指的是后端服务器本身，而不是你的电脑。如果后端跑在 Docker 中，那么容器里的 localhost 不会指向宿主机——此时应改用 host.docker.internal 或后端服务器实际 IP
用户级工具服务器：浏览器所在地址也很重要

即使是用户级工具服务器，只有当你在浏览器中通过 http://localhost:... 访问 Open WebUI 时，localhost 才通常会正常工作。

如果你访问 Open WebUI 用的是其他 IP 地址——例如通过局域网里的 http://10.0.0.5:3000 从另一台设备访问，或者使用 npm run dev 输出的 network URL——那么此时浏览器眼中的 localhost 就不是工具服务器所在机器，而是浏览器当前运行的设备。

解决办法： 把 localhost 换成实际运行工具服务器那台机器的 IP（例如 http://10.0.0.5:8000），并确保工具服务器绑定在 0.0.0.0 上，而不是仅绑定到 127.0.0.1。

浏览器控制台出现 CORS 错误​

如果你看到了 CORS 报错，说明工具服务器需要允许来自 Open WebUI origin 的请求。你可以查看 FAQ 中关于 CORS 的条目，其中提供了 FastAPI 示例。

通用建议​

  • 🔒 如果你使用远程服务器，请检查防火墙与 HTTPS 配置
  • 📝 如果你希望服务器在重启后仍保持运行，建议用 Docker 或系统服务来部署
  • 🔍 不确定时，直接在同一个浏览器中打开工具服务器 URL（例如 http://localhost:8000/docs）——如果能打开，说明浏览器能访问该服务器

需要帮助？请访问 👉 Discussions 页面 或 提交 issue。

本内容仅供参考，不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议 以了解适用条款。