Plugin-hookfuncties

Documentation Index

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

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

​

Snel aan de slag

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 — handler-volgorde (hoger wordt eerst uitgevoerd).
• timeoutMs — optioneel budget per hook. Wanneer dit is ingesteld, breekt de hook-runner die handler af nadat het budget is verstreken en gaat door met de volgende, in plaats van trage setup of recall-werk de door de aanroeper geconfigureerde model-timeout te laten verbruiken. Laat dit weg om de standaard observatie-/beslissingstime-out te gebruiken die de hook-runner generiek toepast.

​

Hook-catalogus

• before_model_resolve — overschrijf provider of model voordat sessieberichten laden
• agent_turn_prepare — verwerk in de wachtrij geplaatste plugin-turn-injecties en voeg context voor dezelfde beurt toe vóór prompt-hooks
• before_prompt_build — voeg dynamische context of systeemprompttekst toe vóór de modelaanroep
• before_agent_start — gecombineerde fase alleen voor compatibiliteit; geef de voorkeur aan de twee hooks hierboven
• before_agent_reply — beëindig de modelbeurt vroegtijdig met een synthetisch antwoord of stilte
• before_agent_finalize — inspecteer het natuurlijke eindantwoord en vraag één extra modelpassage aan
• agent_end — observeer eindberichten, successtatus en uitvoeringsduur
• heartbeat_prompt_contribution — voeg alleen-Heartbeat-context toe voor achtergrondmonitor- en lifecycle-plugins

• model_call_started / model_call_ended — observeer opgeschoonde provider-/modelaanroepmetadata, timing, uitkomst en begrensde request-id-hashes zonder prompt- of responsinhoud
• llm_input — observeer providerinvoer (systeemprompt, prompt, geschiedenis)
• llm_output — observeer provideruitvoer

• before_tool_call — herschrijf toolparameters, blokkeer uitvoering of vereis goedkeuring
• after_tool_call — observeer toolresultaten, fouten en duur
• tool_result_persist — herschrijf het assistentbericht dat uit een toolresultaat wordt geproduceerd
• before_message_write — inspecteer of blokkeer een lopende berichtschrijfactie (zeldzaam)

• inbound_claim — claim een inkomend bericht vóór agent-routering (synthetische antwoorden)
• message_received — observeer inkomende inhoud, afzender, thread en metadata
• message_sending — herschrijf uitgaande inhoud of annuleer aflevering
• message_sent — observeer succes of mislukking van uitgaande aflevering
• before_dispatch — inspecteer of herschrijf een uitgaande dispatch vóór overdracht aan het kanaal
• reply_dispatch — neem deel aan de uiteindelijke reply-dispatch-pipeline

• session_start / session_end — volg grenzen van de sessielevenscyclus
• before_compaction / after_compaction — observeer of annoteer Compaction-cycli
• before_reset — observeer sessie-resetgebeurtenissen (/reset, programmatische resets)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended — coördineer subagent-routering en afleveren van voltooiing

• gateway_start / gateway_stop — start of stop plugin-eigen services met de Gateway
• cron_changed — observeer gateway-eigen Cron-levenscycluswijzigingen (toegevoegd, bijgewerkt, verwijderd, gestart, voltooid, gepland)
• before_install — inspecteer Skills- of plugin-installatiescans en blokkeer optioneel

​

Toolaanroepbeleid

• event.toolName
• event.params
• optioneel event.runId
• optioneel event.toolCallId
• contextvelden zoals ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (ingesteld bij Cron-gestuurde runs) en diagnostische 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 is terminaal en slaat handlers met lagere prioriteit over.
• block: false wordt behandeld als geen beslissing.
• params herschrijft de toolparameters voor uitvoering.
• requireApproval pauzeert de agentrun en vraagt de gebruiker om goedkeuring via plugin-goedkeuringen. De opdracht /approve kan zowel exec- als plugin-goedkeuringen goedkeuren.
• Een block: true met lagere prioriteit kan nog steeds blokkeren nadat een hook met hogere prioriteit goedkeuring heeft gevraagd.
• onResolution ontvangt de opgeloste goedkeuringsbeslissing — allow-once, allow-always, deny, timeout of cancelled.

​

Persistentie van toolresultaten

• OpenClaw verwijdert toolResult.details vóór provider-replay en Compaction-invoer, zodat metadata geen modelcontext wordt.
• Gepersisteerde sessie-items behouden alleen begrensde details. Te grote details worden vervangen door een compacte samenvatting en persistedDetailsTruncated: true.
• tool_result_persist en before_message_write worden uitgevoerd vóór de uiteindelijke persistentielimiet. Hooks moeten geretourneerde details nog steeds klein houden en vermijden promptrelevante tekst alleen in details te plaatsen; zet voor het model zichtbare tooluitvoer in content.

​

Prompt- en model-hooks

• before_model_resolve: ontvangt alleen de huidige prompt en attachment-metadata. Retourneer providerOverride of modelOverride.
• agent_turn_prepare: ontvangt de huidige prompt, voorbereide sessieberichten en alle exactly-once wachtrij-injecties die voor deze sessie zijn verwerkt. Retourneer prependContext of appendContext.
• before_prompt_build: ontvangt de huidige prompt en sessieberichten. Retourneer prependContext, appendContext, systemPrompt, prependSystemContext of appendSystemContext.
• heartbeat_prompt_contribution: wordt alleen uitgevoerd voor Heartbeat-beurten en retourneert prependContext of appendContext. Het is bedoeld voor achtergrondmonitors die de huidige status moeten samenvatten zonder door de gebruiker geïnitieerde beurten te wijzigen.

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

​

Sessie-extensies en next-turn-injecties

​

Berichthooks

• message_received: observeer inkomende inhoud, afzender, threadId, messageId, senderId, optionele run-/sessiecorrelatie en metadata.
• message_sending: herschrijf content of retourneer { cancel: true }.
• message_sent: observeer uiteindelijk succes of mislukking.

• message_sending met cancel: true is terminaal.
• message_sending met cancel: false wordt behandeld als geen beslissing.
• Herschreven content gaat door naar hooks met lagere prioriteit, tenzij een latere hook de levering annuleert.

​

Hooks installeren

​

Gateway-levenscyclus

​

Aankomende deprecaties

• Plattetekst-kanaalenveloppen in inbound_claim- en message_received-handlers. Lees BodyForAgent en de gestructureerde gebruikerscontextblokken in plaats van platte enveloptekst te parsen. Zie Plattetekst-kanaalenveloppen → BodyForAgent.
• before_agent_start blijft bestaan voor compatibiliteit. Nieuwe Plugins moeten before_model_resolve en before_prompt_build gebruiken in plaats van de gecombineerde fase.
• onResolution in before_tool_call gebruikt nu de getypte PluginApprovalResolution-union (allow-once / allow-always / deny / timeout / cancelled) in plaats van een vrije string.

​

Gerelateerd

• Plugin SDK-migratie — actieve deprecaties en verwijderingstijdlijn
• Plugins bouwen
• Plugin SDK-overzicht
• Plugin-entrypoints
• Interne hooks
• Interne Plugin-architectuur