Points d’accroche de 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.

​

Démarrage rapide

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 - ordre des gestionnaires (les valeurs plus élevées s’exécutent en premier).
• timeoutMs - budget facultatif par point d’accroche. Lorsqu’il est défini, l’exécuteur de points d’accroche abandonne ce gestionnaire après l’expiration du budget et continue avec le suivant, au lieu de laisser une configuration ou un rappel lent consommer le délai d’expiration de modèle configuré par l’appelant. Omettez-le pour utiliser le délai d’expiration d’observation/décision par défaut que l’exécuteur de points d’accroche applique de façon générique.

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

​

Catalogue des points d’accroche

• before_model_resolve - remplacer le fournisseur ou le modèle avant le chargement des messages de session
• agent_turn_prepare - consommer les injections de tour de Plugin mises en file d’attente et ajouter du contexte du même tour avant les points d’accroche d’invite
• before_prompt_build - ajouter du contexte dynamique ou du texte d’invite système avant l’appel au modèle
• before_agent_start - phase combinée conservée uniquement pour compatibilité ; privilégiez les deux points d’accroche ci-dessus
• before_agent_run - inspecter l’invite finale et les messages de session avant la soumission au modèle, et bloquer éventuellement l’exécution
• before_agent_reply - court-circuiter le tour de modèle avec une réponse synthétique ou le silence
• before_agent_finalize - inspecter la réponse finale naturelle et demander un passage de modèle supplémentaire
• agent_end - observer les messages finaux, l’état de réussite et la durée d’exécution
• heartbeat_prompt_contribution - ajouter du contexte propre à Heartbeat pour les Plugins de surveillance en arrière-plan et de cycle de vie

• model_call_started / model_call_ended - observer les métadonnées assainies d’appel fournisseur/modèle, le minutage, le résultat et les hachages bornés d’identifiants de requête, sans contenu d’invite ni de réponse
• llm_input - observer l’entrée du fournisseur (invite système, invite, historique)
• llm_output - observer la sortie du fournisseur

• before_tool_call - réécrire les paramètres d’outil, bloquer l’exécution ou exiger une approbation
• after_tool_call - observer les résultats d’outil, les erreurs et la durée
• tool_result_persist - réécrire le message de l’assistant produit à partir d’un résultat d’outil
• before_message_write - inspecter ou bloquer une écriture de message en cours (rare)

• inbound_claim - prendre en charge un message entrant avant le routage vers l’agent (réponses synthétiques)
• message_received - observer le contenu entrant, l’expéditeur, le fil et les métadonnées
• message_sending - réécrire le contenu sortant ou annuler la remise
• message_sent - observer la réussite ou l’échec de la remise sortante
• before_dispatch - inspecter ou réécrire une expédition sortante avant le transfert au canal
• reply_dispatch - participer au pipeline final d’expédition de réponse

• session_start / session_end - suivre les limites du cycle de vie des sessions. Le reason de l’événement est l’une des valeurs new, reset, idle, daily, compaction, deleted, shutdown, restart ou unknown. Les valeurs shutdown et restart sont déclenchées par le finaliseur d’arrêt du Gateway lorsque le processus est arrêté ou redémarré alors que des sessions sont encore actives, afin que les Plugins en aval (comme les magasins de mémoire ou de transcriptions) puissent finaliser les lignes fantômes qui resteraient autrement dans un état ouvert entre les redémarrages. Le finaliseur est borné afin qu’un Plugin lent ne puisse pas bloquer SIGTERM/SIGINT.
• before_compaction / after_compaction - observer ou annoter les cycles de Compaction
• before_reset - observer les événements de réinitialisation de session (/reset, réinitialisations programmatiques)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - coordonner le routage des sous-agents et la remise de fin d’exécution

• gateway_start / gateway_stop - démarrer ou arrêter les services gérés par le Plugin avec le Gateway
• cron_changed - observer les changements du cycle de vie Cron gérés par le Gateway (ajouté, mis à jour, supprimé, démarré, terminé, planifié)
• before_install - inspecter les analyses d’installation de Skills ou de Plugins et les bloquer éventuellement

​

Politique d’appel d’outil

