Plugin-Hooks

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.

​

Schnellstart

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-Reihenfolge (höhere Werte laufen zuerst).
• timeoutMs - optionales Budget pro Hook. Wenn gesetzt, bricht der Hook-Runner diesen Handler nach Ablauf des Budgets ab und fährt mit dem nächsten fort, statt langsame Einrichtung oder Abrufarbeit das vom Aufrufer konfigurierte Modell-Timeout verbrauchen zu lassen. Lassen Sie es weg, um das standardmäßige Beobachtungs-/Entscheidungs-Timeout zu verwenden, das der Hook-Runner allgemein anwendet.

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

​

Hook-Katalog

• before_model_resolve - Provider oder Modell überschreiben, bevor Sitzungsnachrichten geladen werden
• agent_turn_prepare - eingereihte Plugin-Turn-Injektionen verbrauchen und Kontext für denselben Durchlauf vor Prompt-Hooks hinzufügen
• before_prompt_build - dynamischen Kontext oder System-Prompt-Text vor dem Modellaufruf hinzufügen
• before_agent_start - kombinierte Phase nur aus Kompatibilitätsgründen; bevorzugen Sie die zwei Hooks oben
• before_agent_run - den endgültigen Prompt und Sitzungsnachrichten vor der Modellübermittlung prüfen und die Ausführung optional blockieren
• before_agent_reply - den Modell-Durchlauf mit einer synthetischen Antwort oder Stille kurzschließen
• before_agent_finalize - die natürliche finale Antwort prüfen und einen weiteren Modelllauf anfordern
• agent_end - finale Nachrichten, Erfolgsstatus und Ausführungsdauer beobachten
• heartbeat_prompt_contribution - Heartbeat-spezifischen Kontext für Hintergrundmonitor- und Lebenszyklus-Plugins hinzufügen

• model_call_started / model_call_ended - bereinigte Metadaten zu Provider-/Modellaufrufen, Timing, Ergebnis und begrenzte Anfrage-ID-Hashes ohne Prompt- oder Antwortinhalt beobachten
• llm_input - Provider-Eingabe beobachten (System-Prompt, Prompt, Verlauf)
• llm_output - Provider-Ausgabe beobachten

• before_tool_call - Tool-Parameter umschreiben, Ausführung blockieren oder Genehmigung anfordern
• after_tool_call - Tool-Ergebnisse, Fehler und Dauer beobachten
• tool_result_persist - die aus einem Tool-Ergebnis erzeugte Assistentennachricht umschreiben
• before_message_write - einen laufenden Nachrichtenschreibvorgang prüfen oder blockieren (selten)

• inbound_claim - eine eingehende Nachricht vor dem Agent-Routing beanspruchen (synthetische Antworten)
• message_received - eingehenden Inhalt, Absender, Thread und Metadaten beobachten
• message_sending - ausgehenden Inhalt umschreiben oder Zustellung abbrechen
• message_sent - erfolgreiche oder fehlgeschlagene ausgehende Zustellung beobachten
• before_dispatch - einen ausgehenden Dispatch vor der Kanalübergabe prüfen oder umschreiben
• reply_dispatch - an der finalen Antwort-Dispatch-Pipeline teilnehmen

• session_start / session_end - Grenzen des Sitzungslebenszyklus nachverfolgen. Der reason des Ereignisses ist einer von new, reset, idle, daily, compaction, deleted, shutdown, restart oder unknown. Die Werte shutdown und restart werden vom Gateway-Shutdown-Finalizer ausgelöst, wenn der Prozess gestoppt oder neu gestartet wird, während Sitzungen noch aktiv sind, sodass nachgelagerte Plugins (wie Speicher- oder Transkript-Speicher) verwaiste Zeilen finalisieren können, die sonst über Neustarts hinweg offen bleiben würden. Der Finalizer ist begrenzt, sodass ein langsames Plugin SIGTERM/SIGINT nicht blockieren kann.
• before_compaction / after_compaction - Compaction-Zyklen beobachten oder annotieren
• before_reset - Sitzungs-Reset-Ereignisse beobachten (/reset, programmatische Resets)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - Routing und Abschlusszustellung von Subagents koordinieren

• gateway_start / gateway_stop - Plugin-eigene Dienste mit dem Gateway starten oder stoppen
• cron_changed - Gateway-eigene Cron-Lebenszyklusänderungen beobachten (hinzugefügt, aktualisiert, entfernt, gestartet, beendet, geplant)
• before_install - Skill- oder Plugin-Installationsscans prüfen und optional blockieren

​

Tool-Aufrufrichtlinie

