Plugin-Hooks

​

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 werden 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, statt langsame Einrichtungs- oder Abrufarbeit das konfigurierte Modell-Timeout des Aufrufers verbrauchen zu lassen. Lassen Sie es weg, um das Standard-Timeout für Beobachtung/Entscheidung 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 verarbeiten 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 zur 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, Erfolgszustand und Laufdauer beobachten
• heartbeat_prompt_contribution – nur Heartbeat-Kontext für Hintergrundmonitor- und Lebenszyklus-Plugins hinzufügen

• model_call_started / model_call_ended – bereinigte Metadaten zu Provider-/Modellaufrufen, 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, Nutzung und das aufgelöste contextTokenBudget beobachten, sofern verfügbar

• before_tool_call – Tool-Parameter umschreiben, Ausführung blockieren oder Genehmigung anfordern
• after_tool_call – Tool-Ergebnisse, Fehler und Dauer beobachten
• resolve_exec_env – Plugin-eigene Umgebungsvariablen zu exec beitragen
• tool_result_persist – die aus einem Tool-Ergebnis erzeugte Assistant-Nachricht 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
• reply_payload_sending — normalisierte Antwort-Payloads vor der Zustellung verändern oder abbrechen
• message_sent — erfolgreiche oder fehlgeschlagene ausgehende Zustellung beobachten
• before_dispatch – einen ausgehenden Dispatch vor der Übergabe an den Kanal prüfen oder umschreiben
• reply_dispatch – an der finalen Reply-Dispatch-Pipeline teilnehmen

• session_start / session_end – Grenzen des Sitzungslebenszyklus verfolgen. Der reason des Ereignisses ist einer von new, reset, idle, daily, compaction, deleted, shutdown, restart oder unknown. Die Werte shutdown und restart werden vom Finalizer beim Herunterfahren des Gateways ausgelöst, wenn der Prozess gestoppt oder neu gestartet wird, während Sitzungen noch aktiv sind. So können nachgelagerte Plugins (z. B. Speicher- oder Transkript-Stores) Ghost-Zeilen finalisieren, die sonst über Neustarts hinweg in einem offenen Zustand verbleiben 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_spawned / subagent_ended – Start und Abschluss von Subagents beobachten.
• subagent_delivery_target – Kompatibilitäts-Hook für Abschlusszustellung, wenn keine Core-Sitzungsbindung eine Route projizieren kann.
• subagent_spawning – veralteter Kompatibilitäts-Hook. Core bereitet jetzt thread: true-Subagent-Bindungen über Adapter für Kanal-Sitzungsbindungen vor, bevor subagent_spawned ausgelöst wird.
• subagent_spawned enthält resolvedModel und resolvedProvider, wenn OpenClaw das native Modell der untergeordneten Sitzung vor dem Start aufgelöst hat.
• subagent_ended trägt targetSessionKey (Identität — dies entspricht subagent_spawned.childSessionKey), targetKind ("subagent" oder "acp"), reason, optional outcome ("ok", "error", "timeout", "killed", "reset" oder "deleted"), optional error, runId, endedAt, accountId und sendFarewell. Es enthält nicht agentId oder childSessionKey; verwenden Sie targetSessionKey, um es mit dem entsprechenden subagent_spawned-Ereignis zu korrelieren.

• gateway_start / gateway_stop – Plugin-eigene Dienste mit dem Gateway starten oder stoppen
• deactivate – veralteter Kompatibilitätsalias für gateway_stop; verwenden Sie gateway_stop in neuen Plugins
• cron_changed – Gateway-eigene Cron-Lebenszyklusänderungen beobachten (hinzugefügt, aktualisiert, entfernt, gestartet, beendet, geplant)
• before_install – bereitgestelltes Skill- oder Plugin-Installationsmaterial aus einer geladenen Plugin-Laufzeitumgebung prüfen

​

Laufzeit-Hooks debuggen

​

Tool-Aufruf-Richtlinie

