Перейти до основного вмісту
Пошук інструментів — експериментальна функція середовища виконання агентів OpenClaw. Вона дає агентам один компактний спосіб знаходити й викликати великі каталоги інструментів. Це корисно, коли для запуску доступно багато інструментів, але модель, імовірно, потребуватиме лише кілька з них. Ця сторінка документує Пошук інструментів OpenClaw. Це не нативний для Codex пошук інструментів або поверхня динамічних інструментів. Нативний для Codex режим коду, пошук інструментів, відкладені динамічні інструменти та вкладені виклики інструментів є стабільними поверхнями Codex harness і не залежать від tools.toolSearch. Коли цю функцію ввімкнено для запусків OpenClaw, модель за замовчуванням отримує один інструмент 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 OpenClaw створює ефективний каталог для запуску:
  1. Розв’язує активну політику інструментів для агента, профілю, пісочниці та сесії.
  2. Перелічує придатні інструменти OpenClaw і Plugin.
  3. Перелічує придатні інструменти MCP через середовище виконання MCP сесії.
  4. Додає придатні клієнтські інструменти, надані для поточного запуску.
  5. Індексує компактні дескриптори для пошуку.
  6. Надає моделі міст коду OpenClaw, структуровані резервні інструменти або компактну поверхню каталогу.
Під час виконання кожен справжній виклик інструмента повертається до OpenClaw. Ізольоване середовище виконання Node не містить реалізацій Plugin, клієнтських об’єктів MCP або секретів. openclaw.tools.call(...) переходить через міст назад у Gateway, де й надалі застосовуються звичайні політики, затвердження, hook-и, журналювання та обробка результатів.

​
Режими

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

​
Навіщо це існує

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

​
API

openclaw.tools.search(query, options?) Шукає в ефективному каталозі для поточного запуску. Результати компактні й безпечні для повернення в контекст prompt. 
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
Режим директорії надає:
  • tool_search
  • tool_describe
  • tool_call
Він також залишає інструменти, надані клієнтом, безпосередньо видимими й може безпосередньо надати невеликий обмежений набір імовірних або потрібних схем інструментів каталогу для поточного ходу. Якщо обмежена директорія пропускає записи, використайте tool_search, щоб знайти їх. Якщо модель безпосередньо запитує точну приховану назву інструмента директорії, OpenClaw гідратує її з авторизованого каталогу перед звичайним виконанням. Назви клієнтських інструментів у режимі директорії не повинні збігатися з назвами інструментів OpenClaw, Plugin або MCP, оскільки точна відкладена диспетчеризація використовує ці назви.

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

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

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

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

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

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

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

Сценарій Gateway у QA Lab доводить обидва шляхи із середовищем виконання OpenClaw: 
pnpm openclaw qa suite --provider-mode mock-openai --scenario tool-search-gateway-e2e
Він створює тимчасовий фальшивий Plugin із великим каталогом інструментів, запускає мок-провайдера OpenAI, запускає Gateway один раз у прямому режимі й один раз із увімкненим Пошуком інструментів, а потім порівнює payload-и запитів провайдера та журнали сесії. Регресія доводить:
  1. Прямий режим може викликати інструмент фальшивого Plugin.
  2. Пошук інструментів може викликати той самий інструмент фальшивого Plugin.
  3. Прямий режим напряму надає провайдеру схеми інструментів фальшивого Plugin.
  4. Пошук інструментів надає лише компактний міст.
  5. Payload запиту Пошуку інструментів менший для великого фальшивого каталогу.
  6. Журнали сесії показують очікувану кількість викликів інструментів і телеметрію викликів через міст.

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

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

​
Пов’язане