• event.toolName
• event.params
• optional event.derivedPaths, mit bestmöglichen, vom Host abgeleiteten Zielpfad-Hinweisen für bekannte Tool-Umschläge wie apply_patch; sofern vorhanden, können diese Pfade unvollständig sein oder überschätzen, was das Tool tatsächlich berühren wird (zum Beispiel bei fehlerhaften oder unvollständigen Eingaben)
• optional event.runId
• optional event.toolCallId
• Kontextfelder wie ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (gesetzt bei Cron-gesteuerten Ausführungen) und diagnostisches 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 ist terminal und überspringt Handler mit niedrigerer Priorität.
• block: false wird als keine Entscheidung behandelt.
• params schreibt die Tool-Parameter für die Ausführung um.
• requireApproval pausiert die Agent-Ausführung und fragt den Benutzer über Plugin-Genehmigungen. Der Befehl /approve kann sowohl Exec- als auch Plugin-Genehmigungen erteilen.
• Ein block: true mit niedrigerer Priorität kann weiterhin blockieren, nachdem ein Hook mit höherer Priorität Genehmigung angefordert hat.
• onResolution erhält die aufgelöste Genehmigungsentscheidung - allow-once, allow-always, deny, timeout oder cancelled.

​

Persistenz von Tool-Ergebnissen

• OpenClaw entfernt toolResult.details vor Provider-Replay und Compaction-Eingabe, sodass Metadaten nicht zu Modellkontext werden.
• Persistierte Sitzungseinträge behalten nur begrenzte details. Zu große Details werden durch eine kompakte Zusammenfassung und persistedDetailsTruncated: true ersetzt.
• tool_result_persist und before_message_write laufen vor der finalen Persistenzgrenze. Hooks sollten zurückgegebene details dennoch klein halten und vermeiden, promptrelevanten Text nur in details abzulegen; platzieren Sie modellseitig sichtbare Tool-Ausgabe in content.

​

Prompt- und Modell-Hooks

• before_model_resolve: erhält nur den aktuellen Prompt und Anhangsmetadaten. Geben Sie providerOverride oder modelOverride zurück.
• agent_turn_prepare: erhält den aktuellen Prompt, vorbereitete Sitzungsnachrichten und alle exakt einmaligen, für diese Sitzung entnommenen eingereihten Injektionen. Geben Sie prependContext oder appendContext zurück.
• before_prompt_build: erhält den aktuellen Prompt und Sitzungsnachrichten. Geben Sie prependContext, appendContext, systemPrompt, prependSystemContext oder appendSystemContext zurück.
• heartbeat_prompt_contribution: läuft nur für Heartbeat-Durchläufe und gibt prependContext oder appendContext zurück. Es ist für Hintergrundmonitore vorgesehen, die den aktuellen Zustand zusammenfassen müssen, ohne benutzerinitiierte Durchläufe zu ändern.

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

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

​

Sitzungserweiterungen und Next-Turn-Injections

​

Nachrichten-Hooks

• message_received: eingehende Inhalte, Absender, threadId, messageId, senderId, optionale Ausführungs-/Sitzungskorrelation und Metadaten beobachten.
• message_sending: content umschreiben oder { cancel: true } zurückgeben.
• message_sent: finalen Erfolg oder Fehler beobachten.

• message_sending mit cancel: true ist terminal.
• message_sending mit cancel: false wird als keine Entscheidung behandelt.
• Umgeschriebener content wird an Hooks mit niedrigerer Priorität weitergereicht, sofern kein späterer Hook die Zustellung abbricht.
• message_sending kann cancelReason und begrenzte metadata zusammen mit einem Abbruch zurückgeben. Neue Nachrichtenlebenszyklus-APIs stellen dies als unterdrücktes Zustellungsergebnis mit dem Grund cancelled_by_message_sending_hook bereit; Legacy-Direktzustellung gibt aus Kompatibilitätsgründen weiterhin ein leeres Ergebnisarray zurück.
• message_sent dient nur der Beobachtung. Handler-Fehler werden protokolliert und ändern das Zustellungsergebnis nicht.

​

Installations-Hooks

​

Gateway-Lebenszyklus

​

Anstehende Deprecations

• Klartext-Kanal-Envelopes in Handlern für inbound_claim und message_received. Lesen Sie stattdessen BodyForAgent und die strukturierten Benutzerkontextblöcke, statt flachen Envelope-Text zu parsen. Siehe Klartext-Kanal-Envelopes → BodyForAgent.
• before_agent_start bleibt aus Kompatibilitätsgründen erhalten. Neue Plugins sollten before_model_resolve und before_prompt_build statt der kombinierten Phase verwenden.
• onResolution in before_tool_call verwendet nun die typisierte PluginApprovalResolution-Union (allow-once / allow-always / deny / timeout / cancelled) statt eines frei formulierten string.

​

Verwandt

• Plugin-SDK-Migration - aktive Deprecations und Zeitplan für Entfernungen
• Plugins erstellen
• Plugin-SDK-Übersicht
• Plugin-Einstiegspunkte
• Interne Hooks
• Interne Plugin-Architektur