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

# Хуки

## 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 для тестирования).