Wyszukiwanie narzędzi

Tool Search to eksperymentalna funkcja środowiska wykonawczego agentów OpenClaw. Zapewnia agentom jeden kompaktowy sposób wyszukiwania i wywoływania dużych katalogów narzędzi. Jest przydatna, gdy przebieg ma wiele dostępnych narzędzi, ale model prawdopodobnie będzie potrzebował tylko kilku z nich.

Ta strona opisuje Tool Search w OpenClaw. Nie jest to natywna dla Codex funkcja wyszukiwania narzędzi ani mechanizm narzędzi dynamicznych. Natywny dla Codex tryb kodu, wyszukiwanie narzędzi, odroczone narzędzia dynamiczne oraz zagnieżdżone wywołania narzędzi są stabilnymi mechanizmami uprzęży Codex i nie zależą od tools.toolSearch.

Po włączeniu dla przebiegów OpenClaw model domyślnie otrzymuje jedno narzędzie tool_search_code oraz wszystkie narzędzia dostępne wyłącznie bezpośrednio, których ustrukturyzowane wyniki nie mogą przejść przez kompaktowy most. Narzędzie kodowe uruchamia krótki fragment JavaScript w izolowanym podprocesie Node z mostem 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...",});

Katalog może obejmować narzędzia OpenClaw kwalifikujące się do katalogu, narzędzia pluginów, narzędzia MCP oraz narzędzia dostarczone przez klienta. Model nie widzi z góry wszystkich skatalogowanych schematów. Zamiast tego przeszukuje kompaktowe deskryptory, pobiera opis jednego wybranego narzędzia, gdy potrzebuje dokładnego schematu, i wywołuje je za pośrednictwem OpenClaw. Narzędzia dostępne wyłącznie bezpośrednio pozostają widoczne dla modelu i nie są dodawane do katalogu.

Przebiegi uprzęży Codex nie otrzymują tych eksperymentalnych mechanizmów sterowania Tool Search w OpenClaw. OpenClaw przekazuje możliwości produktu do Codex jako narzędzia dynamiczne, a Codex odpowiada za stabilny natywny tryb kodu, natywne wyszukiwanie narzędzi, odroczone narzędzia dynamiczne oraz zagnieżdżone wywołania narzędzi.

Jak przebiega tura

Na etapie planowania osadzony mechanizm wykonawczy OpenClaw tworzy efektywny katalog dla przebiegu:

1. Ustala aktywną politykę narzędzi dla agenta, profilu, piaskownicy i sesji.
2. Wyświetla listę kwalifikujących się narzędzi OpenClaw i pluginów.
3. Wyświetla listę kwalifikujących się narzędzi MCP za pośrednictwem środowiska wykonawczego MCP sesji.
4. Dodaje kwalifikujące się narzędzia klienta dostarczone dla bieżącego przebiegu.
5. Pozostawia narzędzia dostępne wyłącznie bezpośrednio jako widoczne dla modelu i indeksuje kompaktowe deskryptory pozostałych narzędzi kwalifikujących się do katalogu.
6. Udostępnia most kodowy OpenClaw, ustrukturyzowane narzędzia awaryjne lub kompaktowy interfejs katalogowy obok narzędzi dostępnych wyłącznie bezpośrednio.

W czasie wykonywania każde rzeczywiste wywołanie narzędzia wraca do OpenClaw. Izolowane środowisko Node nie przechowuje implementacji pluginów, obiektów klientów MCP ani danych poufnych. openclaw.tools.call(...) przechodzi przez most z powrotem do Gateway, gdzie nadal obowiązują standardowe mechanizmy polityki, zatwierdzania, punktów zaczepienia, rejestrowania i obsługi wyników.

Tryby

tools.toolSearch ma trzy tryby widoczne dla modelu:

• code: udostępnia tool_search_code, domyślny kompaktowy most JavaScript, obok narzędzi dostępnych wyłącznie bezpośrednio.
• tools: udostępnia tool_search, tool_describe i tool_call jako zwykłe ustrukturyzowane narzędzia awaryjne dla dostawców, którzy nie powinni otrzymywać kodu, obok narzędzi dostępnych wyłącznie bezpośrednio.
• directory: udostępnia tool_search, tool_describe i tool_call oraz ograniczony katalog w monicie, zawierający nazwy i opisy dostępnych narzędzi, dla dostawców, którzy powinni widzieć nazwy narzędzi bez wszystkich pełnych schematów. OpenClaw może również bezpośrednio udostępnić niewielki, ograniczony zestaw prawdopodobnych lub wymaganych schematów narzędzi dla bieżącej tury. Narzędzia dostępne wyłącznie bezpośrednio pozostają widoczne również w tym trybie.

