Tool Search（工具搜索）

概述

Tool Search 是 OpenClaw PI Agent 的实验性功能，让 PI Agent 通过搜索、描述、调用三步操作来使用大型工具目录，而无需将所有工具 schema 预先注入 prompt。适用于工具数量多但每次只需少数工具的场景。

核心功能

• code 模式：暴露 tool_search_code 工具，Agent 在隔离 Node 子进程中运行 JS 代码
• tools 模式：暴露 tool_search、tool_describe、tool_call 三个结构化工具
• 支持 OpenClaw 工具、插件工具、MCP 工具、客户端工具的统一目录
• 隔离运行时：Node 子进程无文件系统/网络/子进程权限
• 所有实际工具调用仍通过 OpenClaw 执行（保留策略/审批/钩子/日志）

API

// 搜索工具目录
const hits = await openclaw.tools.search("create a GitHub issue");
 
// 获取工具完整 schema
const tool = await openclaw.tools.describe(hits[0].id);
 
// 调用工具
return await openclaw.tools.call(tool.id, {
  title: "Crash on startup",
  body: "Steps to reproduce...",
});

配置/使用

{
  tools: {
    toolSearch: true,  // 启用（默认 code 模式）
  },
}

高级配置：

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

注意事项

• 仅适用于 PI Agent，不适用于 Codex harness 运行
• 小型工具目录建议直接暴露工具（不使用 Tool Search）
• code 模式子进程无法创建子进程、访问文件系统或网络
• 若无法创建隔离运行时，自动回退到 tools 模式

相关页面

• concepts/tool-subagents — Sub-agents（另一种任务委托机制）
• concepts/tool-acp-agents-setup — ACP agents 设置
• concepts/tool-multi-agent-sandbox-tools — 多 Agent 沙箱与工具策略