Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Пошук інструментів — це експериментальна функція PI-агента OpenClaw. Вона дає PI-агентам один компактний спосіб виявляти й викликати великі каталоги інструментів. Це корисно, коли під час запуску доступно багато інструментів, але моделі, імовірно, знадобляться лише кілька з них. Ця сторінка документує пошук інструментів OpenClaw PI. Це не нативний для Codex пошук інструментів і не поверхня динамічних інструментів. Нативний режим коду Codex, пошук інструментів, відкладені динамічні інструменти та вкладені виклики інструментів є стабільними поверхнями Codex harness і не залежать від tools.toolSearch. Коли цю функцію ввімкнено для PI, модель за замовчуванням отримує один інструмент tool_search_code. Цей інструмент запускає коротке тіло JavaScript в ізольованому підпроцесі Node з мостом 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...",
});
Каталог може містити інструменти OpenClaw, інструменти Plugin, інструменти MCP та інструменти, надані клієнтом. Модель не бачить кожну повну схему наперед. Натомість вона шукає компактні дескриптори, описує один вибраний інструмент, коли їй потрібна точна схема, і викликає цей інструмент через OpenClaw. Запуски Codex harness не отримують ці експериментальні засоби керування пошуком інструментів OpenClaw. OpenClaw передає можливості продукту до Codex як динамічні інструменти, а Codex володіє стабільним нативним режимом коду, нативним пошуком інструментів, відкладеними динамічними інструментами та вкладеними викликами інструментів.

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

Під час планування вбудований runner PI створює ефективний каталог для запуску:
  1. Визначає активну політику інструментів для агента, профілю, пісочниці та сеансу.
  2. Перелічує придатні інструменти OpenClaw і Plugin.
  3. Перелічує придатні інструменти MCP через середовище виконання MCP сеансу.
  4. Додає придатні клієнтські інструменти, надані для поточного запуску.
  5. Індексує компактні дескриптори для пошуку.
  6. Надає моделі або міст коду PI, або структуровані резервні інструменти.
Під час виконання кожен реальний виклик інструмента повертається до OpenClaw. Ізольоване середовище виконання Node не зберігає реалізації Plugin, клієнтські об’єкти MCP або секрети. openclaw.tools.call(...) переходить через міст назад у Gateway, де й надалі застосовуються звичайна політика, схвалення, хуки, журналювання та обробка результатів.

​
Режими

tools.toolSearch має два режими, видимі для моделі:
  • code: надає tool_search_code, типовий компактний міст JavaScript.
  • tools: надає tool_search, tool_describe і tool_call як прості структуровані інструменти для провайдерів, які не мають отримувати код.
Обидва режими використовують той самий каталог і шлях виконання. Єдина різниця — це форма, яку бачить модель. Якщо поточне середовище виконання не може запустити ізольований дочірній процес Node режиму коду, типовий режим code повертається до tools перед Compaction каталогу. Обидва режими експериментальні. Для малих каталогів інструментів PI віддавайте перевагу прямому наданню інструментів, а для запусків Codex harness — нативним стабільним поверхням Codex. Окремої конфігурації вибору джерел немає. Коли пошук інструментів увімкнено, каталог містить придатні інструменти OpenClaw, MCP і клієнтські інструменти після звичайної фільтрації політик.

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

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

​
API

openclaw.tools.search(query, options?) Шукає в ефективному каталозі для поточного запуску. Результати компактні та безпечні для повернення в контекст промпта. 
const hits = await openclaw.tools.search("calendar event", { limit: 5 });
openclaw.tools.describe(id) Завантажує повні метадані для одного результату пошуку, зокрема точну вхідну схему. 
const calendarCreate = await openclaw.tools.describe("mcp:calendar:create_event");
openclaw.tools.call(id, args) Викликає вибраний інструмент через OpenClaw. 
await openclaw.tools.call(calendarCreate.id, {
  summary: "Planning",
  start: "2026-05-09T14:00:00Z",
});
Структурований резервний режим надає ті самі операції як інструменти:
  • tool_search
  • tool_describe
  • tool_call

​
Межа виконання

Кодовий міст працює в короткоживучому підпроцесі Node. Підпроцес запускається з увімкненим режимом дозволів Node, порожнім середовищем, без дозволів на файлову систему чи мережу, а також без дозволів на дочірні процеси або worker-и. OpenClaw застосовує таймаут за реальним часом у батьківському процесі й завершує підпроцес після таймауту, зокрема після асинхронних продовжень. Середовище виконання надає лише:
  • console.log, console.warn і console.error
  • openclaw.tools.search
  • openclaw.tools.describe
  • openclaw.tools.call
Звичайна поведінка OpenClaw усе ще застосовується до фінальних викликів:
  • політики дозволу й заборони інструментів
  • обмеження інструментів для окремого агента й окремої пісочниці
  • пропуск лише для власника
  • хуки схвалення
  • хуки plugin before_tool_call
  • ідентичність сеансу, журнали й телеметрія

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

Увімкніть Tool Search для запусків PI зі стандартним кодовим мостом: 
openclaw config set tools.toolSearch true
Еквівалентний JSON: 
{
  tools: {
    toolSearch: true,
  },
}
Натомість використовуйте структуровані резервні інструменти для запусків PI: 
{
  tools: {
    toolSearch: {
      mode: "tools",
    },
  },
}
Налаштуйте таймаут code-mode і ліміти результатів пошуку: 
{
  tools: {
    toolSearch: {
      mode: "code",
      codeTimeoutMs: 10000,
      searchDefaultLimit: 8,
      maxSearchLimit: 20,
    },
  },
}
Вимкніть це: 
{
  tools: {
    toolSearch: false,
  },
}

​
Prompt і телеметрія

Tool Search записує достатньо телеметрії, щоб порівняти його з прямим наданням інструментів:
  • загальна кількість серіалізованих байтів інструментів і prompt, надісланих до harness
  • розмір каталогу й розподіл за джерелами
  • кількість пошуків, описів і викликів
  • фінальні виклики інструментів, виконані через OpenClaw
  • вибрані ідентифікатори інструментів і джерела
Журнали сеансу мають давати змогу відповісти:
  • скільки схем інструментів модель побачила спочатку
  • скільки операцій пошуку й опису вона виконала
  • який фінальний інструмент було викликано
  • чи результат надійшов з OpenClaw, MCP або клієнтського інструмента

​
E2E-валідація

E2E runner Gateway підтверджує обидва шляхи з PI harness: 
node --import tsx scripts/tool-search-gateway-e2e.ts
Він створює тимчасовий фейковий plugin із великим каталогом інструментів, запускає mock провайдер OpenAI, запускає Gateway один раз у прямому режимі й один раз з увімкненим Tool Search, а потім порівнює payload-и запитів провайдера та журнали сеансу. Регресія підтверджує:
  1. Прямий режим може викликати інструмент фейкового plugin.
  2. Tool Search може викликати той самий інструмент фейкового plugin.
  3. Прямий режим надає схеми інструментів фейкового plugin безпосередньо провайдеру.
  4. Tool Search надає лише компактний міст.
  5. Payload запиту Tool Search менший для великого фейкового каталогу.
  6. Журнали сеансу показують очікувану кількість викликів інструментів і телеметрію викликів через міст.

​
Поведінка в разі збою

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

​
Пов’язане