Hooki

Hooki to małe skrypty uruchamiane wewnątrz Gateway po wystąpieniu zdarzeń agenta: poleceń takich jak /new, /reset, /stop, Compaction sesji, zdarzeń cyklu życia Gateway oraz przepływu wiadomości. Są wykrywane w katalogach i zarządzane za pomocą openclaw hooks. Gateway ładuje wewnętrzne hooki dopiero po ich włączeniu lub skonfigurowaniu co najmniej jednego wpisu hooka, pakietu hooków, starszego mechanizmu obsługi albo dodatkowego katalogu hooków.

W OpenClaw istnieją dwa rodzaje hooków:

• Wewnętrzne hooki (ta strona): działają wewnątrz Gateway po wystąpieniu zdarzeń agenta.
• Webhooki: zewnętrzne punkty końcowe HTTP, które umożliwiają innym systemom uruchamianie zadań w OpenClaw. Zobacz Webhooki.

Hooki mogą być również dołączane do pluginów. openclaw hooks list wyświetla zarówno samodzielne hooki, jak i hooki zarządzane przez pluginy (wyświetlane jako plugin:<id>).

Wybór odpowiedniego mechanizmu rozszerzeń

OpenClaw udostępnia kilka podobnych mechanizmów rozszerzeń, które rozwiązują różne problemy:

Używaj wewnętrznych hooków, gdy potrzebujesz automatyzacji działającej jak mała zainstalowana integracja. Używaj typowanych hooków pluginów, gdy potrzebujesz kontroli nad cyklem życia środowiska uruchomieniowego.

Szybki start

# Wyświetl dostępne hookiopenclaw hooks list # Włącz hookopenclaw hooks enable session-memory # Sprawdź stan hookówopenclaw hooks check # Pobierz szczegółowe informacjeopenclaw hooks info session-memory

Typy zdarzeń

Hooki subskrybują określony klucz z tej tabeli albo samą nazwę rodziny (command, session, agent, gateway, message), aby otrzymywać wszystkie akcje z tej rodziny. Rdzeń OpenClaw nie emituje żadnych innych zdarzeń, więc każda inna nazwa jest niemal zawsze literówką, przez którą hook pozostaje bezczynny bez żadnego komunikatu (może go uruchomić tylko plugin emitujący niestandardowe zdarzenie). Mechanizm ładowania hooków rejestruje ostrzeżenie dla takich nazw (na przykład command:nwe), a openclaw hooks info <name> je oznacza, dzięki czemu można zdiagnozować hook, który nigdy się nie uruchamia.

Pisanie hooków

Struktura hooka

Każdy hook jest katalogiem zawierającym dwa pliki:

my-hook/├── HOOK.md          # Metadane i dokumentacja└── handler.ts       # Implementacja mechanizmu obsługi

Plik mechanizmu obsługi może mieć nazwę handler.ts, handler.js, index.ts lub index.js.

Format HOOK.md

---name: my-hookdescription: "Krótki opis działania tego hooka"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # Mój hook Tutaj znajduje się szczegółowa dokumentacja.

Pola metadanych (metadata.openclaw):

Implementacja mechanizmu obsługi

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;

Każde zdarzenie zawiera: type, action, sessionKey, timestamp, messages oraz context (dane właściwe dla danego zdarzenia). Konteksty typowanych hooków pluginów dla hooków agenta i narzędzi mogą również zawierać trace — przeznaczony tylko do odczytu, zgodny z W3C kontekst śledzenia diagnostycznego, który pluginy mogą przekazywać do ustrukturyzowanych dzienników w celu korelacji OTEL.

Ciągi znaków dodane do event.messages są dostarczane z powrotem do czatu tylko dla command:new i command:reset (kierowane jako odpowiedź do rozmowy źródłowej) oraz dla session:compact:before / session:compact:after (wysyłane jako powiadomienia o stanie Compaction). Wszystkie pozostałe zdarzenia, w tym command:stop, message:*, agent:bootstrap, session:patch i gateway:*, ignorują dodane wiadomości.

