Plugin-hooks

​

Snelstart

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 - volgorde van handlers (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-werkzaamheden de geconfigureerde model-timeout van de aanroeper te laten verbruiken. Laat dit weg om de standaard time-out voor observatie/beslissingen te gebruiken die de hook-runner generiek toepast.

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

​

Hook-catalogus

• before_model_resolve - overschrijf provider of model voordat sessieberichten laden
• agent_turn_prepare - verbruik in de wachtrij geplaatste plugin-turn-injecties en voeg context voor dezelfde turn toe voor prompt-hooks
• before_prompt_build - voeg dynamische context of systeemprompttekst toe voor de modelaanroep
• before_agent_start - gecombineerde fase alleen voor compatibiliteit; geef de voorkeur aan de twee hooks hierboven
• before_agent_run - inspecteer de definitieve prompt en sessieberichten voor modelindiening en blokkeer de run optioneel
• before_agent_reply - kortsluit de model-turn met een synthetisch antwoord of stilte
• before_agent_finalize - inspecteer het natuurlijke eindantwoord en vraag nog een model-pass aan
• agent_end - observeer definitieve berichten, successtatus en runduur
• heartbeat_prompt_contribution - voeg alleen-Heartbeat-context toe voor achtergrondmonitor- en levenscyclusplugins

• model_call_started / model_call_ended - observeer opgeschoonde provider-/modelaanroepmetadata, timing, resultaat en begrensde request-id-hashes zonder prompt- of antwoordinhoud
• llm_input - observeer providerinvoer (systeemprompt, prompt, geschiedenis)
• llm_output - observeer provideruitvoer, gebruik en het opgeloste contextTokenBudget wanneer beschikbaar

• before_tool_call - herschrijf toolparameters, blokkeer uitvoering of vereis goedkeuring
• after_tool_call - observeer toolresultaten, fouten en duur
• resolve_exec_env - draag plugin-eigen omgevingsvariabelen bij aan exec
• tool_result_persist - herschrijf het assistant-bericht dat uit een toolresultaat is geproduceerd
• before_message_write - inspecteer of blokkeer een berichtschrijfactie die bezig is (zeldzaam)

• inbound_claim - claim een inkomend bericht voor agent-routing (synthetische antwoorden)
• message_received — observeer inkomende inhoud, afzender, thread en metadata
• message_sending — herschrijf uitgaande inhoud of annuleer bezorging
• reply_payload_sending — muteer of annuleer genormaliseerde antwoordpayloads voor bezorging
• message_sent — observeer succes of mislukking van uitgaande bezorging
• before_dispatch - inspecteer of herschrijf een uitgaande dispatch voor kanaaloverdracht
• reply_dispatch - neem deel aan de definitieve reply-dispatch-pijplijn

• session_start / session_end - volg grenzen van de sessielevenscyclus. De reason van het event is een van new, reset, idle, daily, compaction, deleted, shutdown, restart of unknown. De waarden shutdown en restart worden geactiveerd vanuit de gateway-shutdown-finalizer wanneer het proces wordt gestopt of herstart terwijl sessies nog actief zijn, zodat downstream-plugins (zoals geheugen- of transcriptstores) ghost-rijen kunnen finaliseren die anders na herstarts in een open staat zouden blijven. De finalizer is begrensd zodat een trage plugin SIGTERM/SIGINT niet kan blokkeren.
• before_compaction / after_compaction - observeer of annoteer Compaction-cycli
• before_reset - observeer sessie-reset-events (/reset, programmatische resets)

• subagent_spawned / subagent_ended - observeer het starten en voltooien van subagents.
• subagent_delivery_target - compatibiliteitshook voor voltooiingsbezorging wanneer geen core-sessiebinding een route kan projecteren.
• subagent_spawning - verouderde compatibiliteitshook. Core bereidt nu thread: true subagent-bindingen voor via kanaal-sessiebindingadapters voordat subagent_spawned wordt geactiveerd.
• subagent_spawned bevat resolvedModel en resolvedProvider wanneer OpenClaw het native model van de child-sessie voor het starten heeft opgelost.
• subagent_ended draagt targetSessionKey (identiteit — dit komt overeen met subagent_spawned.childSessionKey), targetKind ("subagent" of "acp"), reason, optioneel outcome ("ok", "error", "timeout", "killed", "reset" of "deleted"), optioneel error, runId, endedAt, accountId en sendFarewell. Het bevat niet agentId of childSessionKey; gebruik targetSessionKey om te correleren met het bijbehorende subagent_spawned-event.

• gateway_start / gateway_stop - start of stop plugin-eigen services met de Gateway
• deactivate - verouderde compatibiliteitsalias voor gateway_stop; gebruik gateway_stop in nieuwe plugins
• cron_changed - observeer gateway-eigen Cron-levenscycluswijzigingen (toegevoegd, bijgewerkt, verwijderd, gestart, voltooid, gepland)
• before_install - inspecteer staged skill- of plugin-installatiemateriaal vanuit een geladen plugin-runtime

​

Runtime-hooks debuggen

​

Beleid voor toolaanroepen

• event.toolName
• event.params
• optioneel event.toolKind en event.toolInputKind, host-autoritatieve discriminators voor tools die bewust namen delen; bijvoorbeeld, buitenste code-mode exec-aanroepen gebruiken toolKind: "code_mode_exec" en bevatten toolInputKind: "javascript" | "typescript" wanneer de invoertaal bekend is
• optioneel event.derivedPaths, met best-effort, door de host afgeleide doelpad- hints voor bekende tool-envelopes zoals apply_patch; wanneer aanwezig, kunnen deze paden onvolledig zijn of kunnen ze ruimer inschatten wat de tool daadwerkelijk zal aanraken (bijvoorbeeld bij misvormde of gedeeltelijke invoer)
• optioneel event.runId
• optioneel event.toolCallId
• contextvelden zoals ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (ingesteld op door Cron aangedreven runs), ctx.toolKind, ctx.toolInputKind 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";
    allowedDecisions?: Array<"allow-once" | "allow-always" | "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 agent-run en vraagt de gebruiker om goedkeuring via plugin- goedkeuringen. De opdracht /approve kan zowel exec- als plugin-goedkeuringen goedkeuren. In native PreToolUse-relays van Codex app-server report-mode wordt dit uitgesteld naar het overeenkomende goedkeuringsverzoek van de app-server; zie Codex harness runtime.
• 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.

​

Exec-omgevingshook

• event.sessionKey
• event.toolName, momenteel altijd "exec"
• event.host, een van "gateway", "sandbox" of "node"
• contextvelden zoals ctx.agentId, ctx.sessionKey, ctx.messageProvider en ctx.channelId

​

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 teruggegeven details nog steeds klein houden en vermijden promptrelevante tekst alleen in details te plaatsen; zet modelzichtbare tooluitvoer in content.

​

Prompt- en modelhooks

• before_model_resolve: ontvangt alleen de huidige prompt en bijlagemetadata. Retourneer providerOverride of modelOverride.
• agent_turn_prepare: ontvangt de huidige prompt, voorbereide sessieberichten en eventuele precies eenmalige ingeplande invoegingen 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: draait alleen voor Heartbeat-beurten en retourneert prependContext of appendContext. Dit is bedoeld voor achtergrondmonitors die de huidige status moeten samenvatten zonder door de gebruiker gestarte beurten te wijzigen.

• ctx.senderId — kanaalgebonden afzender-ID (bijv. Feishu open_id, Discord gebruikers-ID). Ingevuld wanneer de run afkomstig is van een gebruikersbericht met bekende afzendermetadata.
• ctx.chatId — transport-native gespreksidentifier (bijv. Feishu chat_id, Telegram chat_id). Ingevuld wanneer het oorspronkelijke kanaal een native gespreks-ID levert.
• ctx.channelContext.sender.id — dezelfde afzender-ID als ctx.senderId, onder een kanaaleigen object dat plugins kunnen uitbreiden met kanaalspecifieke velden.
• ctx.channelContext.chat.id — dezelfde gespreks-ID als ctx.chatId, onder een kanaaleigen object dat plugins kunnen uitbreiden met kanaalspecifieke velden.

declare module "openclaw/plugin-sdk/channel-inbound" {
  interface PluginHookChannelSenderContext {
    unionId?: string;
    userId?: string;
  }
}

buildChannelInboundEventContext({
  // ...
  channelContext: {
    sender: { id: senderOpenId, unionId, userId },
    chat: { id: chatId },
  },
});

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

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

​

Sessie-extensies en invoegingen voor de volgende beurt

​

Berichthooks

• message_received: observeer inbound content, afzender, threadId, messageId, senderId, optionele run-/sessiecorrelatie en metadata.
• message_sending: herschrijf content of retourneer { cancel: true }.
• reply_payload_sending: herschrijf genormaliseerde ReplyPayload-objecten (inclusief presentation, delivery, mediarefs en tekst) of retourneer { cancel: true }.
• message_sent: observeer uiteindelijke successen of fouten.

• 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 levering annuleert.
• reply_payload_sending wordt uitgevoerd na payloadnormalisatie en vóór kanaallevering, inclusief antwoorden die terug naar het oorspronkelijke kanaal worden gerouteerd. Handlers worden sequentieel uitgevoerd en elke handler ziet de nieuwste payload die door handlers met hogere prioriteit is geproduceerd.
• reply_payload_sending-payloads stellen geen runtime-vertrouwensmarkeringen bloot, zoals trustedLocalMedia; plugins kunnen de payloadvorm bewerken, maar kunnen geen vertrouwen voor lokale media verlenen.
• message_sending kan cancelReason en begrensde metadata retourneren met een annulering. Nieuwe API’s voor de berichtlevenscyclus stellen dit bloot als een onderdrukte leveringsuitkomst met reden cancelled_by_message_sending_hook; legacy directe levering blijft voor compatibiliteit een lege resultaatarray retourneren.
• message_sent is alleen voor observatie. Handlerfouten worden gelogd en wijzigen het leveringsresultaat niet.

​

Installatiehooks

​

Gateway-levenscyclus

​

Aankomende deprecaties

• Plaintext channel envelopes in handlers voor inbound_claim en message_received. Lees BodyForAgent en de gestructureerde gebruikerscontextblokken in plaats van platte enveloptekst te parsen. Zie Plaintext channel envelopes → 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.
• subagent_spawning blijft bestaan voor compatibiliteit met oudere plugins, maar nieuwe plugins mogen hieruit geen threadroutering retourneren. Core bereidt thread: true-subagentbindingen voor via adapters voor kanaalsessiebinding voordat subagent_spawned wordt geactiveerd.
• deactivate blijft als deprecated compatibiliteitsalias voor opschoning bestaan tot na 2026-08-16. Nieuwe plugins moeten gateway_stop gebruiken.
• 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 pluginarchitectuur