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.

​

Início 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 - ordenação dos manipuladores (valores mais altos são executados primeiro).
• timeoutMs - orçamento opcional por gancho. Quando definido, o executor de ganchos aborta esse manipulador após o orçamento transcorrer e continua com o próximo, em vez de permitir que configuração lenta ou trabalho de recuperação consuma o tempo limite de modelo configurado pelo chamador. Omita para usar o tempo limite padrão de observação/decisão que o executor de ganchos aplica genericamente.

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

​

Catálogo de ganchos

• before_model_resolve - substitui provedor ou modelo antes que as mensagens de sessão sejam carregadas
• agent_turn_prepare - consome injeções de turno de Plugin enfileiradas e adiciona contexto no mesmo turno antes dos ganchos de prompt
• before_prompt_build - adiciona contexto dinâmico ou texto de prompt do sistema antes da chamada ao modelo
• before_agent_start - fase combinada apenas para compatibilidade; prefira os dois ganchos acima
• before_agent_run - inspeciona o prompt final e as mensagens de sessão antes do envio ao modelo e, opcionalmente, bloqueia a execução
• before_agent_reply - interrompe o turno do modelo com uma resposta sintética ou silêncio
• before_agent_finalize - inspeciona a resposta final natural e solicita mais uma passagem do modelo
• agent_end - observa mensagens finais, estado de sucesso e duração da execução
• heartbeat_prompt_contribution - adiciona contexto somente de Heartbeat para monitor em segundo plano e Plugins de ciclo de vida

• model_call_started / model_call_ended - observa metadados sanitizados de chamada de provedor/modelo, temporização, resultado e hashes limitados de ID de solicitação sem conteúdo de prompt ou resposta
• llm_input - observa a entrada do provedor (prompt do sistema, prompt, histórico)
• llm_output - observa a saída do provedor

• before_tool_call - reescreve parâmetros de ferramenta, bloqueia a execução ou exige aprovação
• after_tool_call - observa resultados de ferramenta, erros e duração
• tool_result_persist - reescreve a mensagem do assistente produzida a partir de um resultado de ferramenta
• before_message_write - inspeciona ou bloqueia uma escrita de mensagem em andamento (raro)

• inbound_claim - reivindica uma mensagem de entrada antes do roteamento do agente (respostas sintéticas)
• message_received - observa conteúdo de entrada, remetente, thread e metadados
• message_sending - reescreve conteúdo de saída ou cancela a entrega
• message_sent - observa sucesso ou falha de entrega de saída
• before_dispatch - inspeciona ou reescreve um despacho de saída antes da transferência ao canal
• reply_dispatch - participa do pipeline final de despacho de resposta

• session_start / session_end - rastreia limites do ciclo de vida da sessão. O reason do evento é um de new, reset, idle, daily, compaction, deleted, shutdown, restart ou unknown. Os valores shutdown e restart disparam a partir do finalizador de desligamento do Gateway quando o processo é parado ou reiniciado enquanto sessões ainda estão ativas, para que Plugins downstream (como memória ou armazenamentos de transcrições) possam finalizar linhas fantasma que, de outra forma, permaneceriam em estado aberto entre reinicializações. O finalizador é limitado para que um Plugin lento não possa bloquear SIGTERM/SIGINT.
• before_compaction / after_compaction - observa ou anota ciclos de Compaction
• before_reset - observa eventos de redefinição de sessão (/reset, redefinições programáticas)

• subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - coordena roteamento de subagentes e entrega de conclusão

• gateway_start / gateway_stop - inicia ou para serviços pertencentes ao Plugin com o Gateway
• cron_changed - observa alterações de ciclo de vida de Cron pertencente ao Gateway (adicionado, atualizado, removido, iniciado, concluído, agendado)
• before_install - inspeciona varreduras de instalação de skill ou Plugin e, opcionalmente, bloqueia

​

Política de chamada de ferramenta

