Plugin-Hooks

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.

​

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öher wird zuerst ausgeführt).
• 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, anstatt langsame Setup- oder Recall-Arbeit 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 generisch 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 - in die Warteschlange gestellte Plugin-Turn-Injektionen verbrauchen und Kontext für denselben Turn 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 für Kompatibilität; bevorzugen Sie die beiden Hooks oben
• before_agent_run - den finalen Prompt und die Sitzungsnachrichten vor der Modellübermittlung prüfen und den Lauf optional blockieren
• before_agent_reply - den Modell-Turn mit einer synthetischen Antwort oder Stille kurzschließen
• before_agent_finalize - die natürliche finale Antwort prüfen und einen weiteren Modelldurchlauf anfordern
• agent_end - finale Nachrichten, Erfolgsstatus und Laufdauer beobachten
• heartbeat_prompt_contribution - Heartbeat-spezifischen Kontext für Hintergrundmonitor- und Lebenszyklus-Plugins hinzufügen

• model_call_started / model_call_ended - bereinigte Provider-/Modellaufruf-Metadaten, Timing, Ergebnis und begrenzte Request-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 Agenten-Routing beanspruchen (synthetische Antworten)
• message_received - eingehenden Inhalt, Absender, Thread und Metadaten beobachten
• message_sending - ausgehenden Inhalt umschreiben oder Zustellung abbrechen
• message_sent - Erfolg oder Fehler der ausgehenden Zustellung beobachten
• before_dispatch - einen ausgehenden Dispatch vor der Channel-Übergabe prüfen oder umschreiben
• reply_dispatch - an der finalen Antwort-Dispatch-Pipeline teilnehmen

• session_start / session_end - Grenzen des Sitzungslebenszyklus verfolgen
• 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 - Subagent-Routing und Abschlusszustellung koordinieren

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

​

Richtlinie für Tool-Aufrufe

• event.toolName
• event.params
• optional event.derivedPaths, das Best-Effort-Hinweise zu vom Host abgeleiteten Zielpfaden für bekannte Tool-Umschläge wie apply_patch enthält; wenn vorhanden, können diese Pfade unvollständig sein oder überschätzen, was das Tool tatsächlich berühren wird (zum Beispiel bei fehlerhaften oder partiellen Eingaben)
• optional event.runId
• optional event.toolCallId
• Kontextfelder wie ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (bei Cron-gesteuerten Läufen gesetzt) 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 so behandelt, als gäbe es keine Entscheidung.
• params schreibt die Tool-Parameter für die Ausführung um.
• requireApproval pausiert den Agentenlauf 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 eine 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, damit Metadaten nicht zu Modellkontext werden.
• Persistierte Sitzungseinträge behalten nur begrenzte details. Überdimensionierte Details werden durch eine kompakte Zusammenfassung und persistedDetailsTruncated: true ersetzt.
• tool_result_persist und before_message_write laufen vor der finalen Persistenzbegrenzung. Hooks sollten zurückgegebene details dennoch klein halten und vermeiden, promptrelevanten Text nur in details abzulegen; platzieren Sie für das Modell sichtbare Tool-Ausgabe in content.

​

Prompt- und Modell-Hooks

• before_model_resolve: erhält nur den aktuellen Prompt und Anhang- Metadaten. Geben Sie providerOverride oder modelOverride zurück.
• agent_turn_prepare: erhält den aktuellen Prompt, vorbereitete Sitzungsnachrichten und alle Exactly-once-Injektionen in der Warteschlange, die für diese Sitzung entnommen wurden. 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-Turns und gibt prependContext oder appendContext zurück. Er ist für Hintergrundmonitore vorgesehen, die den aktuellen Zustand zusammenfassen müssen, ohne benutzerinitiierte Turns zu ändern.

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

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

​

Sitzungserweiterungen und Injektionen für den nächsten Turn

​

Nachrichten-Hooks

• message_received: eingehenden Inhalt, Absender, threadId, messageId, senderId, optionale Lauf-/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 weitergegeben, sofern kein späterer Hook die Zustellung abbricht.
• message_sending kann cancelReason und begrenzte metadata zusammen mit einem Abbruch zurückgeben. Neue Nachrichten-Lebenszyklus-APIs stellen dies als unterdrücktes Zustellungsergebnis mit dem Grund cancelled_by_message_sending_hook bereit; ältere direkte Zustellung 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

​

Bevorstehende Veraltungen

• Klartext-Kanalumschläge in inbound_claim- und message_received- Handlern. Lesen Sie stattdessen BodyForAgent und die strukturierten Benutzerkontextblöcke, anstatt flachen Umschlagtext zu parsen. Siehe Klartext-Kanalumschläge → 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 jetzt die typisierte Union PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) anstelle eines frei formulierten string.

​

Verwandt

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