Хуки OpenClaw: событийная автоматизация агента — что это и как настроить

Коротко. Хук в OpenClaw — это маленький обработчик на JavaScript или TypeScript, который выполняется внутри процесса Gateway, когда агент генерирует событие: новый диалог, сброс контекста, остановка, сжатие истории, запуск или остановка сервера, входящее сообщение. С их помощью владелец собственного агента включает то, что «из коробки» выключено: ведёт журнал команд, сохраняет выжимку разговора перед сбросом, выполняет инструкции при старте. Плагин для этого писать не нужно — часто достаточно включить готовый хук одной командой. Ниже — рабочий порядок настройки на OpenClaw 2026.9.8: готовые хуки, свой пример и таблица событий.

На чём это проверено

Все команды, названия событий и ключи конфигурации в статье сверены с официальной документацией OpenClaw 6 октября 2026 года. В реестре npm на эту дату: канал latest — версия 2026.9.8 (выпущена 3 октября 2026), канал extended-stable — 2026.8.35. Проект выходит часто, поэтому перед переносом в боевой конфиг сверьтесь с документацией по хукам — исходники тех же разделов лежат в репозитории openclaw/openclaw.

Статья предполагает, что OpenClaw уже установлен и первично настроен: провайдер подключён, модель выбрана, мессенджер отвечает. Если нет — начните с материалов как установить OpenClaw и первичная настройка OpenClaw.

Что такое внутренние хуки и зачем они бизнесу

Внутренние хуки — это доверенный код, который выполняется в том же процессе, что и Gateway (серверная часть OpenClaw). Когда происходит событие, Gateway по очереди вызывает подписанные обработчики и дожидается их завершения. По сути это событийная автоматизация агента: вместо ручных действий вы описываете правило «когда X — сделай Y».

Практические сценарии для рабочего агента:

журнал команд /new, /reset и /stop — видно, когда и что сбрасывали;
автосохранение короткой выжимки диалога перед сбросом — контекст не теряется;
выполнение инструкций при старте сервера — агент сам готовит рабочее окружение;
уведомление о сжатии истории — видно, когда контекст «ужался».

Это не замена ручной настройки, а её автоматизация. Если задача сложнее — доработка поведения агента, подключение CRM или Битрикс24, перехват ответов — настроим хуки и событийную автоматизацию OpenClaw под ваши задачи.

Где включаются хуки

Конфигурация OpenClaw лежит в файле ~/.openclaw/openclaw.json (формат JSON5 — допускаются комментарии). Внутренние хуки настраиваются в секции hooks.internal. Чтобы включить конкретный хук по имени, добавьте запись:

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

Главный выключатель — hooks.internal.enabled, а каждый хук управляется флагом enabled в entries. Именованные записи образуют список разрешённых хуков: включённый главный флаг не «включает всё подряд», если вы явно перечислили имена. По умолчанию действует режим перезагрузки hybrid — изменения конфигурации применяются без перезапуска Gateway.

Готовые хуки, которые стоит включить первыми

OpenClaw поставляет пять готовых хуков — писать их самому не нужно:

Хук	События	Что делает
`boot-md`	`gateway:startup`	Выполняет инструкции из `BOOT.md` рабочего пространства при старте
`bootstrap-extra-files`	`agent:bootstrap`	Добавляет нужные файлы рабочего пространства в контекст
`command-logger`	`command`	Пишет события команд в JSONL-журнал
`compaction-notifier`	`session:compact:before`, `session:compact:after`	Показывает уведомление о сжатии истории
`session-memory`	`command:new`, `command:reset`, `session:auto-reset`	Сохраняет выжимку разговора в память рабочего пространства

Начать лучше всего с command-logger: он не требует дополнительных программ и не вызывает модель — вы сразу получаете файл, который можно посмотреть. Выполните на хосте, где работает Gateway:

openclaw hooks list
openclaw hooks info command-logger
openclaw hooks enable command-logger

После этого отправьте агенту команду /new или /reset в тестовом диалоге и проверьте журнал:

tail -n 5 ~/.openclaw/logs/commands.log

