Ganchos 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.

​

Inicio rápido

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: orden del manejador (los valores más altos se ejecutan primero).
• timeoutMs: presupuesto opcional por hook. Cuando se establece, el ejecutor de hooks aborta ese manejador después de que venza el presupuesto y continúa con el siguiente, en lugar de permitir que una configuración lenta o trabajo de recuperación consuma el timeout de modelo configurado por el llamador. Omítelo para usar el timeout predeterminado de observación/decisión que el ejecutor de hooks aplica de forma genérica.

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

​

Catálogo de hooks

• before_model_resolve: sobrescribe el proveedor o el modelo antes de que se carguen los mensajes de sesión
• agent_turn_prepare: consume inyecciones de turno de plugin en cola y agrega contexto del mismo turno antes de los hooks de prompt
• before_prompt_build: agrega contexto dinámico o texto de prompt del sistema antes de la llamada al modelo
• before_agent_start: fase combinada solo por compatibilidad; prefiere los dos hooks anteriores
• before_agent_run: inspecciona el prompt final y los mensajes de sesión antes del envío al modelo y, opcionalmente, bloquea la ejecución
• before_agent_reply: interrumpe el turno del modelo con una respuesta sintética o silencio
• before_agent_finalize: inspecciona la respuesta final natural y solicita una pasada más del modelo
• agent_end: observa los mensajes finales, el estado de éxito y la duración de la ejecución
• heartbeat_prompt_contribution: agrega contexto solo de Heartbeat para plugins de monitor en segundo plano y ciclo de vida

• model_call_started / model_call_ended: observa metadatos saneados de llamadas a proveedor/modelo, tiempos, resultado y hashes acotados de ID de solicitud sin contenido de prompt ni respuesta
• llm_input: observa la entrada del proveedor (prompt del sistema, prompt, historial)
• llm_output: observa la salida del proveedor

• before_tool_call: reescribe parámetros de la herramienta, bloquea la ejecución o requiere aprobación
• after_tool_call: observa resultados de herramientas, errores y duración
• tool_result_persist: reescribe el mensaje del asistente producido a partir de un resultado de herramienta
• before_message_write: inspecciona o bloquea una escritura de mensaje en curso (raro)

• inbound_claim: reclama un mensaje entrante antes del enrutamiento del agente (respuestas sintéticas)
• message_received: observa el contenido entrante, remitente, hilo y metadatos
• message_sending: reescribe contenido saliente o cancela la entrega
• message_sent: observa el éxito o fallo de la entrega saliente
• before_dispatch: inspecciona o reescribe un envío saliente antes de la transferencia al canal
• reply_dispatch: participa en la canalización final de despacho de respuestas

• session_start / session_end: rastrea límites del ciclo de vida de la sesión. El reason del evento es uno de new, reset, idle, daily, compaction, deleted, shutdown, restart o unknown. Los valores shutdown y restart se disparan desde el finalizador de apagado del gateway cuando el proceso se detiene o reinicia mientras las sesiones siguen activas, de modo que los plugins posteriores (como almacenes de memoria o transcripciones) puedan finalizar filas fantasma que, de lo contrario, quedarían en estado abierto entre reinicios. El finalizador está acotado para que un plugin lento no pueda bloquear SIGTERM/SIGINT.
• before_compaction / after_compaction: observa o anota ciclos de Compaction
• before_reset: observa eventos de restablecimiento de sesión (/reset, restablecimientos programáticos)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - coordinan el enrutamiento de subagentes y la entrega de finalización

• gateway_start / gateway_stop - inician o detienen servicios propiedad del plugin con el Gateway
• cron_changed - observan cambios del ciclo de vida de cron propiedad del gateway (agregado, actualizado, eliminado, iniciado, finalizado, programado)
• before_install - inspecciona análisis de instalación de Skills o plugins y, opcionalmente, bloquea

​

Política de llamadas a herramientas

