Hook dei Plugin

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.

​

Avvio rapido

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 - ordinamento degli handler (i valori più alti vengono eseguiti per primi).
• timeoutMs - budget opzionale per singolo hook. Quando impostato, il runner degli hook interrompe quell’handler dopo che il budget è scaduto e continua con il successivo, invece di lasciare che configurazioni lente o lavoro di recupero consumino il timeout del modello configurato dal chiamante. Omettilo per usare il timeout predefinito di osservazione/decisione che il runner degli hook applica genericamente.

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

​

Catalogo degli hook

• before_model_resolve - esegue l’override del provider o del modello prima che i messaggi della sessione vengano caricati
• agent_turn_prepare - consuma le iniezioni di turno del plugin in coda e aggiunge contesto nello stesso turno prima degli hook del prompt
• before_prompt_build - aggiunge contesto dinamico o testo del system prompt prima della chiamata al modello
• before_agent_start - fase combinata solo per compatibilità; preferisci i due hook sopra
• before_agent_run - ispeziona il prompt finale e i messaggi della sessione prima dell’invio al modello e, facoltativamente, blocca l’esecuzione
• before_agent_reply - interrompe anticipatamente il turno del modello con una risposta sintetica o silenzio
• before_agent_finalize - ispeziona la risposta finale naturale e richiede un altro passaggio del modello
• agent_end - osserva messaggi finali, stato di successo e durata dell’esecuzione
• heartbeat_prompt_contribution - aggiunge contesto solo Heartbeat per monitor in background e plugin del ciclo di vita

• model_call_started / model_call_ended - osserva metadati sanificati di chiamata provider/modello, tempistiche, esito e hash limitati degli ID richiesta senza contenuto del prompt o della risposta
• llm_input - osserva l’input del provider (system prompt, prompt, cronologia)
• llm_output - osserva l’output del provider

• before_tool_call - riscrive i parametri dello strumento, blocca l’esecuzione o richiede approvazione
• after_tool_call - osserva risultati dello strumento, errori e durata
• tool_result_persist - riscrive il messaggio dell’assistente prodotto da un risultato dello strumento
• before_message_write - ispeziona o blocca una scrittura di messaggio in corso (raro)

• inbound_claim - rivendica un messaggio in ingresso prima dell’instradamento all’agente (risposte sintetiche)
• message_received - osserva contenuto in ingresso, mittente, thread e metadati
• message_sending - riscrive contenuto in uscita o annulla la consegna
• message_sent - osserva il successo o il fallimento della consegna in uscita
• before_dispatch - ispeziona o riscrive un dispatch in uscita prima del passaggio al canale
• reply_dispatch - partecipa alla pipeline finale di dispatch della risposta

• session_start / session_end - traccia i confini del ciclo di vita della sessione. Il reason dell’evento è uno tra new, reset, idle, daily, compaction, deleted, shutdown, restart o unknown. I valori shutdown e restart vengono attivati dal finalizer di shutdown del Gateway quando il processo viene arrestato o riavviato mentre le sessioni sono ancora attive, così i plugin downstream (come store di memoria o trascrizioni) possono finalizzare righe fantasma che altrimenti resterebbero in stato aperto tra i riavvii. Il finalizer è limitato, così un plugin lento non può bloccare SIGTERM/SIGINT.
• before_compaction / after_compaction - osserva o annota cicli di Compaction
• before_reset - osserva eventi di reset della sessione (/reset, reset programmatici)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - coordina instradamento dei subagent e consegna del completamento

• gateway_start / gateway_stop - avvia o arresta servizi di proprietà del plugin con il Gateway
• cron_changed - osserva modifiche del ciclo di vita Cron di proprietà del gateway (aggiunto, aggiornato, rimosso, avviato, terminato, pianificato)
• before_install - ispeziona scansioni di installazione di skill o plugin e, facoltativamente, blocca

​

Criteri per le chiamate agli strumenti