Wszystkie tryby korzystają z tego samego katalogu filtrowanego zgodnie z polityką i standardowej ścieżki wykonywania OpenClaw. Narzędzia oznaczone catalogMode: "direct-only" pozostają poza tym katalogiem i są nadal widoczne dla modelu. Jeśli bieżące środowisko wykonawcze nie może uruchomić izolowanego procesu podrzędnego Node dla trybu kodu, domyślny tryb code przechodzi awaryjnie na tools przed Compaction katalogu. W trybie directory narzędzia dostarczone przez klienta pozostają bezpośrednio widoczne dla bieżącego przebiegu, natomiast narzędzia OpenClaw, pluginów i MCP mogą zostać skompaktowane za katalogiem. Bezpośrednie wywołanie dokładnej, ukrytej nazwy z katalogu powoduje załadowanie jej z tego samego autoryzowanego katalogu przed wykonaniem.

Wszystkie tryby są eksperymentalne. W przypadku małych katalogów narzędzi OpenClaw preferuj bezpośrednie udostępnianie narzędzi, a w przypadku przebiegów uprzęży Codex preferuj stabilne mechanizmy natywne dla Codex.

Nie istnieje osobna konfiguracja wyboru źródeł. Po włączeniu Tool Search katalog obejmuje kwalifikujące się narzędzia OpenClaw, MCP i klienta po standardowym filtrowaniu zgodnie z polityką; narzędzia dostępne wyłącznie bezpośrednio są przechowywane oddzielnie.

Dlaczego ta funkcja istnieje

Duże katalogi są przydatne, ale kosztowne. Wysyłanie do modelu każdego schematu narzędzia zwiększa rozmiar żądania, spowalnia planowanie i zwiększa ryzyko przypadkowego wyboru narzędzia.

Tool Search zmienia ten układ:

• narzędzia bezpośrednie: model widzi każdy wybrany schemat przed pierwszym tokenem
• tryb kodu Tool Search: model widzi jedno kompaktowe narzędzie kodowe, krótki kontrakt API oraz wszystkie narzędzia dostępne wyłącznie bezpośrednio
• tryb narzędzi Tool Search: model widzi trzy kompaktowe, ustrukturyzowane narzędzia awaryjne oraz wszystkie narzędzia dostępne wyłącznie bezpośrednio
• tryb katalogu Tool Search: model widzi ograniczony katalog wraz z mechanizmami wyszukiwania/opisywania/wywoływania i niewielkim, ograniczonym zestawem prawdopodobnych lub wymaganych schematów oraz wszystkimi narzędziami dostępnymi wyłącznie bezpośrednio
• podczas tury: model może w razie potrzeby ładować pozostałe schematy

Bezpośrednie udostępnianie narzędzi nadal jest właściwym ustawieniem domyślnym dla małych katalogów. Tool Search sprawdza się najlepiej, gdy jeden przebieg może korzystać z wielu narzędzi, zwłaszcza z serwerów MCP lub narzędzi aplikacji dostarczonych przez klienta.

API

openclaw.tools.search(query, options?)

Przeszukuje efektywny katalog dla bieżącego przebiegu. Wyniki są kompaktowe i można je bezpiecznie ponownie umieścić w kontekście monitu.

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

openclaw.tools.describe(id)

Ładuje pełne metadane jednego wyniku wyszukiwania, w tym dokładny schemat danych wejściowych.

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

openclaw.tools.call(id, args)

Wywołuje wybrane narzędzie za pośrednictwem OpenClaw.

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

Ustrukturyzowany tryb awaryjny udostępnia te same operacje jako narzędzia:

• tool_search
• tool_describe
• tool_call

Tryb katalogu udostępnia:

• tool_search
• tool_describe
• tool_call

Utrzymuje również bezpośrednią widoczność narzędzi dostarczonych przez klienta i wszystkich narzędzi dostępnych wyłącznie bezpośrednio oraz może bezpośrednio udostępnić dla bieżącej tury niewielki, ograniczony zestaw prawdopodobnych lub wymaganych schematów narzędzi katalogowych. Jeśli ograniczony katalog pomija wpisy, użyj tool_search, aby je znaleźć. Jeśli model bezpośrednio zażąda narzędzia o dokładnej, ukrytej nazwie z katalogu, OpenClaw ładuje je z autoryzowanego katalogu przed standardowym wykonaniem. Nazwy narzędzi klienta w trybie katalogu nie mogą kolidować z nazwami narzędzi OpenClaw, pluginów ani MCP, ponieważ dokładne odroczone przekazywanie używa tych nazw.

