什么是 Tools？

⚠️ 关键安全警告

Workspace Tools 和 Functions 会在您的服务器上执行任意 Python 代码。 只能从受信任的来源安装，在导入之前检查代码，并仅限受信任的管理员访问 Workspace。授予用户创建或导入 Tools 的能力相当于赋予他们对服务器的 shell 访问权限。有关完整详细信息，请参阅 Plugin 安全警告。

⚙️ Tools 是您在简单文本生成之外扩展 LLM 能力的各种方式。启用后，它们允许您的聊天机器人完成惊人的事情——例如搜索网页、抓取数据、生成图像、使用 AI 语音进行对话等。

因为在 Open WebUI 中有几种集成“Tools”的方法，所以了解您正在使用哪种类型非常重要。

---

工具分类法：你正在使用哪种“工具”？

🧩 用户经常在不同的语境中遇到“Tools”这个词。以下是区分它们的方法：

类型	UI 中的位置	最适合...	来源
原生功能	Admin/Settings	核心平台功能	内置于 Open WebUI
Workspace Tools	Workspace > Tools	用户创建或社区的 Python 脚本	社区库
原生 MCP (HTTP)	Settings > Connections	可通过 HTTP/SSE 访问的标准 MCP 服务器	外部 MCP 服务器
MCP via Proxy (MCPO)	Settings > Connections	本地基于 stdio 的 MCP 服务器（例如，Claude Desktop 工具）	MCPO 适配器
OpenAPI 服务器	Settings > Connections	标准 REST/OpenAPI Web 服务	外部 Web API
Open Terminal	Settings > Integrations	隔离 Docker 容器中的完整 shell 访问（始终开启）	Open Terminal

1. 原生功能（内置）

这些功能深度集成在 Open WebUI 中，通常不需要外部脚本。

• 网页搜索：通过 SearXNG、Google 或 Tavily 等引擎集成。
• URL 获取：使用 # 或原生工具直接从网站提取文本内容。
• 图像生成：与 DALL-E、ComfyUI 或 Automatic1111 集成。
• Memory：模型跨聊天记住关于您的事实的能力。
• RAG (Knowledge)：查询已上传文档（#）的能力。

在 Native Mode（原生模式）下，这些功能将作为模型可以独立调用的 Tools 暴露出来。

2. Workspace Tools（自定义插件）

这些是直接在 Open WebUI 环境中运行的 Python 脚本。

• 功能：可以执行 Python 能做的任何事情（网页抓取、复杂数学计算、API 调用）。
• 访问：通过 Workspace 菜单进行管理。
• 安全：在导入之前务必检查代码，因为这些脚本在您的服务器上运行。
• ⚠️ 安全警告：普通或不受信任的用户不应被授予访问 Workspace Tools 部分的权限。该访问权限允许用户在您的服务器上上传和执行任意 Python 代码，这可能导致系统完全被攻破。

3. MCP (Model Context Protocol)

🔌 MCP 是一个开放标准，允许 LLM 与外部数据和工具进行交互。

• 原生 HTTP MCP：Open WebUI 可以直接连接 to 任何暴露了 HTTP/SSE 端点的 MCP 服务器。
• MCPO (Proxy)：大多数社区 MCP 服务器使用 stdio（本地命令行）。要在 Open WebUI 中使用这些服务，您需要使用 MCPO Proxy 来桥接连接。

4. OpenAPI / 函数调用服务器

提供 OpenAPI（.json 或 .yaml）规范的通用 Web 服务器。Open WebUI 可以摄取这些规范，并将每个端点视为一个工具。

---

如何安装和管理 Workspace Tools

📦 Workspace Tools 是通过社区功能扩展您的实例最常用的方式。

1. 前往 社区工具库
2. 选择一个 Tool，然后点击 Get 按钮。
3. 输入您的 Open WebUI 实例的 URL（例如 http://localhost:3000）。
4. 点击 Import to WebUI。

安全提示

切勿导入您不认识或不信任的 Tool。这些是 Python 脚本，可能会在您的宿主系统上运行不安全的代码。至关重要的是，确保您仅向受信任的用户授予“Tool”权限，因为创建或导入 tools 的能力相当于在服务器上运行任意代码的能力。

---

如何在聊天中使用 Tools

🔧 一旦安装或连接，以下是为您的对话启用它们的方法：

选项 1：即时启用（针对特定聊天）

在聊天时，点击输入区域的 ➕ (加号) 图标。您将看到可用 Tools 的列表——您可以专门为该会话启用它们。

选项 2：默认启用（全局/模型级别）

1. 前往 Workspace ➡️ Models。
2. 选择您正在使用的模型，然后点击 ✏️ 编辑图标。
3. 滚动到 Tools 部分。
4. ✅ 勾选您希望该模型默认始终可以访问的 Tools。
5. 点击 Save。

对于支持该功能的模型，Native tool calling mode（原生工具调用模式，见下文 Tool Calling Modes）允许模型本身决定在每轮对话中调用哪些已附加的工具。这取代了较旧的提示词注入“自动工具”过滤方法，是让模型自动选择工具的推荐方式。

