OpenClaw PI Tool Search 让智能体通过单个压缩代码桥或三个结构化回退工具来搜索、描述和调用大量工具，无需将所有 schema 塞入提示词。启用后模型默认收到一个 tool_search_code 工具，在隔离的 Node 子进程中执行 search → describe → call 三步。适合 MCP 工具或客户端工具较多的运行场景，小工具目录应直接使用工具暴露。调试可用 openclaw config set tools.toolSearch true 启用，并通过 E2E 测试脚本对比直接模式与 Tool Search 模式的请求载荷。

OpenClaw PI 代理工具搜索配置与调试

Tool Search 是 OpenClaw PI 智能体的实验性功能。它让 PI 智能体通过一种紧凑的方式发现和调用大型工具目录，当运行时有大量可用工具但模型可能只需要其中少数时尤其有用。

本文档描述 OpenClaw PI Tool Search，它不同于 Codex 原生的工具搜索或动态工具表面。Codex 原生的代码模式、工具搜索、延迟动态工具和嵌套工具调用是稳定的 Codex harness 表面，不依赖 tools.toolSearch。

启用 Tool Search 后，模型会默认收到一个 tool_search_code 工具。该工具在隔离的 Node 子进程中运行一段短 JavaScript 代码，并通过 openclaw.tools 桥接：

const hits = await openclaw.tools.search("create a GitHub issue");
const tool = await openclaw.tools.describe(hits[0].id);
return await openclaw.tools.call(tool.id, {
  title: "Crash on startup",
  body: "Steps to reproduce...",
});

目录可以包含 OpenClaw 工具、插件工具、MCP 工具和客户端提供的工具。模型不会预先看到每个工具的完整 schema，而是先搜索紧凑的描述符，在需要确切 schema 时描述选中工具，然后通过 OpenClaw 调用。

Codex harness 运行不会收到这些实验性 OpenClaw Tool Search 控制。OpenClaw 以动态工具的形式将产品能力传递给 Codex，而 Codex 拥有稳定的原生代码模式、原生工具搜索、延迟动态工具和嵌套工具调用。

单次运行流程

在规划阶段，PI 嵌入式运行器为本次运行构建有效目录：

解析智能体、profile、沙箱和会话的当前工具策略。
列出符合条件的 OpenClaw 和插件工具。
通过会话 MCP 运行时列出符合条件的 MCP 工具。
添加本次运行提供的客户端工具。
为搜索建立紧凑描述符索引。
向模型暴露 PI 代码桥或结构化回退工具。

执行时每个真实的工具调用都会返回 OpenClaw。隔离的 Node 运行时不会持有插件实现、MCP 客户端对象或密钥。openclaw.tools.call(...) 通过桥接回到网关，常规的策略、审批、钩子、日志和结果处理仍然生效。

模式

tools.toolSearch 有两种面向模型的模式：

code（默认）：暴露 tool_search_code，紧凑的 JavaScript 桥接。
tools：暴露 tool_search、tool_describe 和 tool_call 三个纯结构化工具，适用于不应接收代码的 provider。

两种模式使用相同的目录和执行路径，区别仅在于模型看到的形状。如果当前运行时无法启动隔离的 Node 代码模式子进程，默认的 code 模式会在目录压缩前回退到 tools。

两种模式均为实验性。小工具目录应优先使用直接工具暴露；Codex harness 运行应优先使用 Codex 原生稳定表面。

没有独立的源选择配置。启用 Tool Search 后，目录将包含经过正常策略过滤后的符合条件的 OpenClaw、MCP 和客户端工具。

为什么存在

大型目录有用但开销大。将所有工具 schema 发给模型会使请求变大、减慢规划、增加误选风险。

Tool Search 改变了形状：

直接工具：模型在第一个 token 前看到每个选中的 schema
Tool Search code 模式：模型看到一个紧凑代码工具和简短 API 契约
Tool Search tools 模式：模型看到三个紧凑的结构化回退工具
运行期间：模型仅加载实际需要的工具 schema

对于小目录，直接工具暴露仍然是正确的默认选择。Tool Search 最适合一次运行可以见到大量工具的场景，尤其是来自 MCP 服务器或客户端提供的应用工具。

API

openclaw.tools.search(query, options?)

搜索当前运行的有效目录，返回紧凑且可安全放回提示上下文的结果。

const hits = await openclaw.tools.search("calendar event", { limit: 5 });

openclaw.tools.describe(id)

加载一个搜索结果的完整元数据，包括精确的输入 schema。

const calendarCreate = await openclaw.tools.describe("mcp:calendar:create_event");

openclaw.tools.call(id, args)

通过 OpenClaw 调用所选工具。

