Tools

Werkzeugsuche

Tool Search ist eine experimentelle OpenClaw-PI-Agentenfunktion. Sie gibt PI-Agenten eine kompakte Möglichkeit, große Tool-Kataloge zu entdecken und aufzurufen. Sie ist nützlich, wenn der Lauf viele verfügbare Tools hat, das Modell aber voraussichtlich nur wenige davon benötigt.

Diese Seite dokumentiert OpenClaw PI Tool Search. Es ist nicht die Codex-native Tool-Suche oder Dynamic-Tools-Oberfläche. Codex-nativer Code-Modus, Tool-Suche, verzögerte dynamische Tools und verschachtelte Tool-Aufrufe sind stabile Codex-Harness-Oberflächen und hängen nicht von tools.toolSearch ab.

Wenn sie für PI aktiviert ist, erhält das Modell standardmäßig ein tool_search_code-Tool. Dieses Tool führt einen kurzen JavaScript-Body in einem isolierten Node-Unterprozess mit einer openclaw.tools-Bridge aus:

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

Der Katalog kann OpenClaw-Tools, Plugin-Tools, MCP-Tools und vom Client bereitgestellte Tools enthalten. Das Modell sieht nicht jedes vollständige Schema im Voraus. Stattdessen durchsucht es kompakte Deskriptoren, beschreibt ein ausgewähltes Tool, wenn es das exakte Schema benötigt, und ruft dieses Tool über OpenClaw auf.

Codex-Harness-Läufe erhalten diese experimentellen OpenClaw-Tool-Search-Steuerelemente nicht. OpenClaw übergibt Produktfunktionen als dynamische Tools an Codex, und Codex besitzt den stabilen nativen Code-Modus, die native Tool-Suche, verzögerte dynamische Tools und verschachtelte Tool-Aufrufe.

Wie ein Turn abläuft

Zur Planungszeit baut der eingebettete PI-Runner den effektiven Katalog für den Lauf auf:

Aktive Tool-Richtlinie für Agent, Profil, Sandbox und Sitzung auflösen.
Zulässige OpenClaw- und Plugin-Tools auflisten.
Zulässige MCP-Tools über die MCP-Laufzeit der Sitzung auflisten.
Zulässige Client-Tools hinzufügen, die für den aktuellen Lauf bereitgestellt wurden.
Kompakte Deskriptoren für die Suche indexieren.
Dem Modell entweder die PI-Code-Bridge oder die strukturierten Fallback-Tools bereitstellen.

Zur Ausführungszeit kehrt jeder echte Tool-Aufruf zu OpenClaw zurück. Die isolierte Node- Laufzeit enthält keine Plugin-Implementierungen, MCP-Client-Objekte oder Secrets. openclaw.tools.call(...) überquert die Bridge zurück in das Gateway, wo weiterhin die normale Richtlinie, Freigabe, Hook-Ausführung, Protokollierung und Ergebnisbehandlung gelten.

Modi

tools.toolSearch hat zwei modellseitige Modi:

code: stellt tool_search_code bereit, die standardmäßige kompakte JavaScript-Bridge.
tools: stellt tool_search, tool_describe und tool_call als einfache strukturierte Tools für Provider bereit, die keinen Code erhalten sollten.

Beide Modi verwenden denselben Katalog und Ausführungspfad. Der einzige Unterschied ist die Form, die das Modell sieht. Wenn die aktuelle Laufzeit den isolierten Node- Kindprozess für den Code-Modus nicht starten kann, fällt der standardmäßige code-Modus vor der Katalog-Compaction auf tools zurück.

Beide Modi sind experimentell. Bevorzugen Sie direkte Tool-Bereitstellung für kleine PI-Tool- Kataloge und die Codex-nativen stabilen Oberflächen für Codex-Harness-Läufe.

Es gibt keine separate Konfiguration zur Quellenauswahl. Wenn Tool Search aktiviert ist, enthält der Katalog zulässige OpenClaw-, MCP- und Client-Tools nach normaler Richtlinienfilterung.

Warum es das gibt

Große Kataloge sind nützlich, aber teuer. Jedes Tool-Schema an das Modell zu senden, macht die Anfrage größer, verlangsamt die Planung und erhöht die Wahrscheinlichkeit versehentlicher Tool-Auswahl.

Tool Search ändert die Form:

direkte Tools: Das Modell sieht jedes ausgewählte Schema vor dem ersten Token
Tool-Search-Code-Modus: Das Modell sieht ein kompaktes Code-Tool und einen kurzen API- Vertrag
Tool-Search-Tools-Modus: Das Modell sieht drei kompakte strukturierte Fallback- Tools
während des Turns: Das Modell lädt nur die Tool-Schemas, die es tatsächlich benötigt

Direkte Tool-Bereitstellung bleibt für kleine Kataloge der richtige Standard. Tool Search eignet sich am besten, wenn ein Lauf viele Tools sehen kann, insbesondere von MCP-Servern oder vom Client bereitgestellten App-Tools.

API

openclaw.tools.search(query, options?)