附加的 Tools 仍需要用户访问权限

将 workspace tool 附加到模型中并不能绕过访问控制。当用户与模型聊天时，Open WebUI 会检查该特定用户是否对每个附加的 tool 拥有读取权限。用户无法访问的 Tools 将被默默跳过——模型将无法调用它们。

示例场景：管理员创建了一个私有 tool，并将其附加到与所有用户共享的模型中。与该模型聊天的普通用户将无法使用该 tool，因为他们没有该 tool 本身的读取权限。

解决方案：确保需要使用模型 tools 的用户也对每个 tool 拥有读取权限（通过访问授权、组权限或将 tool 设置为公开）。"Workspace → Tools" 权限控制用户是否可以创建和管理 tools，它不影响附加到模型的 tools 是否对他们有效。

---

工具调用模式：Default 与 Native

Default 模式已过时且不再支持——请使用 Native 模式

所有模型都应配置为 Native (Agentic) 模式。 Default 模式是一种遗留的提示词注入回退方案，其出现早于 LLM 中广泛的原生函数调用支持。它不再受支持：它不会再接收功能开发、错误修复或内置系统工具，并且与现代 Open WebUI 功能不兼容（如 Agentic Research、Interleaved Thinking、内置 Memory/Notes/Knowledge/Channels 工具、网页搜索/图像生成/代码解释器工具注入）。

Default 模式在下拉菜单中仍然存在，仅为了让具有较旧工具代码路径的实例保持运行，以便管理员进行迁移。如果您的部署仍处于 Default 模式，请将每个模型切换到 Native 模式（见下文 如何启用 Native 模式）。如果特定模型在 Native 模式下遇到问题，正确的解决方法是为工具调用选择更好的模型，而不是退回到 Default 模式。

Open WebUI 在 Model Settings → Advanced Params → Function Calling 中提供了两种模式：Native Mode (Agentic Mode)（唯一受支持的模式）和 Default Mode（仅为了向后兼容而保留在 UI 中）。

🔴 Default 模式（基于提示词）—— 遗留 / 不再受支持

不再受支持

Default 模式是遗留的且不再受支持。在此处记录仅供参考。新的部署必须使用 Native 模式；现有部署应进行迁移。关于 Default 模式行为的错误报告、功能需求和支持问题将不予处理。

在 Default 模式下，Open WebUI 通过注入长提示词模板来管理工具选择，该模板引导模型以特定格式输出工具请求。在 2023 年这是一种合理的方法；但自主流提供商和开源权重模型获得适当的函数调用 API 以来，它已过时。

为什么它是遗留的：

• 破坏 KV cache。 注入的提示词每轮都会改变，阻止 LLM 引擎重用缓存的键值对。每条消息都必须重新支付完整的 prefill（首字延迟）成本。
• 更高的延迟和 token 成本。 每轮对话中都有冗长的工具描述提示词。
• 对于多步链式调用不可靠。 与结构化工具调用相比，解析自然语言工具请求非常脆弱。
• 无法访问内置系统工具。 Memory、Notes、Knowledge、Channels、Agentic Research、Interleaved Thinking 以及工具注入的 Web Search / Image Generation / Code Interpreter 功能都是 Native 专用的。
• 不支持现代能力。 自 2024 年以来发布的所有新功能都以 Native 模式为目标。

🟢 Native 模式（Agentic 模式 / 系统函数调用）—— 唯一受支持的模式

Native 模式（也称为 Agentic 模式）利用模型内置的能力来处理工具定义并返回结构化工具调用（JSON）。对于所有支持它的模型，这是推荐的模式——这包括了绝大多数现代模型（2024年及以后）。

模型质量至关重要

Agentic 工具调用需要高质量的模型才能可靠运行。 虽然小型本地模型在技术上可能支持函数调用，但它们通常难以应对多步工具使用所需的复杂推理。为了获得最佳效果，请使用前沿模型，例如 GPT-5、Claude 4.5 Sonnet、Gemini 3 Flash 或 MiniMax M2.5。小型本地模型可能会产生格式错误的 JSON，或者无法遵循 Agentic 行为所需的严格状态管理。

为什么使用 Native 模式（Agentic 模式）？

• 速度与效率：更低的延迟，因为它避免了繁琐的基于提示词的工具选择。
• 对 KV Cache 友好：工具定义作为结构化参数发送（而不是注入到提示词中），因此它们不会使两轮之间的 KV cache 失效。这可以显着降低延迟和 token 成本。
• 可靠性：在遵循工具 schema（配合优质模型）方面具有更高的准确度。
• 多步链式调用：对于 Agentic Research 和 Interleaved Thinking 至关重要，在这些场景中，模型需要连续调用多个工具。
• 自主决策：模型可以决定何时搜索、使用哪些工具以及如何合并结果。
• 系统工具：只有 Native 模式才能解锁 内置系统工具（memory、notes、knowledge、channels 等）。

