> ## Documentation Index
> Fetch the complete documentation index at: https://ohmyclaw.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Инструменты

Настоящая сила OpenClaw — не в чате, а в **инструментах (tools)**. Именно они превращают языковую модель из простого собеседника в полноценного агента, способного выполнять команды, управлять браузером, отправлять сообщения и работать по расписанию.

В этой статье мы подробно разберём каждую категорию инструментов, доступных в OpenClaw: built-in tools, skills, cron-задачи, автоматизацию и расширения.

***

## Архитектура: как инструменты работают внутри

OpenClaw представляет инструменты агенту по двум каналам одновременно. Первый — текстовое описание в системном промпте, чтобы модель понимала, какие инструменты существуют и зачем они нужны. Второй — структурированные JSON-схемы, которые передаются как function definitions при вызове модели. Если инструмент не представлен ни в системном промпте, ни в схеме, модель не сможет его вызвать.

Важно понимать разницу между инструментами и навыками (skills). **Инструменты — это органы**: они определяют, *может ли* OpenClaw что-то сделать (читать файлы, выполнять команды, открывать браузер). **Навыки — это инструкции**: они объясняют агенту, *как именно* выполнять задачу. Навык без соответствующего инструмента бесполезен — он может описывать шаги, но агент не сможет их исполнить, если инструмент заблокирован политикой.

***

## Built-in инструменты

Встроенные инструменты — ядро OpenClaw. Они доступны «из коробки» и покрывают все базовые операции.

### Файловая система: read, write, edit, apply\_patch

Эти четыре инструмента управляют доступом к файлам. `read` — только чтение, `write` и `edit` — изменение содержимого, `apply_patch` — применение структурированных патчей к одному или нескольким файлам (мультихунковое редактирование). Инструмент `apply_patch` является экспериментальным и включается через `tools.exec.applyPatch.enabled`. По умолчанию он ограничен рабочей директорией (`workspaceOnly: true`), чтобы агент не мог модифицировать файлы за пределами воркспейса.

В политиках инструментов все четыре объединены в группу `group:fs`.

### exec — выполнение команд

`exec` — самый мощный (и самый опасный) built-in инструмент. Он позволяет агенту выполнять произвольные shell-команды в рабочей директории.

Ключевые параметры:

* **command** — команда для выполнения (обязательный).
* **yieldMs** — после указанного таймаута (по умолчанию 10 секунд) процесс автоматически уходит в фон и возвращает `status: "running"` с `sessionId`.
* **background** — сразу запустить в фоне.
* **timeout** — максимальное время выполнения в секундах (по умолчанию 1800, то есть 30 минут).
* **elevated** — выполнить на хосте, если включён elevated-режим. Это актуально только когда агент работает в песочнице.
* **host** — выбор среды: `sandbox`, `gateway` или `node`. Параметр `host=node` позволяет выполнять команды на macOS-компаньоне или headless-ноде.
* **security** — уровень безопасности: `deny`, `allowlist` или `full`.
* **pty** — если нужен настоящий TTY (например, для интерактивных CLI-утилит), установите `pty: true`.

Когда процесс уходит в фон, для управления им используется инструмент **process** с действиями `list`, `poll`, `log`, `write`, `kill`, `clear`, `remove`. Процессы привязаны к конкретному агенту — один агент не видит фоновых задач другого.

### web\_search и web\_fetch

Два «лёгких» инструмента для работы с интернетом.

**web\_search** отправляет поисковые запросы через Brave Search API (по умолчанию), Perplexity Sonar, Gemini, Grok или Kimi. Результаты кешируются на 15 минут. Для настройки достаточно выполнить `openclaw configure --section web` и ввести API-ключ провайдера.

**web\_fetch** выполняет HTTP GET и извлекает читаемый контент (HTML → markdown или текст). Он не выполняет JavaScript, поэтому для JS-тяжёлых сайтов лучше использовать инструмент browser. Максимальное количество символов ограничено параметром `tools.web.fetch.maxCharsCap` (по умолчанию 50 000). Для сайтов с анти-бот защитой можно подключить Firecrawl как fallback.

Оба инструмента входят в группу `group:web`.

### browser — управление браузером

OpenClaw может управлять собственным экземпляром Chrome/Chromium через CDP (Chrome DevTools Protocol). Это полноценная браузерная автоматизация: открытие вкладок, навигация, скриншоты, клики, ввод текста, работа с диалогами и загрузка файлов.

Рекомендуемый агентский workflow выглядит так:

1. Проверить статус или запустить браузер (`status` / `start`).
2. Получить снимок состояния страницы (`snapshot` в режиме `ai` или `aria`).
3. Выполнить действие (`act` — click, type, press, hover и т.д.), используя `ref` из снимка.
4. При необходимости сделать `screenshot` для визуальной верификации.

Браузер поддерживает мультипрофильность: каждый профиль — это отдельный экземпляр с автоматически выделенным портом (диапазон 18800–18899, до \~100 профилей). Управление профилями: `profiles`, `create-profile`, `delete-profile`, `reset-profile`.

### message — отправка сообщений

Инструмент для кроссплатформенного взаимодействия с пользователями через Discord, Slack, Telegram, WhatsApp, Signal, iMessage, Google Chat и MS Teams. Помимо простой отправки текста и медиа, поддерживает:

* Реакции, редактирование и удаление сообщений.
* Закреплённые сообщения (pin/unpin).
* Треды (создание, просмотр, ответ).
* Поиск сообщений.
* Опросы (polls) в WhatsApp, Discord и MS Teams.
* Управление ролями и правами участников.
* Создание событий (event-create).
* Модерацию (timeout, kick, ban).

Когда инструмент привязан к активной сессии, отправка ограничена целью этой сессии — это защита от утечки контекста между разными чатами.

### image — анализ изображений

Анализирует изображение с помощью настроенной модели для работы с визуальным контентом. Принимает путь к файлу или URL, опциональный промпт и параметр выбора модели. Работает независимо от основной чат-модели — использует отдельно настроенную image model.

### sessions — управление сессиями

Группа инструментов для мультисессионной работы:

* **sessions\_list** — просмотр всех сессий.
* **sessions\_history** — получение истории конкретной сессии.
* **sessions\_send** — отправка сообщения в другую сессию (с поддержкой ping-pong режима).
* **sessions\_spawn** — запуск субагентов (одноразовых или привязанных к треду).
* **session\_status** — проверка и управление текущей сессией.

Видимость сессий контролируется параметром `tools.sessions.visibility`. По умолчанию установлен режим `tree` — агент видит только свою сессию и порождённые субагентские. Для мультипользовательских сценариев рекомендуется `self`, чтобы исключить пересечение.

### gateway — управление шлюзом

Позволяет агенту перезапускать Gateway, применять обновления конфигурации (`config.apply`, `config.patch`), получать текущую конфигурацию (`config.get`) и запускать обновления (`update.run`). Все действия, меняющие состояние шлюза, используют задержку (`delayMs`, по умолчанию 2 секунды), чтобы не прервать текущий ответ.

### canvas и nodes

**canvas** управляет визуальным рабочим пространством (Canvas) на подключённых нодах. Поддерживает рендеринг (`present`), выполнение JS (`eval`), снимки экрана (`snapshot`) и экспериментальный A2UI (Agent-to-UI) для генерации интерфейсов.

**nodes** — инструмент для работы с подключёнными устройствами (macOS, iOS, Android): уведомления (`notify`), выполнение команд (`run`), камера (`camera_snap`, `camera_clip`), запись экрана (`screen_record`), геолокация и статус устройства.

### loop-detection — защита от зацикливания

OpenClaw отслеживает историю вызовов инструментов и блокирует повторяющиеся бессмысленные циклы. Три детектора:

* **genericRepeat** — повторный вызов одного инструмента с теми же параметрами.
* **knownPollNoProgress** — повторяющийся опрос без изменения результатов.
* **pingPong** — чередование двух вызовов A/B/A/B без прогресса.

Включается через `tools.loopDetection.enabled: true`. Настраиваемые пороги: `warningThreshold` (предупреждение), `criticalThreshold` (критическое предупреждение), `globalCircuitBreakerThreshold` (полная остановка).

***

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

Управление доступом к инструментам — одна из ключевых функций безопасности OpenClaw.

### allow / deny

Глобальные списки разрешений настраиваются в `openclaw.json`:

```text theme={null}
{
  "tools": {
    "allow": ["group:fs", "browser"],
    "deny": ["exec"]
  }
}
```

Правило: **deny всегда побеждает allow**. Поддерживаются wildcards (`*`) и сопоставление без учёта регистра.

### Группы инструментов

Для удобства инструменты объединены в именованные группы:

| Группа             | Инструменты                                                                         |
| :----------------- | :---------------------------------------------------------------------------------- |
| `group:runtime`    | exec, bash, process                                                                 |
| `group:fs`         | read, write, edit, apply\_patch                                                     |
| `group:sessions`   | sessions\_list, sessions\_history, sessions\_send, sessions\_spawn, session\_status |
| `group:memory`     | memory\_search, memory\_get                                                         |
| `group:web`        | web\_search, web\_fetch                                                             |
| `group:ui`         | browser, canvas                                                                     |
| `group:automation` | cron, gateway                                                                       |
| `group:messaging`  | message                                                                             |
| `group:nodes`      | nodes                                                                               |
| `group:openclaw`   | все встроенные инструменты (без плагинов)                                           |

### Профили

Профили — это предустановленные наборы инструментов:

* **minimal** — только `session_status`.
* **coding** — файловая система, рантайм, сессии, память, image.
* **messaging** — мессенджи, базовые сессионные инструменты.
* **full** — без ограничений (по умолчанию).

Профили можно назначать глобально и переопределять для конкретных агентов:

```text theme={null}
{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}
```

### Политики по провайдерам

Через `tools.byProvider` можно ограничить набор инструментов для конкретного провайдера моделей. Это полезно, когда определённые модели плохо справляются с большим набором tool-схем:

```text theme={null}
{
  "tools": {
    "profile": "coding",
    "byProvider": {
      "google-antigravity": { "profile": "minimal" }
    }
  }
}
```

***

## Skills (навыки)

Навыки — это модульные инструкции, которые учат агента выполнять конкретные задачи. Каждый навык представляет собой директорию с файлом `SKILL.md`, содержащим YAML-метаданные (frontmatter) и markdown-инструкции.

### Структура SKILL.md

```text theme={null}
---
name: my-skill
description: Управление задачами через Todoist API.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - TODOIST_API_KEY
      bins:
        - curl
    primaryEnv: TODOIST_API_KEY
---

# Инструкции для агента

Ниже — шаги, которые агент должен выполнять при использовании этого навыка.
...
```

**description** в frontmatter — не маркетинговый текст, а триггерная фраза. OpenClaw использует имя и описание навыка, чтобы решить, релевантен ли он текущему запросу. Только после этого полные инструкции загружаются в контекст. Поэтому описание должно содержать те же слова, которые пользователь реально использует в запросе.

### Загрузка и приоритеты

Навыки загружаются из трёх мест (в порядке убывания приоритета):

1. **Workspace skills** — `<workspace>/skills` (наивысший приоритет).
2. **Managed/local skills** — `~/.openclaw/skills`.
3. **Bundled skills** — поставляются с установкой OpenClaw.

Если имена конфликтуют, побеждает навык с более высоким приоритетом. Дополнительные директории можно указать через `skills.load.extraDirs`. В мультиагентных сетапах каждый агент имеет собственный воркспейс, поэтому per-agent навыки живут в `<workspace>/skills` конкретного агента, а общие — в `~/.openclaw/skills`.

### Фильтрация при загрузке

OpenClaw фильтрует навыки при старте на основе окружения, конфигурации и наличия бинарных зависимостей. Если навык требует переменную окружения `TODOIST_API_KEY`, а она не установлена, навык не будет загружен. Аналогично с бинарниками: если в `requires.bins` указан `curl`, а он не найден в PATH, навык отключается.

Проверить статус навыков можно через CLI:

```text theme={null}
openclaw skills list            # все навыки
openclaw skills list --eligible # только доступные
openclaw skills info my-skill   # детали конкретного навыка
```

### Hot-reload

По умолчанию OpenClaw следит за директориями навыков и обновляет снимок при изменении файлов `SKILL.md`. Это работает через file watcher с дебаунсом в 250 мс. Перезапуск Gateway не требуется.

### Влияние на контекст

Каждый загруженный навык добавляет текст в системный промпт. Даже если навык не используется в текущем запросе, модель видит его в списке. Формула расхода символов:

```text theme={null}
total = 195 + Σ (97 + len(name) + len(description) + len(location))
```

Грубая оценка: \~24 токена на навык плюс длина ваших текстовых полей. При большом количестве мелких навыков рекомендуется объединять те, что используют одни и те же бинарники и относятся к одному домену.

### ClawHub — реестр навыков

ClawHub — это публичный реестр навыков для OpenClaw. На данный момент он содержит более 5 400 навыков. Установка через CLI:

```text theme={null}
clawhub install <skill-name>
```

Навыки устанавливаются в `./skills` текущей директории (или воркспейса). Перед установкой сторонних навыков крайне рекомендуется проверять исходный код: навыки могут содержать prompt injections, вредоносные скрипты или небезопасные паттерны работы с данными. ClawHub предоставляет VirusTotal-сканирование для каждого навыка.

