// dokumentacja openclaw

Hooki w OpenClaw — zdarzenia i skrypty automatyzacji

Czym sa hooki w OpenClaw?

Hooki to male skrypty, ktore uruchamiaja sie automatycznie, gdy wewnatrz Gateway nastapi okreslone zdarzenie. System automatycznego wykrywania (discovery) laduje je z wielu lokalizacji. Wyrozniamy dwa podstawowe typy: hooki wewnetrzne (uruchamiane w Gateway na zdarzenia agenta) oraz webhooki (zewnetrzne endpointy HTTP).

Typy zdarzen

Dokumentacja wymienia 13 zdarzen, na ktore moga reagowac hooki. Oto najwazniejsze z nich:

  • command:new — nowe polecenie zostalo wydane agentowi.
  • command:reset — sesja agenta zostala zresetowana.
  • session:compact:before — tuż przed kompaktowaniem sesji.
  • message:received — agent otrzymal nowa wiadomosc.
  • message:sent — agent wyslal wiadomosc.
  • agent:bootstrap — agent uruchamia sie po raz pierwszy w sesji.

Kazde zdarzenie posiada specyficzne warunki wyzwolenia, dzieki czemu mozesz precyzyjnie kontrolowac, kiedy skrypt sie uruchomi.

Struktura hooka

Kazdy hook wymaga katalogu zawierajacego dwa pliki:

  • HOOK.md — metadane i dokumentacja hooka. Zawiera pola takie jak: emoji, tablica zdarzen (events), wymagania systemowe (os) i specyfikacje zaleznosci.
  • handler.ts — implementacja logiki. To asynchroniczna funkcja otrzymujaca obiekt zdarzenia.

Obiekt zdarzenia przekazywany do handlera zawiera nastepujace pola:

{
  type: string,        // typ zdarzenia, np. "message:received"
  action: string,      // akcja szczegolowa
  sessionKey: string,  // klucz sesji
  timestamp: number,   // znacznik czasu
  messages: array,     // tablica wiadomosci
  context: object      // kontekst dodatkowy
}

System wykrywania (discovery)

Hooki sa ladowane z czterech lokalizacji, w kolejnosci rosnacego priorytetu:

  • Hooki wbudowane — dostarczane z OpenClaw.
  • Hooki wtyczek (plugins) — instalowane z zewnetrznych pakietow.
  • Hooki zarzadzane — w katalogu ~/.openclaw/hooks/.
  • Hooki workspace — specyficzne dla danego projektu, najwyzszy priorytet.

Hooki o wyzszym priorytecie nadpisuja te o nizszym, jesli dotycza tego samego zdarzenia.

Wbudowane hooki

OpenClaw dostarcza cztery gotowe hooki:

  • session-memory — automatyczne zapisywanie i odtwarzanie pamieci sesji.
  • bootstrap-extra-files — wstrzykiwanie dodatkowych plikow przy starcie sesji.
  • command-logger — logowanie wszystkich komend wydanych agentowi.
  • boot-md — ladowanie plikow Markdown przy bootstrapie.

Konfiguracja hookow

Ustawienia hookow przechowywane sa w formacie JSON i obsluguja:

  • Stan enabled / disabled dla kazdego hooka.
  • Zmienne srodowiskowe specyficzne dla poszczegolnych hookow.
  • Dodatkowe sciezki katalogow do przeszukiwania hookow.

Komendy CLI

# Lista zainstalowanych hookow
openclaw hooks list

# Szczegoly hooka
openclaw hooks info <hookName>

# Sprawdz poprawnosc hookow
openclaw hooks check

# Wlacz/wylacz hooka
openclaw hooks enable <hookName>
openclaw hooks disable <hookName>

Najlepsze praktyki

  • Szybkosc wykonania — hooki powinny dzialac jak najszybciej. Ciezkie operacje deleguj do zadan w tle.
  • Obsluga bledow — zawsze obsluguj wyjatki wewnatrz handlera, aby blad w hooku nie zaburzyl pracy agenta.
  • Wczesne filtrowanie — sprawdzaj typ zdarzenia na poczatku handlera i wyjdz wczesnie, jesli zdarzenie Cie nie dotyczy.
  • Specyficzne klucze zdarzen — subskrybuj tylko te zdarzenia, ktore rzeczywiscie potrzebujesz, zamiast nasluchiwac na wszystkie.
Wróc do dokumentacji