Busca de ferramentas

A Busca de Ferramentas é um recurso experimental de agente PI do OpenClaw. Ela oferece aos agentes PI uma forma compacta de descobrir e chamar grandes catálogos de ferramentas. É útil quando a execução tem muitas ferramentas disponíveis, mas o modelo provavelmente precisará de apenas algumas delas. Esta página documenta a Busca de Ferramentas PI do OpenClaw. Ela não é a busca de ferramentas nativa do Codex nem a superfície de ferramentas dinâmicas. O modo de código nativo do Codex, a busca de ferramentas, as ferramentas dinâmicas adiadas e as chamadas de ferramentas aninhadas são superfícies estáveis do harness do Codex e não dependem de tools.toolSearch. Quando habilitado para PI, o modelo recebe uma ferramenta tool_search_code por padrão. Essa ferramenta executa um corpo JavaScript curto em um subprocesso Node isolado com uma ponte 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...",
});

O catálogo pode incluir ferramentas do OpenClaw, ferramentas de Plugin, ferramentas MCP e ferramentas fornecidas pelo cliente. O modelo não vê todos os esquemas completos de antemão. Em vez disso, ele pesquisa descritores compactos, descreve uma ferramenta selecionada quando precisa do esquema exato e chama essa ferramenta por meio do OpenClaw. Execuções do harness do Codex não recebem esses controles experimentais da Busca de Ferramentas do OpenClaw. O OpenClaw passa capacidades do produto para o Codex como ferramentas dinâmicas, e o Codex é responsável pelo modo de código nativo estável, pela busca de ferramentas nativa, pelas ferramentas dinâmicas adiadas e pelas chamadas de ferramentas aninhadas.

Como um turno é executado

No momento do planejamento, o executor PI incorporado cria o catálogo efetivo para a execução:

Resolver a política de ferramentas ativa para o agente, perfil, sandbox e sessão.
Listar as ferramentas elegíveis do OpenClaw e de Plugin.
Listar as ferramentas MCP elegíveis por meio do runtime MCP da sessão.
Adicionar ferramentas de cliente elegíveis fornecidas para a execução atual.
Indexar descritores compactos para busca.
Expor a ponte de código PI ou as ferramentas estruturadas de fallback ao modelo.

No momento da execução, toda chamada real de ferramenta retorna para o OpenClaw. O runtime Node isolado não mantém implementações de Plugin, objetos de cliente MCP nem segredos. openclaw.tools.call(...) cruza a ponte de volta para o Gateway, onde a política, a aprovação, o hook, o registro em logs e o tratamento de resultados normais ainda se aplicam.

Modos

tools.toolSearch tem dois modos visíveis ao modelo:

code: expõe tool_search_code, a ponte JavaScript compacta padrão.
tools: expõe tool_search, tool_describe e tool_call como ferramentas estruturadas simples para provedores que não devem receber código.

Ambos os modos usam o mesmo catálogo e caminho de execução. A única diferença é o formato que o modelo vê. Se o runtime atual não puder iniciar o processo filho Node isolado do modo de código, o modo code padrão recua para tools antes da compactação do catálogo. Ambos os modos são experimentais. Prefira exposição direta de ferramentas para catálogos pequenos de ferramentas PI, e prefira as superfícies estáveis nativas do Codex para execuções do harness do Codex. Não há uma configuração separada de seleção de fonte. Quando a Busca de Ferramentas está habilitada, o catálogo inclui ferramentas elegíveis do OpenClaw, MCP e de cliente após a filtragem normal por política.

Por que isso existe

Catálogos grandes são úteis, mas caros. Enviar todos os esquemas de ferramentas ao modelo aumenta a requisição, desacelera o planejamento e aumenta a seleção acidental de ferramentas. A Busca de Ferramentas muda o formato:

ferramentas diretas: o modelo vê todos os esquemas selecionados antes do primeiro token
modo de código da Busca de Ferramentas: o modelo vê uma ferramenta de código compacta e um contrato de API curto
modo de ferramentas da Busca de Ferramentas: o modelo vê três ferramentas estruturadas compactas de fallback
durante o turno: o modelo carrega apenas os esquemas de ferramentas de que realmente precisa