Durchsucht den effektiven Katalog für den aktuellen Lauf. Ergebnisse sind kompakt und sicher wieder in den Prompt-Kontext einzufügen.

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

openclaw.tools.describe(id)

Lädt vollständige Metadaten für ein Suchergebnis, einschließlich des exakten Eingabeschemas.

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

openclaw.tools.call(id, args)

Ruft ein ausgewähltes Tool über OpenClaw auf.

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

Der strukturierte Fallback-Modus stellt dieselben Operationen als Tools bereit:

tool_search
tool_describe
tool_call

Laufzeitgrenze

Die Code-Bridge läuft in einem kurzlebigen Node-Unterprozess. Der Unterprozess startet mit aktiviertem Node-Berechtigungsmodus, einer leeren Umgebung, ohne Dateisystem- oder Netzwerkfreigaben und ohne Kindprozess- oder Worker-Freigaben. OpenClaw erzwingt ein Wall-Clock-Timeout im Elternprozess und beendet den Unterprozess bei Timeout, auch nach asynchronen Fortsetzungen.

Die Laufzeit stellt nur Folgendes bereit:

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

Normales OpenClaw-Verhalten gilt weiterhin für finale Aufrufe:

Tool-Zulassungs- und Sperrrichtlinien
Tool-Einschränkungen pro Agent und pro Sandbox
Nur-Owner-Gating
Freigabe-Hooks
Plugin-before_tool_call-Hooks
Sitzungsidentität, Logs und Telemetrie

Konfiguration

Aktivieren Sie Tool Search für PI-Läufe mit der standardmäßigen Code-Bridge:

openclaw config set tools.toolSearch true

Äquivalentes JSON:

{
  tools: {
    toolSearch: true,
  },
}

Verwenden Sie stattdessen die strukturierten Fallback-Tools für PI-Läufe:

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

Passen Sie Timeout im Code-Modus und Suchergebnislimits an:

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

Deaktivieren:

{
  tools: {
    toolSearch: false,
  },
}

Prompt und Telemetrie

Tool Search zeichnet genug Telemetrie auf, um es mit direkter Tool-Bereitstellung zu vergleichen:

gesamte serialisierte Tool- und Prompt-Bytes, die an das Harness gesendet wurden
Kataloggröße und Quellenaufschlüsselung
Anzahl von Suchen, Beschreibungen und Aufrufen
finale Tool-Aufrufe, die über OpenClaw ausgeführt wurden
ausgewählte Tool-IDs und Quellen

Sitzungslogs sollten es ermöglichen, Folgendes zu beantworten:

wie viele Tool-Schemas das Modell im Voraus gesehen hat
wie viele Such- und Beschreibungsoperationen es durchgeführt hat
welches finale Tool aufgerufen wurde
ob das Ergebnis von OpenClaw, MCP oder einem Client-Tool kam

E2E-Validierung

Der Gateway-E2E-Runner weist beide Pfade mit dem PI-Harness nach:

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

Er erstellt ein temporäres Fake-Plugin mit einem großen Tool-Katalog, startet den Mock- OpenAI-Provider, startet ein Gateway einmal im direkten Modus und einmal mit aktivierter Tool Search und vergleicht dann Provider-Anfragepayloads und Sitzungslogs.

Die Regression weist nach:

Der direkte Modus kann das Fake-Plugin-Tool aufrufen.
Tool Search kann dasselbe Fake-Plugin-Tool aufrufen.
Der direkte Modus stellt die Schemas des Fake-Plugin-Tools direkt dem Provider bereit.
Tool Search stellt nur die kompakte Bridge bereit.
Der Tool-Search-Anfragepayload ist für den großen Fake-Katalog kleiner.
Sitzungslogs zeigen die erwarteten Tool-Aufrufzahlen und Telemetrie für überbrückte Aufrufe.

Fehlerverhalten

Tool Search sollte geschlossen fehlschlagen:

wenn ein Tool nicht in der effektiven Richtlinie enthalten ist, sollte die Suche es nicht zurückgeben
wenn ein ausgewähltes Tool nicht mehr verfügbar ist, sollte tool_call fehlschlagen
wenn Richtlinie oder Freigabe die Ausführung blockieren, sollte das Aufrufergebnis diese Blockade melden, statt sie zu umgehen
wenn die Code-Bridge keine isolierte Laufzeit erstellen kann, verwenden Sie mode: "tools" oder deaktivieren Sie Tool Search für diese Bereitstellung

Werkzeugsuche

Wie ein Turn abläuft

Modi

Warum es das gibt

API

Laufzeitgrenze

Konfiguration

Prompt und Telemetrie

E2E-Validierung

Fehlerverhalten

Verwandt

Ask OpenClaw

# Wie ein Turn abläuft

# Modi

# Warum es das gibt

# API

# Laufzeitgrenze

# Konfiguration

# Prompt und Telemetrie

# E2E-Validierung

# Fehlerverhalten

# Verwandt

Wie ein Turn abläuft

Modi

Warum es das gibt

API

Laufzeitgrenze

Konfiguration

Prompt und Telemetrie

E2E-Validierung

Fehlerverhalten

Verwandt