--- read_when: - Вам потрібна автоматизація, керована подіями, для /new, /reset, /stop і подій життєвого циклу агента - Ви хочете створювати, встановлювати або налагоджувати хуки summary: 'Хуки: автоматизація на основі подій для команд і подій життєвого циклу' title: Хуки x-i18n: generated_at: "2026-07-12T12:57:37Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: ba09acf45cc09d4ce84b9dda36af2a720ccefbfaed23a1558dd36358ce56701a source_path: automation/hooks.md workflow: 16 --- Хуки — це невеликі скрипти, які виконуються всередині Gateway під час спрацювання подій агента: команд на кшталт `/new`, `/reset`, `/stop`, ущільнення сеансу, подій життєвого циклу Gateway і обміну повідомленнями. Їх виявляють у каталогах і керують ними за допомогою `openclaw hooks`. Gateway завантажує внутрішні хуки лише після того, як ви ввімкнете хуки або налаштуєте принаймні один запис хука, пакет хуків, застарілий обробник чи додатковий каталог хуків. В OpenClaw є два види хуків: - **Внутрішні хуки** (ця сторінка): виконуються всередині Gateway під час спрацювання подій агента. - **Вебхуки**: зовнішні кінцеві точки HTTP, які дають змогу іншим системам запускати роботу в OpenClaw. Див. [Вебхуки](/uk/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` | Перед узагальненням історії під час ущільнення | | `session:compact:after` | Після завершення ущільнення | | `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] New command triggered`); // Ваша логіка тут // За потреби надіслати відповідь у механізмах, що підтримують відповіді 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` (надсилаються як сповіщення про стан ущільнення). Усі інші події, зокрема `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`. Події зміни можуть запускати лише привілейовані клієнти; контекст є копією, тому обробники не можуть змінювати активний запис сеансу. **Події ущільнення**: `session:compact:before` містить `messageCount`, `tokenCount`. `session:compact:after` додає `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. `command:stop` фіксує, що користувач видав `/stop`; це частина життєвого циклу скасування або команди, а не контрольна точка завершення агента. Плагіни, яким потрібно перевірити природну остаточну відповідь і попросити агента виконати ще один прохід, натомість мають використовувати типізований хук плагіна `before_agent_finalize`. Див. [Хуки плагінів](/uk/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` не може заблокувати вихід із процесу, а сеанси, які вже були завершені через заміну, скидання, видалення або ущільнення, пропускаються, щоб уникнути подвійного спрацювання. ## Виявлення хуків Хуки виявляються з чотирьох джерел: 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`, використовуючи локальну дату хоста. Захоплення пам’яті виконується у фоновому режимі, тому читання транскрипту або необов’язкове генерування slug не затримують підтвердження `/new` і `/reset`. Установіть `hooks.internal.entries.session-memory.llmSlug: true`, щоб генерувати описові slug для назв файлів, і за потреби задайте в `hooks.internal.entries.session-memory.model` налаштований псевдонім, наприклад `sonnet`, простий ідентифікатор моделі у стандартного провайдера агента або посилання `provider/model`. Якщо `model` не вказано, для генерування slug використовується стандартна модель агента; якщо вона недоступна, застосовуються slug на основі часової позначки. Потрібно налаштувати `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 Записує кожну slash-команду як рядок JSON (часова позначка, дія, ключ сеансу, ідентифікатор відправника, джерело) до `~/.openclaw/logs/commands.log`. ### Докладно про compaction-notifier Надсилає короткі повідомлення про стан у поточну розмову, коли OpenClaw починає та завершує Compaction транскрипту сеансу. Це робить тривалі взаємодії менш заплутаними в чатах, оскільки користувач бачить, що асистент узагальнює контекст і продовжить після Compaction. ### Докладно про boot-md Запускає `BOOT.md` під час запуску Gateway для кожної налаштованої області агента, якщо цей файл існує у визначеному робочому просторі агента. ## Хуки Plugin Plugin можуть реєструвати типізовані хуки через Plugin SDK для глибшої інтеграції: перехоплення викликів інструментів, змінення підказок, керування потоком повідомлень тощо. Використовуйте хуки Plugin, коли вам потрібні `before_tool_call`, `before_agent_reply`, `before_install` або інші внутрішньопроцесні хуки життєвого циклу. Внутрішні хуки, якими керують Plugin, відрізняються: вони беруть участь в описаній на цій сторінці загальній системі подій команд і життєвого циклу та відображаються в `openclaw hooks list` як `plugin:`. Використовуйте їх для побічних ефектів і сумісності з наборами хуків, а не для впорядкованого проміжного ПЗ або шлюзів політик. Повний довідник хуків Plugin див. у розділі [Хуки Plugin](/uk/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: хуки](/uk/cli/hooks) - [Вебхуки](/uk/automation/cron-jobs#webhooks) - [Хуки Plugin](/uk/plugins/hooks) — внутрішньопроцесні хуки життєвого циклу Plugin - [Конфігурація](/uk/gateway/configuration-reference#hooks)