如何启用 Native 模式（Agentic 模式）

Native 模式可以在两个级别启用：

1. 每个模型的通用默认值（最快——推荐）：
   • 导航到 Admin Panel ➡️ Settings ➡️ Models。
   • 点击模型列表右上方的 Settings 按钮——这将打开全局模型参数，除非特定模型重写了它们，否则这些参数将应用于您实例中的每一个模型（当前和未来）。
   • 在 Model Parameters 下，将 Function Calling 设置为 Native。
   • 保存。所有尚未显式设置自己参数的现有模型，以及您以后添加的所有模型，都将继承 Native。您不需要逐一编辑它们。
2. 单模型覆盖：
   • 在 Admin Panel ➡️ Settings ➡️ Models 中，选择一个特定模型并点击其编辑按钮。
   • 在 Model Parameters 下，将 Function Calling 设置为 Native。此值仅覆盖该特定模型的全局默认值。
   • 当特定模型需要不同的参数时使用此方法——否则首选全局设置。
3. 单聊天覆盖：
   • 在聊天中，打开 Chat Controls（右侧边栏）。
   • 在 Advanced Params 下，将 Function Calling 设置为 Native。仅应用于该聊天。

一次性为所有模型全局设置 Function Calling

厌倦了逐一将每个模型切换到 Native？全局模型参数面板（Admin Panel ➡️ Settings ➡️ Models 右上角的 Settings 按钮）允许您为 Open WebUI 实例中的每个模型配置任何模型参数——function_calling、temperature、top_p、max_tokens 等。在此处设置的值将成为尚未覆盖它们的每个现有模型以及您以后添加的每个模型的默认值。在此处设置 Function Calling = Native，保存，搞定。

模型要求与注意事项

推荐用于 Agentic 模式的模型

为了实现可靠的 Agentic 工具调用，请使用高阶前沿模型：

• GPT-5 (OpenAI)
• Claude 4.5 Sonnet (Anthropic)
• Gemini 3 Flash (Google)
• MiniMax M2.5

这些模型在多步推理、正确的 JSON 格式化和自主工具选择方面表现出色。

• 大型本地模型：大型本地模型（例如 Qwen 3 32B、Llama 3.3 70B、DeepSeek V3/R1）在 Native 模式下工作良好；结果随模型质量而提升。
• 小型本地模型：小型本地模型（参数量在 ~30B 以下）即使在 Native 模式下也经常产生格式错误的 JSON，或者在多步工具链中失败。解决方法是为工具调用工作负载使用更强的模型，而不是退回到 Default 模式——Default 是遗留且不受支持的。如果您的硬件迫使您使用小型模型，请接受在该级别工具调用将是不可靠的，或者仅将使用工具的对话分流到云端模型。

已知特定模型问题

DeepSeek V3.2 函数调用问题

DeepSeek V3.2 在原生函数调用方面存在已知问题，会导致可复现的失败。尽管它是 600B+ 参数模型，但它经常输出格式错误的工具调用。

问题所在：DeepSeek V3.2 在训练时使用了一种名为 DSML (DeepSeek Markup Language) 的专有格式来进行工具调用。当使用原生函数调用时，该模型有时会输出原始的 DSML/XML 样式的语法，而不是正确的 JSON：

• <functionInvoke name="fetch_url"> 而不是有效的 JSON
• 内容中的 <function_calls> / </function_calls> 标签
• 混乱的混合文本，如 prominentfunction_cinvoke name="search_parameter

原因为何：这是在 DeepSeek 的微调过程中引入的重度依赖模型行为。DeepSeek 选择在其 DSML 上训练模型，而不是标准的 OpenAI 样式的 JSON 工具调用。虽然推理提供商（VertexAI、OpenRouter 等）尝试拦截 DSML 块并将其转换为 OpenAI 样式的 JSON，但这种翻译层在某些条件下（流式传输、高 temperature、高并发、多轮对话）是不可靠的。主要责任在于 DeepSeek，因为它使用了一种需要脆弱翻译的非标准格式。

已知的促成因素：

• 较高的 temperature 值与更多格式错误的输出呈正相关
• 多轮对话（6-8 轮以上）可能会导致模型完全停止调用函数
• 复杂的多步工作流（15-30 次工具调用）可能会导致“schema 漂移”，从而使参数格式退化

变通方法：

• 为 Agentic 工作负载使用不同的模型。 Claude 4.5 Sonnet、GPT-5、Gemini 3 Flash 和 MiniMax M2.5 在 Native 模式下均非常可靠，并且是 DeepSeek V3.2 表现不佳时的推荐选择。
• 在对 DeepSeek V3.2 使用工具调用时降低 temperature。
• 限制多轮工具调用会话。

即使对于 DeepSeek，Default 模式也不是一个受支持的变通方法——它是遗留的，不会被扩展来覆盖这种情况。这是一个 DeepSeek 模型/API 问题，而不是 Open WebUI 的问题。Open WebUI 正确地发送了标准 OpenAI 格式的工具；格式错误的输出源自 DeepSeek 的非标准内部 DSML 格式。