• event.toolName
• event.params
• event.derivedPaths opzionale, contenente suggerimenti best-effort sui percorsi target derivati dall’host per envelope di strumenti noti come apply_patch; quando presenti, questi percorsi possono essere incompleti o possono sovrastimare ciò che lo strumento toccherà effettivamente (per esempio, con input malformati o parziali)
• event.runId opzionale
• event.toolCallId opzionale
• campi di contesto come ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (impostato su esecuzioni guidate da Cron) e ctx.trace diagnostico

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 è terminale e salta gli handler con priorità inferiore.
• block: false viene trattato come assenza di decisione.
• params riscrive i parametri dello strumento per l’esecuzione.
• requireApproval mette in pausa l’esecuzione dell’agente e chiede all’utente tramite approvazioni dei plugin. Il comando /approve può approvare sia approvazioni exec sia approvazioni plugin.
• Un block: true con priorità inferiore può comunque bloccare dopo che un hook con priorità maggiore ha richiesto l’approvazione.
• onResolution riceve la decisione di approvazione risolta - allow-once, allow-always, deny, timeout o cancelled.

​

Persistenza dei risultati degli strumenti

• OpenClaw rimuove toolResult.details prima del replay del provider e dell’input di Compaction, così i metadati non diventano contesto del modello.
• Le voci di sessione persistite mantengono solo details limitati. I details troppo grandi vengono sostituiti con un riepilogo compatto e persistedDetailsTruncated: true.
• tool_result_persist e before_message_write vengono eseguiti prima del limite finale di persistenza. Gli hook dovrebbero comunque mantenere piccoli i details restituiti ed evitare di inserire testo rilevante per il prompt solo in details; inserisci l’output dello strumento visibile al modello in content.

​

Hook di prompt e modello

• before_model_resolve: riceve solo il prompt corrente e i metadati degli allegati. Restituisce providerOverride o modelOverride.
• agent_turn_prepare: riceve il prompt corrente, i messaggi di sessione preparati e le eventuali iniezioni in coda esattamente una volta svuotate per questa sessione. Restituisce prependContext o appendContext.
• before_prompt_build: riceve il prompt corrente e i messaggi della sessione. Restituisce prependContext, appendContext, systemPrompt, prependSystemContext o appendSystemContext.
• heartbeat_prompt_contribution: viene eseguito solo per turni Heartbeat e restituisce prependContext o appendContext. È pensato per monitor in background che devono riassumere lo stato corrente senza modificare i turni avviati dall’utente.

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

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

​

Estensioni di sessione e iniezioni per il turno successivo

​

Hook dei messaggi

• message_received: osserva contenuto in entrata, mittente, threadId, messageId, senderId, correlazione facoltativa di run/sessione e metadati.
• message_sending: riscrivi content o restituisci { cancel: true }.
• message_sent: osserva il successo o l’errore finale.

• message_sending con cancel: true è terminale.
• message_sending con cancel: false viene trattato come nessuna decisione.
• Il content riscritto continua verso gli hook a priorità inferiore a meno che un hook successivo annulli la consegna.
• message_sending può restituire cancelReason e metadata limitati con un annullamento. Le nuove API del ciclo di vita dei messaggi espongono questo come esito di consegna soppressa con motivo cancelled_by_message_sending_hook; la consegna diretta legacy continua a restituire un array di risultati vuoto per compatibilità.
• message_sent è solo osservazione. Gli errori degli handler vengono registrati e non modificano il risultato della consegna.

​

Hook di installazione

​

Ciclo di vita del Gateway

​

Deprecazioni imminenti

• Envelope di canale in testo semplice negli handler inbound_claim e message_received. Leggi BodyForAgent e i blocchi strutturati del contesto utente invece di analizzare testo envelope piatto. Vedi Envelope di canale in testo semplice → BodyForAgent.
• before_agent_start resta per compatibilità. I nuovi plugins dovrebbero usare before_model_resolve e before_prompt_build invece della fase combinata.
• onResolution in before_tool_call ora usa l’unione tipizzata PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) invece di una string libera.

​

Correlati

• Migrazione del Plugin SDK - deprecazioni attive e timeline di rimozione
• Creazione di plugins
• Panoramica del Plugin SDK
• Entry point dei plugin
• Hook interni
• Internals dell’architettura dei plugin