Heartbeat

O Heartbeat executa turnos periódicos do agente na sessão principal para que o modelo possa apresentar qualquer coisa que precise de atenção sem enviar mensagens em excesso.

O Heartbeat é um turno agendado da sessão principal — ele não cria registros de tarefas em segundo plano. Os registros de tarefas destinam-se a trabalhos desvinculados (execuções ACP, subagentes e trabalhos Cron isolados).

Solução de problemas: Tarefas agendadas

Início rápido (iniciante)

Exemplo de configuração:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress        lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files        isolatedSession: true, // optional: fresh session each run (no conversation history)        skipWhenBusy: true, // optional: also defer when this agent's subagent or nested lanes are busy        // activeHours: { start: "08:00", end: "24:00" },        // includeReasoning: true, // optional: send separate `Thinking` message too      },    },  },}

Padrões

• Intervalo: 30m. A aplicação dos padrões do provedor Anthropic aumenta esse valor para 1h quando o modo de autenticação resolvido é OAuth/por token (incluindo a reutilização da CLI do Claude), mas somente enquanto heartbeat.every não estiver definido. Defina agents.defaults.heartbeat.every ou agents.list[].heartbeat.every por agente; use 0m para desativar.
• Corpo do prompt (configurável por meio de agents.defaults.heartbeat.prompt): Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
• Tempo limite: turnos de Heartbeat sem um valor definido usam agents.defaults.timeoutSeconds quando configurado. Caso contrário, usam a frequência do Heartbeat, limitada a 600 segundos. Defina agents.defaults.heartbeat.timeoutSeconds ou agents.list[].heartbeat.timeoutSeconds por agente para trabalhos de Heartbeat mais longos.
• O prompt do Heartbeat é enviado textualmente como a mensagem do usuário. O prompt do sistema inclui uma seção "Heartbeats" somente quando os Heartbeats estão ativados para o agente padrão (e includeSystemPromptSection não é false), e a execução é sinalizada internamente.
• Quando os Heartbeats são desativados com 0m, as execuções normais também omitem HEARTBEAT.md do contexto de inicialização para que o modelo não veja instruções exclusivas de Heartbeat.
• O horário ativo (heartbeat.activeHours) é verificado no fuso horário configurado. Fora desse período, os Heartbeats são ignorados até a próxima marcação dentro do período.
• Os Heartbeats são adiados automaticamente enquanto houver trabalho Cron ativo ou na fila. Defina heartbeat.skipWhenBusy: true para também adiar um agente quando seu próprio subagente vinculado à chave de sessão ou suas linhas de comando aninhadas estiverem ocupados; agentes pares não são mais pausados apenas porque outro agente tem trabalho de subagente em andamento.

Para que serve o prompt do Heartbeat

O prompt padrão é intencionalmente abrangente:

• Tarefas em segundo plano: "Considere as tarefas pendentes" incentiva o agente a revisar acompanhamentos (caixa de entrada, calendário, lembretes e trabalhos na fila) e apresentar qualquer coisa urgente.
• Contato com a pessoa: "Às vezes, verifique como está sua pessoa durante o dia" incentiva uma mensagem ocasional e breve perguntando "precisa de algo?", mas evita mensagens excessivas durante a noite usando o fuso horário local configurado (consulte Fuso horário).

O Heartbeat pode reagir a tarefas em segundo plano concluídas, mas uma execução de Heartbeat não cria um registro de tarefa.

Se quiser que um Heartbeat faça algo muito específico (por exemplo, "verificar as estatísticas do Gmail PubSub" ou "verificar a integridade do Gateway"), defina agents.defaults.heartbeat.prompt (ou agents.list[].heartbeat.prompt) com um corpo personalizado (enviado textualmente).

Contrato de resposta

• Se nada precisar de atenção, responda com HEARTBEAT_OK.
• Em vez disso, as execuções de Heartbeat podem chamar heartbeat_respond com notify: false para não exibir nenhuma atualização, ou com notify: true e notificationText para emitir um alerta. Quando presente, a resposta estruturada da ferramenta tem precedência sobre o texto alternativo.
• Durante execuções de Heartbeat, o OpenClaw trata HEARTBEAT_OK como uma confirmação quando aparece no início ou no fim da resposta. O token é removido, e a resposta é descartada se o conteúdo restante tiver ≤ ackMaxChars (padrão: 300).
• Se HEARTBEAT_OK aparecer no meio de uma resposta, ele não receberá tratamento especial.
• Para alertas, não inclua HEARTBEAT_OK; retorne apenas o texto do alerta.

Fora dos Heartbeats, ocorrências isoladas de HEARTBEAT_OK no início ou no fim de uma mensagem são removidas e registradas; uma mensagem que contenha apenas HEARTBEAT_OK é descartada.

Configuração

