Hooki Plugin

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Szybki start

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "tool-preflight",
  name: "Tool Preflight",
  register(api) {
    api.on(
      "before_tool_call",
      async (event) => {
        if (event.toolName !== "web_search") {
          return;
        }

        return {
          requireApproval: {
            title: "Run web search",
            description: `Allow search query: ${String(event.params.query ?? "")}`,
            severity: "info",
            timeoutMs: 60_000,
            timeoutBehavior: "deny",
          },
        };
      },
      { priority: 50 },
    );
  },
});

• priority - kolejność handlerów (wyższa wartość działa wcześniej).
• timeoutMs - opcjonalny budżet dla pojedynczego hooka. Gdy jest ustawiony, runner hooków przerywa ten handler po upływie budżetu i przechodzi do następnego, zamiast pozwalać, aby powolna konfiguracja lub praca odtwarzania kontekstu zużywała skonfigurowany dla wywołującego timeout modelu. Pomiń go, aby użyć domyślnego timeoutu obserwacji/decyzji, który runner hooków stosuje ogólnie.

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "timeoutMs": 30000,
          "timeouts": {
            "before_prompt_build": 90000,
            "agent_end": 60000
          }
        }
      }
    }
  }
}

​

Katalog hooków

• before_model_resolve - nadpisz dostawcę lub model, zanim wiadomości sesji zostaną załadowane
• agent_turn_prepare - zużyj zakolejkowane wstrzyknięcia tur pluginu i dodaj kontekst tej samej tury przed hookami promptu
• before_prompt_build - dodaj dynamiczny kontekst lub tekst promptu systemowego przed wywołaniem modelu
• before_agent_start - połączona faza wyłącznie dla zgodności; preferuj dwa hooki powyżej
• before_agent_run - sprawdź finalny prompt i wiadomości sesji przed wysłaniem do modelu oraz opcjonalnie zablokuj uruchomienie
• before_agent_reply - przerwij turę modelu syntetyczną odpowiedzią albo ciszą
• before_agent_finalize - sprawdź naturalną odpowiedź finalną i zażądaj jeszcze jednego przebiegu modelu
• agent_end - obserwuj finalne wiadomości, stan powodzenia i czas trwania uruchomienia
• heartbeat_prompt_contribution - dodaj kontekst tylko dla Heartbeat na potrzeby pluginów monitorów w tle i cyklu życia

• model_call_started / model_call_ended - obserwuj oczyszczone metadane wywołania dostawcy/modelu, timing, wynik oraz ograniczone hashe identyfikatorów żądań bez treści promptu ani odpowiedzi
• llm_input - obserwuj wejście dostawcy (prompt systemowy, prompt, historia)
• llm_output - obserwuj wyjście dostawcy

• before_tool_call - przepisz parametry narzędzia, zablokuj wykonanie albo wymagaj zatwierdzenia
• after_tool_call - obserwuj wyniki narzędzi, błędy i czas trwania
• tool_result_persist - przepisz wiadomość asystenta utworzoną z wyniku narzędzia
• before_message_write - sprawdź albo zablokuj trwający zapis wiadomości (rzadkie)

• inbound_claim - przejmij wiadomość przychodzącą przed routingiem agenta (syntetyczne odpowiedzi)
• message_received - obserwuj treść przychodzącą, nadawcę, wątek i metadane
• message_sending - przepisz treść wychodzącą albo anuluj dostarczenie
• message_sent - obserwuj powodzenie lub niepowodzenie dostarczenia wychodzącego
• before_dispatch - sprawdź albo przepisz wychodzącą dyspozycję przed przekazaniem do kanału
• reply_dispatch - uczestnicz w finalnym potoku dyspozycji odpowiedzi

• session_start / session_end - śledź granice cyklu życia sesji. reason zdarzenia to jedna z wartości: new, reset, idle, daily, compaction, deleted, shutdown, restart albo unknown. Wartości shutdown i restart są emitowane z finalizatora zamykania gateway, gdy proces jest zatrzymywany lub restartowany, a sesje nadal są aktywne, dzięki czemu pluginy niżej w potoku (takie jak magazyny pamięci lub transkryptów) mogą domknąć osierocone wiersze, które inaczej pozostałyby w stanie otwartym między restartami. Finalizator jest ograniczony czasowo, więc powolny plugin nie może blokować SIGTERM/SIGINT.
• before_compaction / after_compaction - obserwuj albo adnotuj cykle Compaction
• before_reset - obserwuj zdarzenia resetowania sesji (/reset, resetowania programowe)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - koordynuj routing subagentów i dostarczanie zakończenia

• gateway_start / gateway_stop - uruchamiaj albo zatrzymuj usługi należące do pluginu razem z Gateway
• cron_changed - obserwuj zmiany cyklu życia Cron należącego do gateway (dodane, zaktualizowane, usunięte, rozpoczęte, zakończone, zaplanowane)
• before_install - sprawdź skany instalacji Skills lub pluginów i opcjonalnie zablokuj

​

Polityka wywołań narzędzi

