Хуки

Хуки — це невеликі скрипти, які виконуються всередині 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] 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. Див. Хуки плагінів.

Події життєвого циклу 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 не може заблокувати вихід із процесу, а сеанси, які вже були завершені через заміну, скидання, видалення або ущільнення, пропускаються, щоб уникнути подвійного спрацювання.

Виявлення хуків

Хуки виявляються з чотирьох джерел:

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, використовуючи локальну дату хоста. Захоплення пам’яті виконується у фоновому режимі, тому читання транскрипту або необов’язкове генерування 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

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

Повний довідник хуків Plugin див. у розділі Хуки Plugin.

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

{  "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: хуки
• Вебхуки
• Хуки Plugin — внутрішньопроцесні хуки життєвого циклу Plugin
• Конфігурація