### Безопасность

Навыки **не дают** полномочий. Если ваша политика инструментов блокирует `exec`, навык, опирающийся на shell-команды, загрузится, но не сможет ничего выполнить. Навыки — это операционные инструкции, а не исполняемые плагины.

***

## Cron Jobs (задачи по расписанию)

Cron — встроенный планировщик Gateway. Он сохраняет задачи на диск, будит агента в нужное время и может доставлять результаты в чат. Задачи хранятся в `~/.openclaw/cron/jobs.json` и переживают перезапуски.

### Три типа расписаний

**at** — одноразовое выполнение. Идеально для напоминаний и отложенных действий. По умолчанию задача удаляется после успешного выполнения (можно отключить через `deleteAfterRun: false`).

```text theme={null}
openclaw cron add \
  --name "Перезвонить клиенту" \
  --at "2h" \
  --session main \
  --system-event "Перезвони клиенту по заявке #1234" \
  --wake now
```

**every** — интервальное повторение. Подходит для задач, требующих регулярного внимания без привязки к точному времени.

**cron** — классическое cron-выражение (5 полей, или 6 с секундами) с опциональной IANA-таймзоной. Для снижения нагрузки при top-of-hour выражениях (вроде `0 * * * *`) OpenClaw автоматически применяет стохастическое смещение до 5 минут. Точные выражения (например, `0 7 * * *`) выполняются точно. Поведением можно управлять через `schedule.staggerMs`.

```text theme={null}
openclaw cron add \
  --name "Утренний брифинг" \
  --cron "0 7 * * *" \
  --tz "Europe/Moscow" \
  --session isolated \
  --message "Подготовь утренний брифинг: погода, календарь, важные письма, новости." \
  --model opus \
  --announce \
  --channel telegram \
  --to "+79001234567"
```

### Main vs Isolated сессии

**Main session** — задача добавляет системное событие в очередь и (опционально) пробуждает heartbeat-раннер. Агент выполняет задачу в контексте основной сессии, со всей историей и памятью.

Параметр `wakeMode` определяет момент выполнения:

* `now` — немедленный heartbeat-запуск.
* `next-heartbeat` — ожидание следующего планового heartbeat.

**Isolated session** — задача выполняется в выделенной сессии `cron:<jobId>`. Каждый запуск — это новая сессия без предыдущего контекста. Результат анонсируется в основной сессии. Этот режим безопаснее: исключает контаминацию контекста и позволяет использовать отдельную модель для каждой задачи.

Рекомендации:

* Рутинные автоматизации → isolated (чистый контекст, другая модель, нет «загрязнения» основной сессии).
* Задачи, которым нужен контекст текущих разговоров → main.

### Доставка результатов

Для isolated-задач параметр `delivery.mode` определяет, что происходит с результатом:

* **announce** (по умолчанию) — краткая сводка отправляется в целевой канал и в основную сессию.
* **webhook** — POST-запрос с результатом на указанный URL.
* **none** — результат остаётся внутренним.

### Обработка ошибок

OpenClaw применяет экспоненциальный backoff для рекуррентных задач при последовательных ошибках: 30 секунд → 1 минута → 5 минут → 15 минут → 60 минут. Backoff сбрасывается после первого успешного выполнения. Одноразовые задачи (`at`) не ретраются — они отключаются после терминального статуса (`ok`, `error`, `skipped`).

### CLI для управления

```text theme={null}
openclaw cron list              # список задач
openclaw cron list --verbose    # детальный список с расписанием
openclaw cron add ...           # создать задачу
openclaw cron edit <jobId> ...  # редактировать
openclaw cron remove <jobId>    # удалить
openclaw cron run <jobId>       # ручной запуск (debug)
openclaw cron runs --id <jobId> # история запусков
```

***

## Heartbeat — фоновое «пульсирование»

Heartbeat и cron решают разные задачи, хотя оба работают по расписанию. Heartbeat — это регулярный «пульс» (по умолчанию каждые 30 минут), во время которого агент просматривает контрольный список и решает, нужно ли что-то предпринять.

Ключевые отличия от cron:

* Heartbeat работает в основной сессии с полным контекстом.
* Один heartbeat может заменить 5 отдельных cron-задач (проверка почты, календаря, погоды, уведомлений, статуса проектов).
* Агент принимает решения на основе контекста: что срочно, а что может подождать.
* Сохраняется континуальность разговора — агент помнит недавние обсуждения.

