OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

Пошук інструментів

Tool Search — це експериментальна функція середовища виконання агентів OpenClaw. Вона надає агентам один компактний спосіб знаходити й викликати великі каталоги інструментів. Це корисно, коли для виконання доступно багато інструментів, але моделі, імовірно, знадобляться лише деякі з них.

На цій сторінці описано Tool Search в OpenClaw. Це не нативний для Codex пошук інструментів і не поверхня динамічних інструментів. Нативний для Codex режим коду, пошук інструментів, відкладені динамічні інструменти та вкладені виклики інструментів є стабільними поверхнями середовища Codex і не залежать від tools.toolSearch.

Коли функцію ввімкнено для виконань OpenClaw, модель за замовчуванням отримує один інструмент tool_search_code, а також усі інструменти лише прямого доступу, структуровані результати яких неможливо передати через компактний міст. Інструмент коду виконує короткий фрагмент JavaScript в ізольованому дочірньому процесі Node із мостом openclaw.tools:

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

Каталог може містити придатні для каталогу інструменти OpenClaw, інструменти плагінів, інструменти MCP та інструменти, надані клієнтом. Модель не бачить наперед усі схеми з каталогу. Натомість вона шукає компактні описи, отримує опис одного вибраного інструмента, коли їй потрібна точна схема, і викликає цей інструмент через OpenClaw. Інструменти лише прямого доступу залишаються видимими для моделі й не додаються до каталогу.

Виконання в середовищі Codex не отримують ці експериментальні елементи керування Tool Search від OpenClaw. OpenClaw передає продуктові можливості до Codex як динамічні інструменти, а Codex керує стабільним нативним режимом коду, нативним пошуком інструментів, відкладеними динамічними інструментами та вкладеними викликами інструментів.

Як виконується хід

На етапі планування вбудоване середовище виконання OpenClaw формує ефективний каталог для виконання:

  1. Визначає активну політику інструментів для агента, профілю, пісочниці та сеансу.
  2. Перелічує придатні інструменти OpenClaw і плагінів.
  3. Перелічує придатні інструменти MCP через середовище виконання MCP сеансу.
  4. Додає придатні клієнтські інструменти, надані для поточного виконання.
  5. Залишає інструменти лише прямого доступу видимими для моделі та індексує компактні описи для решти придатних для каталогу інструментів.
  6. Надає міст коду OpenClaw, структуровані резервні інструменти або компактну поверхню каталогу разом із цими інструментами лише прямого доступу.

Під час виконання кожен фактичний виклик інструмента повертається до OpenClaw. Ізольоване середовище Node не містить реалізацій плагінів, об’єктів клієнта MCP або секретів. openclaw.tools.call(...) переходить через міст назад до Gateway, де й надалі застосовуються звичайні політики, схвалення, перехоплювачі, журналювання та обробка результатів.

Режими

tools.toolSearch має три режими, доступні моделі:

  • code: надає tool_search_code — стандартний компактний міст JavaScript — разом з інструментами лише прямого доступу.
  • tools: надає tool_search, tool_describe і tool_call як звичайні структуровані інструменти для постачальників, які не повинні отримувати код, разом з інструментами лише прямого доступу.
  • directory: надає tool_search, tool_describe і tool_call, а також обмежений каталог у запиті з назвами й описами доступних інструментів для постачальників, які повинні бачити назви інструментів, але не кожну повну схему. OpenClaw також може безпосередньо надавати невеликий обмежений набір імовірних або обов’язкових схем інструментів для поточного ходу. Інструменти лише прямого доступу також залишаються видимими в цьому режимі.

Усі режими використовують той самий відфільтрований політиками каталог і звичайний шлях виконання OpenClaw. Інструменти з позначкою catalogMode: "direct-only" залишаються поза цим каталогом і видимими для моделі. Якщо поточне середовище виконання не може запустити ізольований дочірній процес Node для режиму коду, стандартний режим code переходить до tools перед ущільненням каталогу. У режимі directory інструменти, надані клієнтом, залишаються безпосередньо видимими для поточного виконання, тоді як інструменти OpenClaw, плагінів і MCP можуть бути ущільнені за каталогом директорії. Прямий виклик за точною назвою прихованого інструмента з каталогу завантажується з того самого авторизованого каталогу перед виконанням.

Усі режими є експериментальними. Для невеликих каталогів інструментів OpenClaw віддавайте перевагу безпосередньому наданню інструментів, а для виконань у середовищі Codex — стабільним нативним поверхням Codex.

Окремого налаштування вибору джерел немає. Коли Tool Search увімкнено, каталог містить придатні для каталогу інструменти OpenClaw, MCP і клієнта після звичайної фільтрації політиками; інструменти лише прямого доступу зберігаються окремо.

Навіщо це потрібно

Великі каталоги корисні, але ресурсомісткі. Надсилання кожної схеми інструмента моделі збільшує запит, сповільнює планування та підвищує ймовірність випадкового вибору інструмента.

Tool Search змінює структуру:

  • прямі інструменти: модель бачить кожну вибрану схему до першого токена
  • режим коду Tool Search: модель бачить один компактний інструмент коду, короткий контракт API та всі інструменти лише прямого доступу
  • режим інструментів Tool Search: модель бачить три компактні структуровані резервні інструменти та всі інструменти лише прямого доступу
  • режим каталогу Tool Search: модель бачить обмежений каталог, а також елементи керування пошуком, описом і викликом та невеликий обмежений набір імовірних або обов’язкових схем разом з усіма інструментами лише прямого доступу
  • під час ходу: модель може завантажувати решту схем за потреби

