工具搜索
Tool Search 是 OpenClaw agent 运行时的一项实验性功能。它为 agent 提供了一种紧凑的方式来发现和调用大型工具目录。当运行中有许多可用工具,但模型可能只需要其中少数几个时,该功能非常实用。
本文档介绍 OpenClaw Tool Search。它不是 Codex 原生的工具搜索或动态工具表面。Codex 原生代码模式、工具搜索、延迟动态工具和嵌套工具调用是稳定的 Codex harness 表面,不依赖于 tools.toolSearch。
对于公开 JavaScript exec/wait 表面(而非 Tool Search 控件)的通用 OpenClaw 运行时,请参阅 Code Mode。
当 tools.toolSearch 未设置时,OpenClaw embedded 和 Copilot 运行会自动使用结构化 Tool Search。这会在保留经策略批准的能力的同时延迟工具 schema。它不会启用精简模式或移除可选工具。设置 tools.toolSearch: false 可恢复直接 schema。已启用的 Code Mode 优先,Codex 保持其原生表面。此自动默认行为不会重写配置文件。
当为 OpenClaw 运行启用该功能时,模型会自动收到一个受限目录,其中包含可用可信工具的名称和描述,以及结构化的 tool_search、tool_describe 和 tool_call 控件。设置 tools.toolSearch: true 或不含 mode 的对象会选择此结构化表面。仅直接调用(direct-only)工具在控件旁边保持可见。
目录会随活动模型的上下文窗口进行缩放。当空间紧张时,描述会先被缩短,然后才会省略工具名称;每个经授权的目录条目仍然可搜索、可调用。对于 OpenClaw 自有工具的无效参数,如果能够呈现受限的预期输入签名,错误中会包含该签名,以便模型无需再次查询 schema 即可纠正调用。如果调用将已接纳的技能名称误认为工具 ID,错误会指向该技能的完整说明,而不是让模型进入工具搜索流程。
延迟目录会省略已经直接公开的工具。它们仍然可搜索,因此发现操作仍可返回它们的完整 schema,而无需重复原生指南。
目录可以包含符合目录条件的 OpenClaw 工具、插件工具、MCP 工具和客户端提供的工具。目录让模型了解它可以发现哪些受信任的能力,而无需预先公开每个已编目 schema。它还说明了经策略批准的 MCP 和客户端工具可能是可发现的。它们不受信任的名称和描述不会被复制到系统提示词中。相反,模型会搜索紧凑的描述符,在需要精确 schema 时描述一个选定的工具,并通过 OpenClaw 调用该工具。仅直接调用工具保持模型可见,且不会被添加到目录中。
Codex harness 运行不会收到这些实验性的 OpenClaw Tool Search 控件。OpenClaw 将产品能力作为动态工具传递给 Codex,Codex 拥有稳定的原生代码模式、原生工具搜索、延迟动态工具和嵌套工具调用。
轮次的运行方式¶
在规划阶段,OpenClaw embedded 运行器会为本次运行构建有效目录:
- 解析 agent、profile、sandbox 和 session 的生效工具策略。
- 列出符合条件的 OpenClaw 和插件工具。
- 通过 session MCP 运行时列出符合条件的 MCP 工具。
- 添加为当前运行提供的符合条件的客户端工具。
- 保持核心编码原语和仅直接调用工具对模型可见,并为其余符合目录条件的工具建立紧凑描述符索引。
- 将确定性的、受限的、经过策略过滤的能力目录添加到缓存稳定的系统提示词前缀中。
- 公开结构化的搜索、描述和调用工具,或将紧凑的目录表面与这些稳定的、可直接调用的工具一起展示。
在执行阶段,每个真实的工具调用都会返回到 OpenClaw,正常的策略、审批、钩子、日志记录和结果处理仍然适用。
模式¶
tools.toolSearch 有两种面向模型的模式:
tools:当tools.toolSearch未设置、为true或不含 mode 的对象时的默认模式。将tool_search、tool_describe和tool_call公开为普通结构化工具,与能力目录和仅直接调用工具并列。directory:公开tool_search、tool_describe和tool_call,外加一个受限的、缓存稳定的提示词目录。核心编码原语、仅直接调用工具以及运行交付策略所需的工具保持可见;其他 schema 保持延迟状态。
所有模式都使用相同的策略过滤目录和正常的 OpenClaw 执行路径。标记为 catalogMode: "direct-only" 的工具保持在目录之外,并对模型可见。在 directory 模式下,客户端提供的工具在当前运行期间保持直接可见,而 OpenClaw 工具、插件工具和 MCP 工具可以被压缩到目录之后。在 embedded harness 中,对精确的隐藏目录名称的直接调用会在执行前从同一经授权目录中水合。而 Copilot harness 则将 directory 映射为结构化的 tools 语义:隐藏的 OpenClaw 目录名称必须通过 tool_call 调用,因为它们不是已注册的 SDK 处理器。
结构化的 tools 表面默认对 OpenClaw 运行开启。目标工具保留自己的超时和审批行为。Codex harness 运行使用其原生表面。
压缩并不总是更便宜:小型目录会增加 schema 开销,额外的发现轮次可能会抵消初始负载节省。当直接 schema 更适合你的工作负载时,请设置 tools.toolSearch: false。
没有单独的来源选择配置。启用 Tool Search 后,经过正常策略过滤,目录会包含符合目录条件的 OpenClaw、MCP 和客户端工具;仅直接调用工具会单独保留。
为什么存在此功能¶
大型目录很有用,但成本高昂。将每个工具 schema 发送给模型会使请求变大、减慢规划速度,并增加误选工具的风险。
工具搜索会改变形态:
- 直接工具:模型在第一个 token 之前看到每个选定的 schema
- 工具搜索工具模式:模型看到三个紧凑的结构化工具、相同的能力目录以及任何仅限直接调用的工具
- 工具搜索目录模式:模型看到一个有界的目录,以及搜索/描述/调用控制、策略要求的直接工具和任何仅限直接调用的工具
- 在回合期间:模型可以根据需要加载剩余的 schema
当一个运行可以同时看到许多工具时,工具搜索非常有用,尤其是来自 MCP 服务器或客户端提供的应用工具。结构化搜索是默认方式,但实际的请求大小和延迟取决于目录和模型的调用。
能力目录按工具名称排序,限制为 18,000 个字符,并由已经过策略过滤的目录构建。OpenClaw 对未更改的目录快照复用已渲染的目录,并将其放置在系统提示词缓存边界之上。用户消息、每次回合的工具猜测、会话标识符以及不受信任的 MCP 或客户端元数据不会进入目录。这使重复的回合能够进行提示词 KV 缓存复用。当授权目录发生变化时,OpenClaw 会为新快照构建新的目录。提示词钩子 toolsAllow 限制在最终提示词提交之前生效:嵌入式和 Copilot 提示词仅展示剩余的目录,而不会重新运行钩子或重写较早的对话回合。
结构化控制¶
搜索¶
tool_search 搜索当前运行的有效目录。它接受一个查询和一个可选的限制参数。
查询必须用英语编写。排序是基于词法的(对工具名称、描述以及第一方参数名称和描述应用 Okapi BM25),带有轻度英语词干提取,因此 scheduling 可以匹配到描述为 Schedule a recurring task 的工具,并有少量意图扩展,因此 look up the price 可以匹配到描述为 Search the web 的工具。工具名称和描述是用英语编写的,因此使用其他语言的查询通常不会匹配到任何内容。它不会被拒绝——目录可能合理地使用其他书写系统描述工具——但没有可用术语的查询不会返回排序结果,也不会返回目录的任意切片。即使精确的工具名称无法被分词,它仍然会被识别。tool_search 在其面向模型的描述中说明了这一要求。
不受信任的参数 schema 永远不会被索引。MCP 和客户端工具仅通过名称和描述进行匹配,这与将其输入签名延迟为 input: "unknown" 的边界相同。
结果紧凑且可以安全地放回提示词上下文中。每个命中结果都包含一个有界的 TypeScript 风格 input 签名,例如 { id: string; mode?: "drip" | "flood" },因此当该签名足够时,模型可以跳过 tool_describe。受信任的 OpenClaw 核心或插件工具还可能包含一个紧凑的 output 提示,例如 Array<{ id: string; paid: boolean }>。MCP 和客户端输出 schema 的声明不会被提升到此受信任的提示中。它们不受信任的输入 schema 也会被延迟为 input: "unknown";在调用它们之前请使用 tool_describe。开放式、过大或其他不完整的输出 schema 会省略该提示,但可以通过 tool_describe 获取。
描述¶
tool_describe 接受搜索结果的 id 并加载其完整元数据,包括精确的输入 schema;如果工具声明了受信任的完整 outputSchema,也会一并加载。
调用¶
tool_call 接受工具的 id 及其目标 args,通过 OpenClaw 调用所选工具,并返回 { tool, result } 封装。返回 JSON 的工具通常将其值放在 result.details 中。OpenClaw 在执行前会验证受信任的核心或插件工具所声明的输入 schema。缺少必需参数、类型不正确以及包含禁止属性时,会返回可操作的工具错误,而不是执行该工具;拼写错误的属性在可用时会包含建议的参数。如果受信任的工具还声明了 outputSchema,OpenClaw 会在执行前编译该 schema,并在正常工具钩子之后、返回目录调用之前验证最终的 details。MCP 和客户端拥有的 schema 仍然延迟到其所属的执行边界。
如果 tool_call 指定了为当前回合声明的仅限直接调用的工具,它会返回指导,提示按该工具声明的名称和参数直接调用它。它不会通过目录调度仅限直接调用的工具,也不会建议搜索它们。当前回合不可用的工具仍会收到普通的目录未命中错误。
tool_call 还会修复来自本地模型的扁平化目标参数。它保留 id 和 name 等目标字段,并拒绝有歧义的工具选择器,而不是调用错误的工具。当目标字段与另一个已编入目录的工具匹配时,请将目标参数嵌套在 args 下。
结构化控制面向模型的文本仅包含工具的 id、name 和 source,以及未更改的目标 result;它不会重复描述和输入签名。其结构化的 details 为运行时消费者保留完整的调用封装。如需完整的工具元数据,请使用 tool_describe。
{
"id": "mcp:calendar:create_event",
"args": {
"summary": "Planning",
"start": "2026-05-09T14:00:00Z"
}
}
工具作者在工具的 outputSchema 属性上声明输出契约。它描述的是 AgentToolResult.details,而不是渲染的内容块。包括所有不会抛出异常的变体;对于不稳定的结果,则省略它。参见 代码模式输出契约 和 工具插件。
延迟名称是目录条目,不是此模式下可直接调用的函数。将结果 ID 或名称放在 tool_call.id 中,并将所有目标参数放在 tool_call.args 中,即使其他指令按名称引用延迟工具时也是如此。紧凑的搜索签名可能足以调用它;当需要完整 schema 时,请使用 tool_describe。
批量搜索¶
tool_search 接受单查询形式或独立查询批次:
{
"queries": [
{ "query": "today's calendar events", "limit": 3 },
{ "query": "Slack messages needing attention", "limit": 3 }
]
}
单查询调用仍会直接返回紧凑候选数组。当两种形式都包含搜索时,非空 query 先运行,顶层 limit 仅作用于它。批次条目按请求顺序跟随,包括重复的查询文本;每次出现保留自己的 limit,并计入批次预算。
当存在非空批次时,省略、null、空或仅空白字符的 query 会被忽略。此时应省略顶层 limit 或将其设为 null;非 null 的顶层 limit 会被拒绝,而不会应用到批次。省略或 null 的 queries 保持标量行为,当 query 非空时,queries: [] 也会回退到标量形式。没有批次时的空白标量查询仍返回空候选数组。没有批次时缺失或 null 的标量,或没有非空标量的空批次,会被拒绝。标量 limit: null 使用默认 limit,与省略 limit 相同。无效的查询形式、无效的 limit 以及超出预算的批次仍会失败。
批量调用按请求顺序返回 { results: [{ query, candidates }] }。每个查询使用与普通搜索相同的有效目录、排序、过滤和每查询 limit;某个候选可能出现在多个结果组中。描述在输出前会被压缩。如果完整批次将超过 4,000 字符的响应预算,排名较低的候选会被移除,并且响应包含 truncated: true。丢失候选的结果组也会包含 truncated: true,因此空的截断组不会被误认为没有匹配的查询。省略的每查询 limit 使用 searchDefaultLimit。一个批次中的有效 limit 最多可请求总计 50 个候选。一个批次最多接受 16 个查询,每个查询最多 512 个字符,序列化查询列表总计最多 512 个 UTF-8 字节。无效批次会作为单个请求失败,而没有匹配的合法查询返回空的 candidates 数组。
目录模式¶
目录模式公开:
tool_searchtool_describetool_call
它还会保持核心文件和 shell 原语、客户端提供的工具、仅限直接调用的工具以及策略要求的交付工具直接可见。其他已授权的工具 schema 保持延迟,而不是随每个用户提示变化。MCP 工具不能冒充直接可见的核心工具或策略要求的交付工具。如果有限目录省略了条目,请使用 tool_search 查找它们,并使用 tool_describe 获取其完整 schema。如果模型直接请求确切的隐藏目录工具名称,嵌入式 harness 会在正常执行前从已授权目录中解析它。Copilot 则改用 tool_call,如 模式 中所述。
目录模式的客户端工具名称不得与 OpenClaw、插件或 MCP 工具名称冲突,因为精确延迟调度使用这些名称。
执行策略¶
普通 OpenClaw 行为仍适用于最终调用:
- 工具允许和拒绝策略
- 每个 agent 和每个 sandbox 的工具限制
- 通道/运行时工具策略
- 审批 hooks
- 插件
before_tool_callhooks - 工具
executionMode:顺序调用与同一目录中的其他调用互斥运行,包括来自其他 Tool Search 或 Code Mode 单元格的调用 - 会话身份、日志和遥测
配置¶
在未设置 tools.toolSearch 时,OpenClaw 运行使用结构化 tools 模式,默认搜索 limit 为 8,最大值为 20。本地 Ollama 模型、LM Studio 和管理型本地服务保留其较小的 limit,分别为 5 和 10。已知的托管 Ollama 路由使用通用 limit。由 Ollama daemon 提供的未标记别名会继承该 daemon 的 limit,即使该别名转发到托管模型。仅凭模型名称或 loopback URL 不会将其他提供商分类为本地。
显式的 tools.toolSearch 值优先,包括 false。
设置 agents.defaults.experimental.localModelLean: false 会恢复可选工具,但不会关闭自动 Tool Search。
显式启用结构化 Tool Search:
等效 JSON:
显式固定结构化默认值:
对于 OpenClaw 运行,改用紧凑目录界面:
调整搜索结果 limit(所示值为默认值):
运行时会将 maxSearchLimit 限制在 1-50,并将 searchDefaultLimit 限制在 1..maxSearchLimit。
禁用它:
升级¶
Tool Search 代码模式(tool_search_code)已弃用。运行 openclaw doctor --fix 可将 tools.toolSearch.mode: "code" 迁移为 "tools",并移除 codeTimeoutMs。迁移会保留 Tool Search 是否启用。openclaw update 通常会替你运行它;延迟 Doctor 配置修复的更新(例如较旧的 Git 更新器)之后需要运行 openclaw doctor --fix。在未迁移配置上启动的 Gateway 会退出,并指出已弃用的键和此命令。
toolSearch: true 以及没有 mode 的对象现在会选择结构化搜索。对于 JavaScript 编排,请使用 Code Mode 及其 exec/wait 界面。
会话活动¶
搜索、描述和调用结果会携带该操作的目录数据。OpenClaw 不记录序列化的工具或 prompt 字节数。E2E 场景 单独测量提供商 payload 字节数,与 mock 提供商通道分开。
无论处于哪种模式,已完成的目标调用都会作为有界、脱敏的展示活动保留在会话历史中,而不会添加用于回放的合成模型轮次。
搜索、描述和调用结果都会携带每个工具的 id 和 source。
因此,会话日志仍然可以回答:
- 模型最初看到了多少个工具 schema
- 它执行了多少次搜索和描述操作
- 最终调用了哪个工具
- 结果来自 OpenClaw、MCP 还是客户端工具
E2E 验证¶
QA Lab Gateway 场景使用 OpenClaw 运行时比较直接模式和结构化 Tool Search:
它会创建一个带有大型工具目录的临时假插件,启动 mock OpenAI 提供商,然后以直接模式和结构化 Tool Search 模式运行 Gateway。它会比较提供商请求负载,然后验证两种模式中的会话日志和工具流。
该回归测试证明:
- 直接模式可以调用假插件工具。
- Tool Search 可以调用同一个假插件工具。
- 直接模式会直接将假插件工具 schema 暴露给提供商。
- Tool Search 会暴露紧凑的结构化控件以及任何仅限直接模式的工具。
- 对于大型假目录,Tool Search 请求负载更小。
- 会话日志显示预期的工具调用次数。
- 结构化模式在选定的插件工具通过
tool_call运行之前,使用一次tool_search调用解决两个查询。
真实模型对比¶
此可选检查使用已配置的 OpenAI 凭据;如果没有这些凭据,则会被跳过。 它通过 OpenClaw runner 使用小型和大型合成目录,比较直接暴露、未设置的默认值以及两种显式 Tool Search 模式。在目标工具内部创建的验证代码可证明实际执行。该检查覆盖策略拒绝和仅限直接模式的工具、延迟 schema 以及转录投递,且不会强制模型选择工具。它报告请求字节数、发现和调用次数、schema 恢复以及耗时。小型目录通过测量来评估,而不是假定它们能从压缩中受益。成功的检查并不是跨提供商可靠性基准。
失败行为¶
Tool Search 应当失败关闭:
- 如果工具不在有效策略中,搜索不应返回它
- 如果所选工具变得不可用,
tool_call应当失败 - 如果策略或审批阻止执行,调用结果应报告该阻止,而不是绕过它
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw