OpenClaw Hooks: O guia completo do desenvolvedor (2026) — EasyClaw

Como funciona a descoberta de gancho OpenClaw

O Gateway usa verificação automática de diretório para descobrir ganchos. Na inicialização, ele verifica os diretórios de ganchos configurados e carrega todos os pacotes de ganchos válidos que encontrar.

Dois pré-requisitos importantes antes da ativação dos ganchos:

1. Hooks deve ser explicitamente ativado — um diretório de gancho por si só não é suficiente
2. Pelo menos uma entrada de gancho deve ser configurada nas configurações do seu gateway

Cada pacote de ganchos requer exatamente dois arquivos:

• HOOK.md — arquivo de metadados que declara o nome do gancho, versão, descrição, assinaturas de eventos de ciclo de vida e quaisquer permissões necessárias
• handler.ts (ou handler.js) — o arquivo de implementação que contém a lógica real que é executada quando o evento é acionado

Os quatro eventos do ciclo de vida que todo desenvolvedor deve conhecer

PreToolUse é o mais poderoso - é o único evento que pode abortar uma chamada de ferramenta antes de ser executada. Se o seu gancho retornar um sinal de rejeição durante PreToolUse, o agente nunca chamará a ferramenta.

PostToolUse é o carro-chefe da automação. Arquivo escrito? Execute seu linter. Teste modificado? Execute o conjunto. Código confirmado? Acione uma compilação.

Step-by-Step: Escrevendo seu primeiro gancho personalizado do zero

A maior parte da documentação mostra comandos. Isso mostra o caminho completo do nada até um gancho funcional.

Step 1 — Crie o diretório de gancho

mkdir -p .openclaw/hooks/auto-lint

Step 2 — Escreva os metadados HOOK.md

# auto-lint

**Version:** 1.0.0
**Event:** PostToolUse
**Description:** Runs ESLint on any file written by the agent
**Tools:** write_file, edit_file

O campo Tools abrange seu gancho para chamadas de ferramentas específicas. Sem ele, o gancho dispara todo Evento PostToolUse - geralmente não é o que você deseja.

Step 3 — Implementar handler.ts

import { PostToolUseEvent } from "@openclaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const filePath = event.toolResult?.path;
  if (!filePath) return;

  try {
    execSync(`npx eslint --fix "${filePath}"`, { stdio: "inherit" });
  } catch (err) {
    console.error(`[auto-lint] ESLint failed on ${filePath}`);
  }
}

Step 4 — Habilitar via CLI

openclaw hooks enable auto-lint

Step 5 — Verifique se está carregado

openclaw hooks list

Você deverá ver auto-lint com status enabled. Inicie uma sessão, escreva um arquivo e observe o linter disparar.

JavaScript vs. TypeScript para manipuladores de ganchos – O que escolher em 2026

O SDK é fornecido com tipificações TypeScript completas e, a partir das versões 2026 do SDK, TypeScript é o padrão recomendado para novos ganchos.

Se você estiver escrevendo um gancho que irá comprometer com o controle de versão ou compartilhar com uma equipe, use TypeScript. Para uma proteção local descartável, JavaScript simples é adequado - basta nomeá-lo handler.js e pular a etapa de compilação.

OpenClaw Hooks CLI Reference

Managing Hook Packs — Instalação, atualização e fluxo de trabalho --dry-run

Os pacotes de ganchos agrupam vários ganchos relacionados como uma única unidade instalável. O fluxo de trabalho de instalação verifica um hash de integridade antes de gravar qualquer coisa no disco.

# Preview what would be installed without committing
openclaw hooks install productivity-pack --dry-run

# Install non-interactively (for CI environments)
openclaw hooks install productivity-pack --yes

# Update all installed packs
openclaw hooks update --all

Bundled Hooks Reference: O que vem com OpenClaw

Execute openclaw hooks inspect session-memory para ver todas as opções de configuração. A maioria dos ganchos incluídos vem com padrões razoáveis, mas expõe campos de configuração para personalização.

Casos de uso de ganchos do mundo real (com exemplos práticos)

1. File Protection Guardrail (PreToolUse)

Evite que o agente toque no seu arquivo .env:

import { PreToolUseEvent } from "@openclaw/sdk";

export default function handler(event: PreToolUseEvent) {
  const target = event.toolInput?.path ?? "";
  if (target.includes(".env")) {
    return { abort: true, reason: "Modification of .env files is blocked by policy." };
  }
}

Solte isso em .openclaw/hooks/protect-env/ com o HOOK.md correspondente inscrito em PreToolUse com escopo para write_file e edit_file. O agente recebe o motivo da rejeição em seu contexto e não tentará novamente.

2. Slack Notification on Session Stop

import { StopEvent } from "@openclaw/sdk";

export default async function handler(event: StopEvent) {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `OpenClaw session ended. Files modified: ${event.session.filesModified ?? 0}`
    })
  });
}

Inscreva este gancho no evento Stop. Cada final de sessão dispara uma mensagem Slack com um resumo. Não é necessário servidor externo — o processo Gateway faz a solicitação de saída diretamente.

3. Auto-Format + Test on PostToolUse

import { PostToolUseEvent } from "@openclaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const file = event.toolResult?.path;
  if (!file?.endsWith(".ts")) return;

  execSync(`prettier --write "${file}"`);
  execSync("npm test -- --passWithNoTests", { stdio: "inherit" });
}

Isso é acionado após cada gravação do arquivo TypeScript, formata-o e executa seu conjunto de testes. Lento em projetos grandes – faça um escopo rigoroso usando o campo Tools em HOOK.md.

Hooks para equipes — Aplicação de proteções em um projeto compartilhado

Confirme seu diretório .openclaw/hooks/ para controle de versão. Cada desenvolvedor que clona o repositório automaticamente tem a mesma configuração de gancho.

• Bloqueie ganchos críticos para enabled na configuração do projeto — evita que colegas de equipe desativem acidentalmente os protetores de arquivos
• Use descrições HOOK.md para documentar a intenção - trate-os como comentários de código, os colegas de equipe irão lê-los
• Scope hooks to tool-level granularity — ganchos amplos retardam todas as interações dos agentes, criando atrito que faz com que os colegas de equipe os desativem
• Em monorepos, os ganchos em um diretório pai se aplicam a todos os projetos aninhados, a menos que sejam substituídos no nível do subdiretório

CI/CD Integration — Executando OpenClaw Hooks de forma não interativa

Em ações GitHub ou em qualquer ambiente headless, o prompt de confirmação interativo irá travar seu pipeline. Use --yes para pular:

- name: Install hooks non-interactively
  run: openclaw hooks install qa-pack --yes

- name: Run OpenClaw session
  env:
    OPENCLAW_HOOKS_ENABLED: "true"
    SLACK_WEBHOOK_URL: secrets.SLACK_WEBHOOK_URL
  run: openclaw run --task "audit dependencies" --yes

Hook Security: o que funciona, o que pode acessar e como se manter seguro

Esta é a parte que a maioria da documentação ignora completamente — e é a seção mais importante se você estiver instalando pacotes de ganchos da comunidade.

Quais ganchos podem acessar: Os scripts de gancho herdam o permissões completas do processo Gateway. Se o Gateway for executado como sua conta de usuário, seus ganchos poderão ler qualquer arquivo que a conta possa ler, fazer solicitações de rede, executar subprocessos e acessar variáveis ​​de ambiente, incluindo segredos.

Hook Pack Audit Checklist

Execute isto antes de instalar qualquer pacote de terceiros:

O comando openclaw hooks inspect mostra o caminho de origem completo de um gancho instalado — use-o para revisar novamente o código do manipulador após as atualizações.

Troubleshooting OpenClaw Hooks – Quando eles não disparam

Perguntas frequentes

Considerações finais – Escolhendo a estratégia de gancho certa para o seu fluxo de trabalho

Comece com um gancho que resolva um problema real – um protetor de arquivo ou um linter pós-gravação. Faça com que funcione de ponta a ponta antes de aplicar mais camadas. O poder dos ganchos se compõe: uma sessão com três ganchos com bom escopo funcionando perfeitamente é significativamente mais confiável do que uma com dez ganchos com escopo ruim em que você não confia.