功能	Default 模式（遗留 / 不再受支持）	Native 模式（唯一受支持的模式）
状态	❌ 遗留，不再支持	✅ 必需——所有模型均应使用此模式
延迟	中/高	低
KV Cache	❌ 每轮都会破坏缓存	✅ 缓存友好
模型兼容性	任何文本模型（已过时的担忧）	自 2024 年以来的所有主流模型
逻辑	由 Open WebUI 解析提示词注入	通过提供商 API 进行结构化工具调用
系统工具	❌ 不可用	✅ 完全访问 (Memory, Notes, Knowledge, Channels, Web Search, Image Gen, Code Interpreter)
Agentic Research / Interleaved Thinking	❌ 不支持	✅ 支持
复杂链式调用	⚠️ 不可靠	✅ 优秀
未来开发	❌ 无	✅ 所有新功能均以此模式为目标

内置系统工具（Native/Agentic 模式）

🛠️ 启用 Native Mode (Agentic Mode) 后，Open WebUI 会自动注入强大的系统工具。这解锁了真正的 Agentic 行为，使有能力的模型（如 GPT-5、Claude 4.5 Sonnet、Gemini 3 Flash 或 MiniMax M2.5）能够自主进行多步研究、探索知识库或管理用户 memory。

工具	用途
Search & Web	需要启用 ENABLE_WEB_SEARCH 且启用单次聊天的 "Web Search" 开关。
search_web	在公共网页上搜索信息。最适合时事、外部引用或内部文档未涵盖的主题。
fetch_url	访问 URL 并通过 Web Loader 提取文本内容。
Knowledge Base	需要启用单模型的 "Knowledge Base" 类别（默认：开启）。注入哪些工具取决于模型是否附加了知识——见下文说明。
list_knowledge	列出附加的知识（知识库、文件、便签）。存在附件时从这里开始。
list_knowledge_bases	列出可访问的知识库及其文件数量。
query_knowledge_bases	对知识库名称/描述进行语义搜索以找到正确的知识库。
search_knowledge_bases	对知识库名称/描述进行文本搜索。
query_knowledge_files	通过 RAG 检索管道（启用时为混合 + 重排）搜索文件内容。用于在文档中寻找答案的主要工具。
search_knowledge_files	按文件名搜索文件。
view_file	通过 ID 并使用分页（offset，max_chars）读取用户可访问的文件。
view_knowledge_file	通过 ID 并使用分页（offset，max_chars）读取知识库文件。
Image Gen	需要启用图像生成（单工具）且启用单次聊天的 "Image Generation" 开关。
generate_image	根据提示词生成新图像。需要 ENABLE_IMAGE_GENERATION。
edit_image	根据提示词和图像 URL 编辑现有图像。需要 ENABLE_IMAGE_EDIT。
Code Interpreter	需要启用 ENABLE_CODE_INTERPRETER（默认：开启）且启用单次聊天的 "Code Interpreter" 开关。
execute_code	在沙箱环境中执行代码并返回输出。
Memory	需要启用 Memory 功能且启用单模型的 "Memory" 类别（默认：开启）。
search_memories	搜索用户的个人记忆/个性化库。
add_memory	在用户的个性化记忆中存储一个新事实。
replace_memory_content	通过唯一 ID 更新现有的记忆记录。
delete_memory	通过 ID 删除记忆。
list_memories	列出用户存储的所有记忆，包含内容和日期。
Notes	需要启用 ENABLE_NOTES 且启用单模型的 "Notes" 类别（默认：开启）。
search_notes	按标题和内容搜索用户的便签。
view_note	获取特定便签的完整 Markdown 内容。
write_note	为用户创建一个新的私有便签。
replace_note_content	更新现有便签的内容或标题。
Chat History	需要启用单模型的 "Chat History" 类别（默认：开启）。
search_chats	在聊天标题和消息内容中进行简单的文本搜索。返回匹配的聊天 ID 和片段。
view_chat	通过 ID 读取并返回特定聊天的完整消息历史记录。
Channels	需要启用 ENABLE_CHANNELS 且启用单模型的 "Channels" 类别（默认：开启）。
search_channels	按名称/描述寻找公开或可访问的频道。
search_channel_messages	在可访问的频道中搜索特定消息。
view_channel_message	查看频道中的特定消息或其详细信息。
view_channel_thread	查看频道中的完整消息线程/回复。
Task Management	需要启用单模型的 "Task Management" 类别（默认：开启）。
create_tasks	为当前聊天创建结构化的任务清单。在多步工作开始时调用一次，以定义所有步骤。
update_task	通过 id 更新单个任务的状态（pending、in_progress、completed、cancelled）。在完成每一步后调用。
Automations	需要启用单模型的 "Automations" 类别（默认：开启）且启用 ENABLE_AUTOMATIONS，且用户拥有 features.automations 权限（管理员始终通过）。
create_automation	创建包含名称、提示词和 RRULE 日程安排的定时自动化。使用当前聊天模型。
update_automation	更新现有自动化的名称、提示词、日程安排或模型。
list_automations	列出用户的定时自动化，包含状态、日程和下次运行时间。
toggle_automation	暂停或恢复定时自动化。
delete_automation	永久删除定时自动化及其所有运行历史记录。
Calendar	需要启用单模型的 "Calendar" 类别（默认：开启）且启用 ENABLE_CALENDAR，且用户拥有 features.calendar 权限（管理员始终通过）。
search_calendar_events	在所有可访问的日历中按文本和/或日期范围搜索日历事件。
create_calendar_event	在用户的默认或指定日历上创建新事件。
update_calendar_event	更新现有事件的标题、时间、描述、位置，或取消该事件。
delete_calendar_event	永久删除日历事件。
Skills	需要通过 Workspace/Admin Panel ➡️ Models ➡️ Edit ➡️ Skills 将至少一个 skill 附加到模型。模型在其系统提示词中会收到附加 skills 的摘要，并可以根据需要调用 view_skill 来加载完整指令。不需要单独的内置工具类别复选框——附加 skill 是唯一的条件。
view_skill	通过名称加载某个 skill 的完整指令。该工具在附加 skills 时被注入；解析 skill 仍需遵循正常的归属/访问权限授予检查。
Time Tools	需要启用单模型的 "Time & Calculation" 类别（默认：开启）。
get_current_timestamp	获取当前的 UTC Unix 时间戳和 ISO 日期。
calculate_timestamp	计算相对时间戳（例如，“3 天前”）。

