什么是工具？
工作区工具与 Functions 都会在你的服务器上执行任意 Python 代码。 你只能从可信来源安装，导入前必须审阅代码，并且只能把工作区访问权限交给可信管理员。允许用户创建或导入 Tool，本质上等同于给了他们服务器 shell 级别的执行能力。完整背景见 Plugin Security Warning。
在 OPL 数据空间 中，Tools 指的是让模型能力超出纯文本生成的一整套机制。启用后，聊天机器人可以搜索网页、抓取内容、生成图片、执行代码、读取知识库、操作日历等。
由于 OPL 数据空间 里存在多种“工具”接入方式，先分清你在使用哪一类非常重要。
工具分类
| 类型 | UI 位置 | 适合场 景 | 来源 |
|---|---|---|---|
| 原生功能 | 管理员 / 设置 | 平台内建能力 | OPL 数据空间 自带 |
| 工作区工具 | 工作区 > 工具 | 用户自建或社区 Python 脚本 | 社区 Library |
| 原生 MCP (HTTP) | 设置 > Connections | 可通过 HTTP 暴露的 MCP 服务 | 外部 MCP 服务器 |
| 通过 MCPO 代理的 MCP | 设置 > Connections | 基于本地 stdio 的 MCP 服务 | MCPO |
| OpenAPI 服务端 | 设置 > 连接 | 标准 REST / OpenAPI 服务 | 外部 Web API |
| Open Terminal | 设置 > 集成 | 持续运行的隔离 Docker Shell | Open Terminal |
1. 原生功能
这些能力深度集成在 OPL 数据空间 里，通常不需要额外脚本：
- 网页搜索
- URL Fetching
- 图像生成
- Memory
- RAG / Knowledge
在 Native 模式 下，它们会以可调用 Tool 的形式注入给模型。
2. 工作区工具
工作区工具是直接运行在 OPL 数据空间 环境内的 Python 脚本。
- 能力范围：Python 能做什么，它基本就能做什么
- 管理入口：
工作区 → 工具 - 风险级别：很高，导入前必须审查代码
- 权限要求：不要把工作区工具创建/导入权限交给普通或不可信用户
3. MCP（Model Context Protocol）
MCP 是一套让 LLM 与外部数据源、工具交互的开放协议。
- 原生 HTTP MCP： OPL 数据空间 可直接连接暴露 HTTP 端点的 MCP 服务器
- MCPO 代理：大多数社区 MCP 服务用的是
stdio；要在 OPL 数据空间 中接入，通常需要 MCPO 代理
4. OpenAPI / Function Calling 服务器
如果一个外部服务暴露 OpenAPI 规范（.json 或 .yaml）， OPL 数据空间 就可以把这些 endpoint 读入，并把它们当作可调用工具。
安装与管理工作区工具
- 访问 社区 Tool Library
- 选择目标 Tool，点击 Get
- 输入你的 OPL 数据空间 地址，例如
http://localhost:3000 - 点击 导入到 WebUI
不要导入你不了解或不信任的 Tool。它们是 Python 脚本，可能直接在宿主环境执行危险操作。更关键的是，只有可信用户才应该被授予工具相关权限，因为他们实际上获得的是任意代码执行能力。
在聊天中使用 Tools
方式一：按聊天临时启用
在聊天界面里，点击输入区域旁边的 ➕。你会看到可用工具列表，可以只为这次会话启用需要的工具。
方式二：按模型默认启用
- 打开 工作区 → 模型
- 编辑目标模型
- 滚动到 工具
- 勾选希望该模型默认可用的工具
- 保存
如果模型支持，推荐搭配 Native tool calling 使用，让模型自己决定何时调用哪个工具，而不是依赖早期的 prompt 注入式自动工具方案。
把一个工作区工具挂到模型上，不会绕过访问控制。用户实际对话时， OPL 数据空间 会检查这个用户是否对每个挂载工具都具备读取权限。没有权限的工具会被静默跳过。
也就是说，管理员即便把一个私有工具挂到“所有人都能用”的模型上，普通用户也不一定能用到这个工具。想让模型工具真正可用，还需要同时给用户相应工具的读取权限。
Tool Calling 模式：Default vs Native
所有模型都应该切换到 Native（Agentic）模式。 Default 模式是早期为了兼容没有原生函数调用能力的模型而设计的 prompt 注入式兜底方案。它已经停止演进，不会再获得新特性、修复或系统工具支持。
OPL 数据空间 在 模型设置 → 高级参数 → Function Calling 中暴露两种模式：
- Native Mode（Agentic Mode）：唯 一推荐、唯一持续支持的模式
- Default Mode：仅为向后兼容保留
Default Mode（遗留）
在 Default 模式下， OPL 数据空间 会把工具定义拼进 prompt，让模型输出一种约定格式的“工具调用请求”。这种方式在 2023 年还算实用，但现在已经过时。
它的问题包括：
- 会破坏 KV Cache
- 额外增加延迟与 token 成本
- 多步工具链可靠性差
- 无法访问 Memory、Notes、Knowledge、Channels、Agentic Research 等新系统工具
- 与近两年的新功能路线不兼容
Native Mode（Agentic Mode）
Native 模式利用模型原生的函数调用 / tool calling 能力，以结构化 schema 和 JSON 工具调用完成协作。这是 2024 之后主流模型的标准路线。
优势：
- 延迟更低
- 对 KV Cache 更友好
- 结构化调用更可靠
- 支持多步 chaining
- 支持系统工具与 agentic 能力
- 后续新特性都以它为目标
原生 agentic tool calling 不只是“模型支持 function calling”就够了。较小的本地模型即便语法上支持，也可能在多步推理、JSON 严格性和状态管理上表现很差。要获得稳定体验，优先选择 GPT-5、Claude 4.5 Sonnet、Gemini 3 Flash、MiniMax M2.5 这类高质量模型。
如何启用 Native
- 全局默认（推荐）
- 打开 管理面板 → 设置 → 模型
- 点击右上角 设置
- 在 模型参数 中将 Function Calling 设为
Native - 保存
- 按模型覆盖
- 编辑具体模型
- 将 Function Calling 改为
Native
- 按聊天覆盖
- 在聊天右侧的 聊天控制 里修改 高级参数
如果你不想一个个改模型，直接在 管理面板 → 设置 → 模型 顶部的全局模型参数里设置 Function Calling = Native。这样所有未单独覆盖的模型，以及之后新增的模型，都会自动继承这个默认值。
模型要求与已知问题
- 大型本地模型通常可以在 Native 模式下工作，但质量与模型能力强相关
- 小型本地模型经常会输出损坏的 JSON，或无法稳定完成多步工具链
- 对 DeepSeek V3.2 等特定模型，已知存在函数调用格式漂移问题；这不是 OPL 数据空间 的调用协议错误，而是模型本身训练格式与标准 JSON 调用不一致导致
如果某个模型在 Native 模式下表现差，正确做法是换更适合 tool calling 的模型，而不是退回 Default。
Interleaved Thinking
Interleaved Thinking 指的是模型在一次长任务中，能够在“思考”和“调用工具”之间多轮交替推进。像 Agentic Research、分阶段网页检索、连续知识库查询这类工作流，都依赖这种能力，因此同样要求使用 Native 模式。
| 维度 | Default Mode（遗留） | Native Mode（推荐） |
|---|---|---|
| 状态 | 不再支持 | 当前标准 |
| 延迟 | 中到高 | 低 |
| KV Cache | 每轮失效 | 友好 |
| 系统工具 | 不支持 | 完整支持 |
| 多步链式调用 | 不稳定 | 稳定 |
| 后续特性 | 无 | 全部新特性都基于它 |
内建系统工具（Native/Agentic 模式）
启用 Native 后， OPL 数据空间 会自动注入一组系统工具，让模型能执行更像 agent 的操作。
| 类别 | 代表工具 | 用途 |
|---|---|---|
| 搜索与网页 | search_web, fetch_url | 搜索互联网与抓取网页内容 |
| 知识库 | list_knowledge, query_knowledge_files, view_file | 浏览知识库、搜索文件、读取文档 |
| 图像生成 | generate_image, edit_image | 生成与编辑图片 |
| 代码执行器 | execute_code | 在隔离环境中执行代码 |
| Memory | search_memories, add_memory | 检索与维护用户记忆 |
| Notes | search_notes, write_note, view_note | 管理笔记 |
| Chat History | search_chats, view_chat | 搜索历史聊天 |
| Channels | search_channels, view_channel_thread | 检索频道与线程消息 |
| 任务管理 | create_tasks, update_task | 在当前聊天里维护任务清单 |
| 自动化 | create_automation, list_automations | 调度与管理自动化任务 |
| 日历 | search_calendar_events, create_calendar_event | 日历搜索与事件操作 |
| 技能 | view_skill | 按需读取挂载到模型上的 skill 说明 |
| 时间与计算 | get_current_timestamp, calculate_timestamp | 时间获取与相对时间计算 |
OPL 数据空间 会在用户登录时自动识别浏览器时区，用于时间相关工具和功能，无需额外配置。
知识库工具可用性
知识库工具是否注入，取决于模型是否挂载了知识对象。
| 工具 | 模型已挂载知识 | 模型未挂载知识 |
|---|---|---|
list_knowledge | ✅ | ❌ |
list_knowledge_bases | ❌ | ✅ |
search_knowledge_files | ✅（自动限域） | ✅ |
query_knowledge_files | ✅（自动限域） | ✅ |
view_file | ✅（挂载文件/集合时） | ❌ |
view_knowledge_file | ✅ | ✅ |
快速规则：
list_knowledge与list_knowledge_bases互斥- 有挂载知识时，模型拿到的是“限域”检索能力
- 没有挂载知识时，模型先拿到的是“发现可用知识库”的能力
当使用 Native Function Calling 时，挂载的知识不会自动注入到上下文里。模型需要主动调用知识工具去发现和检索内容。
如果模型没有主动使用知识：
- 在 system prompt 中明确要求它先调用
list_knowledge/query_knowledge_files - 或禁用该模型的 Native Function Calling，恢复自动 RAG 注入
- 或在附件上选择 Full Context，直接注入全文
有挂载知识时：
- 先调用
list_knowledge - 再用
query_knowledge_files做内容检索 - 需要精读时再用
view_file/view_knowledge_file
没有挂载知识时：
- 先调用
list_knowledge_bases - 再调用
query_knowledge_files - 如果仍然为空，检查是否尚未完成 embedding，或是否启用了 Full Context
如何按模型关闭内建工具
在 工作区 → 模型 编辑器中，可以为每个模型开关 内建工具 能力。
适合关闭的场景：
- 模型本身不支持函数调用
- 你希望模型行为更可预测，只依赖预注入上下文
- 你不希望模型主动检索知识、记忆、聊天记录等
- 你想节省上下文 token
关闭后会发生什么：
- 不再注入任何内建系统工具
- 如果 文件上下文 仍然开启，RAG 仍可工作
- 模型无法自主检索额外信息，只能基于已给出的上下文回答
内建工具类别级控制
当 内建工具 打开后，你还可以进一步按类别精细控制工具注入。
| 类别 | 包含工具 | 说明 |
|---|---|---|
| 时间与计算 | 时间与日期计算 | 当前时间、相对时间 |
| Memory | 用户记忆工具 | 搜索、写入、替换、删除 |
| Chat History | 历史聊天工具 | 搜索和查看聊天 |
| Notes | 笔记工具 | 搜索、读取、写入和更新笔记 |
| 知识库 | 知识库工具 | 浏览知识库与文档检索 |
| 网页搜索 | 网页搜索工具 | 搜索网页与抓取 URL |
| 图像生成 | 图像工具 | 生成与编辑图片 |
| 代码执行器 | 代码执行工具 | 沙箱执行代码 |
| Channels | 频道工具 | 搜索频道与消息 |
| 任务管理 | 任务工具 | 创建和更新任务清单 |
| 自动化 | 自动化工具 | 创建和维护定时任务 |
| 日历 | 日历工具 | 搜索、创建、更新、删除事件 |
这些类别默认全部启用。关闭某个类别，只会移除这部分工具，不影响其他类别。
view_skill 不是类别开关的一部分view_skill 只有在模型实际挂载了至少一个 skill 时才会注入。没有挂 skill，就不会有这个工具。
即使模型上勾选了某个类别，只要对应全局特性在管理面板中被关闭，该类工具依然不会注入。模型级开关只能进一步收紧范围，不能绕过全局禁用。
很多内建工具还会继续受用户的 features.* 权限控制。例如，即使模型启用了 Notes 类别、全局也启用了 Notes，只要用户没有 features.notes 权限，相应工具依旧不会注入。
这三类工具除了全局开关和模型能力开关外，还要求用户在当前聊天中显式打开对应功能。只有三层都满足，工具才会在 Native 模式下注入。
- 内建工具 决定模型是否获得“自主检索”的工具
- 文件上下文 决定文件内容是否通过 RAG 注入上下文
两者可以独立开启或关闭。