---
read_when:
    - Вы хотите, чтобы агенты OpenClaw использовали большой каталог инструментов, не добавляя каждую схему инструмента в prompt
    - Вам нужно, чтобы инструменты OpenClaw, инструменты MCP и клиентские инструменты были доступны через одну компактную поверхность среды выполнения
    - Вы реализуете или отлаживаете обнаружение инструментов для запусков OpenClaw
summary: 'Поиск инструментов: компактное представление больших каталогов инструментов OpenClaw через поиск, описание и вызов'
title: Поиск инструментов
x-i18n:
    generated_at: "2026-06-28T23:56:09Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 23b46264bab307bbfdfeb1e358c566d498f3bcf77f187ba05d2ae319e115e1f4
    source_path: tools/tool-search.md
    workflow: 16
---

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

На этой странице описан OpenClaw Tool Search. Это не нативный для Codex интерфейс
поиска инструментов или динамических инструментов. Нативный режим кода Codex, поиск инструментов,
отложенные динамические инструменты и вложенные вызовы инструментов являются стабильными интерфейсами среды Codex и
не зависят от `tools.toolSearch`.

Когда функция включена для запусков OpenClaw, модель по умолчанию получает один инструмент `tool_search_code`.
Этот инструмент выполняет короткое тело JavaScript в изолированном подпроцессе Node
с мостом `openclaw.tools`:

```js
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 строит эффективный каталог для
запуска:

1. Разрешает активную политику инструментов для агента, профиля, песочницы и сеанса.
2. Перечисляет подходящие инструменты OpenClaw и Plugin.
3. Перечисляет подходящие инструменты MCP через среду выполнения MCP сеанса.
4. Добавляет подходящие клиентские инструменты, предоставленные для текущего запуска.
5. Индексирует компактные дескрипторы для поиска.
6. Открывает модели мост кода 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.

```js
const hits = await openclaw.tools.search("calendar event", { 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: "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-запросы провайдера и логи сеанса.

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

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

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

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

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

## Связанное

- [Инструменты и plugins](/ru/tools)
- [Мультиагентная песочница и инструменты](/ru/tools/multi-agent-sandbox-tools)
- [Инструмент exec](/ru/tools/exec)
- [Настройка агентов ACP](/ru/tools/acp-agents-setup)
- [Создание plugins](/ru/plugins/building-plugins)