Skip to main content

Hooki

Hooki zapewniają rozszerzalny system sterowany zdarzeniami do automatyzacji działań w odpowiedzi na polecenia agenta i zdarzenia. Hooki są automatycznie wykrywane z katalogów i mogą być zarządzane za pomocą poleceń CLI, podobnie jak Skills w OpenClaw.

Orientacja

Hooki to małe skrypty uruchamiane, gdy coś się wydarzy. Istnieją dwa rodzaje:
  • Hooki (ta strona): uruchamiane wewnątrz Gateway, gdy występują zdarzenia agenta, takie jak /new, /reset, /stop lub zdarzenia cyklu życia.
  • Webhooki: zewnętrzne webhooki HTTP, które pozwalają innym systemom wyzwalać działania w OpenClaw. Zobacz Webhook Hooks lub użyj openclaw webhooks dla poleceń pomocniczych Gmail.
Hooki mogą być także dołączane do wtyczek; zobacz Plugins. Typowe zastosowania:
  • Zapisywanie migawki pamięci przy resetowaniu sesji
  • Prowadzenie śladu audytowego poleceń na potrzeby rozwiązywania problemów lub zgodności
  • Wyzwalanie dalszej automatyzacji przy rozpoczęciu lub zakończeniu sesji
  • Zapisywanie plików w obszarze roboczym agenta lub wywoływanie zewnętrznych API po wystąpieniu zdarzeń
Jeśli potrafisz napisać małą funkcję w TypeScript, możesz napisać hook. Hooki są wykrywane automatycznie, a ich włączanie lub wyłączanie odbywa się przez CLI.

Przegląd

System hooków umożliwia:
  • Zapisywanie kontekstu sesji do pamięci po wydaniu /new
  • Rejestrowanie wszystkich poleceń do audytu
  • Wyzwalanie niestandardowych automatyzacji przy zdarzeniach cyklu życia agenta
  • Rozszerzanie zachowania OpenClaw bez modyfikowania kodu rdzenia

Pierwsze kroki

Dołączone hooki

OpenClaw zawiera cztery dołączone hooki, które są automatycznie wykrywane:
  • 💾 session-memory: zapisuje kontekst sesji do obszaru roboczego agenta (domyślnie ~/.openclaw/workspace/memory/) po wydaniu /new
  • Zamienia wstrzykniętą treść SOUL.md na SOUL_EVIL.md podczas okna czyszczenia lub losowo.
  • 📝 command-logger: rejestruje wszystkie zdarzenia poleceń do ~/.openclaw/logs/commands.log
  • 🚀 boot-md: uruchamia BOOT.md przy starcie gateway (wymaga włączonych hooków wewnętrznych)
Wyświetl dostępne hooki:
Włącz hook:
Sprawdź status hooka:
Uzyskaj szczegółowe informacje:

Onboarding

Podczas onboardingu (openclaw onboard) zostaniesz poproszony o włączenie zalecanych hooków. Kreator automatycznie wykrywa kwalifikujące się hooki i prezentuje je do wyboru.

Wykrywanie hooków

Hooki są automatycznie wykrywane z trzech katalogów (w kolejności priorytetu):
  1. Hooki obszaru roboczego: <workspace>/hooks/ (na agenta, najwyższy priorytet)
  2. Hooki zarządzane: ~/.openclaw/hooks/ (instalowane przez użytkownika, współdzielone między obszarami roboczymi)
  3. Hooki dołączone: <openclaw>/dist/hooks/bundled/ (dostarczane z OpenClaw)
Katalogi hooków zarządzanych mogą być pojedynczym hookiem lub pakietem hooków (katalog pakietu). Każdy hook jest katalogiem zawierającym:

Pakiety hooków (npm/archiwa)

Pakiety hooków to standardowe pakiety npm, które eksportują jeden lub więcej hooków poprzez openclaw.hooks w package.json. Instaluj je poleceniem:
Specyfikacje Npm są dostępne wyłącznie z rejestru (nazwa pakietu + opcjonalna wersja/tag). Specyfikacje Git/URL/file są odrzucane. Przykład package.json:
Każdy wpis wskazuje na katalog hooka zawierający HOOK.md oraz handler.ts (lub index.ts). Pakiety hooków mogą dostarczać zależności; zostaną one zainstalowane w ~/.openclaw/hooks/<id>. Uwaga dotycząca bezpieczeństwa: openclaw hooks install instaluje zależności za pomocą npm install --ignore-scripts (bez skryptów cyklu życia). Utrzymuj drzewa zależności pakietów hooków jako „pure JS/TS” i unikaj pakietów, które polegają na kompilacji w postinstall.

Struktura hooka

Format HOOK.md

Plik HOOK.md zawiera metadane w YAML frontmatter oraz dokumentację Markdown:

Pola metadanych