• event.toolName
• event.params
• event.derivedPaths facultatif, contenant des indices de chemins cibles déduits par l’hôte au mieux pour des enveloppes d’outil bien connues telles que apply_patch ; lorsqu’ils sont présents, ces chemins peuvent être incomplets ou surestimer ce que l’outil touchera réellement (par exemple avec des entrées mal formées ou partielles)
• event.runId facultatif
• event.toolCallId facultatif
• des champs de contexte comme ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (défini sur les exécutions pilotées par Cron) et le diagnostic 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 est terminal et ignore les gestionnaires de priorité inférieure.
• block: false est traité comme une absence de décision.
• params réécrit les paramètres d’outil pour l’exécution.
• requireApproval met en pause l’exécution de l’agent et interroge l’utilisateur via les approbations de Plugin. La commande /approve peut approuver à la fois les approbations d’exécution et de Plugin.
• Un block: true de priorité inférieure peut toujours bloquer après qu’un point d’accroche de priorité supérieure a demandé une approbation.
• onResolution reçoit la décision d’approbation résolue - allow-once, allow-always, deny, timeout ou cancelled.

​

Persistance des résultats d’outil

• OpenClaw retire toolResult.details avant le rejeu côté fournisseur et l’entrée de Compaction afin que les métadonnées ne deviennent pas du contexte de modèle.
• Les entrées de session persistées conservent uniquement des details bornés. Les détails surdimensionnés sont remplacés par un résumé compact et persistedDetailsTruncated: true.
• tool_result_persist et before_message_write s’exécutent avant la limite finale de persistance. Les points d’accroche doivent néanmoins garder les details renvoyés petits et éviter de placer du texte pertinent pour l’invite uniquement dans details ; placez la sortie d’outil visible par le modèle dans content.

​

Points d’accroche d’invite et de modèle

• before_model_resolve : reçoit uniquement l’invite actuelle et les métadonnées des pièces jointes. Renvoyez providerOverride ou modelOverride.
• agent_turn_prepare : reçoit l’invite actuelle, les messages de session préparés, et toutes les injections en file d’attente à usage unique drainées pour cette session. Renvoyez prependContext ou appendContext.
• before_prompt_build : reçoit l’invite actuelle et les messages de session. Renvoyez prependContext, appendContext, systemPrompt, prependSystemContext ou appendSystemContext.
• heartbeat_prompt_contribution : s’exécute uniquement pour les tours Heartbeat et renvoie prependContext ou appendContext. Il est destiné aux moniteurs en arrière-plan qui doivent résumer l’état actuel sans modifier les tours initiés par l’utilisateur.

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

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

​

Extensions de session et injections au tour suivant

​

Hooks de message

• message_received : observer le contenu entrant, l’expéditeur, threadId, messageId, senderId, la corrélation optionnelle d’exécution/session et les métadonnées.
• message_sending : réécrire content ou retourner { cancel: true }.
• message_sent : observer le succès ou l’échec final.

• message_sending avec cancel: true est terminal.
• message_sending avec cancel: false est traité comme une absence de décision.
• Le content réécrit continue vers les hooks de priorité inférieure sauf si un hook ultérieur annule la livraison.
• message_sending peut retourner cancelReason et des metadata bornées avec une annulation. Les nouvelles API de cycle de vie des messages exposent cela comme un résultat de livraison supprimée avec la raison cancelled_by_message_sending_hook ; la livraison directe héritée continue de retourner un tableau de résultats vide par compatibilité.
• message_sent sert uniquement à l’observation. Les échecs de gestionnaire sont journalisés et ne modifient pas le résultat de livraison.

​

Hooks d’installation

​

Cycle de vie du Gateway

​

Dépréciations à venir

• Enveloppes de canal en texte brut dans les gestionnaires inbound_claim et message_received. Lisez BodyForAgent et les blocs structurés de contexte utilisateur au lieu d’analyser le texte d’enveloppe plat. Voir Enveloppes de canal en texte brut → BodyForAgent.
• before_agent_start reste présent pour la compatibilité. Les nouveaux plugins doivent utiliser before_model_resolve et before_prompt_build au lieu de la phase combinée.
• onResolution dans before_tool_call utilise désormais l’union typée PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) au lieu d’un string libre.

​

Liens connexes

• Migration du Plugin SDK - dépréciations actives et calendrier de suppression
• Créer des plugins
• Vue d’ensemble du Plugin SDK
• Points d’entrée de Plugin
• Hooks internes
• Internes de l’architecture de Plugin