• event.toolName
• event.params
• event.derivedPaths opcional, contendo dicas de caminho de destino derivadas do host em regime de melhor esforço para envelopes de ferramentas conhecidos, como apply_patch; quando presentes, esses caminhos podem estar incompletos ou podem superestimar o que a ferramenta realmente tocará (por exemplo, com entradas malformadas ou parciais)
• event.runId opcional
• event.toolCallId opcional
• campos de contexto como ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (definido em execuções acionadas por Cron) e 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 é terminal e pula manipuladores de prioridade mais baixa.
• block: false é tratado como ausência de decisão.
• params reescreve os parâmetros da ferramenta para execução.
• requireApproval pausa a execução do agente e pergunta ao usuário por meio de aprovações de Plugin. O comando /approve pode aprovar aprovações de exec e de Plugin.
• Um block: true de prioridade mais baixa ainda pode bloquear depois que um gancho de prioridade mais alta solicitou aprovação.
• onResolution recebe a decisão de aprovação resolvida - allow-once, allow-always, deny, timeout ou cancelled.

​

Persistência de resultado de ferramenta

• O OpenClaw remove toolResult.details antes de repetição pelo provedor e entrada de Compaction para que metadados não se tornem contexto do modelo.
• Entradas de sessão persistidas mantêm apenas details limitados. Detalhes grandes demais são substituídos por um resumo compacto e persistedDetailsTruncated: true.
• tool_result_persist e before_message_write são executados antes do limite final de persistência. Ganchos ainda devem manter os details retornados pequenos e evitar colocar texto relevante para prompt apenas em details; coloque a saída de ferramenta visível ao modelo em content.

​

Ganchos de prompt e modelo

• before_model_resolve: recebe apenas o prompt atual e metadados de anexos. Retorne providerOverride ou modelOverride.
• agent_turn_prepare: recebe o prompt atual, mensagens de sessão preparadas e quaisquer injeções enfileiradas exatamente uma vez drenadas para esta sessão. Retorne prependContext ou appendContext.
• before_prompt_build: recebe o prompt atual e mensagens de sessão. Retorne prependContext, appendContext, systemPrompt, prependSystemContext ou appendSystemContext.
• heartbeat_prompt_contribution: é executado somente para turnos de Heartbeat e retorna prependContext ou appendContext. Ele é destinado a monitores em segundo plano que precisam resumir o estado atual sem alterar turnos iniciados pelo usuário.

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

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

​

Extensões de sessão e injeções para o próximo turno

​

Hooks de mensagem

• message_received: observa conteúdo de entrada, remetente, threadId, messageId, senderId, correlação opcional de execução/sessão e metadados.
• message_sending: reescreve content ou retorna { cancel: true }.
• message_sent: observa sucesso ou falha final.

• message_sending com cancel: true é terminal.
• message_sending com cancel: false é tratado como nenhuma decisão.
• content reescrito continua para hooks de prioridade menor, a menos que um hook posterior cancele a entrega.
• message_sending pode retornar cancelReason e metadata limitados com um cancelamento. Novas APIs de ciclo de vida de mensagem expõem isso como um resultado de entrega suprimida com o motivo cancelled_by_message_sending_hook; a entrega direta legada continua retornando um array de resultados vazio por compatibilidade.
• message_sent é somente observação. Falhas de handler são registradas e não alteram o resultado da entrega.

​

Hooks de instalação

​

Ciclo de vida do Gateway

​

Próximas descontinuações

• Envelopes de canal em texto simples em handlers inbound_claim e message_received. Leia BodyForAgent e os blocos estruturados de contexto do usuário em vez de analisar texto de envelope plano. Consulte Envelopes de canal em texto simples → BodyForAgent.
• before_agent_start permanece por compatibilidade. Novos plugins devem usar before_model_resolve e before_prompt_build em vez da fase combinada.
• onResolution em before_tool_call agora usa a união tipada PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) em vez de uma string de formato livre.

​

Relacionados

• Migração do Plugin SDK - descontinuações ativas e cronograma de remoção
• Como criar plugins
• Visão geral do Plugin SDK
• Pontos de entrada de plugin
• Hooks internos
• Detalhes internos da arquitetura de plugins