Granica środowiska wykonawczego

Most kodowy działa w krótkotrwałym podprocesie Node. Podproces uruchamia się z włączonym trybem uprawnień Node, pustym środowiskiem, bez dostępu do systemu plików ani sieci oraz bez uprawnień do procesów podrzędnych lub procesów roboczych. OpenClaw wymusza limit czasu zegarowego w procesie nadrzędnym i kończy podproces po jego przekroczeniu, również po kontynuacjach asynchronicznych.

Środowisko wykonawcze udostępnia wyłącznie:

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

Standardowe zachowanie OpenClaw nadal obowiązuje w przypadku końcowych wywołań:

• polityki zezwalania na narzędzia i ich blokowania
• ograniczenia narzędzi dotyczące poszczególnych agentów i piaskownic
• polityka narzędzi kanału/środowiska wykonawczego
• punkty zaczepienia zatwierdzania
• punkty zaczepienia pluginu before_tool_call
• tożsamość sesji, dzienniki i telemetria

Konfiguracja

Włącz Tool Search dla przebiegów OpenClaw z domyślnym mostem kodowym:

openclaw config set tools.toolSearch true

Równoważny JSON:

{  tools: {    toolSearch: true,  },}

Zamiast tego użyj ustrukturyzowanych narzędzi awaryjnych dla przebiegów OpenClaw:

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

Zamiast tego użyj kompaktowego interfejsu katalogowego dla przebiegów OpenClaw:

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

Dostosuj limit czasu trybu kodu i limity wyników wyszukiwania (pokazane wartości są domyślne):

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

Środowisko wykonawcze ogranicza codeTimeoutMs do zakresu 1000–60000, maxSearchLimit do 1–50, a searchDefaultLimit do 1..maxSearchLimit.

Wyłączanie:

{  tools: {    toolSearch: false,  },}

Monit i telemetria

Tool Search rejestruje wystarczającą ilość danych telemetrycznych, aby porównać je z bezpośrednim udostępnianiem narzędzi:

• łączna liczba bajtów zserializowanych narzędzi i monitu wysłanych do uprzęży
• rozmiar katalogu i podział według źródeł
• liczba operacji wyszukiwania, opisywania i wywoływania
• końcowe wywołania narzędzi wykonane za pośrednictwem OpenClaw
• identyfikatory i źródła wybranych narzędzi

Dzienniki sesji powinny umożliwiać ustalenie:

• ile schematów narzędzi model zobaczył z góry
• ile operacji wyszukiwania i opisywania wykonał
• które narzędzie końcowe zostało wywołane
• czy wynik pochodził z OpenClaw, MCP czy narzędzia klienta

Walidacja E2E

Scenariusz Gateway w QA Lab weryfikuje obie ścieżki za pomocą środowiska wykonawczego OpenClaw:

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

Tworzy tymczasowy fikcyjny plugin z dużym katalogiem narzędzi, uruchamia testowego dostawcę OpenAI, uruchamia Gateway raz w trybie bezpośrednim i raz z włączonym Tool Search, a następnie porównuje ładunki żądań dostawcy i dzienniki sesji.

Test regresji wykazuje, że:

1. Tryb bezpośredni może wywołać narzędzie fikcyjnego pluginu.
2. Tool Search może wywołać to samo narzędzie fikcyjnego pluginu.
3. Tryb bezpośredni udostępnia schematy narzędzi fikcyjnego pluginu bezpośrednio dostawcy.
4. Tool Search udostępnia tylko kompaktowy most oraz wszystkie narzędzia dostępne wyłącznie bezpośrednio.
5. Ładunek żądania Tool Search jest mniejszy w przypadku dużego fikcyjnego katalogu.
6. Dzienniki sesji pokazują oczekiwaną liczbę wywołań narzędzi i telemetrię wywołań przez most.

Zachowanie w przypadku błędów

Tool Search powinno działać w trybie bezpiecznego blokowania:

• jeśli narzędzie nie jest objęte efektywną polityką, wyszukiwanie nie powinno go zwrócić
• jeśli wybrane narzędzie stanie się niedostępne, tool_call powinno zakończyć się błędem
• jeśli polityka lub zatwierdzanie blokuje wykonanie, wynik wywołania powinien zgłosić tę blokadę zamiast ją omijać
• jeśli most kodowy nie może utworzyć izolowanego środowiska wykonawczego, użyj mode: "tools" lub wyłącz Tool Search dla tego wdrożenia

Powiązane

• Narzędzia i pluginy
• Piaskownica i narzędzia dla wielu agentów
• Narzędzie Exec
• Konfiguracja agentów ACP
• Tworzenie pluginów