Hooks de Plugin

​

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 les plus élevées s’exécutent d’abord).
• timeoutMs - budget optionnel par hook. Lorsqu’il est défini, l’exécuteur de hooks interrompt ce gestionnaire une fois le budget écoulé et continue avec le suivant, au lieu de laisser une configuration lente ou un travail de rappel consommer le délai d’expiration de modèle configuré par l’appelant. Omettez-le pour utiliser le délai d’observation/décision par défaut que l’exécuteur de hooks applique de façon générique.

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

​

Catalogue des hooks

• 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 en file d’attente et ajouter du contexte au même tour avant les hooks de prompt
• before_prompt_build - ajouter du contexte dynamique ou du texte de prompt système avant l’appel au modèle
• before_agent_start - phase combinée uniquement pour compatibilité ; préférez les deux hooks ci-dessus
• before_agent_run - inspecter le prompt final et les messages de session avant l’envoi au modèle, et éventuellement bloquer l’exécution
• before_agent_reply - court-circuiter le tour du 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 succès et la durée d’exécution
• heartbeat_prompt_contribution - ajouter du contexte uniquement 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 de prompt ni de réponse
• llm_input - observer l’entrée du fournisseur (prompt système, prompt, historique)
• llm_output - observer la sortie du fournisseur, l’utilisation et le contextTokenBudget résolu lorsqu’il est disponible

• before_tool_call - réécrire les paramètres d’outil, bloquer l’exécution ou demander une approbation
• after_tool_call - observer les résultats d’outils, les erreurs et la durée
• resolve_exec_env - fournir des variables d’environnement appartenant au plugin à exec
• 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 - revendiquer un message entrant avant le routage de 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 livraison
• reply_payload_sending — modifier ou annuler les charges utiles de réponse normalisées avant la livraison
• message_sent — observer le succès ou l’échec de la livraison sortante
• before_dispatch - inspecter ou réécrire une distribution sortante avant le transfert au canal
• reply_dispatch - participer au pipeline final de distribution de réponse

• session_start / session_end - suivre les limites du cycle de vie des sessions. Le reason de l’événement est l’un de new, reset, idle, daily, compaction, deleted, shutdown, restart ou unknown. Les valeurs shutdown et restart se déclenchent depuis 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 des lignes fantômes qui resteraient autrement dans un état ouvert après 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_spawned / subagent_ended - observer le lancement et l’achèvement d’un sous-agent.
• subagent_delivery_target - hook de compatibilité pour la livraison d’achèvement lorsqu’aucune liaison de session cœur ne peut projeter une route.
• subagent_spawning - hook de compatibilité obsolète. Le cœur prépare désormais les liaisons de sous-agent thread: true via des adaptateurs de liaison de session de canal avant le déclenchement de subagent_spawned.
• subagent_spawned inclut resolvedModel et resolvedProvider lorsqu’OpenClaw a résolu le modèle natif de la session enfant avant le lancement.
• subagent_ended transporte targetSessionKey (identité — cela correspond à subagent_spawned.childSessionKey), targetKind ("subagent" ou "acp"), reason, outcome optionnel ("ok", "error", "timeout", "killed", "reset" ou "deleted"), error optionnel, runId, endedAt, accountId et sendFarewell. Il n’inclut pas agentId ni childSessionKey ; utilisez targetSessionKey pour le corréler à l’événement subagent_spawned correspondant.

• gateway_start / gateway_stop - démarrer ou arrêter les services appartenant au plugin avec le Gateway
• deactivate - alias de compatibilité obsolète pour gateway_stop ; utilisez gateway_stop dans les nouveaux plugins
• cron_changed - observer les changements de cycle de vie Cron appartenant au gateway (ajouté, mis à jour, supprimé, démarré, terminé, planifié)
• before_install - inspecter le matériel d’installation de Skill ou de plugin préparé depuis un runtime de plugin chargé

​

Déboguer les hooks de runtime

​

Politique d’appel d’outil

• event.toolName
• event.params
• event.toolKind et event.toolInputKind optionnels, discriminateurs faisant autorité côté hôte pour les outils qui partagent intentionnellement des noms ; par exemple, les appels exec externes en mode code utilisent toolKind: "code_mode_exec" et incluent toolInputKind: "javascript" | "typescript" lorsque le langage d’entrée est connu
• event.derivedPaths optionnel, contenant des indications de chemins cibles dérivées par l’hôte au mieux pour les enveloppes d’outils bien connues telles que apply_patch ; lorsqu’ils sont présents, ces chemins peuvent être incomplets ou peuvent sur-approximer ce que l’outil touchera réellement (par exemple, avec des entrées mal formées ou partielles)
• event.runId optionnel
• event.toolCallId optionnel
• champs de contexte tels que ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (défini sur les exécutions pilotées par Cron), ctx.toolKind, ctx.toolInputKind et ctx.trace de diagnostic

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 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 de l’outil pour l’exécution.
• requireApproval met l’exécution de l’agent en pause et interroge l’utilisateur via les approbations de plugin. La commande /approve peut approuver à la fois les approbations exec et les approbations de plugin. Dans les relais natifs PreToolUse en mode rapport du serveur d’application Codex, cela est différé jusqu’à la demande d’approbation correspondante du serveur d’application ; consultez runtime du harnais Codex.
• Un block: true de priorité inférieure peut toujours bloquer après qu’un hook 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.