await openclaw.tools.call(calendarCreate.id, {
  summary: "Planning",
  start: "2026-05-09T14:00:00Z",
});

结构化回退模式暴露相同的操作作为工具：

tool_search
tool_describe
tool_call

运行时边界

代码桥在短命的 Node 子进程中运行。子进程启动时启用 Node 权限模式、空环境、无文件系统或网络授权、无子进程或 Worker 授权。OpenClaw 强制执行父进程挂钟超时，超时后强制结束子进程，包括异步延续之后。

运行时仅暴露：

console.log、console.warn 和 console.error
openclaw.tools.search
openclaw.tools.describe
openclaw.tools.call

最终调用仍遵循 OpenClaw 常规行为：

工具允许/拒绝策略
按智能体和沙箱的工具限制
渠道/运行时工具策略
审批钩子
插件 before_tool_call 钩子
会话身份、日志和遥测

配置

使用默认代码桥启用 PI 运行的 Tool Search：

bash

openclaw config set tools.toolSearch true

等价 JSON：

json5

{
  tools: {
    toolSearch: true,
  },
}

使用结构化回退工具代替：

json5

{
  tools: {
    toolSearch: {
      mode: "tools",
    },
  },
}

调整代码模式超时和搜索结果限制：

json5

{
  tools: {
    toolSearch: {
      mode: "code",
      codeTimeoutMs: 10000,
      searchDefaultLimit: 8,
      maxSearchLimit: 20,
    },
  },
}

禁用：

json5

{
  tools: {
    toolSearch: false,
  },
}

提示与遥测

Tool Search 记录足够的遥测以便与直接工具暴露对比：

发送给 harness 的总序列化工具和提示字节数
目录大小和来源分布
搜索、描述和调用计数
通过 OpenClaw 执行的最终工具调用
选中的工具 ID 和来源

会话日志应能回答以下问题：

模型预先看到了多少工具 schema
它执行了多少次搜索和描述操作
最终调用了哪个工具
结果来自 OpenClaw、MCP 还是客户端工具

E2E 验证

网关 E2E 运行器通过 PI harness 验证两种路径：

bash

node --import tsx scripts/tool-search-gateway-e2e.ts

它会创建一个带有大型工具目录的临时虚假插件，启动 mock OpenAI provider，分别以直接模式和启用 Tool Search 模式启动网关，然后比较 provider 请求载荷和会话日志。

验证回归：

直接模式能调用虚假插件工具。
Tool Search 能调用同一个虚假插件工具。
直接模式将虚假插件工具 schema 直接暴露给 provider。
Tool Search 仅暴露紧凑桥接。
对于大型虚假目录，Tool Search 请求载荷更小。
会话日志显示预期的工具调用计数和桥接调用遥测。

故障行为

Tool Search 应失败关闭：

如果工具不在有效策略中，搜索不应返回它
如果选中的工具变得不可用，tool_call 应失败
如果策略或审批阻止执行，调用结果应报告该阻止，而不是绕过它
如果代码桥无法创建隔离运行时，应使用 mode: "tools" 或对该部署禁用 Tool Search

常见问题

如何启用 OpenClaw Tool Search？

运行 openclaw config set tools.toolSearch true。如果想使用结构化回退模式而非代码桥，设置 {"tools": {"toolSearch": {"mode": "tools"}}}。禁用设为 false。

code 模式和 tools 模式有什么区别？

code 模式暴露一个 tool_search_code 工具，允许模型在隔离子进程中编写 JavaScript 调用 search、describe 和 call。tools 模式暴露三个独立的结构化工具（tool_search、tool_describe、tool_call），适用于不能接收代码的 provider。两者使用相同的目录和执行逻辑。

什么场景应该禁用 Tool Search？

当工具目录很小（少于 10～20 个工具）时，直接工具暴露更简单且无额外延迟。如果遇到代码桥启动失败或超时，应回退到 mode: "tools" 或完全禁用。对于 Codex harness 运行，应使用 Codex 原生工具表面而非 OpenClaw Tool Search。

OpenClaw PI 代理工具搜索配置与调试 ​

单次运行流程 ​

模式 ​

为什么存在 ​

API ​

运行时边界 ​

配置 ​

提示与遥测 ​

E2E 验证 ​

故障行为 ​

相关链接 ​

常见问题 ​

如何启用 OpenClaw Tool Search？ ​

code 模式和 tools 模式有什么区别？ ​

什么场景应该禁用 Tool Search？ ​

OpenClaw PI 代理工具搜索配置与调试

单次运行流程

模式

为什么存在

API

运行时边界

配置

提示与遥测

E2E 验证

故障行为

相关链接

常见问题

如何启用 OpenClaw Tool Search？

code 模式和 tools 模式有什么区别？

什么场景应该禁用 Tool Search？