Hooks

Hooks são pequenos scripts que são executados quando algo acontece dentro do Gateway. Eles podem ser descobertos a partir de diretórios e inspecionados com openclaw hooks. O Gateway carrega hooks internos somente depois que você habilita hooks ou configura pelo menos uma entrada de hook, pacote de hooks, manipulador legado ou diretório extra de hooks.

Há dois tipos de hooks no OpenClaw:

• Hooks internos (esta página): são executados dentro do Gateway quando eventos do agente disparam, como /new, /reset, /stop ou eventos de ciclo de vida.
• Webhooks: endpoints HTTP externos que permitem que outros sistemas acionem trabalho no OpenClaw. Consulte Webhooks.

Hooks também podem ser agrupados dentro de plugins. openclaw hooks list mostra tanto hooks independentes quanto hooks gerenciados por plugins.

Escolha a superfície certa

O OpenClaw tem várias superfícies de extensão que parecem similares, mas resolvem problemas diferentes:

Use hooks internos quando quiser uma automação que se comporte como uma pequena integração instalada. Use hooks de plugin tipados quando precisar de controle do ciclo de vida em tempo de execução.

Início rápido

# List available hooksopenclaw hooks list # Enable a hookopenclaw hooks enable session-memory # Check hook statusopenclaw hooks check # Get detailed informationopenclaw hooks info session-memory

Tipos de evento

Escrevendo hooks

Estrutura do hook

Cada hook é um diretório que contém dois arquivos:

my-hook/├── HOOK.md          # Metadata + documentation└── handler.ts       # Handler implementation

Formato de HOOK.md

---name: my-hookdescription: "Short description of what this hook does"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # My Hook Detailed documentation goes here.

Campos de metadados (metadata.openclaw):