Типичный `HEARTBEAT.md`:

```text theme={null}
# Контрольный список heartbeat
1. Проверить входящие на предмет срочных писем
2. Посмотреть ближайшие события в календаре (2 часа)
3. Проверить статус незавершённых задач
4. Если тихо больше 8 часов — лёгкий check-in
```

Правило выбора: используйте **heartbeat** для лёгкого мониторинга и контекстно-зависимых проверок, а **cron** — когда нужно точное время выполнения.

***

## Webhooks и Hooks

### Webhooks — внешние триггеры

Webhooks позволяют внешним сервисам запускать агента. Например, при пуше в GitHub или при заполнении формы на сайте:

```text theme={null}
{
  "webhooks": {
    "github-push": {
      "prompt": "Новый коммит в {{repo}} от {{author}}: '{{message}}'. Сделай ревью и отправь сводку в #dev-updates.",
      "channel": "slack",
      "secret": "${WEBHOOK_SECRET_GITHUB}"
    }
  }
}
```

Промпты поддерживают шаблонные переменные `{{variable}}`, которые заполняются из тела входящего запроса.

### Hooks — внутренние события

Hooks реагируют на внутренние события OpenClaw. Ключевой хук — **boot-md**: он срабатывает при старте новой сессии и загружает указанные файлы в контекст:

```text theme={null}
{
  "hooks": {
    "boot-md": {
      "enabled": true,
      "files": ["SOUL.md", "IDENTITY.md", "USER.md", "MEMORY.md", "HEARTBEAT.md"]
    }
  }
}
```

Это гарантирует, что агент всегда начинает работу с правильным контекстом.

***

## Плагины

Плагины расширяют набор инструментов (и CLI-команд) за пределы встроенного набора. Они регистрируют дополнительные tools, а некоторые поставляются с собственными навыками.

Встроенные опциональные плагины:

* **Lobster** — типизированный workflow-рантайм с поддержкой resumable approvals. Подходит для мультишаговых пайплайнов, требующих детерминированного выполнения и человеческих чекпоинтов. Требует Lobster CLI на хосте.
* **LLM Task** — JSON-only шаг для получения структурированного вывода от LLM с опциональной валидацией по схеме.
* **Diffs** — просмотр диффов и рендер PNG/PDF для визуального сравнения до/после.
* **Voice Call** — голосовые звонки через ElevenLabs и системный TTS.

***

## Мультиагентная координация

OpenClaw поддерживает работу нескольких агентов одновременно, каждый со своим воркспейсом, набором инструментов и навыков.

* **agent\_send** — отправка сообщений между агентами.
* **sessions\_spawn** — порождение субагентов с параметрами: рантайм (`subagent` или `acp`), модель, уровень мышления, рабочая директория, таймаут.
* **agents\_list** — список агентов, доступных для текущей сессии.

Инструменты каждого агента можно ограничить независимо через `agents.list[].tools.profile`, `tools.allow` и `tools.deny`.

***

## Итого: что когда использовать

| Задача                               | Механизм                   |
| :----------------------------------- | :------------------------- |
| Выполнить shell-команду              | `exec`                     |
| Найти информацию в интернете         | `web_search` + `web_fetch` |
| Автоматизировать веб-интерфейс       | `browser`                  |
| Отправить сообщение в мессенджер     | `message`                  |
| Научить агента новому workflow       | Создать skill (`SKILL.md`) |
| Выполнять задачу каждый день в 9:00  | `cron` (isolated)          |
| Фоновый мониторинг почты и календаря | `heartbeat`                |
| Реагировать на GitHub-пуш            | `webhook`                  |
| Мультишаговый pipeline с аппрувами   | Lobster (plugin)           |
| Напомнить через 20 минут             | `cron` с `--at "20m"`      |

***

## Полезные ссылки

* Официальная документация по инструментам: [docs.openclaw.ai/tools](https://docs.openclaw.ai/tools)
* Документация по навыкам: [docs.openclaw.ai/tools/skills](https://docs.openclaw.ai/tools/skills)
* Документация по cron: [docs.openclaw.ai/automation/cron-jobs](https://docs.openclaw.ai/automation/cron-jobs)
* Cron vs Heartbeat: [docs.openclaw.ai/automation/cron-vs-heartbeat](https://docs.openclaw.ai/automation/cron-vs-heartbeat)
* ClawHub (реестр навыков): [github.com/openclaw/clawhub](https://github.com/openclaw/clawhub)