A exposição direta de ferramentas ainda é o padrão correto para catálogos pequenos. A Busca de Ferramentas é melhor quando uma execução pode ver muitas ferramentas, especialmente de servidores MCP ou ferramentas de aplicativos fornecidas pelo cliente.

API

openclaw.tools.search(query, options?) Pesquisa o catálogo efetivo da execução atual. Os resultados são compactos e seguros para recolocar no contexto do prompt.

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

openclaw.tools.describe(id) Carrega os metadados completos de um resultado de busca, incluindo o esquema de entrada exato.

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

openclaw.tools.call(id, args) Chama uma ferramenta selecionada por meio do OpenClaw.

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

O modo estruturado de fallback expõe as mesmas operações como ferramentas:

tool_search
tool_describe
tool_call

Limite de runtime

A ponte de código é executada em um subprocesso Node de curta duração. O subprocesso inicia com o modo de permissão do Node habilitado, um ambiente vazio, sem concessões de sistema de arquivos ou rede, e sem concessões de processo filho ou worker. O OpenClaw impõe um timeout de tempo real no processo pai e encerra o subprocesso no timeout, inclusive após continuações assíncronas. O runtime expõe apenas:

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

O comportamento normal do OpenClaw ainda se aplica às chamadas finais:

políticas de permissão e negação de ferramentas
restrições de ferramentas por agente e por sandbox
bloqueio exclusivo do proprietário
hooks de aprovação
hooks before_tool_call de Plugin
identidade da sessão, logs e telemetria

Configuração

Habilite a Busca de Ferramentas para execuções PI com a ponte de código padrão:

openclaw config set tools.toolSearch true

JSON equivalente:

{
  tools: {
    toolSearch: true,
  },
}

Use as ferramentas estruturadas de fallback em vez disso para execuções PI:

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

Ajuste o timeout do modo de código e os limites de resultados de busca:

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

Desabilite:

{
  tools: {
    toolSearch: false,
  },
}

Prompt e telemetria

A Busca de Ferramentas registra telemetria suficiente para compará-la com a exposição direta de ferramentas:

total de bytes serializados de ferramentas e prompt enviados ao harness
tamanho do catálogo e detalhamento por fonte
contagens de busca, descrição e chamada
chamadas finais de ferramentas executadas por meio do OpenClaw
ids e fontes das ferramentas selecionadas

Os logs de sessão devem permitir responder:

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

Validação E2E

O executor E2E do Gateway comprova ambos os caminhos com o harness PI:

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

Ele cria um Plugin falso temporário com um grande catálogo de ferramentas, inicia o provedor OpenAI simulado, inicia um Gateway uma vez no modo direto e uma vez com a Busca de Ferramentas habilitada, e então compara os payloads de requisição do provedor e os logs de sessão. A regressão comprova:

O modo direto consegue chamar a ferramenta do Plugin falso.
A Busca de Ferramentas consegue chamar a mesma ferramenta do Plugin falso.
O modo direto expõe os esquemas de ferramentas do Plugin falso diretamente ao provedor.
A Busca de Ferramentas expõe apenas a ponte compacta.
O payload de requisição da Busca de Ferramentas é menor para o grande catálogo falso.
Os logs de sessão mostram as contagens esperadas de chamadas de ferramentas e a telemetria de chamadas em ponte.

Comportamento de falha

A Busca de Ferramentas deve falhar fechada:

se uma ferramenta não estiver na política efetiva, a busca não deve retorná-la
se uma ferramenta selecionada ficar indisponível, tool_call deve falhar
se a política ou a aprovação bloquear a execução, o resultado da chamada deve 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 Busca de Ferramentas para essa implantação

Documentation Index

​Como um turno é executado

​Modos

​Por que isso existe

​API

​Limite de runtime

​Configuração

​Prompt e telemetria

​Validação E2E

​Comportamento de falha

​Relacionados