Implementação do manipulador

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] New command triggered`);  // Your logic here   // Optionally send a reply on replyable surfaces  event.messages.push("Hook executed!");}; export default handler;

Cada evento inclui: type, action, sessionKey, timestamp, messages (adicione respostas aqui apenas em superfícies que aceitam resposta) e context (dados específicos do evento). Contextos de hooks de agente e de plugin de ferramentas também podem incluir trace, um contexto de rastreamento de diagnóstico somente leitura compatível com W3C que os plugins podem passar para logs estruturados para correlação com OTEL.

event.messages só é entregue automaticamente em superfícies que aceitam resposta, como command:* e message:received. Eventos apenas de ciclo de vida, como agent:bootstrap, session:*, gateway:* ou message:sent, não têm um canal de resposta e ignoram mensagens adicionadas.

Destaques do contexto de evento

Eventos de comando (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.workspaceDir, context.cfg.

Eventos de mensagem (message:received): context.from, context.content, context.channelId, context.metadata (dados específicos do provedor, incluindo senderId, senderName, guildId). context.content prefere um corpo de comando não vazio para mensagens semelhantes a comandos; em seguida, recorre ao corpo bruto de entrada e ao corpo genérico; ele não inclui enriquecimento apenas do agente, como histórico de thread ou resumos de links.

Eventos de mensagem (message:sent): context.to, context.content, context.success, context.channelId.

Eventos de mensagem (message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath.

Eventos de mensagem (message:preprocessed): context.bodyForAgent (corpo enriquecido final), context.from, context.channelId.

Eventos de bootstrap (agent:bootstrap): context.bootstrapFiles (array mutável), context.agentId.

Eventos de patch de sessão (session:patch): context.sessionEntry, context.patch (somente campos alterados), context.cfg. Somente clientes privilegiados podem acionar eventos de patch.

Eventos de Compaction: session:compact:before inclui messageCount, tokenCount. session:compact:after adiciona compactedCount, summaryLength, tokensBefore, tokensAfter.

command:stop observa o usuário emitindo /stop; ele é um ciclo de vida de cancelamento/comando, não um gate de finalização do agente. Plugins que precisam inspecionar uma resposta final natural e pedir ao agente mais uma passagem devem usar o hook de plugin tipado before_agent_finalize em vez disso. Consulte Hooks de plugin.

Eventos de ciclo de vida do Gateway: gateway:shutdown inclui reason e restartExpectedMs e dispara quando o desligamento do gateway começa. gateway:pre-restart inclui o mesmo contexto, mas dispara somente quando o desligamento faz parte de uma reinicialização esperada e um valor finito de restartExpectedMs é fornecido. Durante o desligamento, a espera de cada hook de ciclo de vida é de melhor esforço e limitada, para que o desligamento continue se um manipulador travar. O orçamento de espera padrão é de 5 segundos para gateway:shutdown e 10 segundos para gateway:pre-restart.

Use gateway:pre-restart para avisos curtos de reinicialização enquanto os canais ainda estão disponíveis:

  const execFileAsync = promisify(execFile); export default async function handler(event) {  if (event.type !== "gateway" || event.action !== "pre-restart") {    return;  }   const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000);  await execFileAsync("openclaw", [    "system",    "event",    "--mode",    "now",    "--text",    `Gateway restarting in ~${restartInSeconds}s (${event.context.reason}). Checkpoint now.`,  ]);}

Entre o evento gateway:shutdown (ou gateway:pre-restart) e o restante da sequência de desligamento, o gateway também dispara um hook de plugin tipado session_end para cada sessão que ainda estava ativa quando o processo parou. O reason do evento é shutdown para uma parada simples por SIGTERM/SIGINT e restart quando o fechamento foi agendado como parte de uma reinicialização esperada. Essa drenagem é limitada para que um manipulador session_end lento não possa bloquear a saída do processo, e sessões que já foram finalizadas por substituição / redefinição / exclusão / compactação são ignoradas para evitar disparo duplicado.

Descoberta de hooks

Hooks são descobertos a partir destes diretórios, em ordem crescente de precedência de substituição:

1. Hooks agrupados: enviados com o OpenClaw
2. Hooks de plugin: hooks agrupados dentro de plugins instalados
3. Hooks gerenciados: ~/.openclaw/hooks/ (instalados pelo usuário, compartilhados entre workspaces). Diretórios extras de hooks.internal.load.extraDirs compartilham esta precedência.
4. Hooks de workspace: <workspace>/hooks/ (por agente, desabilitados por padrão até serem habilitados explicitamente)

Hooks de workspace podem adicionar novos nomes de hook, mas não podem substituir hooks agrupados, gerenciados ou fornecidos por plugins com o mesmo nome.

O Gateway ignora a descoberta de hooks internos na inicialização até que hooks internos estejam configurados. Habilite um hook agrupado ou gerenciado com openclaw hooks enable <name>, instale um pacote de hooks ou defina hooks.internal.enabled=true para optar por entrar. Quando você habilita um hook nomeado, o Gateway carrega apenas o manipulador desse hook; hooks.internal.enabled=true, diretórios extras de hooks e manipuladores legados optam por descoberta ampla.

Pacotes de hooks

Pacotes de hooks são pacotes npm que exportam hooks via openclaw.hooks em package.json. Instale com:

openclaw plugins install <path-or-spec>

Specs npm são apenas de registro (nome do pacote + versão exata opcional ou dist-tag). Specs Git/URL/arquivo e intervalos semver são rejeitados.

Hooks agrupados

Ative qualquer hook incluído:

openclaw hooks enable <hook-name>

Detalhes de session-memory

Extrai as últimas 15 mensagens de usuário/assistente e salva em <workspace>/memory/YYYY-MM-DD-HHMM.md usando a data local do host. A captura de memória é executada em segundo plano, para que as confirmações de /new e /reset não sejam atrasadas por leituras de transcrição ou geração opcional de slug. Defina hooks.internal.entries.session-memory.llmSlug: true para gerar slugs descritivos de nome de arquivo com o modelo configurado. Requer que workspace.dir esteja configurado.

Configuração de bootstrap-extra-files

{  "hooks": {    "internal": {      "entries": {        "bootstrap-extra-files": {          "enabled": true,          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]        }      }    }  }}

Os caminhos são resolvidos em relação ao workspace. Somente nomes base de bootstrap reconhecidos são carregados (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md).

Detalhes de command-logger

Registra todos os comandos de barra em ~/.openclaw/logs/commands.log.

Detalhes de compaction-notifier

Envia mensagens curtas de status para a conversa atual quando o OpenClaw começa e termina a compactação da transcrição da sessão. Isso torna turnos longos menos confusos em superfícies de chat, porque o usuário pode ver que o assistente está resumindo o contexto e continuará após a Compaction.

Detalhes de boot-md

Executa BOOT.md do workspace ativo quando o gateway inicia.

Hooks de Plugin

Plugins podem registrar hooks tipados por meio do Plugin SDK para uma integração mais profunda: interceptar chamadas de ferramentas, modificar prompts, controlar o fluxo de mensagens e mais. Use hooks de plugin quando precisar de before_tool_call, before_agent_reply, before_install ou outros hooks de ciclo de vida em processo.

Hooks internos gerenciados por plugin são diferentes: eles participam do sistema amplo de eventos de comando/ciclo de vida desta página e aparecem em openclaw hooks list como plugin:<id>. Use-os para efeitos colaterais e compatibilidade com pacotes de hooks, não para middleware ordenado ou barreiras de política.

Para a referência completa de hooks de plugin, veja Hooks de Plugin.

Configuração

{  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": false }      }    }  }}

Variáveis de ambiente por hook:

{  "hooks": {    "internal": {      "entries": {        "my-hook": {          "enabled": true,          "env": { "MY_CUSTOM_VAR": "value" }        }      }    }  }}

Diretórios extras de hooks:

{  "hooks": {    "internal": {      "load": {        "extraDirs": ["/path/to/more/hooks"]      }    }  }}

Referência da CLI

# Listar todos os hooks (adicione --eligible, --verbose ou --json)openclaw hooks list # Mostrar informações detalhadas sobre um hookopenclaw hooks info <hook-name> # Mostrar resumo de elegibilidadeopenclaw hooks check # Ativar/desativaropenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

Boas práticas

• Mantenha os handlers rápidos. Hooks são executados durante o processamento de comandos. Dispare trabalhos pesados sem aguardar com void processInBackground(event).
• Trate erros com cuidado. Envolva operações arriscadas em try/catch; não lance exceções para que outros handlers possam ser executados.
• Filtre eventos cedo. Retorne imediatamente se o tipo/ação do evento não for relevante.
• Use chaves de evento específicas. Prefira "events": ["command:new"] em vez de "events": ["command"] para reduzir a sobrecarga.

Solução de problemas

Hook não descoberto

# Verificar estrutura do diretóriols -la ~/.openclaw/hooks/my-hook/# Deve mostrar: HOOK.md, handler.ts # Listar todos os hooks descobertosopenclaw hooks list

Hook não elegível

openclaw hooks info my-hook

Verifique binários ausentes (PATH), variáveis de ambiente, valores de configuração ou compatibilidade com o sistema operacional.

Hook não executando

1. Verifique se o hook está ativado: openclaw hooks list
2. Reinicie seu processo de gateway para que os hooks sejam recarregados.
3. Verifique os logs do gateway: ./scripts/clawlog.sh | grep hook

Relacionados

• Referência da CLI: hooks
• Webhooks
• Hooks de Plugin — hooks de ciclo de vida de plugin em processo
• Configuração