工具搜索

const hits = await openclaw.tools.search("创建一个 GitHub issue");
const tool = await openclaw.tools.describe(hits[0].id);
return await openclaw.tools.call(tool.id, {
  title: "启动时崩溃",
  body: "复现步骤...",
});

​

一次回合如何运行

1. 为代理、配置文件、沙箱和会话解析当前生效的工具策略。
2. 列出符合条件的 OpenClaw 工具和插件工具。
3. 通过会话 MCP 运行时列出符合条件的 MCP 工具。
4. 添加为此次运行提供的符合条件的客户端工具。
5. 将核心编码原语和仅可直接使用的工具保持为模型可见，并为目录中其余符合条件的工具编制紧凑描述符。
6. 将确定性、有界且经过策略过滤的能力目录添加到缓存稳定的系统提示前缀中。
7. 将 OpenClaw 代码桥、结构化回退工具或紧凑目录界面，与那些稳定且可直接调用的工具一同暴露出来。

​

模式

• code: 暴露 tool_search_code，这是默认的紧凑 JavaScript 桥接， 同时暴露能力目录和仅直接调用工具。
• tools: 暴露 tool_search、tool_describe 和 tool_call 作为纯 结构化工具，适用于不应接收代码的提供方，同时暴露能力目录和仅直接调用工具。
• directory: 暴露 tool_search、tool_describe 和 tool_call，以及一个 有界、缓存稳定的提示目录。核心编码原语、仅直接调用工具，以及运行交付策略要求的工具仍然可见；其他 模式保持延后加载。

​

为什么需要它

• direct tools: 模型在第一个 token 之前就会看到每个已选 schema
• Tool Search code mode: 模型会看到一个紧凑的代码工具、一个有边界的 能力目录、一个简短的 API 契约，以及任何仅直接暴露的工具
• Tool Search tools mode: 模型会看到三个紧凑的结构化回退 工具、相同的能力目录，以及任何仅直接暴露的工具
• Tool Search directory mode: 模型会看到一个有边界的目录，以及 search/describe/call 控制项、策略要求的直接工具，以及任何 仅直接暴露的工具
• 在本轮过程中：模型可以根据需要加载其余 schema

​

API

const hits = await openclaw.tools.search("日历事件", { limit: 5 });

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

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

• tool_search
• tool_describe
• tool_call

{
  "query": "today's calendar events",
  "limit": 3
}

{
  "queries": [
    { "query": "today's calendar events", "limit": 3 },
    { "query": "Slack messages needing attention", "limit": 3 }
  ]
}

• tool_search
• tool_describe
• tool_call

​

运行时边界

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

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

​

配置

openclaw config set tools.toolSearch true

{
  tools: {
    toolSearch: true,
  },
}

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

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

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

{
  tools: {
    toolSearch: false,
  },
}

​

提示词和遥测

• catalogSize: 运行时解析的目录条目数量
• sources: 按 openclaw、mcp 和 client 划分的目录条目数量
• counterScope: 计数器生命周期的不透明标识符；当追加工具或提示词策略缩小目录时保持稳定，而当目录被替换或恢复时发生变化
• searchCount、describeCount、callCount: 目录会话的累计总数，会在多次调用之间延续，而不是每次调用时重置

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

​

端到端验证

pnpm openclaw qa suite --provider-mode mock-openai --scenario tool-search-gateway-e2e

1. Direct mode can call the fake plugin tool.
2. Tool Search can call the same fake plugin tool.
3. Direct mode exposes the fake plugin tool schemas directly to the provider.
4. Tool Search exposes only the compact bridge plus any direct-only tools.
5. The Tool Search request payload is smaller for the large fake catalog.
6. Session logs show the expected tool-call counts and bridged call telemetry.
7. Structured mode resolves two queries with one tool_search call before the selected plugin tool runs through tool_call.

​

失败行为

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

​

相关内容

• 工具和插件
• 多代理沙箱和工具
• Exec 工具
• ACP 代理设置
• 构建插件