知识工具可用性（一览表）

使用此快速矩阵，而不是死记硬背每一行的注意事项。

工具	模型已附加知识	模型未附加知识
list_knowledge	✅	❌
list_knowledge_bases	❌	✅
search_knowledge_bases	❌	✅
query_knowledge_bases	❌	✅
search_knowledge_files	✅（自动限定范围）	✅（所有可访问的知识库）
query_knowledge_files	✅（自动限定范围）	✅
view_file	✅（当附加项包含文件/集合时）	❌
view_knowledge_file	✅（当附加项包含文件/集合时）	✅
view_note	✅（当附加项包含便签时）	❌

快速规则：list_knowledge 和 list_knowledge_bases 是互斥的。

工具参考

工具	参数	输出
Search & Web
search_web	query（必需），count（默认：管理员配置的 WEB_SEARCH_RESULT_COUNT；提供时以管理员最大值为限）	{title, link, snippet} 的数组
fetch_url	url（必需）	纯文本内容（最大 50,000 字符）
Knowledge Base
list_knowledge	无	{knowledge_bases: [{id, name, description, file_count, files: [{id, filename}]}], files: [{id, filename}], notes: [{id, title}]}
list_knowledge_bases	count（默认：10），skip（默认：0）	{id, name, description, file_count} 的数组
query_knowledge_bases	query（必需），count（默认：5）	按相似度排序的 {id, name, description} 数组
search_knowledge_bases	query（必需），count（默认：5），skip（默认：0）	{id, name, description, file_count} 的数组
query_knowledge_files	query（必需），knowledge_ids（可选），count（默认：5）	类似于 {content, source, file_id, distance?} 的分块数组；便签命中结果包含 {note_id, type: "note"}
search_knowledge_files	query（必需），knowledge_id（可选），count（默认：5），skip（默认：0）	{id, filename, knowledge_id, knowledge_name} 的数组
view_file	file_id（必需），offset（默认：0），max_chars（默认：10000，上限：100000）	{id, filename, content, updated_at, created_at}——分页时包含 truncated、total_chars、next_offset
view_knowledge_file	file_id（必需），offset（默认：0），max_chars（默认：10000，上限：100000）	{id, filename, content, knowledge_id, knowledge_name}——截断时包含分页元数据
Image Gen
generate_image	prompt（必需）	{status, message, images}——自动显示
edit_image	prompt（必需），image_urls（必需）	{status, message, images}——自动显示
Code Interpreter
execute_code	code（必需）	{status, stdout, stderr, result}
Memory
search_memories	query（必需），count（默认：5）	{id, date, content} 的数组
add_memory	content（必需）	{status: "success", id}
replace_memory_content	memory_id（必需），content（必需）	{status: "success", id, content}
delete_memory	memory_id（必需）	{status: "success", message}
list_memories	无	{id, content, created_at, updated_at} 的数组
Notes
search_notes	query（必需），count（默认：5），start_timestamp，end_timestamp	{id, title, snippet, updated_at} 的数组
view_note	note_id（必需）	{id, title, content, updated_at, created_at}
write_note	title（必需），content（必需）	{status: "success", id}
replace_note_content	note_id（必需），content（必需），title（可选）	{status: "success", id, title}
Chat History
search_chats	query（必需），count（默认：5），start_timestamp，end_timestamp	{id, title, snippet, updated_at} 的数组
view_chat	chat_id（必需）	{id, title, messages: [{role, content}]}
Channels
search_channels	query（必需），count（默认：5）	{id, name, description, type} 的数组
search_channel_messages	query（必需），count（default: 10），start_timestamp，end_timestamp	{channel_id, channel_name, message_id, content_snippet, is_thread_reply, parent_id, created_at} 的数组
view_channel_message	message_id（必需）	{id, content, user_name, created_at, reply_count}
view_channel_thread	parent_message_id（必需）	{channel_id, channel_name, thread_id, message_count, messages: [...]}
Task Management
create_tasks	tasks（必需）：{content（必需）, status（默认：pending）, id（可选，自动生成）} 的列表	{tasks: [...], summary: {total, pending, in_progress, completed, cancelled}}
update_task	id（必需），status（默认：completed；pending、in_progress、completed、cancelled 之一）	{tasks: [...], summary: {total, pending, in_progress, completed, cancelled}}
Automations
create_automation	name（必需），prompt（必需），rrule（必需）	{status, id, name, model_id, is_active, next_runs}
update_automation	automation_id（必需），name，prompt，rrule，model_id（均为可选——仅更改提供的字段）	{status, id, name, model_id, is_active, next_runs}
list_automations	status（可选："active"、"paused" 或省略代表全部），count（默认：10）	{automations: [{id, name, prompt_snippet, model_id, rrule, is_active, last_run_at, next_runs}], total}
toggle_automation	automation_id（必需）	{status, id, name, is_active}
delete_automation	automation_id（必需）	{status, message}
Calendar
search_calendar_events	query（可选），start（可选日期时间字符串，如 "2026-04-20 00:00"），end（可选日期时间字符串），count（默认：10）	{events: [{id, calendar_id, title, description, start, end, all_day, location, color, is_cancelled}], total}
create_calendar_event	title（必需），start（必需日期时间字符串），end（可选），description（可选），calendar_id（可选——使用默认日历），all_day（默认：false），location（可选）	{status, id, calendar_id, title, start, end, ...}
update_calendar_event	event_id（必需），title，description，start，end，all_day，location，is_cancelled（均为可选——仅更改提供的字段）	{status, id, title, start, end, ...}
delete_calendar_event	event_id（必需）	{status, message}
Skills
view_skill	name（必需）	{name, content}
Time Tools
get_current_timestamp	无	{current_timestamp, current_iso}
calculate_timestamp	days_ago, weeks_ago, months_ago, years_ago（均为默认值：0）	{current_timestamp, current_iso, calculated_timestamp, calculated_iso}

