工具
TIP
本节介绍「能力 → 工具」页面的用法、工具的执行策略，以及工具较多时如何节省上下文。
工具是模型在对话中可以主动调用的外部能力，例如搜索网页、读写文件或运行脚本。工具由插件动态注册：启用插件后工具就会注入系统，停用插件后一并卸载。
在控制台中，你可以查看已注册的工具、所属插件和参数规范，并决定哪些工具可以直接运行、哪些需要人工审批、哪些对模型隐藏。
工具页
前往「能力 → 工具」页面，这里集中列出了当前实例的所有工具。右上角可以在「卡片」和「列表」视图之间切换，并选择分组方式：
- 按插件分组：按所属插件归类。
- 按规则分组：按当前策略（自动、询问、禁用）归类，便于复核高危工具。
- 不分组：平铺展示，适合配合搜索使用。
点击任意工具打开详情面板：
- 名称与说明：模型也会依据说明判断是否调用。模型频繁误用时，先检查说明是否准确。
- 注册插件与作用域：提供该工具的插件，以及它是全局工具还是某个 Agent 专属。
- 参数规格：参数名、类型、取值范围和是否必填。调用失败时可以在这里核对参数。
- 当前策略：点击即可切换。
- 来源标记：来自 MCP 服务时显示服务器名称。
修改策略会自动保存。正在进行的回合不会中断，新策略从下一轮生效。
三种策略
- 自动：直接执行并返回结果（除非权限模式另有要求）。适合查询、计算等只读操作。
- 询问：调用前暂停，等待用户或管理员确认。适合有副作用、产生费用或涉及隐私的操作。
- 禁用：对模型完全隐藏。
在工具策略插件的配置中，还可以用通配符批量设置策略（* 匹配任意多个字符，? 匹配单个字符），例如把所有 MCP 工具设为「询问」。
WARNING
「禁用」只是对模型隐藏工具，插件仍在运行，可以随时重新开启。要彻底移除，请在插件市场卸载对应插件。
工具从哪里来
- 内置工具插件：文件读写、命令执行、代码运行、网页请求与搜索、定时任务、配置管理和运行时自省等。
- 技能：技能目录和脚本暴露的工具。
- MCP 服务器：通过 Model Context Protocol 接入的外部工具。
- 子代理：把任务派发给子代理的工具。
- 机器：远端主机、本地环境或容器沙箱的操作接口。
- 业务插件：群管理、AI 绘图、语音合成、记忆检索等。
不同来源的工具可以在同一回合混合调用，权限、审批和可见性规则对它们一视同仁。
工具可见性
一个工具能否在某个会话中被调用，按以下顺序逐层决定：
- 插件注册时声明的过滤条件。
- 当前 Agent 的工具过滤。
- 「场景规则」中的允许和禁用清单。
- 「工具」页面和工具策略插件中的禁用状态。
- 对应技能或 MCP 服务器的启用状态。
每一层只能进一步收窄范围，不能重新启用前面已隐藏的工具。例如全局禁用的工具，即使加入场景规则的允许清单也无法调用。模型找不到某个工具时，按这个顺序排查即可。
工具模式
「场景规则 → 能力 → 工具」中的「工具模式」决定工具以什么形式提供给模型：
- 直接给全部：完整传入所有可见工具的定义。工具不多时最快最稳定。
- 先搜再用：只保留少量常驻工具和一个工具搜索器，模型需要时先搜索再调用。工具很多时可以大幅节省上下文。
- 写代码调用：模型编写脚本组合调用多个工具，适合多步数据处理和批处理。
- 交给子代理：把子任务派发给子代理，在独立上下文中调用工具并汇总结果，适合步骤长的复杂任务。
默认模式取决于引擎类型，普通对话引擎默认「直接给全部」，以界面显示的默认值为准。
工具搜索
工具搜索把工具分成两类：
- 常驻工具：完整定义始终在提示词中。
- 按需工具：提示词中只有名称和简要说明，模型搜索命中后才注入完整参数。
在「场景规则 → 能力 → 工具」的搜索配置中可以调整：
- 搜索模式：「自动」「始终搜索」或「关闭」。「自动」只对支持工具延迟加载的提供商生效。
- 自动启用阈值：可用工具数超过该值时启用按需检索，默认 20。
- 按需加载列表：需要按需加载的工具，支持通配符，默认包含所有 MCP 工具。
- 单次搜索返回数量：每次搜索最多返回的候选数，默认 5。
在工具详情面板中，也可以把常用的 MCP 工具单独设为「常驻」，或把参数复杂的内置工具设为「按需」。
WARNING
按需检索会多一次交互：模型要先搜索再调用。工具不多时开启搜索反而更慢。
执行与审批
一次工具调用依次经过：模型输出工具名和参数 → 校验参数结构 → 权限判定 → 在指定环境中执行 → 结果写回会话上下文和轨迹日志。
插件还可以在调用前修改参数或中止调用，在调用后补充结果、脱敏字段。插件停用后这些钩子会自动撤回。
审批与权限模式
除了工具自身的「询问」策略，全局权限模式也参与判定：
| 模式 | 表现 | 高危操作（Shell、写文件等） | 适用场景 |
|---|---|---|---|
| 只读 | 只允许查询 | 直接拒绝 | 公开群聊、问答机器人 |
| 文件 | 允许读写普通文件 | 终端命令等需要审批 | 文档编写等轻度协作 |
| 自动 | 审查模型评估安全性 | 安全则放行，高危交给人工 | 个人日常、轻量自动化 |
| 完全放行 | 全部自动放行 | 只对高权限用户生效，低权限用户降级为「自动」 | 本地调试、管理员环境 |
触发审批时会弹出审批卡片，显示工具名、参数和风险提示。可以「仅本次允许」或「拒绝执行」，权限允许时还可以勾选「记住此选择」。超时未响应按拒绝处理。
TIP
「询问」适合有用但需要把关的功能；完全不希望在某个场景使用的功能直接「禁用」。如果某个工具每次询问都会被拒绝，不如直接禁用，以免打断对话。
常见工具家族
具体以控制台显示为准：
- 文件：查看、写入、修改、目录浏览和搜索。
- 命令：在受限终端中执行 Shell 命令，建议开启审批。
- 代码：在隔离解释器中运行代码。
- 网络：搜索、网页抓取、HTTP 请求和 OpenAPI 调用。
- 运行时：查看系统状态、日志、插件和配置，修改核心配置通常需要管理员权限。
- 记忆：长期记忆的检索、更新和存储。
- 技能：列出技能、读取技能正文、执行技能脚本。
- MCP：外部 MCP 工具，通常带服务器名前缀。
- 子代理：派发子任务并汇总结果。
- 机器：本地执行器、SSH 主机、Docker 容器或云端沙箱的操作接口。
- 业务：AI 绘图、语音合成、定时器、群管理等。
推荐配置
| 场景 | 建议 |
|---|---|
| 个人小实例 | 保持「直接给全部」；命令执行和文件修改设为「询问」，查询类保持「自动」 |
| 接了多个 MCP | 开启工具搜索，阈值保持 20，按需列表包含 MCP 工具；最常用的两三个设为「常驻」，会修改外部数据的设为「询问」 |
| 多人群聊 | 为每个群配置工具白名单，只保留查询、搜索和娱乐类工具；配置修改、文件读写和 Shell 只在管理员私聊中开放 |
| 自动化 / 编码 | 使用「写代码调用」或编码引擎，配齐文件、检索和代码解释器工具，高危指令设为「询问」或限制在沙箱中 |
常见问题
模型说自己「没有某个工具」：按工具可见性的顺序排查；如果工具处于按需加载状态，模型可能还没搜索到它。
发起了工具调用但一直没有进展：可能在等待审批，或参数没通过校验。到「轨迹」页面查看该回合的状态和报错，并检查聊天窗口下方是否有待处理的审批卡片。
工具返回内容太长，撑爆上下文：开启大结果自动转存，超过阈值时只给模型摘要和读取路径；也可以把这类工具改为按需检索。
工具调用总被自动拒绝：检查权限模式是否为「只读」，以及调用者的权限等级。「完全放行」只对管理员生效，低权限用户会降级为「自动」。
下一步
- 工具、技能与 MCP — 理清三者的分工。
- 技能 — 把领域指引和脚本打包为技能。
- MCP — 接入外部标准化服务。
- 权限与安全 — 配置权限等级、审批规则和安全模式。
- 场景规则 — 按群聊配置工具清单和工具模式。