Безпосереднє надання інструментів і надалі є правильним стандартним вибором для невеликих каталогів. Tool Search найкраще підходить, коли одне виконання може бачити багато інструментів, особливо із серверів MCP або інструментів застосунків, наданих клієнтом.

API

openclaw.tools.search(query, options?)

Шукає в ефективному каталозі поточного виконання. Результати компактні та безпечні для повернення в контекст запиту.

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

openclaw.tools.describe(id)

Завантажує повні метадані одного результату пошуку, включно з точною схемою введення.

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

openclaw.tools.call(id, args)

Викликає вибраний інструмент через OpenClaw.

js
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

Він також залишає безпосередньо видимими інструменти, надані клієнтом, і всі інструменти лише прямого доступу, а також може безпосередньо надавати невеликий обмежений набір імовірних або обов’язкових схем інструментів каталогу для поточного ходу. Якщо в обмеженому каталозі немає певних записів, використовуйте tool_search, щоб знайти їх. Якщо модель безпосередньо запитує точну назву прихованого інструмента каталогу, OpenClaw завантажує його з авторизованого каталогу перед звичайним виконанням. Назви клієнтських інструментів у режимі каталогу не повинні збігатися з назвами інструментів OpenClaw, плагінів або MCP, оскільки точна відкладена диспетчеризація використовує ці назви.

Межа середовища виконання

Міст коду працює в короткочасному дочірньому процесі Node. Дочірній процес запускається з увімкненим режимом дозволів Node, порожнім середовищем, без дозволів на файлову систему чи мережу, а також без дозволів на дочірні процеси або робочі потоки. OpenClaw забезпечує тайм-аут астрономічного часу в батьківському процесі та завершує дочірній процес після його спливу, зокрема після асинхронних продовжень.

Середовище виконання надає лише:

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

До остаточних викликів і надалі застосовується звичайна поведінка OpenClaw:

  • політики дозволу й заборони інструментів
  • обмеження інструментів для окремих агентів і пісочниць
  • політика інструментів каналу та середовища виконання
  • перехоплювачі схвалення
  • перехоплювачі плагінів before_tool_call
  • ідентичність сеансу, журнали й телеметрія

Конфігурація

Увімкніть Tool Search для виконань OpenClaw зі стандартним мостом коду:

bash
openclaw config set tools.toolSearch true

Еквівалентний JSON:

json5
{  tools: {    toolSearch: true,  },}

Натомість використовуйте структуровані резервні інструменти для виконань OpenClaw:

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

Натомість використовуйте компактну поверхню каталогу для виконань OpenClaw:

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

Налаштуйте тайм-аут режиму коду й обмеження результатів пошуку (показано стандартні значення):

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

Середовище виконання обмежує codeTimeoutMs діапазоном 1000–60000, maxSearchLimit — діапазоном 1–50, а searchDefaultLimit — діапазоном від 1 до maxSearchLimit.

Вимкнення:

json5
{  tools: {    toolSearch: false,  },}

Запит і телеметрія

Tool Search записує достатньо телеметрії, щоб порівнювати його з безпосереднім наданням інструментів:

  • загальний розмір серіалізованих інструментів і запиту, надісланих середовищу, у байтах
  • розмір каталогу та розподіл за джерелами
  • кількість операцій пошуку, опису й виклику
  • остаточні виклики інструментів, виконані через OpenClaw
  • ідентифікатори й джерела вибраних інструментів

Журнали сеансу мають давати змогу визначити:

  • скільки схем інструментів модель бачила наперед
  • скільки операцій пошуку й опису вона виконала
  • який остаточний інструмент було викликано
  • чи надійшов результат від OpenClaw, MCP або клієнтського інструмента

Наскрізна перевірка

Сценарій Gateway у QA Lab перевіряє обидва шляхи із середовищем виконання OpenClaw:

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

Він створює тимчасовий імітаційний плагін із великим каталогом інструментів, запускає імітаційного постачальника OpenAI, запускає Gateway один раз у прямому режимі й один раз з увімкненим Tool Search, а потім порівнює корисні навантаження запитів до постачальника та журнали сеансів.

Регресійна перевірка доводить:

  1. Прямий режим може викликати інструмент імітаційного плагіна.
  2. Tool Search може викликати той самий інструмент імітаційного плагіна.
  3. Прямий режим надає схеми інструментів імітаційного плагіна безпосередньо постачальнику.
  4. Tool Search надає лише компактний міст і всі інструменти лише прямого доступу.
  5. Корисне навантаження запиту Tool Search є меншим для великого імітаційного каталогу.
  6. Журнали сеансу показують очікувану кількість викликів інструментів і телеметрію викликів через міст.

Поведінка в разі помилки

Tool Search має безпечно блокувати доступ у разі помилки:

  • якщо інструмент не входить до ефективної політики, пошук не повинен його повертати
  • якщо вибраний інструмент стає недоступним, tool_call має завершитися помилкою
  • якщо політика або схвалення блокує виконання, результат виклику має повідомляти про це блокування, а не обходити його
  • якщо міст коду не може створити ізольоване середовище виконання, використовуйте mode: "tools" або вимкніть Tool Search для цього розгортання

Пов’язані матеріали

Was this useful?
On this page

On this page