Tool Search | Fivey Can Read OpenClaw

先讲这一页到底在解决什么

Tool Search 给 PI agent 一张轻便工具目录卡

Tool Search 是 OpenClaw PI agent 的实验能力：工具很多时，模型先搜索轻量目录，再描述选中的工具，最后仍通过 OpenClaw 正常调用。它适合大工具目录，不是 Codex harness 的原生工具搜索；策略、审批、hook、日志和失败关闭规则仍然照常生效。

原文共 11 节，先看 Start Here 路径：/tools/tool-search 查看官方原文

先别混淆

这页讲 PI 的 Tool Search，不是 Codex 自己的原生工具搜索

Codex harness 有自己的稳定 code mode、native tool search、deferred dynamic tools 和 nested tool calls。这里的 tools.toolSearch 是给 OpenClaw PI embedded runner 用的实验能力。

PI Tool Search

像给 PI agent 一张可搜索目录卡，适合大工具目录但只会用到少数工具的场景。

Codex native search

属于 Codex harness 自己的运行表面，不依赖 tools.toolSearch 这个开关。

直接暴露工具

工具少时仍然是好选择，模型一开始就能看到完整 schema。

一句话

不要把“PI 的实验目录卡”和“Codex 的原生工具能力”看成同一个按钮。

一次调用怎么走

先搜目录，再看说明，最后回到 OpenClaw 真正执行

Tool Search 的小运行时不会拿着插件实现、MCP client 或 secret 自己开工。真正的调用会跨回 Gateway，让平常的策略、审批、hook、日志和结果处理继续生效。

1

`search`

像在目录里搜“创建日历事件”或“创建 GitHub issue”，拿到轻量候选项。

2

`describe`

选中一个候选工具后，再看它真正需要哪些输入字段。

3

`call`

把参数交给 OpenClaw，由 Gateway 按正常规则执行。

4

策略仍在

不在有效工具策略里的工具不会被搜出来；审批或权限挡住时也不能绕过去。

两种模式

`code` 像小脚本桥，`tools` 像三枚普通按钮

默认的 code 模式给模型一个 tool_search_code 工具，让它在隔离 Node 子进程里写很短的 JavaScript。不能或不该给代码形态时，可以改用结构化 fallback。

mode: "code"

暴露一个紧凑的代码桥，适合模型在一个小脚本里完成搜索、描述和调用。

mode: "tools"

暴露 tool_search、tool_describe、tool_call 三个普通结构化工具。

同一条后端路

两种模式看到的形状不同，但目录、策略和最终执行路径一样。

实验能力

大目录时可以试；小目录或 Codex harness 场景不要硬套。

配置记法

打开它是一颗开关，调细节才需要更多字段

最简单是设置 tools.toolSearch 为 true。需要控制模式、超时和搜索结果数量时，再展开成对象。

默认开启

openclaw config set tools.toolSearch true 会启用默认 code bridge。

结构化模式

{ tools: { toolSearch: { mode: "tools" } } } 适合不想给 provider 代码形态的部署。

调节边界

codeTimeoutMs、searchDefaultLimit、maxSearchLimit 控制小桥跑多久、一次看多少结果。

关闭

{ tools: { toolSearch: false } } 会回到不用 Tool Search 的路。

安全边界

隔离小脚本只负责找路，不负责偷偷搬东西

代码桥运行在短命 Node 子进程里，环境为空，没有文件系统、网络、子进程或 worker 权限。它只暴露日志和 openclaw.tools 三个方法。

没有 secret

子进程不持有插件实现、MCP client 对象或凭据。

超时会停

父进程有墙钟超时，异步没结束也会被杀掉。

失败关闭

工具不可用、策略不允许、审批不通过，都应该报告阻塞，而不是绕路执行。

日志可复盘

telemetry 会记录目录大小、搜索/描述/调用次数、最终工具来源等信息，方便比较直接暴露和 Tool Search 的差异。

最后记住

Tool Search 不是让工具少受管，而是让大目录更省、更清楚

它帮 PI agent 少背完整 schema，但真正执行仍回到 OpenClaw 的规则系统。大工具目录可以用它减负；Codex harness 和小工具目录通常不需要它。