Tools

Поиск инструментов

Tool Search — экспериментальная функция среды выполнения агента OpenClaw. Она дает агентам один компактный способ находить и вызывать большие каталоги инструментов. Это полезно, когда в запуске доступно много инструментов, но модели, вероятно, понадобится лишь несколько из них.

На этой странице описан OpenClaw Tool Search. Это не нативный для Codex интерфейс поиска инструментов или динамических инструментов. Нативный режим кода Codex, поиск инструментов, отложенные динамические инструменты и вложенные вызовы инструментов являются стабильными интерфейсами среды Codex и не зависят от 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 не получают эти экспериментальные элементы управления OpenClaw Tool Search. OpenClaw передает возможности продукта в Codex как динамические инструменты, а Codex владеет стабильным нативным режимом кода, нативным поиском инструментов, отложенными динамическими инструментами и вложенными вызовами инструментов.

Как выполняется ход

Во время планирования встроенный runner OpenClaw строит эффективный каталог для запуска:

Разрешает активную политику инструментов для агента, профиля, песочницы и сеанса.
Перечисляет подходящие инструменты OpenClaw и Plugin.
Перечисляет подходящие инструменты MCP через среду выполнения MCP сеанса.
Добавляет подходящие клиентские инструменты, предоставленные для текущего запуска.
Индексирует компактные дескрипторы для поиска.
Открывает модели мост кода OpenClaw, структурированные fallback-инструменты или компактный интерфейс каталога.

Во время выполнения каждый реальный вызов инструмента возвращается в OpenClaw. Изолированная среда выполнения Node не содержит реализаций Plugin, клиентских объектов 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, а также ограниченный prompt-каталог доступных имен и описаний инструментов для провайдеров, которые должны видеть имена инструментов без каждой полной схемы. OpenClaw также может напрямую открыть небольшой ограниченный набор вероятных или обязательных схем инструментов для текущего хода.

Все режимы используют один и тот же отфильтрованный политиками каталог и обычный путь выполнения OpenClaw. Если текущая среда выполнения не может запустить изолированный дочерний процесс Node для режима кода, режим code по умолчанию откатывается к tools до сжатия каталога. В режиме directory инструменты, предоставленные клиентом, остаются напрямую видимыми для текущего запуска, а инструменты OpenClaw, инструменты Plugin и инструменты MCP могут быть сжаты за каталогом directory. Прямой вызов точного скрытого имени directory гидратируется из того же авторизованного каталога перед выполнением.

Все режимы экспериментальные. Для небольших каталогов инструментов OpenClaw предпочитайте прямое раскрытие инструментов, а для запусков среды Codex предпочитайте нативные стабильные интерфейсы Codex.

Отдельной настройки выбора источника нет. Когда Tool Search включен, каталог включает подходящие инструменты OpenClaw, MCP и клиентские инструменты после обычной фильтрации политиками.

Зачем это нужно

Большие каталоги полезны, но дороги. Отправка каждой схемы инструмента модели увеличивает запрос, замедляет планирование и повышает риск случайного выбора инструмента.

Tool Search меняет форму:

прямые инструменты: модель видит каждую выбранную схему до первого токена
режим кода Tool Search: модель видит один компактный инструмент кода и короткий API contract
режим инструментов Tool Search: модель видит три компактных структурированных fallback- инструмента
режим directory Tool Search: модель видит ограниченный каталог плюс элементы управления search/describe/call и небольшой ограниченный набор вероятных или обязательных схем
во время хода: модель может загружать оставшиеся схемы по мере необходимости

Прямое раскрытие инструментов по-прежнему является правильным вариантом по умолчанию для небольших каталогов. Tool Search лучше всего подходит, когда один запуск может видеть много инструментов, особенно с 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",});

Структурированный fallback-режим открывает те же операции как инструменты:

tool_search
tool_describe
tool_call

Режим directory открывает:

tool_search
tool_describe
tool_call

Он также сохраняет клиентские инструменты напрямую видимыми и может напрямую открывать небольшой ограниченный набор вероятных или обязательных схем инструментов каталога для текущего хода. Если ограниченный каталог пропускает записи, используйте tool_search, чтобы найти их. Если модель напрямую запрашивает точное скрытое имя инструмента directory, OpenClaw гидратирует его из авторизованного каталога перед обычным выполнением. Имена клиентских инструментов в режиме directory не должны конфликтовать с именами инструментов OpenClaw, Plugin или MCP, поскольку точная отложенная диспетчеризация использует эти имена.

Граница среды выполнения

Мост кода работает в короткоживущем подпроцессе Node. Подпроцесс запускается с включенным permission mode Node, пустым окружением, без разрешений на файловую систему или сеть, а также без разрешений на дочерние процессы или workers. OpenClaw применяет таймаут wall-clock в родительском процессе и завершает подпроцесс при таймауте, включая после асинхронных продолжений.

Среда выполнения открывает только:

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

Обычное поведение OpenClaw по-прежнему применяется к финальным вызовам:

политики разрешения и запрета инструментов
ограничения инструментов для каждого агента и каждой песочницы
политика инструментов канала/среды выполнения
хуки подтверждения
хуки Plugin before_tool_call
идентичность сеанса, логи и телеметрия

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

Включите Tool Search для запусков OpenClaw с мостом кода по умолчанию:

bash

openclaw config set tools.toolSearch true

Эквивалентный JSON:

json5

{  tools: {    toolSearch: true,  },}

Вместо этого используйте структурированные fallback-инструменты для запусков OpenClaw:

json5

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

Вместо этого используйте компактный интерфейс directory для запусков OpenClaw:

json5

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

Настройте таймаут режима кода и лимиты результатов поиска:

json5

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

Отключите его:

json5

{  tools: {    toolSearch: false,  },}

Prompt и телеметрия

Tool Search записывает достаточно телеметрии, чтобы сравнивать его с прямым раскрытием инструментов:

общий размер сериализованных инструментов и prompt в байтах, отправленных в среду
размер каталога и разбивка по источникам
количество операций search, describe и call
финальные вызовы инструментов, выполненные через OpenClaw
выбранные идентификаторы инструментов и источники

Логи сеанса должны позволять ответить:

сколько схем инструментов модель увидела заранее
сколько операций search и describe она выполнила
какой финальный инструмент был вызван
пришел ли результат из OpenClaw, MCP или клиентского инструмента

E2E-валидация

E2E-runner Gateway доказывает оба пути со средой выполнения OpenClaw:

bash

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

Он создает временный fake Plugin с большим каталогом инструментов, запускает mock- провайдер OpenAI, запускает Gateway один раз в прямом режиме и один раз с включенным Tool Search, затем сравнивает payload-запросы провайдера и логи сеанса.

Регрессия доказывает:

Прямой режим может вызвать инструмент fake Plugin.
Tool Search может вызвать тот же инструмент fake Plugin.
Прямой режим напрямую открывает схемы инструментов fake Plugin провайдеру.
Tool Search открывает только компактный мост.
Payload запроса Tool Search меньше для большого fake-каталога.
Логи сеанса показывают ожидаемое количество вызовов инструментов и телеметрию bridged-вызовов.

Поведение при сбоях

Tool Search должен отказывать закрыто:

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

Связанное

Was this useful?

Поиск инструментов

Как выполняется ход

Режимы

Зачем это нужно

API

Граница среды выполнения

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

Prompt и телеметрия

E2E-валидация

Поведение при сбоях

Связанное

On this page

Molty