让 AI 从“只动嘴“到“真动手“：Open WebUI 工具调用上手指南

让 AI 从"只动嘴"到"真动手"：Open WebUI 工具调用上手指南

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

Open WebUI 是一个可以自托管的大模型 Web 界面，支持 Ollama、OpenAI API 等多种后端。它最值得上手的能力是工具调用：模型在对话里能直接检索知识库、抓取网页、执行代码，而不是只和你"纸上谈兵"。下面从一个真实痛点讲起，5 分钟带你跑通第一把工具。

为什么需要工具：聊天模型的天花板

没有工具时有多别扭

你让 AI"翻一下这份文档里关于部署的段落"，它只能靠上下文硬答；你让它"算一下这段表达式的值"，它偶尔还会算错。问题出在两处：

• 知识有边界：模型不知道你的私有文档写了什么
• 能力有边界：不能上网、不能执行代码、不能读写文件

工具就是给模型配一双手

工具调用的本质，是让模型从"说"到"做"：能查、能算、能动手。

模型是怎么决定调哪个工具的

先破除一个迷思：不是"猜关键词"

你可能听过"模式匹配"的说法——说白了就是让系统猜你想干什么。但 Open WebUI 里这一步其实由模型自己完成：它读取工具清单里的描述，再根据你的问题决定调哪个、传什么参数。所以工具好不好用，关键在描述写得好不好。

工具 = 一张功能说明书

每个工具在后端都以"名称 + 参数 + 描述"的形式存储，定义见backend/open_webui/models/tools.py。这份描述就是给模型看的说明书，写得清楚，调用才准。

内置工具开箱即用

backend/open_webui/tools/builtin.py里已经备好了不少：execute_code执行代码、fetch_url抓取网页、query_knowledge_bases检索知识库、delegate_task委派子任务。只要你的模型支持原生函数调用，它们会自动生效。

一次工具调用的完整旅程

四步走完一个来回

1. 你输入问题
2. 模型输出一次结构化调用（工具名 + 参数），而不是普通文字
3. 后端按说明执行，执行逻辑在backend/open_webui/utils/tools.py
4. 结果回填对话，模型据此组织最终回答

前端负责"看"和"管"

src/lib/apis/tools/index.ts支撑管理页面里对工具的增删改查：你可以在那里查看每个工具的描述与参数、调整谁能使用它。

🧰 4 步写出你的第一个自定义工具

步骤不复杂

1. 在管理端 Tools 页面新建工具
2. 写一个 Python 函数，加上装饰器
3. 写清 docstring——这是模型判断"该不该用"的主要依据
4. 保存启用，用一句话验证它是否被正确调用

关键代码就这几行

@open_webui.tool async def get_time(timezone: str): """获取指定时区的当前时间"""

真正决定成败的是最后那行注释：把"能干什么、什么时候用"写明白，命中率会明显提升。

动手前容易踩的 3 个坑

⚠️ 坑 1：模型不支持函数调用

选了不支持原生工具调用的基础模型，你说得再清楚它也不会动手。先确认模型能力，再谈配置。

坑 2：描述写得太笼统

"查询数据"这种描述，模型根本不知道何时该用。改成"按关键词检索知识库并返回匹配段落"，效果天差地别。

坑 3：权限给得太松

工具支持按用户和群组控制访问（tools.py里的 access_grants 字段）。能写数据的工具，建议只授予可信成员。

现在就去试一把：登录管理端，打开 Tools，做一个"返回今天日期"的小工具。当模型真的把它调对的那一刻，你就掌握了工具调用的全部核心。

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