Ricerca strumenti

Tool Search è una funzionalità sperimentale del runtime degli agenti OpenClaw. Offre agli agenti un unico modo compatto per individuare e chiamare ampi cataloghi di strumenti. È utile quando l'esecuzione dispone di molti strumenti, ma è probabile che il modello ne utilizzi solo alcuni.

Questa pagina documenta Tool Search di OpenClaw. Non riguarda la ricerca degli strumenti nativa di Codex né la superficie degli strumenti dinamici. La modalità codice nativa di Codex, la ricerca degli strumenti, gli strumenti dinamici differiti e le chiamate annidate agli strumenti sono superfici stabili dell'harness Codex e non dipendono da tools.toolSearch.

Quando è abilitata per le esecuzioni OpenClaw, per impostazione predefinita il modello riceve un unico strumento tool_search_code, oltre agli eventuali strumenti solo diretti i cui risultati strutturati non possono attraversare il bridge compatto. Lo strumento di codice esegue un breve corpo JavaScript in un sottoprocesso Node isolato con un bridge 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...",});

Il catalogo può includere strumenti OpenClaw idonei per il catalogo, strumenti dei plugin, strumenti MCP e strumenti forniti dal client. Il modello non vede anticipatamente tutti gli schemi catalogati. Cerca invece descrittori compatti, recupera la descrizione di uno strumento selezionato quando necessita dello schema esatto e chiama tale strumento tramite OpenClaw. Gli strumenti solo diretti rimangono visibili al modello e non vengono aggiunti al catalogo.

Le esecuzioni dell'harness Codex non ricevono questi controlli sperimentali di Tool Search di OpenClaw. OpenClaw passa le funzionalità del prodotto a Codex come strumenti dinamici e Codex gestisce la modalità codice nativa stabile, la ricerca degli strumenti nativa, gli strumenti dinamici differiti e le chiamate annidate agli strumenti.

Funzionamento di un turno

Durante la pianificazione, il runner incorporato di OpenClaw crea il catalogo effettivo per l'esecuzione:

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.

Durante l'esecuzione, ogni chiamata reale a uno strumento torna a OpenClaw. Il runtime Node isolato non contiene implementazioni dei plugin, oggetti client MCP o segreti. openclaw.tools.call(...) attraversa il bridge e torna nel Gateway, dove continuano ad applicarsi la normale policy, l'approvazione, gli hook, la registrazione e la gestione dei risultati.

Modalità

tools.toolSearch dispone di tre modalità rivolte al modello:

• 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.

Tutte le modalità utilizzano lo stesso catalogo filtrato dalla policy e il normale percorso di esecuzione di OpenClaw. Gli strumenti contrassegnati con catalogMode: "direct-only" rimangono fuori da tale catalogo e restano visibili al modello. Se il runtime corrente non può avviare il processo figlio isolato Node della modalità codice, la modalità predefinita code ripiega su tools prima della Compaction del catalogo. In modalità directory, gli strumenti forniti dal client rimangono direttamente visibili per l'esecuzione corrente, mentre gli strumenti OpenClaw, dei plugin e MCP possono essere compattati dietro il catalogo della directory. Una chiamata diretta a un nome esatto nascosto della directory viene caricata dallo stesso catalogo autorizzato prima dell'esecuzione.

Tutte le modalità sono sperimentali. Per i piccoli cataloghi di strumenti OpenClaw, preferire l'esposizione diretta degli strumenti; per le esecuzioni dell'harness Codex, preferire le superfici stabili native di Codex.

Non esiste una configurazione separata per la selezione delle sorgenti. Quando Tool Search è abilitata, il catalogo include gli strumenti OpenClaw, MCP e del client idonei per il catalogo dopo il normale filtro della policy; gli strumenti solo diretti vengono mantenuti separatamente.

Perché esiste

