--- read_when: - Вам нужна автоматизация на основе событий для /new, /reset, /stop и событий жизненного цикла агента - Вы хотите создать, установить или отладить хуки summary: 'Хуки: автоматизация на основе событий для команд и событий жизненного цикла' title: Хуки x-i18n: generated_at: "2026-07-13T17:51:37Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: ba09acf45cc09d4ce84b9dda36af2a720ccefbfaed23a1558dd36358ce56701a source_path: automation/hooks.md workflow: 16 --- Хуки — это небольшие скрипты, которые выполняются внутри Gateway при возникновении событий агента: команд вроде `/new`, `/reset`, `/stop`, сжатия сеанса, событий жизненного цикла Gateway и потока сообщений. Они обнаруживаются в каталогах и управляются с помощью `openclaw hooks`. Gateway загружает внутренние хуки только после того, как вы включите хуки или настроите хотя бы одну запись хука, пакет хуков, устаревший обработчик либо дополнительный каталог хуков. В OpenClaw есть два вида хуков: - **Внутренние хуки** (эта страница): выполняются внутри Gateway при возникновении событий агента. - **Вебхуки**: внешние конечные точки HTTP, позволяющие другим системам запускать работу в OpenClaw. См. [Вебхуки](/ru/automation/cron-jobs#webhooks). Хуки также могут поставляться в составе плагинов. `openclaw hooks list` показывает как автономные хуки, так и хуки, управляемые плагинами (отображаются как `plugin:`). ## Выбор подходящего механизма В OpenClaw есть несколько похожих механизмов расширения, предназначенных для разных задач: | Если вы хотите... | Используйте... | Почему | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------- | | Сохранить снимок при `/new`, записать `/reset` в журнал, вызвать внешний API после `message:sent` или добавить общую операторскую автоматизацию | Внутренние хуки (`HOOK.md`, эта страница) | Файловые хуки предназначены для управляемых оператором побочных эффектов и автоматизации команд и жизненного цикла | | Переписывать промпты, блокировать инструменты, отменять исходящие сообщения или добавлять упорядоченное промежуточное ПО либо политики | Типизированные хуки плагинов через `api.on(...)` | Типизированные хуки имеют явные контракты, приоритеты, правила объединения и семантику блокировки и отмены | | Добавить экспорт только телеметрии или средства наблюдаемости | Диагностические события | Наблюдаемость использует отдельную шину событий, а не механизм хуков политик | Используйте внутренние хуки для автоматизации, работающей как небольшая установленная интеграция. Используйте типизированные хуки плагинов, когда требуется управление жизненным циклом среды выполнения. ## Быстрый старт ```bash # Показать доступные хуки openclaw hooks list # Включить хук openclaw hooks enable session-memory # Проверить состояние хуков openclaw hooks check # Получить подробную информацию openclaw hooks info session-memory ``` ## Типы событий Хуки подписываются на конкретный ключ из этой таблицы или на простое имя семейства (`command`, `session`, `agent`, `gateway`, `message`), чтобы получать все действия этого семейства. Ядро OpenClaw не генерирует других событий, поэтому любое другое имя почти всегда является опечаткой, из-за которой хук незаметно остаётся неактивным (его мог бы вызвать только плагин, генерирующий пользовательское событие). Загрузчик хуков записывает предупреждение для таких имён (например, `command:nwe`), а `openclaw hooks info ` помечает их, поэтому причину, по которой хук никогда не выполняется, можно диагностировать. | Событие | Когда возникает | | ------------------------ | ---------------------------------------------------------- | | `command:new` | Выполнена команда `/new` | | `command:reset` | Выполнена команда `/reset` | | `command:stop` | Выполнена команда `/stop` | | `command` | Любое событие команды (общий слушатель) | | `session:compact:before` | Перед тем как Compaction обобщает историю | | `session:compact:after` | После завершения Compaction | | `session:patch` | При изменении свойств сеанса | | `agent:bootstrap` | Перед внедрением файлов начальной загрузки рабочей области | | `gateway:startup` | После запуска каналов и загрузки хуков | | `gateway:shutdown` | При начале завершения работы Gateway | | `gateway:pre-restart` | Перед ожидаемым перезапуском Gateway | | `message:received` | Входящее сообщение из любого канала | | `message:transcribed` | После завершения транскрибирования аудио | | `message:preprocessed` | После завершения или пропуска предварительной обработки медиафайлов и ссылок | | `message:sent` | При попытке исходящей отправки (`context.success` содержит результат) | ## Написание хуков ### Структура хука Каждый хук представляет собой каталог с двумя файлами: ```text my-hook/ ├── HOOK.md # Метаданные и документация └── handler.ts # Реализация обработчика ``` Файл обработчика может иметь расширение `handler.ts`, `handler.js`, `index.ts` или `index.js`. ### Формат HOOK.md ```markdown --- name: my-hook description: "Краткое описание назначения этого хука" metadata: { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } --- # Мой хук Здесь размещается подробная документация. ``` **Поля метаданных** (`metadata.openclaw`): | Поле | Описание | | ---------- | ---------------------------------------------------- | | `emoji` | Эмодзи для отображения в CLI | | `events` | Массив отслеживаемых событий | | `export` | Используемый именованный экспорт (по умолчанию `"default"`) | | `os` | Требуемые платформы (например, `["darwin", "linux"]`) | | `requires` | Требуемые пути `bins`, `anyBins`, `env` или `config` | | `always` | Пропуск проверок соответствия требованиям (логическое значение) | | `hookKey` | Переопределение ключа конфигурации (по умолчанию используется имя хука) | | `homepage` | URL документации, отображаемый командой `openclaw hooks info` | | `install` | Способы установки | ### Реализация обработчика ```typescript const handler = async (event) => { if (event.type !== "command" || event.action !== "new") { return; } console.log(`[my-hook] Сработала новая команда`); // Здесь размещается ваша логика // При необходимости отправьте ответ через поверхности, поддерживающие ответы event.messages.push("Хук выполнен!"); }; export default handler; ``` Каждое событие содержит: `type`, `action`, `sessionKey`, `timestamp`, `messages` и `context` (данные, относящиеся к событию). Контексты типизированных хуков плагинов для хуков агента и инструментов также могут содержать `trace` — доступный только для чтения контекст диагностической трассировки, совместимый с W3C, который плагины могут передавать в структурированные журналы для корреляции OTEL. Строки, добавленные в `event.messages`, доставляются обратно в чат только для `command:new` и `command:reset` (маршрутизируются как ответ в исходную беседу), а также для `session:compact:before` / `session:compact:after` (отправляются как уведомления о состоянии Compaction). Все остальные события, включая `command:stop`, `message:*`, `agent:bootstrap`, `session:patch` и `gateway:*`, игнорируют добавленные сообщения. ### Основные данные контекста событий **События команд** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.senderId`, `context.workspaceDir`, `context.cfg`. **События команд** (`command:stop`): `context.sessionEntry`, `context.sessionId`, `context.commandSource`, `context.senderId`. **События сообщений** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (данные, зависящие от провайдера, включая `senderId`, `senderName`, `guildId`). `context.content` предпочитает непустое тело команды для сообщений, похожих на команды, затем использует исходное тело входящего сообщения и общее тело; оно не включает обогащённые данные, доступные только агенту, например историю ветки или сводки по ссылкам. **События сообщений** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`, а также `context.error` при сбое отправки. **События сообщений** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`. **События сообщений** (`message:preprocessed`): `context.bodyForAgent` (итоговое обогащённое тело), `context.from`, `context.channelId`. **События начальной загрузки** (`agent:bootstrap`): `context.bootstrapFiles` (изменяемый массив), `context.agentId`. **События частичного обновления сеанса** (`session:patch`): `context.sessionEntry`, `context.patch` (только изменённые поля), `context.cfg`. События частичного обновления могут инициировать только привилегированные клиенты; контекст является копией, поэтому обработчики не могут изменять активную запись сеанса. **События Compaction**: `session:compact:before` содержит `messageCount`, `tokenCount`. `session:compact:after` также содержит `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. `command:stop` отслеживает выполнение пользователем `/stop`; это событие жизненного цикла отмены или команды, а не точка контроля завершения работы агента. Плагины, которым нужно проверить естественный окончательный ответ и запросить у агента ещё один проход, должны вместо этого использовать типизированный хук плагина `before_agent_finalize`. См. [Хуки плагинов](/ru/plugins/hooks). **События жизненного цикла Gateway**: `gateway:shutdown` содержит `reason` и `restartExpectedMs` и возникает при начале завершения работы Gateway. `gateway:pre-restart` содержит тот же контекст, но возникает только тогда, когда завершение работы является частью ожидаемого перезапуска и указано конечное значение `restartExpectedMs`. Во время завершения работы ожидание каждого хука жизненного цикла выполняется по мере возможности и ограничено по времени, поэтому завершение работы продолжится, если обработчик зависнет. Бюджет ожидания по умолчанию составляет 5 секунд для `gateway:shutdown` и 10 секунд для `gateway:pre-restart`. Используйте `gateway:pre-restart` для кратких уведомлений о перезапуске, пока каналы ещё доступны: ```typescript import { execFile } from "node:child_process"; import { promisify } from "node:util"; const execFileAsync = promisify(execFile); export default async function handler(event) { if (event.type !== "gateway" || event.action !== "pre-restart") { return; } const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000); await execFileAsync("openclaw", [ "system", "event", "--mode", "now", "--text", `Gateway перезапустится примерно через ${restartInSeconds} с (${event.context.reason}). Создайте контрольную точку сейчас.`, ]); } ``` Между событием `gateway:shutdown` (или `gateway:pre-restart`) и остальной последовательностью завершения работы Gateway также вызывает типизированный хук плагина `session_end` для каждого сеанса, который оставался активным на момент остановки процесса. Значение `reason` этого события равно `shutdown` при обычной остановке по SIGTERM/SIGINT и `restart`, когда закрытие было запланировано как часть ожидаемого перезапуска. Этот этап завершения ограничен по времени, поэтому медленный обработчик `session_end` не может заблокировать выход процесса, а сеансы, уже завершённые посредством замены / сброса / удаления / Compaction, пропускаются во избежание повторного срабатывания. ## Обнаружение хуков Хуки обнаруживаются из четырёх источников: 1. **Встроенные хуки**: поставляются с OpenClaw 2. **Хуки плагинов**: поставляются в составе установленных плагинов; могут переопределять встроенные хуки с тем же именем 3. **Управляемые хуки**: `~/.openclaw/hooks/` (устанавливаются пользователем и используются во всех рабочих областях); могут переопределять встроенные хуки и хуки плагинов. Дополнительные каталоги из `hooks.internal.load.extraDirs` имеют такой же приоритет. 4. **Хуки рабочей области**: `/hooks/` (для каждого агента; по умолчанию отключены до явного включения) Хуки рабочей области могут добавлять новые имена хуков, но не могут переопределять встроенные, управляемые или предоставляемые плагинами хуки с тем же именем. При запуске Gateway пропускает обнаружение внутренних хуков, пока они не настроены. Включите встроенный или управляемый хук с помощью `openclaw hooks enable `, установите пакет хуков или задайте `hooks.internal.enabled=true`, чтобы явно включить обнаружение. Когда вы включаете один именованный хук, Gateway загружает только обработчик этого хука; `hooks.internal.enabled=true`, дополнительные каталоги хуков и устаревшие обработчики включают расширенное обнаружение. ### Пакеты хуков Пакеты хуков — это пакеты npm, которые экспортируют хуки через `openclaw.hooks` в `package.json`. Установка: ```bash openclaw plugins install ``` Спецификации npm поддерживаются только для реестра (имя пакета + необязательная точная версия или dist-tag). Спецификации Git/URL/файлов и диапазоны semver отклоняются. Старые команды `openclaw hooks install` и `openclaw hooks update` являются устаревшими псевдонимами для `openclaw plugins install` / `openclaw plugins update`. ## Встроенные хуки | Хук | События | Назначение | | --------------------- | ------------------------------------------------- | -------------------------------------------------------------- | | session-memory | `command:new`, `command:reset` | Сохраняет контекст сеанса в `/memory/` | | bootstrap-extra-files | `agent:bootstrap` | Добавляет дополнительные файлы начальной загрузки по glob-шаблонам | | command-logger | `command` | Записывает все команды в `~/.openclaw/logs/commands.log` | | compaction-notifier | `session:compact:before`, `session:compact:after` | Отправляет видимые уведомления в чат при начале и завершении Compaction сеанса | | boot-md | `gateway:startup` | Запускает `BOOT.md` при запуске Gateway | Включение любого встроенного хука: ```bash openclaw hooks enable ``` ### Сведения о session-memory Извлекает последние сообщения пользователя и ассистента (по умолчанию 15, настраивается с помощью `hooks.internal.entries.session-memory.messages`) и сохраняет их в `/memory/YYYY-MM-DD-HHMM.md`, используя локальную дату хоста. Захват памяти выполняется в фоновом режиме, поэтому подтверждения `/new` и `/reset` не задерживаются чтением расшифровки или необязательным созданием слага. Задайте `hooks.internal.entries.session-memory.llmSlug: true`, чтобы создавать описательные слаги имён файлов, и при необходимости задайте для `hooks.internal.entries.session-memory.model` настроенный псевдоним, например `sonnet`, простой идентификатор модели у провайдера агента по умолчанию или ссылку `provider/model`. Если `model` не указан, для создания слага используется модель агента по умолчанию; если она недоступна, используются слаги с временной меткой. Требуется настроить `workspace.dir`. ### Конфигурация bootstrap-extra-files ```json { "hooks": { "internal": { "entries": { "bootstrap-extra-files": { "enabled": true, "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"] } } } } } ``` `patterns` и `files` принимаются как псевдонимы `paths`. Пути разрешаются относительно рабочей области и должны оставаться внутри неё. Загружаются только распознаваемые базовые имена файлов начальной загрузки (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). ### Сведения о command-logger Записывает каждую команду с косой чертой в виде строки JSON (временная метка, действие, ключ сеанса, идентификатор отправителя, источник) в `~/.openclaw/logs/commands.log`. ### Сведения о compaction-notifier Отправляет короткие сообщения о состоянии в текущий разговор, когда OpenClaw начинает и завершает Compaction расшифровки сеанса. Благодаря этому длинные взаимодействия в чатах становятся понятнее: пользователь видит, что ассистент обобщает контекст и продолжит после Compaction. ### Сведения о boot-md Запускает `BOOT.md` при старте Gateway для каждой настроенной области агента, если файл существует в разрешённой рабочей области этого агента. ## Хуки плагинов Плагины могут регистрировать типизированные хуки через SDK плагинов для более глубокой интеграции: перехвата вызовов инструментов, изменения запросов, управления потоком сообщений и других задач. Используйте хуки плагинов, когда вам нужны `before_tool_call`, `before_agent_reply`, `before_install` или другие внутрипроцессные хуки жизненного цикла. Управляемые плагинами внутренние хуки отличаются от них: они участвуют в описанной на этой странице укрупнённой системе событий команд и жизненного цикла и отображаются в `openclaw hooks list` как `plugin:`. Используйте их для побочных эффектов и совместимости с пакетами хуков, а не для упорядоченного промежуточного ПО или шлюзов политик. Полный справочник по хукам плагинов см. в разделе [Хуки плагинов](/ru/plugins/hooks). ## Конфигурация ```json { "hooks": { "internal": { "enabled": true, "entries": { "session-memory": { "enabled": true }, "command-logger": { "enabled": false } } } } } ``` Значения окружения для отдельных хуков удовлетворяют проверкам применимости `requires.env` хука (наряду с окружением процесса), а обработчики могут читать их из записи конфигурации своего хука: ```json { "hooks": { "internal": { "entries": { "my-hook": { "enabled": true, "env": { "MY_CUSTOM_VAR": "value" } } } } } } ``` Дополнительные каталоги хуков: ```json { "hooks": { "internal": { "load": { "extraDirs": ["/path/to/more/hooks"] } } } } ``` Устаревший формат конфигурации массива `hooks.internal.handlers` по-прежнему поддерживается для обратной совместимости, но новые хуки должны использовать систему на основе обнаружения. ## Справочник CLI ```bash # Перечислить все хуки (добавьте --eligible, --verbose или --json) openclaw hooks list # Показать подробные сведения о хуке openclaw hooks info # Показать сводку применимости openclaw hooks check # Включить/отключить openclaw hooks enable openclaw hooks disable ``` ## Рекомендации - **Обеспечивайте быструю работу обработчиков.** Хуки выполняются во время обработки команд. Запускайте ресурсоёмкую работу без ожидания результата с помощью `void processInBackground(event)`. - **Корректно обрабатывайте ошибки.** Оборачивайте рискованные операции в try/catch; не выбрасывайте исключения, чтобы другие обработчики могли продолжить работу. - **Фильтруйте события как можно раньше.** Немедленно возвращайте управление, если тип или действие события не относится к обработчику. - **Используйте конкретные ключи событий.** Отдавайте предпочтение `"events": ["command:new"]` вместо `"events": ["command"]`, чтобы снизить накладные расходы. ## Устранение неполадок ### Хук не обнаружен ```bash # Проверьте структуру каталога ls -la ~/.openclaw/hooks/my-hook/ # Должны отображаться: HOOK.md, handler.ts # Перечислите все обнаруженные хуки openclaw hooks list ``` ### Хук неприменим ```bash openclaw hooks info my-hook ``` Проверьте наличие отсутствующих исполняемых файлов (PATH), переменных окружения, значений конфигурации или совместимости с ОС. ### Хук не выполняется 1. Убедитесь, что хук включён: `openclaw hooks list` 2. Перезапустите процесс Gateway, чтобы хуки были перезагружены. 3. Проверьте журналы Gateway: `openclaw logs --follow | grep -i hook` ## Связанные материалы - [Справочник CLI: хуки](/ru/cli/hooks) - [Веб-хуки](/ru/automation/cron-jobs#webhooks) - [Хуки плагинов](/ru/plugins/hooks) — внутрипроцессные хуки жизненного цикла плагина - [Конфигурация](/ru/gateway/configuration-reference#hooks)