自动时区检测

Open WebUI 在您登录时会自动检测并存储您的时区。这允许与时间相关的工具和功能提供准确的本地时间，而无需任何手动配置。您的时区是根据您的浏览器设置决定的。

知识工具注入取决于附件

知识工具的可用性会根据模型是否附加了知识而发生变化。请使用上面的知识工具可用性矩阵作为单一事实来源。

• 包含附件：模型将获得限定范围的知识工具。
• 不包含附件：模型将获得知识库发现工具。
• list_knowledge 和 list_knowledge_bases 是互斥的。

附加的知识仍需要用户访问权限

将知识库附加到自定义模型中并不能绕过访问控制。当用户与模型聊天时，query_knowledge_files 会检查该特定用户是否有权访问每个附加的知识项。用户无法访问的项将从搜索结果中被静默排除。

不同知识类型的访问要求：

附加类型	用户需要
知识库（集合）	所有者、管理员或显式读取访问授权
单个文件	仅限所有者或管理员（无访问授权）
便签	所有者、管理员或显式读取访问授权

示例场景：管理员创建了一个私有知识库，并将其附加到与所有用户共享的自定义模型中。与该模型聊天的普通用户在进行 query_knowledge_files 查询时将获得空结果，因为他们没有该知识库本身的读取权限——即使他们可以使用该模型。

解决方案：确保需要访问模型知识的用户也对底层的知识库拥有读取权限（通过知识库设置中的访问授权或组权限）。

推荐的知识库工具工作流

模型有附加知识时：

1. 首先调用 list_knowledge 以发现附加的知识库、文件和便签。
2. 使用 query_knowledge_files 搜索文件内容（自动限定在附件范围内）。
3. 使用 view_file 或 view_knowledge_file 读取特定文件——对大文件使用 offset 和 max_chars。

模型没有附加知识时：

1. 首先调用 list_knowledge_bases 发现有哪些知识库可用。
2. 然后使用 query_knowledge_files 在相关的知识库中搜索文件内容。
3. 如果依然为空，可能是文件尚未嵌入，或者您启用了Full Context模式（这会绕过向量数据库）。

不要在知识工具中启用 Full Context 模式——Full Context 会直接注入文件内容，而不存储嵌入（embeddings），因此 query_knowledge_files 将返回空结果。请使用 Focused Retrieval（聚焦检索，默认）进行基于工具的访问。

知识库工具与混合搜索

当管理员设置中启用 ENABLE_RAG_HYBRID_SEARCH 时，原生的 query_knowledge_files 工具将使用混合搜索 + 重排，这能为您提供与标准 RAG 管道相同的搜索质量。当混合搜索禁用时，它会退回到简单的向量搜索。