{  agents: {    defaults: {      heartbeat: {        every: "30m", // default: 30m (0m disables)        model: "anthropic/claude-opus-4-6",        includeReasoning: false, // default: false (deliver separate Thinking message when available)        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "imessage")        to: "+15551234567", // optional channel-specific override        accountId: "ops-bot", // optional multi-account channel id        prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",        includeSystemPromptSection: true, // default: true; false omits the ## Heartbeats system prompt section for the default agent        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK      },    },  },}

Escopo e precedência

• agents.defaults.heartbeat define o comportamento global do Heartbeat.
• agents.list[].heartbeat é mesclado por cima; se qualquer agente tiver um bloco heartbeat, somente esses agentes executarão Heartbeats.
• channels.defaults.heartbeat define os padrões de visibilidade para todos os canais.
• channels.<channel>.heartbeat substitui os padrões do canal.
• channels.<channel>.accounts.<id>.heartbeat (canais com várias contas) substitui as configurações por canal.

Heartbeats por agente

Se qualquer entrada de agents.list[] incluir um bloco heartbeat, somente esses agentes executarão Heartbeats. O bloco por agente é mesclado por cima de agents.defaults.heartbeat (assim, você pode definir padrões compartilhados uma vez e substituí-los por agente).

Exemplo: dois agentes, mas somente o segundo executa Heartbeats.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",        },      },    ],  },}

Exemplo de horário ativo

Restrinja os Heartbeats ao horário comercial em um fuso horário específico:

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz        },      },    },  },}

Fora desse período (antes das 9h ou depois das 22h no horário do leste dos EUA), os Heartbeats são ignorados. A próxima marcação agendada dentro do período será executada normalmente.

Configuração 24 horas por dia, 7 dias por semana

Se quiser que os Heartbeats sejam executados o dia inteiro, use um destes padrões:

• Omita completamente activeHours (sem restrição de período; esse é o comportamento padrão).
• Defina um período de dia inteiro: activeHours: { start: "00:00", end: "24:00" }.

Exemplo com várias contas

Use accountId para direcionar a uma conta específica em canais com várias contas, como o Telegram:

{  agents: {    list: [      {        id: "ops",        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // optional: route to a specific topic/thread          accountId: "ops-bot",        },      },    ],  },  channels: {    telegram: {      accounts: {        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },      },    },  },}

Observações sobre os campos

Comportamento da entrega

Controles de visibilidade

Por padrão, as confirmações HEARTBEAT_OK são suprimidas enquanto o conteúdo de alerta é entregue. Você pode ajustar isso por canal ou por conta:

channels:  defaults:    heartbeat:      showOk: false # Ocultar HEARTBEAT_OK (padrão)      showAlerts: true # Exibir mensagens de alerta (padrão)      useIndicator: true # Emitir eventos de indicador (padrão)  telegram:    heartbeat:      showOk: true # Exibir confirmações OK no Telegram  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # Suprimir a entrega de alertas para esta conta

Precedência: por conta → por canal → padrões do canal → padrões integrados.

O que cada sinalizador faz

• showOk: envia uma confirmação HEARTBEAT_OK quando o modelo retorna uma resposta contendo apenas OK.
• showAlerts: envia o conteúdo do alerta quando o modelo retorna uma resposta diferente de OK.
• useIndicator: emite eventos de indicador para superfícies de status da interface.

Se todos os três forem falsos, o OpenClaw ignorará completamente a execução do Heartbeat (sem chamada ao modelo).

Exemplos por canal e por conta

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # todas as contas do Slack    accounts:      ops:        heartbeat:          showAlerts: false # suprimir alertas apenas para a conta ops  telegram:    heartbeat:      showOk: true

Padrões comuns

HEARTBEAT.md (opcional)

Se houver um arquivo HEARTBEAT.md no espaço de trabalho, o prompt padrão instruirá o agente a lê-lo. Pense nele como sua "lista de verificação de Heartbeat": pequena, estável e segura para ser considerada a cada 30 minutos.

Em execuções normais, HEARTBEAT.md só é injetado quando a orientação de Heartbeat está ativada para o agente padrão. Desativar a cadência do Heartbeat com 0m ou definir includeSystemPromptSection: false o omite do contexto normal de inicialização.

No ambiente nativo do Codex, o conteúdo de HEARTBEAT.md não é injetado no turno como outros arquivos de inicialização. Se o arquivo existir e tiver conteúdo que não seja apenas espaço em branco, uma observação do modo de colaboração do Heartbeat direcionará o Codex ao arquivo e o instruirá a lê-lo antes de prosseguir.

Se HEARTBEAT.md existir, mas estiver efetivamente vazio (apenas linhas em branco, comentários Markdown/HTML, títulos Markdown como # Heading, marcadores de bloco ou itens vazios de lista de verificação), o OpenClaw ignorará a execução do Heartbeat para economizar chamadas à API. Essa omissão é relatada como reason=empty-heartbeat-file. Se o arquivo não existir, o Heartbeat ainda será executado e o modelo decidirá o que fazer.

Mantenha-o pequeno (uma lista de verificação curta ou lembretes) para evitar o inchaço do prompt.

Exemplo de HEARTBEAT.md:

# Lista de verificação de Heartbeat - Verificação rápida: há algo urgente nas caixas de entrada?- Se for durante o dia, faça uma verificação breve se não houver mais nada pendente.- Se uma tarefa estiver bloqueada, anote _o que está faltando_ e pergunte ao Peter na próxima vez.

Blocos tasks:

O HEARTBEAT.md também oferece suporte a um pequeno bloco estruturado tasks: para verificações baseadas em intervalos dentro do próprio Heartbeat.

Exemplo:

tasks: - name: inbox-triage  interval: 30m  prompt: "Verifique se há e-mails urgentes não lidos e sinalize qualquer item com prazo crítico."- name: calendar-scan  interval: 2h  prompt: "Verifique se há reuniões próximas que precisem de preparação ou acompanhamento." # Instruções adicionais - Mantenha os alertas curtos.- Se nada precisar de atenção depois de todas as tarefas pendentes, responda HEARTBEAT_OK.

O modo de tarefas é útil quando você quer que um único arquivo de Heartbeat contenha várias verificações periódicas sem pagar por todas elas a cada execução.

O agente pode atualizar o HEARTBEAT.md?

Sim — se você pedir.

HEARTBEAT.md é apenas um arquivo normal no espaço de trabalho do agente, portanto, você pode dizer ao agente (em um chat normal) algo como:

• "Atualize HEARTBEAT.md para adicionar uma verificação diária do calendário."
• "Reescreva HEARTBEAT.md para que fique mais curto e focado nos acompanhamentos da caixa de entrada."

Se quiser que isso aconteça proativamente, você também pode incluir uma linha explícita no prompt do Heartbeat, como: "Se a lista de verificação ficar desatualizada, atualize HEARTBEAT.md com uma versão melhor."

Ativação manual (sob demanda)

Use openclaw system event para enfileirar um evento do sistema e, opcionalmente, acionar um Heartbeat imediato:

openclaw system event --text "Check for urgent follow-ups" --mode now

Se nenhum --session-key for fornecido e vários agentes tiverem heartbeat configurado, --mode now executará imediatamente o Heartbeat de cada um desses agentes.

Controles relacionados ao Heartbeat no mesmo grupo da CLI:

openclaw system heartbeat last     # exibir o último evento de Heartbeatopenclaw system heartbeat enable   # ativar Heartbeatsopenclaw system heartbeat disable  # desativar Heartbeats

Entrega de raciocínio (opcional)

Por padrão, os heartbeats entregam apenas o payload final de "resposta".

Se quiser transparência, ative:

• agents.defaults.heartbeat.includeReasoning: true

Quando ativado, os heartbeats também entregarão uma mensagem separada com o prefixo Thinking (no mesmo formato de /reasoning on). Isso pode ser útil quando o agente está gerenciando várias sessões/codexes e você quer saber por que ele decidiu enviar uma notificação — mas também pode expor mais detalhes internos do que você deseja. Prefira mantê-lo desativado em conversas em grupo.

Considerações sobre custos

Os heartbeats executam turnos completos do agente. Intervalos menores consomem mais tokens. Para reduzir os custos:

• Use isolatedSession: true para evitar o envio de todo o histórico da conversa (de cerca de 100 mil tokens para aproximadamente 2 a 5 mil por execução).
• Use lightContext: true para limitar os arquivos de inicialização apenas ao HEARTBEAT.md.
• Defina um model mais econômico (por exemplo, ollama/llama3.2:1b).
• Mantenha o HEARTBEAT.md pequeno.
• Use target: "none" se quiser apenas atualizações de estado internas.

Estouro de contexto após o heartbeat

Os heartbeats preservam o modelo de runtime existente da sessão compartilhada após a conclusão da execução. Portanto, um heartbeat que tenha mudado uma sessão para um modelo local menor (por exemplo, um modelo do Ollama com uma janela de 32 mil tokens) pode manter esse modelo ativo no próximo turno da sessão principal. Se esse próximo turno relatar um estouro de contexto e o último modelo de runtime da sessão corresponder ao heartbeat.model configurado, a mensagem de recuperação do OpenClaw indicará a propagação do modelo do heartbeat como a causa provável e sugerirá uma correção.

Para evitar isso: use isolatedSession: true para executar os heartbeats em uma nova sessão (opcionalmente combinado com lightContext: true para obter o menor prompt possível) ou escolha um modelo de heartbeat com uma janela de contexto grande o suficiente para a sessão compartilhada.

Relacionado

• Automação — visão geral de todos os mecanismos de automação
• Tarefas em segundo plano — como o trabalho desvinculado é monitorado
• Fuso horário — como o fuso horário afeta o agendamento de heartbeats
• Solução de problemas — depuração de problemas de automação