Pesquisa de ferramentas

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

​

Como um turno é executado

1. Resolve a política de ferramentas ativa para o agente, o perfil, o sandbox e a sessão.
2. Lista as ferramentas qualificadas do OpenClaw e dos plugins.
3. Lista as ferramentas MCP qualificadas por meio do runtime MCP da sessão.
4. Adiciona as ferramentas qualificadas do cliente fornecidas para a execução atual.
5. Mantém as ferramentas somente diretas visíveis para o modelo e indexa descritores compactos para as demais ferramentas qualificadas para o catálogo.
6. Expõe a ponte de código do OpenClaw, as ferramentas estruturadas de contingência ou a superfície compacta de diretório junto dessas ferramentas somente diretas.

​

Modos

• code: expõe tool_search_code, a ponte JavaScript compacta padrão, junto das ferramentas somente diretas.
• tools: expõe tool_search, tool_describe e tool_call como ferramentas estruturadas simples para provedores que não devem receber código, junto das ferramentas somente diretas.
• directory: expõe tool_search, tool_describe e tool_call, além de um diretório limitado no prompt com os nomes e as descrições das ferramentas disponíveis, para provedores que devem ver os nomes das ferramentas sem receber todos os esquemas completos. O OpenClaw também pode expor diretamente um pequeno conjunto limitado de esquemas de ferramentas prováveis ou obrigatórias para o turno atual. As ferramentas somente diretas também permanecem visíveis nesse modo.

​

Por que isso existe

• ferramentas diretas: o modelo vê todos os esquemas selecionados antes do primeiro token
• modo de código da Pesquisa de Ferramentas: o modelo vê uma ferramenta de código compacta, um contrato curto de API e quaisquer ferramentas somente diretas
• modo de ferramentas da Pesquisa de Ferramentas: o modelo vê três ferramentas estruturadas compactas de contingência, além de quaisquer ferramentas somente diretas
• modo de diretório da Pesquisa de Ferramentas: o modelo vê um diretório limitado, controles de pesquisa/descrição/chamada e um pequeno conjunto limitado de esquemas prováveis ou obrigatórios, além de quaisquer ferramentas somente diretas
• durante o turno: o modelo pode carregar os esquemas restantes conforme necessário

​

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

​

Limite do runtime

• console.log, console.warn e console.error
• openclaw.tools.search
• openclaw.tools.describe
• openclaw.tools.call

• políticas de permissão e negação de ferramentas
• restrições de ferramentas por agente e por sandbox
• política de ferramentas do canal/runtime
• hooks de aprovação
• hooks before_tool_call de plugins
• identidade da sessão, logs e telemetria

​

Configuração

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

​

Prompt e telemetria

• total de bytes serializados de ferramentas e do prompt enviados ao harness
• tamanho do catálogo e divisão por fonte
• contagens de pesquisas, descrições e chamadas
• chamadas finais de ferramentas executadas por meio do OpenClaw
• IDs e fontes das ferramentas selecionadas

• quantos esquemas de ferramentas o modelo viu antecipadamente
• quantas operações de pesquisa e descrição ele realizou
• qual ferramenta final foi chamada
• se o resultado veio do OpenClaw, do MCP ou de uma ferramenta do cliente

​

Validação E2E

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

1. O modo direto consegue chamar a ferramenta do plugin falso.
2. A Pesquisa de Ferramentas consegue chamar a mesma ferramenta do plugin falso.
3. O modo direto expõe os esquemas das ferramentas do plugin falso diretamente ao provedor.
4. A Pesquisa de Ferramentas expõe apenas a ponte compacta e quaisquer ferramentas somente diretas.
5. O payload da solicitação da Pesquisa de Ferramentas é menor para o grande catálogo falso.
6. Os logs da sessão mostram as contagens esperadas de chamadas de ferramentas e a telemetria das chamadas realizadas pela ponte.

​

Comportamento em caso de falha

• se uma ferramenta não estiver na política efetiva, a pesquisa não deverá retorná-la
• se uma ferramenta selecionada ficar indisponível, tool_call deverá falhar
• se a política ou a aprovação bloquear a execução, o resultado da chamada deverá relatar esse bloqueio em vez de contorná-lo
• se a ponte de código não puder criar um runtime isolado, use mode: "tools" ou desabilite a Pesquisa de Ferramentas nessa implantação

​

Relacionados

• Ferramentas e plugins
• Sandbox multiagente e ferramentas
• Ferramenta Exec
• Configuração de agentes ACP
• Criação de plugins