Obiekt metadata.openclaw obsługuje:
  • emoji: emoji wyświetlane w CLI (np. "💾")
  • events: tablica zdarzeń do nasłuchiwania (np. ["command:new", "command:reset"])
  • export: nazwana eksportowana funkcja do użycia (domyślnie "default")
  • homepage: URL dokumentacji
  • requires: opcjonalne wymagania
    • bins: wymagane binaria w PATH (np. ["git", "node"])
    • anyBins: co najmniej jedno z tych binariów musi być obecne
    • env: wymagane zmienne środowiskowe
    • config: wymagane ścieżki konfiguracji (np. ["workspace.dir"])
    • os: wymagane platformy (np. ["darwin", "linux"])
  • always: pominięcie sprawdzania kwalifikowalności (boolean)
  • install: metody instalacji (dla dołączonych hooków: [{"id":"bundled","kind":"bundled"}])

Implementacja obsługi

Plik handler.ts eksportuje funkcję HookHandler:

Kontekst zdarzenia

Każde zdarzenie zawiera:

Typy zdarzeń

Zdarzenia poleceń

Wyzwalane, gdy wydawane są polecenia agenta:
  • command: wszystkie zdarzenia poleceń (nasłuch ogólny)
  • command:new: gdy wydane zostaje polecenie /new
  • command:reset: gdy wydane zostaje polecenie /reset
  • command:stop: gdy wydane zostaje polecenie /stop

Zdarzenia agenta

  • agent:bootstrap: przed wstrzyknięciem plików bootstrap obszaru roboczego (hooki mogą modyfikować context.bootstrapFiles)

Zdarzenia Gateway

Wyzwalane przy starcie gateway:
  • gateway:startup: po uruchomieniu kanałów i załadowaniu hooków

Hooki wyników narzędzi (API wtyczek)

Te hooki nie są nasłuchiwaczami strumienia zdarzeń; pozwalają wtyczkom synchronicznie modyfikować wyniki narzędzi, zanim OpenClaw je zapisze.
  • tool_result_persist: przekształca wyniki narzędzi przed zapisaniem do transkrypcji sesji. Musi być synchroniczne; zwróć zaktualizowany ładunek wyniku narzędzia lub undefined, aby pozostawić bez zmian. Zobacz Agent Loop.

Przyszłe zdarzenia

Planowane typy zdarzeń:
  • session:start: gdy rozpoczyna się nowa sesja
  • session:end: gdy sesja się kończy
  • agent:error: gdy agent napotyka błąd
  • message:sent: gdy wysyłana jest wiadomość
  • message:received: gdy wiadomość jest odbierana

Tworzenie niestandardowych hooków

1. Wybierz lokalizację

  • Hooki obszaru roboczego (<workspace>/hooks/): na agenta, najwyższy priorytet
  • Hooki zarządzane (~/.openclaw/hooks/): współdzielone między obszarami roboczymi

2. Utwórz strukturę katalogów

3. Utwórz HOOK.md

4. Utwórz handler.ts

5. Włącz i przetestuj

Konfiguracja

Nowy format konfiguracji (zalecany)

Konfiguracja per hook

Hooki mogą mieć niestandardową konfigurację:

Dodatkowe katalogi

Ładowanie hooków z dodatkowych katalogów:

Starszy format konfiguracji (nadal wspierany)

Stary format konfiguracji nadal działa ze względu na zgodność wsteczną:
Uwaga: module musi być ścieżką względną względem workspace. Ścieżki bezwzględne i wyjście poza workspace są odrzucane. Migracja: w przypadku nowych hooków używaj nowego systemu opartego na wykrywaniu. Starsze procedury obsługi są ładowane po hookach opartych na katalogach.

Polecenia CLI

Lista hooków

Informacje o hooku

Sprawdzenie kwalifikowalności

Włączanie/wyłączanie

Referencja dołączonych hooków

session-memory

Zapisuje kontekst sesji do pamięci po wydaniu /new. Zdarzenia: command:new 😈 soul-evil: zamienia wstrzykniętą treść SOUL.md na SOUL_EVIL.md podczas okna czyszczenia lub losowo Wyjście: <workspace>/memory/YYYY-MM-DD-slug.md (domyślnie ~/.openclaw/workspace) Co robi:
  1. Używa wpisu sesji sprzed resetu do zlokalizowania właściwej transkrypcji
  2. Wyodrębnia ostatnie 15 linii rozmowy
  3. Używa LLM do wygenerowania opisowego sluga nazwy pliku
  4. Zapisuje metadane sesji do datowanego pliku pamięci
Przykładowe wyjście:
Przykłady nazw plików:
  • 2026-01-16-vendor-pitch.md
  • 2026-01-16-api-design.md
  • 2026-01-16-1430.md (zapasowy znacznik czasu, jeśli generowanie sluga się nie powiedzie)
Włącz:

bootstrap-extra-files

