Você configurou o OpenClaw, saiu para almoçar, e quando voltou o CI estava quebrado faz duas horas. Ninguém avisou. Seu agente estava ali o tempo todo — mas esperando você perguntar.
O heartbeat resolve exatamente isso: o agente faz rondas periódicas e avisa quando encontra algo fora do lugar, sem precisar de intervenção sua.
| O que | Como | Custo |
|---|---|---|
| Heartbeat (batimento — uma checagem periódica para saber se o sistema está vivo) padrão (30 min) | Já vem habilitado | Tokens (unidades de texto processadas) do modelo principal |
| Heartbeat com modelo gratuito | model: "openrouter/nvidia/nemotron-3-super-120b-a12b:free" | R$ 0 |
| Heartbeat silencioso | target: "none" | Só roda internamente |
| Heartbeat com alerta no Telegram | target: "telegram" + to: "chat_id" | Modelo + Telegram grátis |
O que é heartbeat
Pense num vigia noturno. A cada meia hora ele percorre o prédio, verifica cada porta, olha cada corredor. Se tudo está em ordem, anota no registro: HEARTBEAT_OK. Se encontra uma janela aberta, aciona o responsável. Ele não fica na guarita esperando alguém ligar — vai lá checar por conta própria.
O heartbeat do OpenClaw funciona assim. A cada intervalo configurado, o agente “acorda”, executa o checklist do HEARTBEAT.md, e decide sozinho se precisa mandar um alerta ou só registrar que está tudo bem.
timer dispara
│
▼
lê HEARTBEAT.md
│
▼
checa cada item
│
├── tudo ok ──→ HEARTBEAT_OK (silenciado)
│ │
└── algo urgente ──→ alerta pro canal configurado
│
└── dorme → repete no próximo cicloComo funciona por baixo
A cada intervalo definido em every, o OpenClaw injeta o prompt do heartbeat na sessão (a conversa ativa entre você e o agente) principal do agente. O agente lê o arquivo HEARTBEAT.md na raiz do projeto — se ele existir — e segue as instruções ali descritas.
Se nada precisa de atenção, o agente responde HEARTBEAT_OK. Essa resposta fica oculta por padrão: ninguém vê, nenhuma notificação chega, nenhum log aparece no chat. Só é registrado internamente.
Se algo precisa de atenção, o agente envia uma mensagem para o canal configurado — Telegram, WhatsApp, ou qualquer outro suportado. A mensagem chega com contexto suficiente para você entender o que está acontecendo sem precisar abrir o terminal (a tela preta onde você digita comandos).
Um detalhe importante: se o HEARTBEAT.md estiver vazio ou ausente, o ciclo é pulado inteiramente. Nenhuma chamada ao modelo é feita. Você só paga (ou consome cota) quando tem instruções reais configuradas.
O truque do custo zero — modelo gratuito via OpenRouter
O heartbeat não precisa de um modelo poderoso. A tarefa é simples: ler um checklist curto, verificar condições de contexto e decidir se há algo urgente. Não tem geração criativa, não tem raciocínio complexo.
O OpenRouter oferece modelos gratuitos com capacidade mais do que suficiente para isso. Um deles é o nvidia/nemotron-3-super-120b-a12b:free: um modelo de 120B parâmetros que ativa apenas 12B por vez (Mixture of Experts), com custo de $0 tanto na entrada quanto na saída via OpenRouter.
A ideia é apontar o heartbeat especificamente para esse modelo, enquanto o resto dos seus agentes usa o modelo principal que você escolheu. Cada agente pode ter configurações independentes.
{
agents: {
defaults: {
heartbeat: {
every: "30m", // intervalo entre checagens — aqui a cada 30 minutos
model: "openrouter/nvidia/nemotron-3-super-120b-a12b:free", // modelo gratuito via OpenRouter
target: "last", // envia alertas para o mesmo canal da sua última conversa
activeHours: {
start: "08:00", // começa a rodar às 8h
end: "22:00", // para de rodar às 22h
timezone: "America/Sao_Paulo", // fuso horário de referência
},
},
},
},
}O campo every define o intervalo entre rondas. "30m" significa a cada 30 minutos — você pode usar "1h", "15m", "2h", o que fizer sentido para o que você está monitorando.
O model com o prefixo openrouter/ indica que essa chamada específica passa pelo OpenRouter (um serviço que centraliza acesso a vários modelos de IA) antes de chegar ao modelo. O restante da string é o identificador do modelo no catálogo do OpenRouter.
O target define onde o agente manda os alertas quando encontra algo. "last" usa o mesmo canal da última conversa ativa — útil quando você está no meio de uma sessão (conversa ativa) e quer os alertas no mesmo lugar.
O bloco activeHours limita as rondas a uma janela de horário. Fora desse intervalo, o heartbeat simplesmente não roda. O timezone usa o formato padrão de fuso horário — essencial para não receber alertas de madrugada quando você configurou para “horário comercial”.
HEARTBEAT.md — o checklist do vigia
O agente vai ler esse arquivo a cada ciclo. Mantenha-o curto e direto: quanto menor, menos tokens são consumidos e mais rápida fica a checagem.
# Checklist do heartbeat
- Olhar se tem erro no último deploy (publicação de nova versão)
- Se tem mensagem pendente no canal do Telegram
- Se alguma tarefa está bloqueada há mais de 2 horas
- Se encontrar algo urgente, avisa no Telegram
- Se nada precisa de atenção: HEARTBEAT_OKDois cuidados importantes. Primeiro: não coloque senhas, tokens ou chaves de API nesse arquivo. O agente vai ler o conteúdo, e esse contexto pode aparecer em logs dependendo da configuração. Segundo: seja específico sobre o que “urgente” significa para o seu projeto. “Algo errado” é vago demais — o agente vai interpretar de forma conservadora e provavelmente não alertar.
Receitas prontas
Cenário A — Silencioso (só roda, não avisa ninguém)
Útil quando você quer que o agente faça as checagens mas prefere consultar o histórico manualmente, sem notificações.
heartbeat: {
every: "1h", // checa a cada 1 hora
model: "openrouter/nvidia/nemotron-3-super-120b-a12b:free",
target: "none", // não envia notificações — apenas registra internamente
}Cenário B — Alerta no Telegram quando algo precisa de atenção
O mais comum para quem já usa o Telegram como canal principal. O accountId referencia a conta de bot configurada nas suas integrações.
heartbeat: {
every: "30m", // checa a cada 30 minutos
model: "openrouter/nvidia/nemotron-3-super-120b-a12b:free",
target: "telegram",
to: "SEU_CHAT_ID", // seu ID no Telegram (veja como obter abaixo)
accountId: "meu-bot", // nome do bot configurado nas suas integrações
}Cenário C — Horário comercial, WhatsApp
Para times que usam WhatsApp como canal de operação. O activeHours garante que ninguém recebe alerta fora do expediente.
heartbeat: {
every: "30m",
model: "openrouter/nvidia/nemotron-3-super-120b-a12b:free",
target: "whatsapp",
to: "+5511999999999", // número com código do país
activeHours: {
start: "09:00",
end: "18:00", // fora desse intervalo, o heartbeat não roda
timezone: "America/Sao_Paulo",
},
}Controle de visibilidade
Por padrão, os HEARTBEAT_OK ficam escondidos — você só recebe notificação quando o agente encontra algo. Três flags controlam esse comportamento:
| Flag | Padrão | O que faz |
|---|---|---|
showOk | false | Mostra HEARTBEAT_OK no canal configurado |
showAlerts | true | Mostra alertas reais no canal configurado |
useIndicator | true | Exibe um indicador visual discreto na interface |
O caso mais comum de ajuste é showOk: true para debug — você quer confirmar que o heartbeat está rodando antes de confiar que o silêncio significa “tudo bem”. Depois de validar, volta para false.
Troubleshooting
O heartbeat nunca roda
Verifique se every tem um valor maior que "0m" e se o HEARTBEAT.md existe e não está vazio. Um arquivo vazio faz o ciclo ser pulado completamente — o que pode parecer que o heartbeat está desabilitado. Se o arquivo não existir na raiz do projeto, o mesmo comportamento ocorre.
Recebo HEARTBEAT_OK no Telegram o tempo todo
O padrão do showOk é false. Se você está recebendo OKs, alguém trocou para true na configuração. Adicione showOk: false explicitamente no bloco do heartbeat para sobrescrever qualquer configuração herdada de outro lugar.
heartbeat: {
every: "30m",
showOk: false, // garante que OKs fiquem silenciosos
// resto da config...
}Quero rodar agora sem esperar o próximo ciclo
Use o comando de evento manual. O --mode now ignora o activeHours (o horário configurado) e roda imediatamente.
# Dispara o heartbeat agora, independente do horário configurado
openclaw system event --text "Checar urgências" --mode nowPróximo passo
Se você ainda está conhecendo o OpenClaw, o melhor ponto de entrada é o guia introdutório. Se já está com o agente rodando, as páginas de configuração de modelos e memória vão complementar o que você viu aqui.