• event.toolName
• event.params
• opcjonalne event.derivedPaths, zawierające ustalone best-effort po stronie hosta wskazówki ścieżek docelowych dla dobrze znanych kopert narzędzi, takich jak apply_patch; gdy są obecne, te ścieżki mogą być niekompletne albo mogą zawyżać zakres tego, czego narzędzie faktycznie dotknie (na przykład przy zniekształconych lub częściowych danych wejściowych)
• opcjonalne event.runId
• opcjonalne event.toolCallId
• pola kontekstu takie jak ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (ustawiane w uruchomieniach wyzwalanych przez Cron) oraz diagnostyczne ctx.trace

type BeforeToolCallResult = {
  params?: Record<string, unknown>;
  block?: boolean;
  blockReason?: string;
  requireApproval?: {
    title: string;
    description: string;
    severity?: "info" | "warning" | "critical";
    timeoutMs?: number;
    timeoutBehavior?: "allow" | "deny";
    pluginId?: string;
    onResolution?: (
      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
    ) => Promise<void> | void;
  };
};

• block: true jest terminalne i pomija handlery o niższym priorytecie.
• block: false jest traktowane jak brak decyzji.
• params przepisuje parametry narzędzia do wykonania.
• requireApproval wstrzymuje uruchomienie agenta i prosi użytkownika przez zatwierdzenia pluginów. Polecenie /approve może zatwierdzać zarówno zatwierdzenia exec, jak i pluginów.
• block: true o niższym priorytecie nadal może zablokować po tym, jak hook o wyższym priorytecie zażądał zatwierdzenia.
• onResolution otrzymuje rozstrzygniętą decyzję zatwierdzenia - allow-once, allow-always, deny, timeout albo cancelled.

​

Utrwalanie wyników narzędzi

• OpenClaw usuwa toolResult.details przed ponownym odtworzeniem u dostawcy i wejściem Compaction, aby metadane nie stały się kontekstem modelu.
• Utrwalone wpisy sesji zachowują tylko ograniczone details. Zbyt duże details są zastępowane kompaktowym podsumowaniem i persistedDetailsTruncated: true.
• tool_result_persist i before_message_write działają przed finalnym limitem utrwalania. Hooki powinny mimo to utrzymywać zwracane details małe i unikać umieszczania tekstu istotnego dla promptu wyłącznie w details; widoczne dla modelu wyjście narzędzia umieszczaj w content.

​

Hooki promptu i modelu

• before_model_resolve: otrzymuje tylko bieżący prompt i metadane załączników. Zwróć providerOverride albo modelOverride.
• agent_turn_prepare: otrzymuje bieżący prompt, przygotowane wiadomości sesji oraz wszelkie dokładnie-jeden-raz zakolejkowane wstrzyknięcia opróżnione dla tej sesji. Zwróć prependContext albo appendContext.
• before_prompt_build: otrzymuje bieżący prompt i wiadomości sesji. Zwróć prependContext, appendContext, systemPrompt, prependSystemContext albo appendSystemContext.
• heartbeat_prompt_contribution: działa tylko dla tur Heartbeat i zwraca prependContext albo appendContext. Jest przeznaczony dla monitorów w tle, które muszą podsumować bieżący stan bez zmieniania tur zainicjowanych przez użytkownika.

type BeforeAgentFinalizeRetry = {
  instruction: string;
  idempotencyKey?: string;
  maxAttempts?: number;
};

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

​

Rozszerzenia sesji i wstrzyknięcia do następnej tury

​

Hooki wiadomości

• message_received: obserwuj treść przychodzącą, nadawcę, threadId, messageId, senderId, opcjonalną korelację uruchomienia/sesji oraz metadane.
• message_sending: przepisz content albo zwróć { cancel: true }.
• message_sent: obserwuj końcowy sukces lub niepowodzenie.

• message_sending z cancel: true jest terminalne.
• message_sending z cancel: false jest traktowane jako brak decyzji.
• Przepisane content przechodzi dalej do hooków o niższym priorytecie, chyba że późniejszy hook anuluje dostarczenie.
• message_sending może zwrócić cancelReason oraz ograniczone metadata wraz z anulowaniem. Nowe API cyklu życia wiadomości eksponują to jako wyciszony wynik dostarczenia z powodem cancelled_by_message_sending_hook; starsze bezpośrednie dostarczanie nadal zwraca pustą tablicę wyników dla kompatybilności.
• message_sent służy wyłącznie do obserwacji. Błędy handlerów są logowane i nie zmieniają wyniku dostarczenia.

​

Hooki instalacji

​

Cykl życia Gateway

​

Nadchodzące wycofania

• Koperty kanałów w tekście jawnym w handlerach inbound_claim i message_received. Czytaj BodyForAgent oraz ustrukturyzowane bloki kontekstu użytkownika zamiast parsować płaski tekst koperty. Zobacz Koperty kanałów w tekście jawnym → BodyForAgent.
• before_agent_start pozostaje dla kompatybilności. Nowe pluginy powinny używać before_model_resolve i before_prompt_build zamiast połączonej fazy.
• onResolution w before_tool_call używa teraz typowanej unii PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) zamiast swobodnego string.

​

Powiązane

• Migracja Plugin SDK - aktywne wycofania i harmonogram usunięcia
• Tworzenie pluginów
• Przegląd Plugin SDK
• Punkty wejścia pluginów
• Hooki wewnętrzne
• Wewnętrzne szczegóły architektury pluginów