在 Native 模式下知识不会被自动注入

重要提示： 当使用 Native Function Calling 时，附加的知识不会被自动注入到对话中。模型必须主动调用知识工具来搜索和检索信息。

如果您的模型未在使用附加知识：

1. 在您的系统提示词中添加说明，告诉模型发现和查询知识库。例如："当用户提出问题时，首先使用 list_knowledge 看看有哪些知识可用，然后在回答之前使用 query_knowledge_files 搜索相关的知识库。如果该模型没有附加知识，请先使用 list_knowledge_bases 发现可用的知识库。"
2. 或者为该模型禁用 Native Function Calling 以恢复自动 RAG 注入。
3. 或者对附加知识使用“Full Context”模式（点击附件并选择“使用整篇文档”），这将始终注入完整内容。

有关更多详细信息，请参阅 在 Native Function Calling 下限定知识范围。

为什么使用这些？ It 允许进行 Deep Research（多次搜索网页，或查询知识库）、Contextual Awareness（查找以前的聊天或便签）、Dynamic Personalization（保存事实）以及 Precise Automation（根据现有便签或文档生成内容）。

禁用内置工具（单模型）

可以在 Workspace > Models 编辑器的 Capabilities 下为每个模型开启或关闭 Builtin Tools 功能。当启用（默认）时，在使用 Native 模式时会自动注入上面列出的所有系统工具。

何时禁用内置工具：

场景	禁用的理由
模型不支持函数调用	较小或较旧的模型可能无法正确处理 tools 参数
需要更简单/可预测的行为	您希望模型仅使用预先注入的上下文工作，不进行自主工具调用
安全/控制考量	防止模型主动查询知识库、搜索聊天、访问 memories 等。
Token 效率	工具规范会消耗 token；禁用可以节省上下文窗口空间

禁用 Builtin Tools 时会发生什么：

1. 无工具注入：即使在 Native 模式下，模型也不会接收到任何内置的系统工具。
2. RAG 仍然工作（如果启用了 File Context）：附加的文件仍然会通过 RAG 进行处理并作为上下文注入。
3. 无自主检索：模型无法决定搜索知识库或获取额外信息——它只能使用预先提供的内容。

细粒度的内置工具分类控制（单模型）

当启用 Builtin Tools 功能后，您可以进一步控制模型可以使用哪些类别的内置工具。这在 Model Editor 中表现为 Builtin Tools 下的一组复选框。

类别	包含的工具	描述
Time & Calculation	get_current_timestamp、calculate_timestamp	获取当前时间并进行日期/时间计算
Memory	search_memories、add_memory、replace_memory_content、delete_memory、list_memories	搜索和管理用户 memories
Chat History	search_chats、view_chat	搜索和查看用户聊天历史记录
Notes	search_notes、view_note、write_note、replace_note_content	搜索、查看和管理用户便签
Knowledge Base	list_knowledge、list_knowledge_bases、search_knowledge_bases、query_knowledge_bases、search_knowledge_files、query_knowledge_files、view_file、view_knowledge_file	浏览和查询知识库
Web Search	search_web、fetch_url	搜索网页并获取 URL 内容
Image Generation	generate_image、edit_image	生成并编辑图像
Code Interpreter	execute_code	在沙箱环境中执行代码
Channels	search_channels、search_channel_messages、view_channel_message、view_channel_thread	搜索频道和频道消息
Task Management	create_tasks、update_task	创建结构化任务/待办事项列表，并在活跃聊天中更新单个任务状态
Automations	create_automation、update_automation、list_automations、toggle_automation、delete_automation	在聊天中创建和管理定时自动化任务
Calendar	search_calendar_events、create_calendar_event、update_calendar_event、delete_calendar_event	搜索、创建、更新和删除日历事件

所有类别均默认启用。禁用某个类别将阻止注入这些特定工具，同时保持其他类别处于活动状态。

Skills / view_skill —— 非类别开关

view_skill 工具不会出现在 Builtin Tools 类别复选框中。当至少有一个 skill 附加到模型时（通过 Workspace ➡️ Models ➡️ Edit ➡️ Skills），它才会被注入。当附加 skills 时：

1. 模型会在其系统提示词中通过 <available_skills> 标签接收到每个附加 skill 的摘要（名称 + 描述）。
2. view_skill 工具将被注入，以便模型可以根据需要加载完整指令。
3. 如果未附加任何 skill，则 view_skill 不可用。

用户还可以在每次聊天中选择 skills（通过聊天输入栏），这会直接将 skill 的完整内容注入到系统提示词中，而不需要调用 view_skill。

细粒度控制的使用场景：

场景	推荐配置
注重隐私的模型	禁用 Memory 和 Chat History，以防止访问个人数据
只读助手	禁用 Notes（防止创建/修改便签），但保持 Knowledge Base 启用
最小化 token 使用	仅启用模型实际需要的类别
专注于知识的机器人	禁用除 Knowledge Base 和 Time 之外的所有功能

