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, инструменты плагинов, инструменты MCP и инструменты, предоставленные клиентом. Модель не видит каждую полную схему заранее. Вместо этого она ищет по компактным дескрипторам, описывает один выбранный инструмент, когда ей нужна точная схема, и вызывает этот инструмент через OpenClaw.

Запуски обвязки Codex не получают эти экспериментальные элементы управления OpenClaw Tool Search. OpenClaw передает продуктовые возможности в Codex как динамические инструменты, а Codex владеет стабильным встроенным режимом кода, встроенным поиском инструментов, отложенными динамическими инструментами и вложенными вызовами инструментов.

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

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

Определить активную политику инструментов для агента, профиля, песочницы и сеанса.
Перечислить подходящие инструменты OpenClaw и плагинов.
Перечислить подходящие инструменты MCP через среду выполнения MCP сеанса.
Добавить подходящие клиентские инструменты, предоставленные для текущего запуска.
Проиндексировать компактные дескрипторы для поиска.
Предоставить модели мост кода 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. Если текущая среда выполнения не может запустить изолированный дочерний процесс Node для режима кода, стандартный режим code откатывается к tools перед Compaction каталога. В режиме directory инструменты, предоставленные клиентом, остаются напрямую видимыми для текущего запуска, а инструменты OpenClaw, инструменты плагинов и инструменты MCP могут быть сжаты за каталогом директории. Прямой вызов точного скрытого имени директории гидратируется из того же авторизованного каталога перед выполнением.

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

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

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

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

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

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

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

Режим директории предоставляет:

tool_search
tool_describe
tool_call

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

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

Мост кода работает в короткоживущем подпроцессе Node. Подпроцесс запускается с включенным режимом разрешений Node, пустым окружением, без разрешений на файловую систему или сеть, а также без разрешений на дочерние процессы или worker. 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,    },  },}

Отключите:

json5

{  tools: {    toolSearch: false,  },}

Подсказка и телеметрия

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

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

Журналы сеанса должны позволять ответить:

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

E2E-валидация

Сценарий Gateway в QA Lab подтверждает оба пути со средой выполнения OpenClaw:

bash

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

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

Регрессия подтверждает:

Прямой режим может вызвать инструмент фиктивного плагина.
Tool Search может вызвать тот же инструмент фиктивного плагина.
Прямой режим напрямую предоставляет схемы инструментов фиктивного плагина провайдеру.
Tool Search предоставляет только компактный мост.
Полезная нагрузка запроса Tool Search меньше для большого фиктивного каталога.
Журналы сеанса показывают ожидаемое количество вызовов инструментов и телеметрию мостовых вызовов.

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

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

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

См. также

Was this useful?

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

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

Режимы

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

API

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

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

Подсказка и телеметрия

E2E-валидация

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

См. также

On this page

Molty