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("создать задачу в GitHub");const tool = await openclaw.tools.describe(hits[0].id);return await openclaw.tools.call(tool.id, {  title: "Сбой при запуске",  body: "Шаги для воспроизведения...",});

Каталог может включать подходящие для каталогизации инструменты 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("событие календаря", { 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: "Планирование",  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