跳到主要内容

聊天工具

Chat 可以允许模型调用工具。启用工具的轮次会运行原生多轮循环：模型请求工具，Libre WebUI 以调用用户的身份和权限执行，将结果返回模型，循环继续到模型作答。每个轮次最多八轮，每轮最多八次调用。停止操作会取消模型调用、正在进行的工具调用和待审批等待。

工具调用记录为标准事件（chat.tool-call.v1、chat.tool-result.v1、chat.approval.v1），在私有 WebSocket 路径和持久事件流中的传输完全一致，因此刷新或重新连接会重放相同状态。完成的轮次会把调用及受限结果预览存储在助手消息中。

启用工具​

工具默认关闭。管理员可在设置 → 用户管理中为仅管理员或所有用户开放；每个轮次再通过输入区的扳手图标主动启用。选择器包含总开关，以及每个内置工具和已注册服务器的复选框，因此只使用你明确选择的工具。选择器只能缩小角色配置的绑定范围，不能扩大。私有（隐身）聊天绝不提供工具：工具调用是面向外部的操作，可能留下审批和审计记录。

助手配置（角色）可限制提供的工具：绑定的工具服务器、内置工具子集、技能和知识集合会限制模型在使用该配置的会话中看到的内容。

内置工具​

Chat 内置十三个第一方工具（除修改笔记和日历的工具需走副作用审批流程外，其他均为只读）：

  • web_search——使用管理员配置的搜索引擎，并遵守 Web 搜索访问模式。
  • search_documents——对用户上传的文档和知识集合进行混合搜索，包括与其共享的集合（配置绑定可限制集合）；每个段落都标注片段和源位置。
  • list_documents——列出当前聊天范围内文档的 ID、类型和大小，供模型决定读取对象。
  • read_document——按 ID 和偏移量读取可用文档的受限窗口并标注源位置，以便迭代查看仅靠检索无法解答的文件。
  • load_skill——按 slug 加载技能完整说明；工具描述携带用户已启用技能的清单，因此技能在模型需要前保持延迟。若包含配套文件，说明末尾会附文件清单。
  • read_skill_file——按 slug 和相对路径读取技能的配套文件，使大型参考文档只在实际打开时占用上下文。
  • list_notes——列出用户自有和共享笔记及其 ID。
  • read_note——按 ID 读取一条笔记的完整内容。
  • create_note——创建笔记（有副作用，需要审批）。
  • update_note——替换笔记内容；旧状态保留为可恢复修订，因此模型编辑始终可撤销（有副作用，需要审批）。
  • list_calendar_events——在纪元毫秒范围内列出用户自有和共享的日历事件。
  • create_calendar_event——创建日历事件（有副作用，需要审批）。
  • delete_calendar_event——按 ID 删除日历事件（有副作用，需要审批）。

工具服务器​

管理员在 设置 → 工具 中注册外部工具服务器（初始模板会预填表单，包括安全的公共演示 API）：

  • OpenAPI：获取一次 JSON OpenAPI 3.x 规范并以 SHA-256 摘要固定。每项操作成为工具；GET 默认为只读，其余均视为有副作用，直到管理员按工具覆盖分类。执行时从固定操作重建调用，模型参数绝不选择目标。
  • MCP（Streamable HTTP）：通过 JSON-RPC 获取服务器工具列表并以相同方式固定。annotations.readOnlyHint 将工具标记为只读。有意不支持 stdio MCP 服务器：Web 进程内绝不运行外部进程。

变更后的清单只有在管理员刷新服务器后才生效，此操作会推进固定修订并保留每项工具的覆盖设置。服务器可仅供管理员、供所有用户，或通过共享资源授权模型向用户和组授权。

凭据​

需要身份验证的服务器使用按用户划分的凭据（Bearer 令牌或命名标头）。每个密钥都使用额外的认证数据加密，将其绑定到确切用户和服务器；每位用户在设置 → 工具中自行输入，账户间绝不共享。

出站策略​