Wstrzykuje dodatkowe pliki bootstrap (na przykład lokalne w monorepo AGENTS.md / TOOLS.md) podczas agent:bootstrap. Zdarzenia: agent:bootstrap Wymagania: musi być skonfigurowane workspace.dir Wyjście: brak zapisywanych plików; zamiany odbywają się wyłącznie w pamięci. Konfiguracja:
Dokumentacja: SOUL Evil Hook
  • Ścieżki są rozwiązywane względem workspace.
  • Pliki muszą pozostawać w obrębie workspace (sprawdzane przez realpath).
  • Ładowane są tylko rozpoznane bazowe nazwy plików bootstrap.
  • Zachowana jest lista dozwolonych subagentów (AGENTS.md i TOOLS.md tylko).
Włącz:

command-logger

Rejestruje wszystkie zdarzenia poleceń do scentralizowanego pliku audytu. Zdarzenia: command Wymagania: brak Wyjście: ~/.openclaw/logs/commands.log Co robi:
  1. Przechwytuje szczegóły zdarzeń (akcja polecenia, znacznik czasu, klucz sesji, identyfikator nadawcy, źródło)
  2. Dopisuje do pliku logu w formacie JSONL
  3. Działa cicho w tle
Przykładowe wpisy logu:
Podgląd logów:
Włącz:

boot-md

Uruchamia BOOT.md przy starcie gateway (po uruchomieniu kanałów). Aby to działało, muszą być włączone hooki wewnętrzne. Zdarzenia: gateway:startup Wymagania: musi być skonfigurowane workspace.dir Co robi:
  1. Odczytuje BOOT.md z obszaru roboczego
  2. Uruchamia instrukcje przez runner agenta
  3. Wysyła wszelkie wymagane wiadomości wychodzące przez narzędzie wiadomości
Włącz:

Najlepsze praktyki

Utrzymuj szybkie procedury obsługi

Hooki działają podczas przetwarzania poleceń. Utrzymuj je lekkie:

Obsługa błędów gracyjnie

Zawsze opakowuj ryzykowne operacje:

Wcześnie filtruj zdarzenia

Zwróć wcześniej, jeśli zdarzenie nie jest istotne:

Używaj konkretnych kluczy zdarzeń

Jeśli to możliwe, określaj dokładne zdarzenia w metadanych:
Zamiast:

Debugowanie

Włącz logowanie hooków

Gateway loguje ładowanie hooków przy starcie:

Sprawdź wykrywanie

Wyświetl wszystkie wykryte hooki:

Sprawdź rejestrację

W procedurze obsługi zaloguj, gdy jest wywoływana:

Zweryfikuj kwalifikowalność

Sprawdź, dlaczego hook nie jest kwalifikowalny:
W wyjściu szukaj brakujących wymagań.

Testowanie

Logi Gateway

Monitoruj logi gateway, aby zobaczyć wykonywanie hooków:

Testuj hooki bezpośrednio

Testuj swoje procedury obsługi w izolacji:

Architektura

Główne komponenty

  • src/hooks/types.ts: definicje typów
  • src/hooks/workspace.ts: skanowanie katalogów i ładowanie
  • src/hooks/frontmatter.ts: parsowanie metadanych HOOK.md
  • src/hooks/config.ts: sprawdzanie kwalifikowalności
  • src/hooks/hooks-status.ts: raportowanie statusu
  • src/hooks/loader.ts: dynamiczny loader modułów
  • src/cli/hooks-cli.ts: polecenia CLI
  • src/gateway/server-startup.ts: ładuje hooki przy starcie gateway
  • src/auto-reply/reply/commands-core.ts: wyzwala zdarzenia poleceń

Przepływ wykrywania

Przepływ zdarzeń

Rozwiązywanie problemów

Hook nie został wykryty

  1. Sprawdź strukturę katalogów:
  2. Zweryfikuj format HOOK.md:
  3. Wyświetl wszystkie wykryte hooki:

Hook nie jest wykonywany

Sprawdź wymagania:
Szukaj brakujących:
  • Binaria (sprawdź PATH)
  • Zmienne środowiskowe
  • Wartości konfiguracji
  • Zgodność z systemem operacyjnym

Hook niekwalifikowalny

  1. Sprawdź, czy hook jest włączony:
  2. Zrestartuj proces gateway, aby hooki zostały ponownie załadowane.
  3. Sprawdź logi gateway pod kątem błędów:

Błędy obsługi

Sprawdź błędy TypeScript/importów:

Przewodnik migracji

Z konfiguracji starszej do wykrywania

Przed:
Po:
  1. Utwórz katalog hooka:
  2. Utwórz HOOK.md:
  3. Zaktualizuj konfigurację:
  4. Zweryfikuj i zrestartuj proces gateway:
Korzyści z migracji:
  • Automatyczne wykrywanie
  • Zarządzanie przez CLI
  • Sprawdzanie kwalifikowalności
  • Lepsza dokumentacja
  • Spójna struktura

Zobacz także