В файле появится JSON-строка с полем "action":"new" или "action":"reset". Это доказывает, что обработчик отработал: сама по себе команда openclaw hooks check этого не гарантирует. Если журнал не нужен — отключите хук командой openclaw hooks disable command-logger.

Свой хук: приветствие при сбросе

Собственный хук — это каталог с двумя файлами: метаданными HOOK.md и обработчиком. Простейший пример отвечает короткой строкой на сброс диалога:

mkdir -p ~/.openclaw/hooks/reset-greeting

cat > ~/.openclaw/hooks/reset-greeting/HOOK.md <<'HOOK'
---
name: reset-greeting
description: "Confirm that a reset hook ran"
metadata:
  { "openclaw": { "events": ["command:new", "command:reset"] } }
---

# Reset greeting

Send a short confirmation after an authorized reset command.
HOOK

cat > ~/.openclaw/hooks/reset-greeting/handler.js <<'HANDLER'
export default function handler(event) {
  if (event.type !== "command" || !["new", "reset"].includes(event.action)) {
    return;
  }

  console.log("[reset-greeting] reset hook ran");
  event.messages.push("Reset hook ran.");
}
HANDLER

Обработчик получает объект события с полями type (семейство), action (действие), sessionKey, timestamp и context. Строка, добавленная в event.messages, для команд /new и /reset отправляется обратно в тот же чат. Включите и проверьте хук:

openclaw hooks info reset-greeting
openclaw hooks enable reset-greeting

Отправьте /new в обычном диалоге с ботом — в ответ придёт «Reset hook ran.». Когда закончите, отключите пример:

openclaw hooks disable reset-greeting

Отключение оставляет файлы на месте — дальше хуком можно управлять только конфигурацией. Подробности про HOOK.md и контракт обработчика — в разделе Writing hooks.

Какие события доступны

Обработчик подписывается на точное имя события или на целое семейство. Семейств пять: command, session, agent, gateway и message. Подписка на семейство получает все события внутри него — не подписывайте один обработчик одновременно на command и на command:new, иначе он сработает дважды. Основные события:

Событие	Когда срабатывает
`command:new`	Обработка команды нового диалога; обработчик ожидается
`command:reset`	Обработка команды сброса; обработчик ожидается
`command:stop`	Обработка остановки; ожидается, но без доставки ответа
`session:auto-reset`	Диалог заменён по дневной политике или простою
`session:compact:before` / `session:compact:after`	До и после сжатия истории; обработчики ожидаются
`agent:bootstrap`	Сборка контекста рабочего пространства; обработчик ожидается
`gateway:startup`	После загрузки хуков и старта каналов
`gateway:shutdown`	Начало завершения работы; ожидание ограничено
`message:received`	Принято входящее сообщение; асинхронное наблюдение
`message:sent`	Зафиксирован результат отправки; асинхронное наблюдение

Полный список и состав контекста по каждому событию — на странице Hook event types and context. Поля контекста у событий разные: не рассчитывайте, что поле из одного события существует в другом.

Техника безопасности

Внутренние хуки — это доверенный код, а не изолированный скрипт. Они выполняются с правами процесса Gateway: доступ к файловой системе, сети и переменным окружения. Поэтому:

включайте только тот код, который прочитали и поняли, — особенно из чужого репозитория или установленного пакета;
не логируйте тела сообщений, объекты конфигурации целиком и учётные данные — в диалогах бывают приватные данные;
держите побочные эффекты короткими: у обработчиков нет общего тайм-аута, очереди и повтора, а перезапуск процесса может потерять незавершённую работу.

Безопасность агента шире, чем одни хуки: права на файлы, ограничение инструментов, изоляция рабочего пространства. Если вы запускаете агента для реальных задач бизнеса, это стоит проверить целиком — поможем настроить безопасность AI-агента так, чтобы автоматизация не открыла лишнего доступа.

Стоимость

Хуки — часть OpenClaw с открытым исходным кодом, отдельной платы за них нет. Платят за инфраструктуру, на которой работает агент, и за время настройки, если её делегируют подрядчику. Актуальные цены на наши тарифы — на странице тарифов.