备注

这些单类别开关仅在主 Builtin Tools 功能启用时才会出现。如果您完全禁用了 Builtin Tools，无论类别设置如何，都不会注入任何工具。

全局功能优先

启用单模型类别开关并不能覆盖全局功能标志。例如，如果全局（Admin Panel）禁用了 ENABLE_NOTES，即使在模型中启用了“Notes”类别，便签工具也将不可用。单模型开关仅允许您进一步限制已经可用的功能——它们无法启用在全局级别被禁用的功能。

用户级权限同样适用

对应于 RBAC 功能权限的内置工具也受到用户 Features 权限的限制。即使模型上启用了工具类别且全局功能标志处于开启状态，如果用户缺乏相应的 features.* 权限，该工具也不会被注入。管理员始终可以通过这些检查。

工具类别	所需的 features.* 权限
Memory	features.memories
Web Search	features.web_search
Image Generation	features.image_generation
Code Interpreter	features.code_interpreter
Notes	features.notes
Channels	features.channels
Automations	features.automations
Calendar	features.calendar

这确保了端到端的 RBAC 权限得到尊重——为用户禁用某项功能会阻止模型代表他们调用这些工具，而不仅仅是在 UI 中将其隐藏。

单聊天功能开关（Web Search, Image Generation, Code Interpreter）

Web Search、Image Generation 和 Code Interpreter 内置工具具有额外的控制层：聊天输入栏中的单聊天功能开关。为了在 Native 模式下注入这些工具，必须同时满足以下三个条件：

1. 全局配置已启用——该功能在 Admin Panel 中已开启（例如 ENABLE_WEB_SEARCH）
2. 模型能力已启用——该模型在 Workspace > Models 中勾选了该能力（例如 “Web Search”）
3. 单聊天开关已启用——用户已通过聊天输入栏开关专门为该聊天激活了该功能

这意味着用户可以在单次对话的基础上禁用网页搜索（或图像生成，或代码解释器），即使它在全局和模型上都是启用的。这对于需要保持离线状态或希望防止意外工具调用的聊天非常有用。

完整 Agentic 体验

为了获得最佳的开箱即用 Agentic 体验，管理员可以将 Web Search、Image Generation 和 Code Interpreter 启用为模型的默认功能。在 Admin Panel > Settings > Models 中，找到目标模型的 Model Specific Settings，然后在 Default Features 下将这三个功能切换为开启。这可确保它们在每次新聊天中默认处于活动状态，从而使用户无需手动启用每个开关即可获得完整的工具调用体验。如果需要，用户仍然可以在单次聊天中将其关闭。

内置工具 vs File Context

Builtin Tools 控制模型是否获得用于自主检索的工具。它并不控制文件内容是否通过 RAG 注入——这由单独的 File Context 能力控制。

• File Context = Open WebUI 是否提取并注入文件内容（RAG 处理）
• Builtin Tools = 模型是否获得自主搜索/检索额外内容的工具

参见 File Context 对比 Builtin Tools 以获取详细对比。

交织思考

🧠 当使用 Native Mode (Agentic Mode) 时，高阶模型可以参与 Interleaved Thinking（交织思考）。这是一个强大的“Thought ➡️ Action ➡️ Thought ➡️ Action ➡️ Thought ➡️ ...”循环，模型可以在其中对任务进行推理、执行一个或多个工具、评估结果，然后决定下一步的行动。

需要高质量模型

交织思考需要模型具有强大的推理能力。此功能在能够跨多个工具调用维持上下文并对何时使用哪些工具做出智能决策的前沿模型（GPT-5、Claude 4.5+、Gemini 3+）上效果最佳。

这与单次工具调用有着本质的区别。在交织的工作流中，模型遵循以下循环：

1. 推理 (Reason)：分析用户意图并找出信息缺口。
2. 行动 (Act)：调用工具（例如，针对内部文档使用 query_knowledge_files，或者针对网页研究使用 search_web 和 fetch_url）。
3. 思考 (Think)：读取工具的输出并更新其内部认知。
4. 迭代 (Iterate)：如果答案不明确，则调用另一个工具（例如，使用 view_knowledge_file 读取特定文档，或使用 fetch_url 读取特定页面）或优化搜索。
5. 完成 (Finalize)：只有在完成这个“Deep Research”（深度研究）循环后，模型才会提供最终的、有依据的回答。

正是这种行为，将标准的聊天机器人转变为能够自主解决复杂、多步问题的 Agentic AI。

对于长时间运行的工作流，可以将交织的工具使用与 create_tasks（预先制定计划）和 update_task（随着工作进展将每一步标记为已完成）结合起来，以便模型可以进行显式规划、跟踪进度并让用户了解下一步的行动。

---

---

🚀 总结与后续步骤

Tools 通过赋予 AI 与世界互动的手臂，让您的 AI 焕发生机。

• 浏览 Tools：openwebui.com/search
• 高级设置：了解关于 MCP 支持 的更多信息
• 开发：编写您自己的自定义 Toolkits