Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Їх можна виявляти з каталогів і переглядати за допомогоюDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw hooks. Gateway завантажує внутрішні хуки лише після того, як ви ввімкнете хуки або налаштуєте принаймні один запис хука, пакет хуків, застарілий обробник чи додатковий каталог хуків.
В OpenClaw є два типи хуків:
- Внутрішні хуки (ця сторінка): запускаються всередині Gateway, коли спрацьовують події агента, як-от
/new,/reset,/stopабо події життєвого циклу. - Webhooks: зовнішні HTTP-кінцеві точки, які дають змогу іншим системам запускати роботу в OpenClaw. Див. Webhooks.
openclaw hooks list показує як автономні хуки, так і хуки, керовані plugin.
Швидкий старт
Типи подій
| Подія | Коли спрацьовує |
|---|---|
command:new | Видано команду /new |
command:reset | Видано команду /reset |
command:stop | Видано команду /stop |
command | Будь-яка подія команди (загальний слухач) |
session:compact:before | Перед тим, як compaction підсумовує історію |
session:compact:after | Після завершення compaction |
session:patch | Коли змінюються властивості сесії |
agent:bootstrap | Перед вставленням bootstrap-файлів робочої області |
gateway:startup | Після запуску каналів і завантаження хуків |
gateway:shutdown | Коли починається завершення роботи gateway |
gateway:pre-restart | Перед очікуваним перезапуском gateway |
message:received | Вхідне повідомлення з будь-якого каналу |
message:transcribed | Після завершення транскрибування аудіо |
message:preprocessed | Після завершення або пропуску попередньої обробки медіа й посилань |
message:sent | Доставлено вихідне повідомлення |
Написання хуків
Структура хука
Кожен хук — це каталог, що містить два файли:Формат HOOK.md
metadata.openclaw):
| Поле | Опис |
|---|---|
emoji | Емодзі для відображення в CLI |
events | Масив подій, які потрібно слухати |
export | Іменований експорт для використання (типово "default") |
os | Потрібні платформи (наприклад, ["darwin", "linux"]) |
requires | Потрібні шляхи bins, anyBins, env або config |
always | Обійти перевірки придатності (boolean) |
install | Методи встановлення |
Реалізація обробника
type, action, sessionKey, timestamp, messages (додавайте через push, щоб надіслати користувачу) і context (дані, специфічні для події). Контексти хуків агента й tool plugin також можуть містити trace — діагностичний контекст трасування, сумісний із W3C і доступний лише для читання, який plugins можуть передавати в структуровані журнали для кореляції OTEL.
Основне про контекст подій
Події команд (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.workspaceDir, context.cfg.
Події повідомлень (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.
Події повідомлень (message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath.
Події повідомлень (message:preprocessed): context.bodyForAgent (остаточне збагачене тіло), context.from, context.channelId.
Bootstrap-події (agent:bootstrap): context.bootstrapFiles (змінюваний масив), context.agentId.
Події patch сесії (session:patch): context.sessionEntry, context.patch (лише змінені поля), context.cfg. Події patch можуть запускати лише привілейовані клієнти.
Події Compaction: session:compact:before містить messageCount, tokenCount. session:compact:after додає compactedCount, summaryLength, tokensBefore, tokensAfter.
command:stop фіксує, що користувач видає /stop; це життєвий цикл скасування/команди, а не шлюз фіналізації агента. Plugins, яким потрібно перевірити природну фінальну відповідь і попросити агента виконати ще один прохід, мають натомість використовувати типізований plugin-хук before_agent_finalize. Див. Plugin-хуки.
Події життєвого циклу Gateway: gateway:shutdown містить reason і restartExpectedMs та спрацьовує, коли починається завершення роботи gateway. gateway:pre-restart містить той самий контекст, але спрацьовує лише тоді, коли завершення роботи є частиною очікуваного перезапуску й надано скінченне значення restartExpectedMs. Під час завершення роботи очікування кожного хука життєвого циклу є best-effort і обмеженим, щоб завершення роботи продовжувалося, якщо обробник зависає.
Між подією gateway:shutdown (або gateway:pre-restart) і рештою послідовності завершення роботи gateway також запускає типізований plugin-хук session_end для кожної сесії, яка все ще була активною, коли процес зупинився. Значення reason події — shutdown для звичайної зупинки SIGTERM/SIGINT і restart, коли закриття було заплановано як частину очікуваного перезапуску. Це спорожнення обмежене, тому повільний обробник session_end не може заблокувати вихід процесу, а сесії, які вже були фіналізовані через replace / reset / delete / compaction, пропускаються, щоб уникнути подвійного спрацьовування.
Виявлення хуків
Хуки виявляються з цих каталогів у порядку зростання пріоритету перевизначення:- Вбудовані хуки: постачаються з OpenClaw
- Plugin-хуки: хуки, що постачаються всередині встановлених plugins
- Керовані хуки:
~/.openclaw/hooks/(встановлені користувачем, спільні для робочих областей). Додаткові каталоги зhooks.internal.load.extraDirsмають такий самий пріоритет. - Хуки робочої області:
<workspace>/hooks/(для окремого агента, вимкнені за замовчуванням, доки їх явно не ввімкнуть)
openclaw hooks enable <name>, встановіть пакет хуків або встановіть hooks.internal.enabled=true, щоб увімкнути їх. Коли ви вмикаєте один іменований хук, Gateway завантажує лише обробник цього хука; hooks.internal.enabled=true, додаткові каталоги хуків і застарілі обробники вмикають широке виявлення.
Пакети хуків
Пакети хуків — це npm-пакети, які експортують хуки черезopenclaw.hooks у package.json. Установіть за допомогою:
Вбудовані хуки
| Хук | Події | Що робить |
|---|---|---|
| session-memory | command:new, command:reset | Зберігає контекст сесії в <workspace>/memory/ |
| bootstrap-extra-files | agent:bootstrap | Вставляє додаткові 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 стартує |
Подробиці session-memory
Витягує останні 15 повідомлень користувача/асистента та зберігає їх у<workspace>/memory/YYYY-MM-DD-HHMM.md, використовуючи локальну дату хоста. Захоплення пам’яті виконується у фоновому режимі, тому підтвердження /new і /reset не затримуються читанням транскрипта або необов’язковою генерацією slug. Установіть hooks.internal.entries.session-memory.llmSlug: true, щоб генерувати описові slug-и назв файлів за допомогою налаштованої моделі. Потрібно, щоб було налаштовано workspace.dir.
Конфігурація bootstrap-extra-files
AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).
Подробиці command-logger
Записує кожну slash-команду в~/.openclaw/logs/commands.log.
Подробиці compaction-notifier
Надсилає короткі статусні повідомлення в поточну розмову, коли OpenClaw починає й завершує ущільнення транскрипта сесії. Це робить довгі ходи менш заплутаними на чат-поверхнях, оскільки користувач бачить, що асистент підсумовує контекст і продовжить після compaction.Подробиці boot-md
ЗапускаєBOOT.md з активної робочої області, коли gateway стартує.
Plugin-хуки
Plugins можуть реєструвати типізовані хуки через Plugin SDK для глибшої інтеграції: перехоплення викликів інструментів, змінення prompts, керування потоком повідомлень тощо. Використовуйте plugin-хуки, коли вам потрібніbefore_tool_call, before_agent_reply, before_install або інші хуки життєвого циклу всередині процесу.
Повний довідник plugin-хуків див. у Plugin-хуки.
Конфігурація
Застарілий формат конфігурації масиву
hooks.internal.handlers досі підтримується для зворотної сумісності, але нові хуки мають використовувати систему на основі виявлення.Довідник CLI
Найкращі практики
- Тримайте обробники швидкими. Хуки виконуються під час обробки команд. Запускайте важку роботу у режимі «запустити й забути» за допомогою
void processInBackground(event). - Обробляйте помилки коректно. Обгортайте ризиковані операції в try/catch; не викидайте винятки, щоб інші обробники могли виконатися.
- Фільтруйте події рано. Одразу повертайтеся, якщо тип/дія події не є релевантними.
- Використовуйте конкретні ключі подій. Надавайте перевагу
"events": ["command:new"]замість"events": ["command"], щоб зменшити накладні витрати.
Усунення несправностей
Хук не виявлено
Хук не придатний
Хук не виконується
- Переконайтеся, що хук увімкнено:
openclaw hooks list - Перезапустіть процес Gateway, щоб хуки перезавантажилися.
- Перевірте журнали Gateway:
./scripts/clawlog.sh | grep hook
Пов’язане
- Довідник CLI: хуки
- Webhooks
- Plugin-хуки — внутрішньопроцесні хуки життєвого циклу Plugin
- Конфігурація