• event.toolName
• event.params
• event.derivedPaths opcional, que contiene indicios de rutas de destino derivadas del host con el mejor esfuerzo para envoltorios de herramientas conocidos como apply_patch; cuando están presentes, estas rutas pueden estar incompletas o sobreestimar lo que la herramienta realmente tocará (por ejemplo, con entradas mal formadas o parciales)
• event.runId opcional
• event.toolCallId opcional
• campos de contexto como ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (establecido en ejecuciones impulsadas por cron) y ctx.trace de diagnóstico

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 es terminal y omite los controladores de menor prioridad.
• block: false se trata como ninguna decisión.
• params reescribe los parámetros de la herramienta para la ejecución.
• requireApproval pausa la ejecución del agente y solicita al usuario mediante aprobaciones de plugin. El comando /approve puede aprobar tanto aprobaciones de exec como de plugin.
• Un block: true de menor prioridad aún puede bloquear después de que un hook de mayor prioridad haya solicitado aprobación.
• onResolution recibe la decisión de aprobación resuelta: allow-once, allow-always, deny, timeout o cancelled.

​

Persistencia de resultados de herramientas

• OpenClaw elimina toolResult.details antes de la reproducción del proveedor y de la entrada de Compaction para que los metadatos no se conviertan en contexto del modelo.
• Las entradas de sesión persistidas conservan solo details acotados. Los detalles demasiado grandes se reemplazan por un resumen compacto y persistedDetailsTruncated: true.
• tool_result_persist y before_message_write se ejecutan antes del límite final de persistencia. Aun así, los hooks deben mantener pequeños los details devueltos y evitar colocar texto relevante para el prompt solo en details; coloca la salida de la herramienta visible para el modelo en content.

​

Hooks de prompt y modelo

• before_model_resolve: recibe solo el prompt actual y los metadatos de adjuntos. Devuelve providerOverride o modelOverride.
• agent_turn_prepare: recibe el prompt actual, los mensajes de sesión preparados y cualquier inyección en cola exactamente una vez drenada para esta sesión. Devuelve prependContext o appendContext.
• before_prompt_build: recibe el prompt actual y los mensajes de sesión. Devuelve prependContext, appendContext, systemPrompt, prependSystemContext o appendSystemContext.
• heartbeat_prompt_contribution: se ejecuta solo para turnos de Heartbeat y devuelve prependContext o appendContext. Está pensado para monitores en segundo plano que necesitan resumir el estado actual sin cambiar turnos iniciados por el usuario.

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

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

​

Extensiones de sesión e inyecciones para el siguiente turno

​

Hooks de mensaje

• message_received: observa el contenido entrante, remitente, threadId, messageId, senderId, correlación opcional de ejecución/sesión y metadatos.
• message_sending: reescribe content o devuelve { cancel: true }.
• message_sent: observa el éxito o fallo final.

• message_sending con cancel: true es terminal.
• message_sending con cancel: false se trata como ausencia de decisión.
• El content reescrito continúa hacia hooks de menor prioridad salvo que un hook posterior cancele la entrega.
• message_sending puede devolver cancelReason y metadata acotados con una cancelación. Las nuevas API de ciclo de vida de mensajes lo exponen como un resultado de entrega suprimida con motivo cancelled_by_message_sending_hook; la entrega directa heredada sigue devolviendo un array de resultados vacío por compatibilidad.
• message_sent es solo de observación. Los fallos de handlers se registran y no cambian el resultado de entrega.

​

Hooks de instalación

​

Ciclo de vida del Gateway

​

Próximas deprecaciones

• Envoltorios de canal en texto plano en handlers inbound_claim y message_received. Lee BodyForAgent y los bloques estructurados de contexto de usuario en lugar de analizar texto plano de envoltorio. Consulta Envoltorios de canal en texto plano → BodyForAgent.
• before_agent_start se mantiene por compatibilidad. Los plugins nuevos deben usar before_model_resolve y before_prompt_build en lugar de la fase combinada.
• onResolution en before_tool_call ahora usa la unión tipada PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) en lugar de un string de formato libre.

​

Relacionado

• Migración del Plugin SDK - deprecaciones activas y cronograma de eliminación
• Construir plugins
• Resumen del Plugin SDK
• Puntos de entrada del Plugin
• Hooks internos
• Elementos internos de arquitectura de plugins