跳到主要内容

OPL 数据空间集成

概览​

OPL 数据空间 v0.6+ 支持通过 OpenAPI tool servers 无缝接入外部工具。这意味着你可以很容易地把自定义或社区提供的工具服务器挂进 OPL 数据空间，扩展 LLM 工作流。

本页会带你完成两件事：

  1. 启动一个 OpenAPI 兼容的工具服务器
  2. 在 OPL 数据空间里把它接进来

第一步：启动一个 OpenAPI Tool Server​

你可以先从 openapi-servers repo 中的参考服务器开始。这里用 time server 作为演示。

git clone https://github.com/open-webui/openapi-servers
cd openapi-servers
cd servers/time
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --reload

启动后，本地 OpenAPI 服务通常会在 http://localhost:8000 上可用。

Time Server

第二步：在 OPL 数据空间中连接工具服务器​

  1. 在浏览器中打开 OPL 数据空间
  2. 打开 ⚙️ 设置
  3. 点击 ➕ 扩展功能
  4. 输入你的 OpenAPI 工具服务器 URL，例如 http://localhost:8000
  5. 点击保存

Settings Page

用户工具服务器 vs 全局工具服务器​

OPL 数据空间里有两种注册方式：

1. 用户工具服务器​

通过普通 设置 添加。

  • 仅当前注册用户可见
  • 请求由浏览器端直接发出
  • 适合个人工作流、本地工具、开发测试

2. 全局工具服务器​

通过 Admin Settings → Tools 添加。

  • 可供整个部署中的所有用户或指定用户使用
  • 请求由 OPL 数据空间后端发出
  • 适合共享工具、企业级集成、团队环境

两者最关键的区别：请求从哪里发出​

类型请求发起位置可以直接用 localhost 吗典型用途
用户工具服务器用户浏览器可以，且只对自己可见个人工具、本地开发
全局工具服务器OPL 数据空间后端只有后端本机能访问时才行团队共享工具、企业接入

用户工具服务器​

  • 请求从你的浏览器发出
  • 这意味着如果你的工具服务器跑在本机，浏览器通常可以直接访问 http://localhost:8000
  • 因为它是浏览器直接连，所以不会暴露给其他用户

全局工具服务器​

  • 请求从 OPL 数据空间后端发出，不是从浏览器
  • 这里的 localhost 指的是后端所在机器，而不是你的个人电脑
  • 如果后端运行在 Docker 中，那么容器内的 localhost 也不是宿主机的 localhost
提示

用户工具服务器更适合个人或实验性质的本地工具；全局工具服务器更适合生产环境和多人共享。

mcpo 配置文件模式的额外注意事项​

如果你通过 mcpo 的配置文件同时暴露多个工具，每个工具会挂在自己的子路径下，例如：

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

这意味着：

  • 在 OPL 数据空间中要填完整的子路径
  • 不能只填根路径 http://localhost:8000

✅ 正确：

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

🚫 错误：

  • http://localhost:8000

MCPO Config Tools Setting

第三步：确认连接成功​

连接成功后， OPL 数据空间会在消息输入区域显示工具服务器指示器。

Tool Server Indicator

点击后可以：

  • 查看已连接工具服务器信息
  • 查看有哪些可用工具
  • 做基本调试或断开连接

Tool Info Modal Expanded

全局工具服务器的显示行为不同​

全局工具默认不会像用户工具那样立刻出现在输入区。它们默认是隐藏的，需要当前用户在聊天里手动启用：

  1. 点击消息输入区左下的 ➕
  2. 打开可用工具列表
  3. 手动启用需要的全局工具

Global Tool Server Message Input

注意：

  • 没有启用前，它们不会出现在 tool indicator 里
  • 每个全局工具都需要单独打开
  • 打开后，用法与普通用户工具一致
  • 管理员仍可通过角色权限控制访问范围

可选：启用 Native Function Calling​

信息

要获得更好的体验，所选模型需要真正支持原生 tool calling。很多本地模型虽然“宣称支持”，但实际效果不稳定。更稳妥的选择是 GPT-4o 或其他原生支持函数调用的 OpenAI 模型。

如果你想让模型直接进行 ReACT 风格的原生工具调用，可以把 Function Calling 切到 Native：

  1. 打开聊天窗口
  2. 进入 ⚙️ Chat Controls → Advanced Params
  3. 将 Function Calling 从 Default 改为 Native

Native Tool Call

需要更多工具​

openapi-servers repo 中还提供了其他参考服务器，例如：

  • 文件系统访问
  • 记忆与知识图谱
  • Git 仓库浏览
  • Web 搜索（WIP）
  • 数据库查询（WIP）

用法和接入步骤都与上面类似。

排障与提示​

刚添加 URL 就连接失败​

先检查协议：

  • 添加工具时输入框可能默认补全成 https://
  • 但大多数本地工具服务器并没有 TLS
  • 这时应改成 http://localhost:8000

再检查端口：

  • uvicorn 默认一般是 8000
  • 某些工具可能用其他端口，例如 Open Terminal 常见为 8888

服务明明启动了，但还是连接失败​

最常见问题是：你理解错了 localhost 指的是哪台机器。

用户工具服务器​

  • 请求从浏览器发出
  • localhost 指运行浏览器的那台机器
  • 如果你访问 OPL 数据空间用的是 http://localhost:3000，通常没问题

全局工具服务器​

  • 请求从OPL 数据空间后端发出
  • localhost 指后端服务器自身
  • 如果后端在 Docker 中，容器内 localhost 通常无法访问宿主机上的本地工具服务
  • 这时要改用 host.docker.internal 或实际机器 IP
用户工具服务器也会受浏览器访问地址影响

即便是用户工具服务器，如果你访问 OPL 数据空间的地址不是 localhost，而是局域网 IP，例如 http://10.0.0.5:3000，那么浏览器里的 localhost 就是“当前使用浏览器的设备”，不一定是跑 Tool Server 的那台机器。

修复方法：

  • 把 localhost 改成实际运行工具服务器那台机器的 IP，例如 http://10.0.0.5:8000
  • 同时确保工具服务器绑定到 0.0.0.0，而不是仅绑定 127.0.0.1

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

说明你的工具服务器没有允许 OPL 数据空间所在来源发起请求。可参考 FAQ 中关于 CORS 的说明。

通用建议​

  • 远程服务要检查防火墙与 HTTPS 配置
  • 若希望重启后仍可用，优先用 Docker 或系统服务管理
  • 不确定时，直接在同一个浏览器里打开工具服务器的 /docs 页面测试；如果浏览器能打开，通常说明浏览器侧可达

需要帮助时，可访问 Discussions 或 提交 issue。