Najważniejsze elementy kontekstu zdarzeń

Zdarzenia poleceń (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.senderId, context.workspaceDir, context.cfg.

Zdarzenia poleceń (command:stop): context.sessionEntry, context.sessionId, context.commandSource, context.senderId.

Zdarzenia wiadomości (message:received): context.from, context.content, context.channelId, context.metadata (dane właściwe dla dostawcy, w tym senderId, senderName, guildId). context.content w przypadku wiadomości przypominających polecenia preferuje niepustą treść polecenia, a następnie używa nieprzetworzonej treści wiadomości przychodzącej lub treści ogólnej; nie zawiera wzbogaceń przeznaczonych wyłącznie dla agenta, takich jak historia wątku lub podsumowania odnośników.

Zdarzenia wiadomości (message:sent): context.to, context.content, context.success, context.channelId oraz context.error, gdy wysyłanie się nie powiodło.

Zdarzenia wiadomości (message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath.

Zdarzenia wiadomości (message:preprocessed): context.bodyForAgent (ostateczna wzbogacona treść), context.from, context.channelId.

Zdarzenia inicjalizacji (agent:bootstrap): context.bootstrapFiles (modyfikowalna tablica), context.agentId.

Zdarzenia aktualizacji sesji (session:patch): context.sessionEntry, context.patch (tylko zmienione pola), context.cfg. Zdarzenia aktualizacji mogą wyzwalać tylko klienci uprzywilejowani; kontekst jest kopią, dlatego mechanizmy obsługi nie mogą modyfikować aktywnego wpisu sesji.

Zdarzenia Compaction: session:compact:before zawiera messageCount, tokenCount. session:compact:after dodaje compactedCount, summaryLength, tokensBefore, tokensAfter.

command:stop obserwuje wydanie przez użytkownika polecenia /stop; dotyczy anulowania i cyklu życia polecenia, a nie bramki finalizacji agenta. Pluginy, które muszą sprawdzić naturalną odpowiedź końcową i poprosić agenta o jeszcze jeden przebieg, powinny zamiast tego używać typowanego hooka pluginu before_agent_finalize. Zobacz Hooki pluginów.

Zdarzenia cyklu życia Gateway: gateway:shutdown zawiera reason i restartExpectedMs oraz jest wyzwalane, gdy rozpoczyna się zamykanie Gateway. gateway:pre-restart zawiera ten sam kontekst, ale jest wyzwalane tylko wtedy, gdy zamykanie stanowi część oczekiwanego ponownego uruchomienia i podano skończoną wartość restartExpectedMs. Podczas zamykania oczekiwanie na każdy hook cyklu życia odbywa się w miarę możliwości i ma ograniczony czas, dzięki czemu zamykanie jest kontynuowane, jeśli mechanizm obsługi przestanie odpowiadać. Domyślny limit oczekiwania wynosi 5 sekund dla gateway:shutdown i 10 sekund dla gateway:pre-restart.

Użyj gateway:pre-restart do wysyłania krótkich powiadomień o ponownym uruchomieniu, gdy kanały są nadal dostępne:

  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.`,  ]);}

Pomiędzy zdarzeniem gateway:shutdown (lub gateway:pre-restart) a pozostałą częścią sekwencji zamykania Gateway wyzwala również typowany hook pluginu session_end dla każdej sesji, która pozostawała aktywna w chwili zatrzymania procesu. Wartość reason tego zdarzenia to shutdown w przypadku zwykłego zatrzymania sygnałem SIGTERM/SIGINT oraz restart, gdy zamknięcie zaplanowano jako część oczekiwanego ponownego uruchomienia. To opróżnianie ma ograniczony czas, dzięki czemu powolny mechanizm obsługi session_end nie może zablokować zakończenia procesu, a sesje, które zostały już sfinalizowane przez zastąpienie, zresetowanie, usunięcie lub Compaction, są pomijane, aby uniknąć podwójnego wyzwolenia.

Wykrywanie hooków

Hooki są wykrywane z czterech źródeł:

1. Dołączone hooki: dostarczane z OpenClaw
2. Hooki pluginów: dołączone do zainstalowanych pluginów; mogą zastępować dołączone hooki o tej samej nazwie
3. Zarządzane hooki: ~/.openclaw/hooks/ (instalowane przez użytkownika i współdzielone między obszarami roboczymi); mogą zastępować dołączone hooki i hooki pluginów. Dodatkowe katalogi z hooks.internal.load.extraDirs mają ten sam priorytet.
4. Hooki obszaru roboczego: <workspace>/hooks/ (dla poszczególnych agentów, domyślnie wyłączone do czasu jawnego włączenia)

Hooki obszaru roboczego mogą dodawać nowe nazwy hooków, ale nie mogą zastępować dołączonych, zarządzanych ani udostępnianych przez pluginy hooków o tej samej nazwie.

Gateway pomija wykrywanie wewnętrznych hooków podczas uruchamiania, dopóki nie zostaną one skonfigurowane. Włącz dołączony lub zarządzany hook za pomocą openclaw hooks enable <name>, zainstaluj pakiet hooków albo ustaw hooks.internal.enabled=true, aby wyrazić zgodę. Po włączeniu jednego nazwanego hooka Gateway ładuje tylko jego mechanizm obsługi; hooks.internal.enabled=true, dodatkowe katalogi hooków i starsze mechanizmy obsługi włączają szerokie wykrywanie.

Pakiety hooków

Pakiety hooków to pakiety npm, które eksportują hooki za pomocą openclaw.hooks w pliku package.json. Zainstaluj je za pomocą:

openclaw plugins install <path-or-spec>

Specyfikacje npm mogą wskazywać wyłącznie rejestr (nazwa pakietu oraz opcjonalnie dokładna wersja lub dist-tag). Specyfikacje Git/URL/plik oraz zakresy semver są odrzucane. Starsze polecenia openclaw hooks install i openclaw hooks update są przestarzałymi aliasami poleceń openclaw plugins install / openclaw plugins update.

Dołączone hooki

Włącz dowolny dołączony hook:

openclaw hooks enable <hook-name>

Szczegóły session-memory

Wyodrębnia ostatnie wiadomości użytkownika i asystenta (domyślnie 15, wartość konfigurowalna za pomocą hooks.internal.entries.session-memory.messages) i zapisuje je w <workspace>/memory/YYYY-MM-DD-HHMM.md, używając lokalnej daty hosta. Przechwytywanie pamięci odbywa się w tle, dzięki czemu odczyty transkrypcji ani opcjonalne generowanie uproszczonej nazwy nie opóźniają potwierdzeń /new i /reset. Ustaw hooks.internal.entries.session-memory.llmSlug: true, aby generować opisowe uproszczone nazwy plików, a opcjonalnie ustaw hooks.internal.entries.session-memory.model na skonfigurowany alias, taki jak sonnet, sam identyfikator modelu u domyślnego dostawcy agenta lub odwołanie provider/model. Jeśli pominięto model, generowanie uproszczonej nazwy używa domyślnego modelu agenta, a gdy jest on niedostępny, stosuje uproszczone nazwy ze znacznikiem czasu. Wymaga skonfigurowania workspace.dir.

Konfiguracja bootstrap-extra-files

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

patterns i files są akceptowane jako aliasy paths. Ścieżki są rozwiązywane względem obszaru roboczego i muszą pozostawać w jego obrębie. Ładowane są wyłącznie rozpoznawane nazwy bazowe plików rozruchowych (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).

Szczegóły command-logger

Rejestruje każde polecenie z ukośnikiem jako wiersz JSON (znacznik czasu, działanie, klucz sesji, identyfikator nadawcy, źródło) w ~/.openclaw/logs/commands.log.

Szczegóły compaction-notifier

Wysyła krótkie komunikaty o stanie do bieżącej rozmowy, gdy OpenClaw rozpoczyna i kończy Compaction transkrypcji sesji. Dzięki temu długie tury są mniej dezorientujące w interfejsach czatu, ponieważ użytkownik widzi, że asystent podsumowuje kontekst i będzie kontynuował po zakończeniu Compaction.

Szczegóły boot-md

Uruchamia BOOT.md podczas uruchamiania Gateway dla każdego skonfigurowanego zakresu agenta, jeśli plik istnieje w rozwiązanym obszarze roboczym tego agenta.

Hooki Pluginów

Pluginy mogą rejestrować typowane hooki za pośrednictwem Plugin SDK w celu głębszej integracji: przechwytywania wywołań narzędzi, modyfikowania promptów, sterowania przepływem wiadomości i nie tylko. Używaj hooków Pluginów, gdy potrzebujesz before_tool_call, before_agent_reply, before_install lub innych hooków cyklu życia działających wewnątrz procesu.

Wewnętrzne hooki zarządzane przez Pluginy działają inaczej: uczestniczą w opisanym na tej stronie ogólnym systemie zdarzeń poleceń i cyklu życia oraz pojawiają się w openclaw hooks list jako plugin:<id>. Używaj ich do efektów ubocznych i zapewniania zgodności z pakietami hooków, a nie jako uporządkowanego oprogramowania pośredniczącego ani bram zasad.

Pełną dokumentację hooków Pluginów zawiera strona Hooki Pluginów.

Konfiguracja

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

Wartości środowiskowe poszczególnych hooków spełniają warunki kwalifikacji requires.env danego hooka (wraz ze środowiskiem procesu), a procedury obsługi mogą je odczytać z wpisu konfiguracji hooka:

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

Dodatkowe katalogi hooków:

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

Dokumentacja CLI

# Wyświetl wszystkie hooki (dodaj --eligible, --verbose lub --json)openclaw hooks list # Wyświetl szczegółowe informacje o hookuopenclaw hooks info <hook-name> # Wyświetl podsumowanie kwalifikacjiopenclaw hooks check # Włącz/wyłączopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

Dobre praktyki

• Dbaj o szybkość procedur obsługi. Hooki działają podczas przetwarzania poleceń. Uruchamiaj ciężkie zadania w tle bez oczekiwania na ich wynik za pomocą void processInBackground(event).
• Poprawnie obsługuj błędy. Otaczaj ryzykowne operacje blokiem try/catch; nie zgłaszaj wyjątków, aby inne procedury obsługi mogły działać.
• Filtruj zdarzenia wcześnie. Natychmiast zakończ działanie, jeśli typ lub działanie zdarzenia nie jest istotne.
• Używaj szczegółowych kluczy zdarzeń. Preferuj "events": ["command:new"] zamiast "events": ["command"], aby zmniejszyć narzut.

Rozwiązywanie problemów

Hook nie został wykryty

# Sprawdź strukturę kataloguls -la ~/.openclaw/hooks/my-hook/# Powinny być widoczne: HOOK.md, handler.ts # Wyświetl wszystkie wykryte hookiopenclaw hooks list

Hook nie spełnia warunków

openclaw hooks info my-hook

Sprawdź brakujące pliki wykonywalne (PATH), zmienne środowiskowe, wartości konfiguracji lub zgodność z systemem operacyjnym.

Hook nie jest wykonywany

1. Sprawdź, czy hook jest włączony: openclaw hooks list
2. Uruchom ponownie proces Gateway, aby ponownie załadować hooki.
3. Sprawdź dzienniki Gateway: openclaw logs --follow | grep -i hook

Powiązane materiały

• Dokumentacja CLI: hooki
• Webhooki
• Hooki Pluginów — hooki cyklu życia Pluginów działające wewnątrz procesu
• Konfiguracja