工具搜索

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...",
});

​

单个轮次如何运行

1. 解析智能体、配置文件、沙箱和会话的活动工具策略。
2. 列出符合条件的 OpenClaw 工具和插件工具。
3. 通过会话 MCP 运行时列出符合条件的 MCP 工具。
4. 添加为当前运行提供的符合条件的客户端工具。
5. 保持仅限直接调用的工具对模型可见，并为其余符合目录收录条件的工具建立紧凑描述符索引。
6. 在这些仅限直接调用的工具旁公开 OpenClaw 代码桥接、结构化回退工具或紧凑目录界面。

​

模式

• code：公开 tool_search_code（默认的紧凑 JavaScript 桥接）以及仅限直接调用的工具。
• tools：将 tool_search、tool_describe 和 tool_call 作为普通结构化工具公开，适用于不应接收代码的提供商，同时还会公开仅限直接调用的工具。
• directory：公开 tool_search、tool_describe 和 tool_call，以及一个包含可用工具名称和描述的有界提示词目录，适用于应看到工具名称但不应看到每个完整 schema 的提供商。OpenClaw 还可以为当前轮次直接公开一小组有界的可能需要或必需的工具 schema。在此模式下，仅限直接调用的工具仍然可见。

​

存在的原因

• 直接工具：模型会在生成第一个 token 前看到每个选定的 schema
• 工具搜索代码模式：模型会看到一个紧凑代码工具、一份简短的 API 契约，以及所有仅限直接调用的工具
• 工具搜索工具模式：模型会看到三个紧凑的结构化回退工具，以及所有仅限直接调用的工具
• 工具搜索目录模式：模型会看到一个有界目录、搜索/描述/调用控制项、一小组有界的可能需要或必需的 schema，以及所有仅限直接调用的工具
• 在轮次期间：模型可以按需加载其余 schema

​

API

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

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

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

• tool_search
• tool_describe
• tool_call

• 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,
  },
}

​

提示词和遥测

• 发送给 harness 的工具和提示词序列化总字节数
• 目录大小和来源明细
• 搜索、描述和调用次数
• 通过 OpenClaw 执行的最终工具调用
• 选定的工具 ID 和来源

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

​

E2E 验证

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

1. 直接模式可以调用虚假插件工具。
2. 工具搜索可以调用同一个虚假插件工具。
3. 直接模式将虚假插件工具的 schema 直接暴露给提供商。
4. 工具搜索仅暴露紧凑型桥接器以及所有仅限直接模式的工具。
5. 对于大型虚假目录，工具搜索的请求载荷更小。
6. 会话日志显示预期的工具调用次数和桥接调用遥测数据。

​

失败行为

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

​

相关内容

• 工具和插件
• 多 Agent 沙盒和工具
• Exec 工具
• ACP Agents 设置
• 构建插件