Хуки

​

Hooks в OpenClaw

Hooks в OpenClaw — это event-driven система расширения, которая позволяет выполнять пользовательские скрипты (TypeScript-хендлеры) в ответ на определённые события в жизненном цикле агента и gateway. По сути, это паттерн «observer/listener», встроенный в runtime платформы.

​

Концепция

Hooks — это небольшие скрипты, которые запускаются при наступлении определённых событий. Они работают внутри Gateway, когда срабатывают события агента — например, команды /new, /reset, /stop или события жизненного цикла. Важно не путать их с Webhooks — Webhooks — это внешние HTTP-эндпоинты, через которые сторонние системы могут инициировать работу в OpenClaw. Hooks же исполняются in-process внутри Gateway.

​

Архитектура и Discovery

Система hooks построена на автоматическом обнаружении (discovery). Hooks автоматически обнаруживаются из трёх директорий в порядке приоритета: workspace hooks (<workspace>/hooks/) — наивысший приоритет, per-agent; managed hooks (~/.openclaw/hooks/) — пользовательские, общие для всех workspace; и bundled hooks (<openclaw>/dist/hooks/bundled/) — встроенные, поставляемые с OpenClaw. Discovery flow выглядит так: при старте Gateway сканируются директории, парсятся HOOK.md-файлы, проверяется eligibility (наличие нужных бинарников, env-переменных, конфигов, совместимость с ОС), затем загружаются хендлеры и регистрируются на соответствующие события.

​

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

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

• HOOK.md — метаданные в YAML frontmatter + документация в Markdown. Здесь указываются имя, описание, эмодзи для CLI, массив событий для подписки, а также requirements (нужные бинарники, переменные окружения, конфиг-пути, целевые ОС).
• handler.ts — TypeScript-файл, экспортирующий функцию типа HookHandler, которая принимает объект события.

​

Event Types

Существует несколько категорий событий: Command Events (command:new, command:reset, command:stop), Agent Events (agent:bootstrap — до инъекции bootstrap-файлов в workspace, хуки могут мутировать context.bootstrapFiles), Gateway Events (gateway:startup — после запуска каналов и загрузки хуков), а также Tool Result Hooks через Plugin API (tool_result_persist — синхронная трансформация tool results до их записи в транскрипт сессии). Объект события содержит: type, action, sessionKey, timestamp, массив messages (куда можно push’ить сообщения для пользователя), и context с метаданными сессии, конфигом, workspace-директорией и т.д.

​

Best Practices

Несколько ключевых рекомендаций из документации: Хендлеры должны быть быстрыми — hooks выполняются во время обработки команд, поэтому их нужно делать легковесными. Тяжёлую работу стоит отправлять в фоновый процесс через fire-and-forget (void processInBackground(event)), а не блокировать pipeline синхронными вызовами. Ранняя фильтрация событий — если подписываешься на общий тип command, делай return в самом начале хендлера для нерелевантных action’ов. Ещё лучше — указывай конкретные события в metadata (command:new вместо просто command), чтобы снизить overhead. Graceful error handling — оборачивай рискованные операции в try/catch и не бросай исключения наружу, чтобы не блокировать выполнение остальных хуков в цепочке.

​

Bundled Hooks

OpenClaw поставляется с четырьмя встроенными хуками: session-memory (сохраняет контекст сессии при /new, используя LLM для генерации slug’а имени файла), command-logger (audit trail всех команд в JSONL-формате), boot-md (исполняет инструкции из BOOT.md при старте gateway), и soul-evil (подменяет SOUL.md на SOUL_EVIL.md с заданной вероятностью или в определённое временное окно — по сути, механизм adversarial personality injection для тестирования).