每个工具请求自行解析目标，拒绝私有、环回和元数据地址空间，并将连接固定到解析地址，防止 DNS 重绑定改变目标。重定向响应会被拒绝。响应有大小上限，每次调用都有硬超时。可通过 TOOLS_PRIVATE_NETWORK_ALLOWLIST 允许确切内部主机名（逗号分隔）；允许的主机仍会固定和限流。工具输出以不可信文本形式重新进入模型。

审批​

只读工具无需询问即可运行。有副作用的工具会暂停轮次并询问用户：允许一次、允许当前聊天、始终允许此服务器上的此工具，或拒绝。决定会持久保存；“始终允许”在重启后仍有效，可从设置 → 工具中撤销。待处理请求两分钟后过期，模型会将其视为拒绝。拒绝和超时绝不会执行调用。每项决定和调用都会留下经过脱敏的安全审计事件。

示例​

请先打开输入区中的扳手开关；以下每个示例都是普通聊天消息。

web_search——查询信息​

最新 SQLite 版本有哪些变化？回答前先搜索 Web。

模型会以 {"query": "SQLite latest release changelog"} 等查询调用 web_search，调用卡片显示收到的结果摘要，回复会引用找到的内容。需要为账户配置并允许 Web 搜索。

search_documents——询问自己的文件​

上传 PDF 或向知识集合添加文档，然后询问：

在我的文档中查找终止条款并准确引用。

模型以 {"query": "termination clause"} 调用 search_documents，并收到带源文档标签的匹配段落，以便引用和归属。

load_skill——应用已保存技能​

在 设置 → 技能 中创建技能（例如 $release-notes，说明你希望如何撰写版本说明），然后询问：

使用 $release-notes 为这个差异撰写版本说明。

模型在清单中看到技能，调用 load_skill {"slug": "release-notes"} 获取完整说明并遵循。输入 $ 会自动补全技能 slug。

OpenAPI 服务器——以天气 API 为例​

  1. 设置 → 工具 → 注册服务器：名称 Weather，类型 OpenAPI，基础 URL https://api.example-weather.dev，规范 URL https://api.example-weather.dev/openapi.json，身份验证模式 bearer。

  2. 规范被固定，操作显示为工具，例如 getForecast（GET，只读）和 createAlert（POST，有副作用）。

  3. 每位希望使用的用户在服务器卡片中保存自己的 API 密钥。

  4. 在聊天中：

    蒙特利尔本周末天气如何？

    模型调用 weather__getForecast {"city": "Montreal"}，并立即执行——只读工具绝不提示审批。

    如果今晚低于 -20，请提醒我。

    weather__createAlert 有副作用，因此轮次会暂停并显示审批卡片：允许一次、允许当前聊天、始终允许 或 拒绝。选择前不会发送任何内容。

MCP 服务器——以 Issue 跟踪器为例​

  1. 设置 → 工具 → 注册服务器：名称 Issues，类型 MCP，基础 URL https://mcp.example-tracker.dev/mcp，身份验证模式 header，标头名 X-Api-Key。

  2. 工具列表被固定；服务器标记为只读的工具（如 search_issues）可直接运行，其余工具（如 create_issue）先请求审批。

  3. 在聊天中：

    查找提到 "database lock" 的开放 Issue，并创建一个新 Issue 总结该模式。

    issues__search_issues 会立即运行；issues__create_issue 在审批卡片中显示确切参数，供你在允许前查看提交内容。

环境变量​

变量效果
TOOLS_ACCESS_MODE将工具功能固定为 admins 或 all-users，并锁定管理员开关。
TOOLS_PRIVATE_NETWORK_ALLOWLIST工具服务器可解析到私有地址的确切主机名（逗号分隔列表）。

边界​

  • 工具调用在 WebSocket 路径（有意排除私有会话传输）和持久聊天使用的持久生成路径上运行。旧版 REST 流式端点不运行工具循环。
  • Work 代理通过同一网关调用同样的服务器：仅限启用网络的运行，缺少凭据的服务器在供给时即被过滤，有副作用的工具受 Work 审批约束。
  • Gemini 和代理 CLI 模型不会接收工具；Ollama、OpenAI 兼容、Responses API 和 Anthropic 提供商会接收。
  • MCP 服务器使用按用户划分的静态凭据进行身份验证；尚不能注册只支持交互式 OAuth 的 MCP 服务器。