Хуки

Хуки — это небольшие скрипты, которые выполняются внутри Gateway при возникновении событий агента: команд вроде /new, /reset, /stop, сжатия сеанса, событий жизненного цикла Gateway и потока сообщений. Они обнаруживаются в каталогах и управляются с помощью openclaw hooks. Gateway загружает внутренние хуки только после того, как вы включите хуки или настроите хотя бы одну запись хука, пакет хуков, устаревший обработчик либо дополнительный каталог хуков.

В OpenClaw есть два вида хуков:

• Внутренние хуки (эта страница): выполняются внутри Gateway при возникновении событий агента.
• Вебхуки: внешние конечные точки HTTP, позволяющие другим системам запускать работу в OpenClaw. См. Вебхуки.

Хуки также могут поставляться в составе плагинов. openclaw hooks list показывает как автономные хуки, так и хуки, управляемые плагинами (отображаются как plugin:<id>).

Выбор подходящего механизма

В OpenClaw есть несколько похожих механизмов расширения, предназначенных для разных задач:

Используйте внутренние хуки для автоматизации, работающей как небольшая установленная интеграция. Используйте типизированные хуки плагинов, когда требуется управление жизненным циклом среды выполнения.

Быстрый старт

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

Написание хуков

Структура хука

Каждый хук представляет собой каталог с двумя файлами:

my-hook/├── HOOK.md          # Метаданные и документация└── handler.ts       # Реализация обработчика

Файл обработчика может иметь расширение handler.ts, handler.js, index.ts или index.js.

Формат HOOK.md

---name: my-hookdescription: "Краткое описание назначения этого хука"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # Мой хук Здесь размещается подробная документация.

Поля метаданных (metadata.openclaw):

Реализация обработчика

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. См. Хуки плагинов.

События жизненного цикла Gateway: gateway:shutdown содержит reason и restartExpectedMs и возникает при начале завершения работы Gateway. gateway:pre-restart содержит тот же контекст, но возникает только тогда, когда завершение работы является частью ожидаемого перезапуска и указано конечное значение restartExpectedMs. Во время завершения работы ожидание каждого хука жизненного цикла выполняется по мере возможности и ограничено по времени, поэтому завершение работы продолжится, если обработчик зависнет. Бюджет ожидания по умолчанию составляет 5 секунд для gateway:shutdown и 10 секунд для gateway:pre-restart.

Используйте gateway:pre-restart для кратких уведомлений о перезапуске, пока каналы ещё доступны:

  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. Хуки рабочей области: <workspace>/hooks/ (для каждого агента; по умолчанию отключены до явного включения)

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

При запуске Gateway пропускает обнаружение внутренних хуков, пока они не настроены. Включите встроенный или управляемый хук с помощью openclaw hooks enable <name>, установите пакет хуков или задайте hooks.internal.enabled=true, чтобы явно включить обнаружение. Когда вы включаете один именованный хук, Gateway загружает только обработчик этого хука; hooks.internal.enabled=true, дополнительные каталоги хуков и устаревшие обработчики включают расширенное обнаружение.

Пакеты хуков

Пакеты хуков — это пакеты npm, которые экспортируют хуки через openclaw.hooks в package.json. Установка:

openclaw plugins install <path-or-spec>

Спецификации npm поддерживаются только для реестра (имя пакета + необязательная точная версия или dist-tag). Спецификации Git/URL/файлов и диапазоны semver отклоняются. Старые команды openclaw hooks install и openclaw hooks update являются устаревшими псевдонимами для openclaw plugins install / openclaw plugins update.

Встроенные хуки

Включение любого встроенного хука:

openclaw hooks enable <hook-name>

Сведения о session-memory

Извлекает последние сообщения пользователя и ассистента (по умолчанию 15, настраивается с помощью hooks.internal.entries.session-memory.messages) и сохраняет их в <workspace>/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

{  "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:<id>. Используйте их для побочных эффектов и совместимости с пакетами хуков, а не для упорядоченного промежуточного ПО или шлюзов политик.

Полный справочник по хукам плагинов см. в разделе Хуки плагинов.

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

{  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": false }      }    }  }}

Значения окружения для отдельных хуков удовлетворяют проверкам применимости requires.env хука (наряду с окружением процесса), а обработчики могут читать их из записи конфигурации своего хука:

{  "hooks": {    "internal": {      "entries": {        "my-hook": {          "enabled": true,          "env": { "MY_CUSTOM_VAR": "value" }        }      }    }  }}

Дополнительные каталоги хуков:

{  "hooks": {    "internal": {      "load": {        "extraDirs": ["/path/to/more/hooks"]      }    }  }}

Справочник CLI

# Перечислить все хуки (добавьте --eligible, --verbose или --json)openclaw hooks list # Показать подробные сведения о хукеopenclaw hooks info <hook-name> # Показать сводку применимостиopenclaw hooks check # Включить/отключитьopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

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

• Обеспечивайте быструю работу обработчиков. Хуки выполняются во время обработки команд. Запускайте ресурсоёмкую работу без ожидания результата с помощью void processInBackground(event).
• Корректно обрабатывайте ошибки. Оборачивайте рискованные операции в try/catch; не выбрасывайте исключения, чтобы другие обработчики могли продолжить работу.
• Фильтруйте события как можно раньше. Немедленно возвращайте управление, если тип или действие события не относится к обработчику.
• Используйте конкретные ключи событий. Отдавайте предпочтение "events": ["command:new"] вместо "events": ["command"], чтобы снизить накладные расходы.

Устранение неполадок

Хук не обнаружен

# Проверьте структуру каталогаls -la ~/.openclaw/hooks/my-hook/# Должны отображаться: HOOK.md, handler.ts # Перечислите все обнаруженные хукиopenclaw hooks list

Хук неприменим

openclaw hooks info my-hook

Проверьте наличие отсутствующих исполняемых файлов (PATH), переменных окружения, значений конфигурации или совместимости с ОС.

Хук не выполняется

1. Убедитесь, что хук включён: openclaw hooks list
2. Перезапустите процесс Gateway, чтобы хуки были перезагружены.
3. Проверьте журналы Gateway: openclaw logs --follow | grep -i hook

Связанные материалы

• Справочник CLI: хуки
• Веб-хуки
• Хуки плагинов — внутрипроцессные хуки жизненного цикла плагина
• Конфигурация