Ricerca strumenti

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

​

Funzionamento di un turno

1. Risolve la policy degli strumenti attiva per l’agente, il profilo, la sandbox e la sessione.
2. Elenca gli strumenti OpenClaw e dei plugin idonei.
3. Elenca gli strumenti MCP idonei tramite il runtime MCP della sessione.
4. Aggiunge gli strumenti idonei forniti dal client per l’esecuzione corrente.
5. Mantiene visibili al modello gli strumenti solo diretti e indicizza descrittori compatti per i restanti strumenti idonei per il catalogo.
6. Espone il bridge di codice OpenClaw, gli strumenti strutturati di ripiego o la superficie compatta della directory insieme agli strumenti solo diretti.

​

Modalità

• code: espone tool_search_code, il bridge JavaScript compatto predefinito, insieme agli strumenti solo diretti.
• tools: espone tool_search, tool_describe e tool_call come semplici strumenti strutturati per i provider che non devono ricevere codice, insieme agli strumenti solo diretti.
• directory: espone tool_search, tool_describe e tool_call, oltre a una directory limitata nel prompt contenente i nomi e le descrizioni degli strumenti disponibili per i provider che devono vedere i nomi degli strumenti senza tutti gli schemi completi. OpenClaw può anche esporre direttamente un piccolo insieme limitato di schemi di strumenti probabili o necessari per il turno corrente. Anche in questa modalità gli strumenti solo diretti rimangono visibili.

​

Perché esiste

• strumenti diretti: il modello vede ogni schema selezionato prima del primo token
• modalità codice di Tool Search: il modello vede un unico strumento di codice compatto, un breve contratto API e gli eventuali strumenti solo diretti
• modalità strumenti di Tool Search: il modello vede tre strumenti strutturati compatti di ripiego, oltre agli eventuali strumenti solo diretti
• modalità directory di Tool Search: il modello vede una directory limitata, oltre ai controlli di ricerca/descrizione/chiamata e a un piccolo insieme limitato di schemi probabili o necessari, nonché gli eventuali strumenti solo diretti
• durante il turno: il modello può caricare gli schemi rimanenti quando necessario

​

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

​

Confine del runtime

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

• policy di autorizzazione e negazione degli strumenti
• restrizioni degli strumenti per agente e per sandbox
• policy degli strumenti del canale/runtime
• hook di approvazione
• hook before_tool_call dei plugin
• identità della sessione, log e telemetria

​

Configurazione

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

• byte totali serializzati degli strumenti e del prompt inviati all’harness
• dimensioni del catalogo e suddivisione per sorgente
• numero di operazioni di ricerca, descrizione e chiamata
• chiamate finali agli strumenti eseguite tramite OpenClaw
• ID e sorgenti degli strumenti selezionati

• quanti schemi di strumenti il modello ha visto anticipatamente
• quante operazioni di ricerca e descrizione ha eseguito
• quale strumento finale è stato chiamato
• se il risultato proveniva da OpenClaw, MCP o da uno strumento del client

​

Convalida E2E

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

1. La modalità diretta può chiamare lo strumento del plugin fittizio.
2. Tool Search può chiamare lo stesso strumento del plugin fittizio.
3. La modalità diretta espone gli schemi degli strumenti del plugin fittizio direttamente al provider.
4. Tool Search espone solo il bridge compatto e gli eventuali strumenti solo diretti.
5. Il payload della richiesta di Tool Search è più piccolo per l’ampio catalogo fittizio.
6. I log della sessione mostrano il numero previsto di chiamate agli strumenti e la telemetria delle chiamate tramite bridge.

​

Comportamento in caso di errore

• se uno strumento non rientra nella policy effettiva, la ricerca non deve restituirlo
• se uno strumento selezionato diventa indisponibile, tool_call deve restituire un errore
• se la policy o l’approvazione blocca l’esecuzione, il risultato della chiamata deve segnalare tale blocco anziché aggirarlo
• se il bridge di codice non può creare un runtime isolato, utilizzare mode: "tools" oppure disabilitare Tool Search per tale distribuzione

​

Contenuti correlati

• Strumenti e plugin
• Sandbox multi-agente e strumenti
• Strumento Exec
• Configurazione degli agenti ACP
• Creazione di plugin