Búsqueda de herramientas

const hits = await openclaw.tools.search("crear una incidencia de GitHub");
const tool = await openclaw.tools.describe(hits[0].id);
return await openclaw.tools.call(tool.id, {
  title: "Fallo al iniciar",
  body: "Pasos para reproducirlo...",
});

​

Cómo se ejecuta un turno

1. Resolver la política de herramientas activa para el agente, el perfil, el entorno aislado y la sesión.
2. Enumerar las herramientas de OpenClaw y de plugins aptas.
3. Enumerar las herramientas de MCP aptas mediante el entorno de ejecución de MCP de la sesión.
4. Añadir las herramientas del cliente aptas proporcionadas para la ejecución actual.
5. Mantener visibles para el modelo las herramientas solo directas e indexar descriptores compactos para las demás herramientas aptas para el catálogo.
6. Exponer el puente de código de OpenClaw, las herramientas estructuradas de respaldo o la superficie compacta de directorio junto con esas herramientas solo directas.

​

Modos

• code: expone tool_search_code, el puente JavaScript compacto predeterminado, junto con las herramientas solo directas.
• tools: expone tool_search, tool_describe y tool_call como herramientas estructuradas simples para proveedores que no deben recibir código, junto con las herramientas solo directas.
• directory: expone tool_search, tool_describe y tool_call, además de un directorio acotado en el prompt con los nombres y las descripciones de las herramientas disponibles para proveedores que deben ver los nombres de las herramientas sin recibir todos los esquemas completos. OpenClaw también puede exponer directamente un pequeño conjunto acotado de esquemas de herramientas probables o necesarios para el turno actual. Las herramientas solo directas también permanecen visibles en este modo.

​

Motivo de su existencia

• herramientas directas: el modelo ve todos los esquemas seleccionados antes del primer token
• modo de código de Tool Search: el modelo ve una herramienta de código compacta, un contrato de API breve y cualquier herramienta solo directa
• modo de herramientas de Tool Search: el modelo ve tres herramientas estructuradas compactas de respaldo, además de cualquier herramienta solo directa
• modo de directorio de Tool Search: el modelo ve un directorio acotado, además de controles de búsqueda, descripción y llamada, un pequeño conjunto acotado de esquemas probables o necesarios y cualquier herramienta solo directa
• durante el turno: el modelo puede cargar los esquemas restantes según sea necesario

​

API

const hits = await openclaw.tools.search("evento del calendario", { limit: 5 });

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

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

• tool_search
• tool_describe
• tool_call

• tool_search
• tool_describe
• tool_call

​

Límite del entorno de ejecución

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

• políticas de autorización y denegación de herramientas
• restricciones de herramientas por agente y por entorno aislado
• política de herramientas del canal o entorno de ejecución
• hooks de aprobación
• hooks before_tool_call de plugins
• identidad de sesión, registros y telemetría

​

Configuración

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 y telemetría

• total de bytes serializados de herramientas y del prompt enviados al arnés
• tamaño del catálogo y desglose por fuente
• recuentos de búsquedas, descripciones y llamadas
• llamadas finales a herramientas ejecutadas mediante OpenClaw
• identificadores y fuentes de las herramientas seleccionadas

• cuántos esquemas de herramientas vio el modelo por adelantado
• cuántas operaciones de búsqueda y descripción realizó
• qué herramienta final se llamó
• si el resultado procedía de OpenClaw, MCP o una herramienta del cliente

​

Validación E2E

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

1. El modo directo puede llamar a la herramienta del Plugin ficticio.
2. Tool Search puede llamar a la misma herramienta del Plugin ficticio.
3. El modo directo expone los esquemas de las herramientas del Plugin ficticio directamente al proveedor.
4. Tool Search expone únicamente el puente compacto y cualquier herramienta exclusiva del modo directo.
5. La carga útil de la solicitud de Tool Search es menor para el amplio catálogo ficticio.
6. Los registros de sesión muestran los recuentos esperados de llamadas a herramientas y la telemetría de las llamadas mediante el puente.

​

Comportamiento ante fallos

• si una herramienta no está incluida en la política efectiva, la búsqueda no debe devolverla
• si una herramienta seleccionada deja de estar disponible, tool_call debe fallar
• si la política o la aprobación bloquean la ejecución, el resultado de la llamada debe informar de ese bloqueo en lugar de eludirlo
• si el puente de código no puede crear un entorno de ejecución aislado, use mode: "tools" o desactive Tool Search para ese despliegue

​

Contenido relacionado

• Herramientas y plugins
• Entorno aislado y herramientas multiagente
• Herramienta de ejecución
• Configuración de agentes ACP
• Creación de plugins