Open WebUI 工具调用实战指南：5 分钟跑通第一个自定义工具-编程实验室

Open WebUI 工具调用实战指南：5 分钟跑通第一个自定义工具

【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui

你让 AI"运行这段代码，把结果给我"，它却只能礼貌地回你一段文字——代码并没有真的跑起来。Open WebUI 的工具调用系统就是为这个痛点而生的：它让模型在对话中自己决定调用哪个函数，由服务端执行，再把真实结果塞回上下文继续对话。聊天没变，但 AI 从此会"干活"了。

AI 只会输出代码不会执行？让工具调用接管执行

说白了，模型本身不碰任何真实系统。整个机制用一个类比就能说透：模型是接线员，工具系统是总机。接线员永远不亲自接线，它只报一个分机号（函数名）和一句话（参数），总机负责真正拨出去，然后把通话结果传回来。

技术上对应的就是 native function calling：模型输出一段结构化的"函数调用"JSON，后端中间件拿到后找到对应的 Python 函数执行，结果作为新消息追加回上下文，模型第二次被调用时就能看到工具结果，再产出最终回答。模型全程只"报号"，执行全在后端。

跟一次完整调用：从输入框到工具返回的五个环节

按时间顺序，一次工具调用在 Open WebUI 里走过五步。

第一步，你在聊天框选中某个工具（或依赖内置工具）发出消息。第二步，请求进模型之前，聊天管道中间件backend/open_webui/utils/middleware.py组装本次可用的工具集：把你选中的自定义工具按权限过滤、按模型能力和功能开关注入内置工具、再把 MCP 服务器工具合进来。

第三步，backend/open_webui/utils/tools.py把每个函数转成模型能懂的"工具定义"（名字、参数、类型），同时把用户身份、聊天文件这类模型不该看见的隐藏参数绑定到函数上。第四步，模型决定调用，返回函数调用结构；中间件的tool_call_handler匹配到对应函数，异步执行，结果写回消息列表。第五步，模型带着工具结果被再次调用，给出最终答案。

三个关键设计决策：为什么工具是"代码"而不是"配置"

决策一：工具即源码，存数据库、按请求编译。问题：如果用户写个自定义工具就得改代码重启服务，插件生态不可能存在。方案：backend/open_webui/models/tools.py把工具整段 Python 源码存进tool表，请求时由插件加载器编译成模块，并在请求内按内容做缓存、内容变了自动重载。代价：任意 Python 在服务端执行本质是信任关系，所以整套机制被 ENABLE_PLUGINS 总开关和每个工具的 access grants 权限项双重把关。

决策二：规格从函数签名推导，而不是手写。问题：手写 schema 和真实函数代码一旦漂移，模型就会用错误的参数调用。方案：系统用 pydantic 直接根据函数的类型注解和 docstring 生成 OpenAI 风格函数定义，代码是唯一事实来源。代价：你的注解和 docstring 必须写干净，含糊的注释会得到含糊的工具定义，模型表现随之变差。

决策三：注入前按权限与能力三重过滤。问题：把机器上所有工具塞给每个模型，既烧 token 又让模型碰到不该碰的能力。方案：中间件组装时逐层过滤——用户对工具是否有读权限、模型是否声明支持该能力、功能开关是否打开，三者全过才注入。代价：过滤逻辑分散在多层，工具"神秘消失"时你得把三层都查一遍。

5 分钟跑通第一个自定义工具：最小上手路径

✅ 最短体验路径如下，四步走完。

拉取代码：git clone https://gitcode.com/GitHub_Trending/op/open-webui，按 README 用 docker compose 或直接脚本启动。
进入 Tools 页面新建工具，粘贴下面这个最小示例。
访问范围设为自己或 Everyone，保存。
在聊天输入框选中这个工具，问"帮我算 2 加 3"，你会看到模型调用add(2, 3)并返回 5。

def add(a: int, b: int) -> int: """Add two numbers together and return the result.""" return a + b

从 API 注册到 MCP 接入：扩展自定义工具的三个入口

写一个函数存进 Tools 页面，是最低门槛的扩展方式；需要编程化管理时，直接调backend/open_webui/routers/tools.py暴露的 create/update API 即可注册工具。函数需要管理员配置的运行时参数，就在源码里声明一个 pydantic 的Valves类，页面上会自动出现对应表单。已有 MCP 或 HTTP 工具服务器的场景，走 Connections 页面注册即可，不用写代码。