I cataloghi di grandi dimensioni sono utili ma costosi. Inviare ogni schema di strumento al modello rende la richiesta più grande, rallenta la pianificazione e aumenta la probabilità di selezionare accidentalmente uno strumento.

Tool Search modifica la struttura:

• 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

L'esposizione diretta degli strumenti rimane l'impostazione predefinita corretta per i cataloghi di piccole dimensioni. Tool Search è particolarmente indicata quando una singola esecuzione può accedere a molti strumenti, soprattutto da server MCP o da strumenti dell'app forniti dal client.

API

openclaw.tools.search(query, options?)

Cerca nel catalogo effettivo dell'esecuzione corrente. I risultati sono compatti e sicuri da reinserire nel contesto del prompt.

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

openclaw.tools.describe(id)

Carica i metadati completi per un risultato di ricerca, incluso lo schema di input esatto.

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

openclaw.tools.call(id, args)

Chiama uno strumento selezionato tramite OpenClaw.

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

La modalità strutturata di ripiego espone le stesse operazioni come strumenti:

• tool_search
• tool_describe
• tool_call

La modalità directory espone:

• tool_search
• tool_describe
• tool_call

Mantiene inoltre direttamente visibili gli strumenti forniti dal client e tutti gli strumenti solo diretti e può esporre direttamente un piccolo insieme limitato di schemi di strumenti del catalogo probabili o necessari per il turno corrente. Se la directory limitata omette alcune voci, utilizzare tool_search per trovarle. Se il modello richiede direttamente il nome esatto di uno strumento nascosto della directory, OpenClaw lo carica dal catalogo autorizzato prima della normale esecuzione. I nomi degli strumenti del client in modalità directory non devono entrare in conflitto con i nomi degli strumenti OpenClaw, dei plugin o MCP, poiché la distribuzione differita esatta utilizza tali nomi.

Confine del runtime

Il bridge di codice viene eseguito in un sottoprocesso Node di breve durata. Il sottoprocesso viene avviato con la modalità delle autorizzazioni di Node abilitata, un ambiente vuoto, nessuna autorizzazione per il filesystem o la rete e nessuna autorizzazione per processi figli o worker. OpenClaw applica un timeout basato sul tempo reale nel processo padre e termina il sottoprocesso allo scadere del timeout, anche dopo continuazioni asincrone.

Il runtime espone esclusivamente:

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

Il normale comportamento di OpenClaw continua ad applicarsi alle chiamate finali:

• 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

Abilitare Tool Search per le esecuzioni OpenClaw con il bridge di codice predefinito:

openclaw config set tools.toolSearch true

JSON equivalente:

{  tools: {    toolSearch: true,  },}

Per le esecuzioni OpenClaw, utilizzare invece gli strumenti strutturati di ripiego:

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

Per le esecuzioni OpenClaw, utilizzare invece la superficie compatta della directory:

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

Regolare il timeout della modalità codice e i limiti dei risultati di ricerca (i valori mostrati sono quelli predefiniti):

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

Il runtime limita codeTimeoutMs all'intervallo 1000-60000, maxSearchLimit all'intervallo 1-50 e searchDefaultLimit all'intervallo 1..maxSearchLimit.

Per disabilitarla:

{  tools: {    toolSearch: false,  },}

Prompt e telemetria

Tool Search registra telemetria sufficiente per confrontarla con l'esposizione diretta degli strumenti:

• 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

I log della sessione dovrebbero consentire di determinare:

• 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

Lo scenario del Gateway di QA Lab verifica entrambi i percorsi con il runtime OpenClaw:

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

Crea un plugin temporaneo fittizio con un ampio catalogo di strumenti, avvia il provider OpenAI simulato, avvia una volta un Gateway in modalità diretta e una volta con Tool Search abilitata, quindi confronta i payload delle richieste al provider e i log della sessione.

La regressione dimostra che:

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

Tool Search deve interrompersi in modo sicuro:

• 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