​

Hook d’environnement exec

• event.sessionKey
• event.toolName, actuellement toujours "exec"
• event.host, l’un de "gateway", "sandbox" ou "node"
• champs de contexte tels que ctx.agentId, ctx.sessionKey, ctx.messageProvider et ctx.channelId

​

Persistance des résultats d’outil

• OpenClaw supprime toolResult.details avant le rejeu 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 trop volumineux sont remplacés par un résumé compact et persistedDetailsTruncated: true.
• tool_result_persist et before_message_write s’exécutent avant le plafond final de persistance. Les hooks doivent tout de même garder les details renvoyés petits et éviter de placer du texte pertinent pour le prompt uniquement dans details ; placez la sortie d’outil visible par le modèle dans content.

​

Hooks de prompt et de modèle

• before_model_resolve : reçoit uniquement le prompt courant et les métadonnées des pièces jointes. Renvoyez providerOverride ou modelOverride.
• agent_turn_prepare : reçoit le prompt courant, les messages de session préparés et toutes les injections en file exactement une fois drainées pour cette session. Renvoyez prependContext ou appendContext.
• before_prompt_build : reçoit le prompt courant 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 courant sans modifier les tours initiés par l’utilisateur.

• ctx.senderId — ID d’expéditeur limité au canal (par exemple Feishu open_id, ID utilisateur Discord). Renseigné lorsque l’exécution provient d’un message utilisateur avec des métadonnées d’expéditeur connues.
• ctx.chatId — identifiant de conversation natif du transport (par exemple Feishu chat_id, Telegram chat_id). Renseigné lorsque le canal d’origine fournit un ID de conversation natif.
• ctx.channelContext.sender.id — le même ID d’expéditeur que ctx.senderId, sous un objet appartenant au canal que les plugins peuvent étendre avec des champs propres au canal.
• ctx.channelContext.chat.id — le même ID de conversation que ctx.chatId, sous un objet appartenant au canal que les plugins peuvent étendre avec des champs propres au canal.

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

​

Extensions de session et injections au tour suivant

​

Hooks de message

• message_received : observe 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éécrit content ou renvoie { cancel: true }.
• reply_payload_sending : réécrit les objets ReplyPayload normalisés (y compris presentation, delivery, les références média et le texte) ou renvoie { cancel: true }.
• message_sent : observe la réussite 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 points d’accroche de priorité inférieure, sauf si un point d’accroche ultérieur annule la livraison.
• reply_payload_sending s’exécute après la normalisation de la charge utile et avant la livraison par le canal, y compris pour les réponses routées vers le canal d’origine. Les gestionnaires s’exécutent séquentiellement et chaque gestionnaire voit la dernière charge utile produite par les gestionnaires de priorité supérieure.
• Les charges utiles reply_payload_sending n’exposent pas les marqueurs de confiance du runtime tels que trustedLocalMedia; les plugins peuvent modifier la forme de la charge utile, mais ne peuvent pas accorder la confiance aux médias locaux.
• message_sending peut renvoyer cancelReason et des metadata bornées avec une annulation. Les nouvelles API du 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 renvoyer un tableau de résultats vide par compatibilité.
• message_sent sert uniquement à l’observation. Les échecs de gestionnaire sont consignés et ne modifient pas le résultat de livraison.

​

Points d’accroche 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 disponible par compatibilité. Les nouveaux plugins doivent utiliser before_model_resolve et before_prompt_build au lieu de la phase combinée.
• subagent_spawning reste disponible par compatibilité avec les anciens plugins, mais les nouveaux plugins ne doivent pas y renvoyer de routage de thread. Le cœur prépare les liaisons de sous-agent thread: true via des adaptateurs de liaison de session de canal avant le déclenchement de subagent_spawned.
• deactivate reste un alias de compatibilité de nettoyage déprécié jusqu’après le 2026-08-16. Les nouveaux plugins doivent utiliser gateway_stop.
• 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.

​

Associés

• 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 des plugins
• Points d’accroche internes
• Internes de l’architecture des plugins