Хуки

Хуки — це невеликі скрипти, які запускаються, коли щось відбувається всередині Gateway. Їх можна виявляти з каталогів і переглядати за допомогою openclaw hooks. Gateway завантажує внутрішні хуки лише після того, як ви ввімкнете хуки або налаштуєте принаймні один запис хука, пакет хуків, застарілий обробник чи додатковий каталог хуків.

В OpenClaw є два типи хуків:

• Внутрішні хуки (ця сторінка): запускаються всередині Gateway, коли спрацьовують події агента, як-от /new, /reset, /stop або події життєвого циклу.
• Webhook-и: зовнішні HTTP-кінцеві точки, які дають іншим системам змогу запускати роботу в OpenClaw. Див. Webhook-и.

Хуки також можуть постачатися всередині плагінів. openclaw hooks list показує як окремі хуки, так і хуки, керовані плагінами.

Виберіть правильну поверхню

OpenClaw має кілька поверхонь розширення, які виглядають схожими, але розв’язують різні задачі:

Використовуйте внутрішні хуки, коли вам потрібна автоматизація, що поводиться як невелика встановлена інтеграція. Використовуйте типізовані хуки плагінів, коли вам потрібен контроль життєвого циклу під час виконання.

Швидкий старт

# List available hooksopenclaw hooks list # Enable a hookopenclaw hooks enable session-memory # Check hook statusopenclaw hooks check # Get detailed informationopenclaw hooks info session-memory

Типи подій

Написання хуків

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

Кожен хук — це каталог із двома файлами:

my-hook/├── HOOK.md          # Metadata + documentation└── handler.ts       # Handler implementation

Формат HOOK.md

---name: my-hookdescription: "Short description of what this hook does"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # My Hook Detailed documentation goes here.

Поля метаданих (metadata.openclaw):

Реалізація обробника

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] New command triggered`);  // Your logic here   // Optionally send a reply on replyable surfaces  event.messages.push("Hook executed!");}; export default handler;

Кожна подія містить: type, action, sessionKey, timestamp, messages (додавайте відповіді сюди лише на поверхнях, що підтримують відповідь) і context (дані, специфічні для події). Контексти хуків агента й інструментальних плагінів також можуть містити trace — діагностичний контекст трасування лише для читання, сумісний із W3C, який плагіни можуть передавати в структуровані журнали для кореляції OTEL.

event.messages автоматично доставляється лише на поверхнях, що підтримують відповідь, як-от command:* і message:received. Події лише життєвого циклу, як-от agent:bootstrap, session:*, gateway:* або message:sent, не мають каналу відповіді й ігнорують додані повідомлення.

Основне про контекст подій

Події команд (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.

Події початкового налаштування (agent:bootstrap): context.bootstrapFiles (змінний масив), context.agentId.

Події латання сесії (session:patch): context.sessionEntry, context.patch (лише змінені поля), context.cfg. Лише привілейовані клієнти можуть запускати події латання.

Події Compaction: session:compact:before містить messageCount, tokenCount. session:compact:after додає compactedCount, summaryLength, tokensBefore, tokensAfter.

command:stop спостерігає, як користувач видає /stop; це життєвий цикл скасування/команди, а не шлюз фіналізації агента. Плагіни, яким потрібно перевірити природну фінальну відповідь і попросити агента виконати ще один прохід, мають використовувати типізований хук плагіна before_agent_finalize натомість. Див. хуки Plugin.

Події життєвого циклу 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 restarting in ~${restartInSeconds}s (${event.context.reason}). Checkpoint now.`,  ]);}

Між подією gateway:shutdown (або gateway:pre-restart) і рештою послідовності завершення роботи gateway також запускає типізований хук плагіна session_end для кожної сесії, яка ще була активною, коли процес зупинився. Значення reason цієї події — shutdown для звичайної зупинки SIGTERM/SIGINT і restart, коли закриття було заплановано як частину очікуваного перезапуску. Це осушення має межу, щоб повільний обробник session_end не міг заблокувати вихід процесу, а сесії, які вже були фіналізовані через replace / reset / delete / compaction, пропускаються, щоб уникнути подвійного спрацювання.

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

Хуки виявляються з цих каталогів у порядку зростання пріоритету перевизначення:

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 підтримують лише registry (назва пакета + необов’язкова точна версія або dist-tag). Специфікації Git/URL/file і діапазони semver відхиляються.

Вбудовані хуки

Увімкніть будь-який вбудований hook:

openclaw hooks enable <hook-name>

подробиці 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

{  "hooks": {    "internal": {      "entries": {        "bootstrap-extra-files": {          "enabled": true,          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]        }      }    }  }}

Шляхи визначаються відносно робочого простору. Завантажуються лише розпізнані базові назви bootstrap (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 hooks

Plugins можуть реєструвати типізовані hooks через Plugin SDK для глибшої інтеграції: перехоплення викликів інструментів, змінення prompts, керування потоком повідомлень тощо. Використовуйте plugin hooks, коли потрібні before_tool_call, before_agent_reply, before_install або інші внутрішньопроцесні hooks життєвого циклу.

Внутрішні hooks, керовані Plugins, відрізняються: вони беруть участь у грубій системі подій команд/життєвого циклу цієї сторінки й відображаються в openclaw hooks list як plugin:<id>. Використовуйте їх для побічних ефектів і сумісності з hook packs, а не для впорядкованого middleware або policy gates.

Повний довідник plugin hooks див. у Plugin hooks.

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

{  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": false }      }    }  }}

Змінні середовища для окремих hooks:

{  "hooks": {    "internal": {      "entries": {        "my-hook": {          "enabled": true,          "env": { "MY_CUSTOM_VAR": "value" }        }      }    }  }}

Додаткові каталоги hooks:

{  "hooks": {    "internal": {      "load": {        "extraDirs": ["/path/to/more/hooks"]      }    }  }}

Довідник CLI

# List all hooks (add --eligible, --verbose, or --json)openclaw hooks list # Show detailed info about a hookopenclaw hooks info <hook-name> # Show eligibility summaryopenclaw hooks check # Enable/disableopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

Найкращі практики

• Тримайте handlers швидкими. Hooks виконуються під час обробки команд. Запускайте важку роботу без очікування результату за допомогою void processInBackground(event).
• Обробляйте помилки коректно. Обгортайте ризиковані операції в try/catch; не кидайте винятки, щоб інші handlers могли виконатися.
• Фільтруйте події рано. Повертайтеся негайно, якщо тип/дія події не релевантні.
• Використовуйте конкретні ключі подій. Надавайте перевагу "events": ["command:new"] замість "events": ["command"], щоб зменшити накладні витрати.

Усунення несправностей

Hook не виявлено

# Verify directory structurels -la ~/.openclaw/hooks/my-hook/# Should show: HOOK.md, handler.ts # List all discovered hooksopenclaw hooks list

Hook не придатний

openclaw hooks info my-hook

Перевірте відсутні binaries (PATH), змінні середовища, значення конфігурації або сумісність з ОС.

Hook не виконується

1. Переконайтеся, що hook увімкнено: openclaw hooks list
2. Перезапустіть процес Gateway, щоб hooks перезавантажилися.
3. Перевірте журнали Gateway: ./scripts/clawlog.sh | grep hook

Пов’язане

• Довідник CLI: hooks
• Webhooks
• Plugin hooks — внутрішньопроцесні hooks життєвого циклу Plugin
• Конфігурація