• event.toolName
• event.params
• optional event.toolKind und event.toolInputKind, host-autoritative Diskriminatoren für Tools, die absichtlich Namen teilen; zum Beispiel verwenden äußere Code-Mode-exec-Aufrufe toolKind: "code_mode_exec" und enthalten toolInputKind: "javascript" | "typescript", wenn die Eingabesprache bekannt ist
• optional event.derivedPaths, mit Best-Effort-Zielpfadhinweisen, die vom Host für bekannte Tool-Envelopes wie apply_patch abgeleitet wurden; wenn vorhanden, können diese Pfade unvollständig sein oder mehr umfassen, als das Tool tatsächlich berührt (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 (bei Cron-gesteuerten Läufen gesetzt), ctx.toolKind, ctx.toolInputKind und Diagnose-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 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 den Agent-Lauf und fragt den Benutzer über Plugin- Genehmigungen. Der Befehl /approve kann sowohl exec- als auch Plugin-Genehmigungen genehmigen. In nativen PreToolUse-Relays im Report-Modus des Codex App-Servers wird dies an die passende Genehmigungsanfrage des App-Servers zurückgestellt; siehe Codex-Harness-Laufzeit.
• Ein niedriger priorisiertes block: true kann weiterhin blockieren, nachdem ein höher priorisierter Hook Genehmigung angefordert hat.
• onResolution erhält die aufgelöste Genehmigungsentscheidung – allow-once, allow-always, deny, timeout oder cancelled.

​

Exec-Umgebungs-Hook

• event.sessionKey
• event.toolName, derzeit immer "exec"
• event.host, einer von "gateway", "sandbox" oder "node"
• Kontextfelder wie ctx.agentId, ctx.sessionKey, ctx.messageProvider und ctx.channelId

​

Persistenz von Tool-Ergebnissen

• OpenClaw entfernt toolResult.details vor Provider-Replay und Compaction- Eingaben, damit Metadaten nicht zum Modellkontext werden.
• Persistierte Sitzungseinträge behalten nur begrenzte details. Übermäßig große Details werden durch eine kompakte Zusammenfassung und persistedDetailsTruncated: true ersetzt.
• tool_result_persist und before_message_write laufen vor der endgültigen Persistenzbegrenzung. Hooks sollten zurückgegebene details dennoch klein halten und vermeiden, prompt-relevanten Text ausschließlich in details abzulegen; legen Sie für das Modell sichtbare Tool-Ausgaben in content ab.

​

Prompt- und Modell-Hooks

• before_model_resolve: erhält nur den aktuellen Prompt und Anhangs- Metadaten. Gibt providerOverride oder modelOverride zurück.
• agent_turn_prepare: erhält den aktuellen Prompt, vorbereitete Sitzungsnachrichten und alle genau einmal eingereihten Injektionen, die für diese Sitzung entnommen wurden. Gibt prependContext oder appendContext zurück.
• before_prompt_build: erhält den aktuellen Prompt und Sitzungsnachrichten. Gibt 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. Es ist für Hintergrundmonitore gedacht, die den aktuellen Zustand zusammenfassen müssen, ohne von Benutzern initiierte Turns zu ändern.

• ctx.senderId — kanalbezogene Absender-ID (z. B. Feishu open_id, Discord- Benutzer-ID). Wird befüllt, wenn der Lauf aus einer Benutzernachricht mit bekannten Absendermetadaten stammt.
• ctx.chatId — transportnative Unterhaltungskennung (z. B. Feishu chat_id, Telegram chat_id). Wird befüllt, wenn der Ursprungskanal eine native Unterhaltungs-ID bereitstellt.
• ctx.channelContext.sender.id — dieselbe Absender-ID wie ctx.senderId, unter einem kanaleigenen Objekt, das Plugins mit kanalspezifischen Feldern erweitern können.
• ctx.channelContext.chat.id — dieselbe Unterhaltungs-ID wie ctx.chatId, unter einem kanaleigenen Objekt, das Plugins mit kanalspezifischen Feldern erweitern können.

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
        }
      }
    }
  }
}

​

Sitzungserweiterungen und Next-Turn-Injektionen

​

Nachrichten-Hooks

• message_received: beobachtet eingehende Inhalte, Absender, threadId, messageId, senderId, optionale Lauf-/Sitzungskorrelation und Metadaten.
• message_sending: schreibt content um oder gibt { cancel: true } zurück.
• reply_payload_sending: schreibt normalisierte ReplyPayload-Objekte um (einschließlich presentation, delivery, Medienreferenzen und Text) oder gibt { cancel: true } zurück.
• message_sent: beobachtet endgültigen Erfolg oder Fehlschlag.

• 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.
• reply_payload_sending wird nach der Payload-Normalisierung und vor der Kanalzustellung ausgeführt, einschließlich Antworten, die zurück an den ursprünglichen Kanal geroutet werden. Handler werden sequenziell ausgeführt, und jeder Handler sieht die neueste Payload, die von Handlern mit höherer Priorität erzeugt wurde.
• reply_payload_sending-Payloads legen keine Laufzeit-Vertrauensmarker wie trustedLocalMedia offen; Plugins können die Payload-Form bearbeiten, aber kein Vertrauen für lokale Medien gewähren.
• message_sending kann bei einem Abbruch cancelReason und begrenzte metadata zurückgeben. Neue Message-Lifecycle-APIs machen dies als unterdrücktes Zustellungs- Ergebnis mit dem Grund cancelled_by_message_sending_hook sichtbar; die alte 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-Lifecycle

​

Kommende Deprecations

• Plaintext-Kanal-Envelopes in inbound_claim- und message_received- Handlern. Lesen Sie BodyForAgent und die strukturierten User-Context-Blöcke, statt flachen Envelope-Text zu parsen. Siehe Plaintext-Kanal-Envelopes → BodyForAgent.
• before_agent_start bleibt aus Kompatibilitätsgründen erhalten. Neue Plugins sollten stattdessen before_model_resolve und before_prompt_build statt der kombinierten Phase verwenden.
• subagent_spawning bleibt aus Kompatibilitätsgründen mit älteren Plugins erhalten, aber neue Plugins sollten daraus kein Thread-Routing zurückgeben. Core bereitet thread: true-Subagent-Bindings über Channel-Session-Binding-Adapter vor, bevor subagent_spawned ausgelöst wird.
• deactivate bleibt bis nach dem 2026-08-16 als deprecated Cleanup-Kompatibilitätsalias erhalten. Neue Plugins sollten gateway_stop 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