Heartbeat

Heartbeat executa turnos periódicos do agente na sessão principal para que o modelo possa destacar qualquer coisa que precise de atenção sem enviar spam.

Heartbeat é um turno agendado da sessão principal — ele não cria registros de tarefa em segundo plano. Registros de tarefas são para trabalho destacado (execuções ACP, subagentes, trabalhos Cron isolados).

Solução de problemas: Tarefas Agendadas

Início rápido (iniciante)

Configuração de exemplo:

{  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 (ou 1h quando autenticação Anthropic OAuth/token for o modo de autenticação detectado, incluindo reutilização da Claude CLI). Defina agents.defaults.heartbeat.every ou agents.list[].heartbeat.every por agente; use 0m para desativar.
• Corpo do prompt (configurável por 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 definição usam agents.defaults.timeoutSeconds quando definido. Caso contrário, usam a cadência do heartbeat limitada a 600 segundos. Defina agents.defaults.heartbeat.timeoutSeconds ou agents.list[].heartbeat.timeoutSeconds por agente para trabalho de heartbeat mais longo.
• O prompt de heartbeat é enviado literalmente como a mensagem do usuário. O prompt do sistema inclui uma seção "Heartbeat" apenas quando heartbeats estão ativados para o agente padrão, e a execução é marcada internamente.
• Quando heartbeats são desativados com 0m, execuções normais também omitem HEARTBEAT.md do contexto de bootstrap para que o modelo não veja instruções exclusivas de heartbeat.
• Horários ativos (heartbeat.activeHours) são verificados no fuso horário configurado. Fora da janela, heartbeats são ignorados até o próximo tick dentro da janela.
• Heartbeats são automaticamente adiados enquanto trabalho Cron está ativo ou enfileirado. Defina heartbeat.skipWhenBusy: true para também adiar um agente em suas próprias lanes de subagente ou comando aninhado com chave de sessão; agentes irmãos não pausam mais apenas porque outro agente tem trabalho de subagente em andamento.

Para que serve o prompt de heartbeat

O prompt padrão é intencionalmente amplo:

• Tarefas em segundo plano: "Consider outstanding tasks" incentiva o agente a revisar acompanhamentos (caixa de entrada, calendário, lembretes, trabalho enfileirado) e destacar qualquer coisa urgente.
• Check-in humano: "Checkup sometimes on your human during day time" incentiva uma mensagem leve ocasional de "precisa de algo?", mas evita spam noturno usando seu fuso horário local configurado (veja Fuso horário).

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

Se você quiser que um heartbeat faça algo muito específico (por exemplo, "check Gmail PubSub stats" ou "verify gateway health"), defina agents.defaults.heartbeat.prompt (ou agents.list[].heartbeat.prompt) para um corpo personalizado (enviado literalmente).

Contrato de resposta

• Se nada precisar de atenção, responda com HEARTBEAT_OK.
• Execuções de heartbeat com capacidade de ferramenta podem, em vez disso, chamar heartbeat_respond com notify: false para nenhuma atualização visível, ou notify: true mais notificationText para um alerta. Quando presente, a resposta estruturada da ferramenta tem precedência sobre o fallback de texto.
• Durante execuções de heartbeat, o OpenClaw trata HEARTBEAT_OK como um ack quando aparece no início ou 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 será tratado de forma especial.
• Para alertas, não inclua HEARTBEAT_OK; retorne apenas o texto do alerta.

Fora de heartbeats, HEARTBEAT_OK avulso no início/fim de uma mensagem é removido e registrado; uma mensagem que contém 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.",        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK      },    },  },}

Escopo e precedência

• agents.defaults.heartbeat define o comportamento global de heartbeat.
• agents.list[].heartbeat é mesclado por cima; se qualquer agente tiver um bloco heartbeat, somente esses agentes executam heartbeats.
• channels.defaults.heartbeat define 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 agents.list[] incluir um bloco heartbeat, somente esses agentes executam heartbeats. O bloco por agente é mesclado por cima de agents.defaults.heartbeat (assim você pode definir padrões compartilhados uma vez e substituir por agente).

Exemplo: dois agentes, apenas o segundo agente 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 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 desta janela (antes das 9h ou depois das 22h no horário do Leste), os heartbeats são ignorados. O próximo tick agendado dentro da janela será executado normalmente.

Configuração 24/7

Se quiser que heartbeats sejam executados o dia todo, use um destes padrões:

• Omita activeHours completamente (sem restrição de janela de tempo; este é o comportamento padrão).
• Defina uma janela de dia inteiro: activeHours: { start: "00:00", end: "24:00" }.

Exemplo com várias contas

Use accountId para direcionar uma conta específica em canais com várias contas, como 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 dos campos

Comportamento de entrega

Controles de visibilidade

Por padrão, 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 # Hide HEARTBEAT_OK (default)      showAlerts: true # Show alert messages (default)      useIndicator: true # Emit indicator events (default)  telegram:    heartbeat:      showOk: true # Show OK acknowledgments on Telegram  whatsapp:    accounts:      work:        heartbeat:          showAlerts: false # Suppress alert delivery for this account

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

O que cada flag faz

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

Se todos os três forem falsos, o OpenClaw ignora totalmente a execução de Heartbeat (sem chamada ao modelo).

Exemplos por canal vs. por conta

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # all Slack accounts    accounts:      ops:        heartbeat:          showAlerts: false # suppress alerts for the ops account only  telegram:    heartbeat:      showOk: true

Padrões comuns

HEARTBEAT.md (opcional)

Se um arquivo HEARTBEAT.md existir no workspace, o prompt padrão instrui o agente a lê-lo. Pense nele como sua "lista de verificação de Heartbeat": pequena, estável e segura para considerar 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 de Heartbeat com 0m ou definir includeSystemPromptSection: false o omite do contexto normal de bootstrap.

No harness nativo do Codex, o conteúdo de HEARTBEAT.md não é injetado no turno. Se o arquivo existir e tiver conteúdo que não seja espaço em branco, as instruções de modo de colaboração de Heartbeat apontam o Codex para o arquivo e dizem para ele ler antes de prosseguir.

Se HEARTBEAT.md existir, mas estiver efetivamente vazio (apenas linhas em branco, comentários Markdown/HTML, cabeçalhos Markdown como # Heading, marcadores de fence ou stubs vazios de lista de verificação), o OpenClaw ignora a execução de Heartbeat para economizar chamadas de API. Esse salto é relatado como reason=empty-heartbeat-file. Se o arquivo estiver ausente, o Heartbeat ainda é executado e o modelo decide o que fazer.

Mantenha-o minúsculo (lista curta de verificação ou lembretes) para evitar inchaço do prompt.

Exemplo de HEARTBEAT.md:

# Heartbeat checklist - Quick scan: anything urgent in inboxes?- If it's daytime, do a lightweight check-in if nothing else is pending.- If a task is blocked, write down _what is missing_ and ask Peter next time.

Blocos tasks:

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

Exemplo:

tasks: - name: inbox-triage  interval: 30m  prompt: "Check for urgent unread emails and flag anything time sensitive."- name: calendar-scan  interval: 2h  prompt: "Check for upcoming meetings that need prep or follow-up." # Additional instructions - Keep alerts short.- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.

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

O agente pode atualizar HEARTBEAT.md?

Sim — se você pedir.

HEARTBEAT.md é apenas um arquivo normal no workspace do agente, então você pode dizer ao agente (em um chat normal) algo como:

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

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

Despertar manual (sob demanda)

Você pode enfileirar um evento de sistema e acionar um Heartbeat imediato com:

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

Se vários agentes tiverem heartbeat configurado, um despertar manual executa imediatamente cada um desses Heartbeats de agente.

Use --mode next-heartbeat para aguardar o próximo tick agendado.

Entrega de raciocínio (opcional)

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

Se quiser transparência, ative:

• agents.defaults.heartbeat.includeReasoning: true

Quando ativado, Heartbeats também entregarão uma mensagem separada prefixada com Thinking (mesmo formato de /reasoning on). Isso pode ser útil quando o agente está gerenciando várias sessões/codexes e você quer ver por que ele decidiu chamar sua atenção — mas também pode vazar mais detalhes internos do que você deseja. Prefira mantê-lo desativado em chats em grupo.

Consciência de custo

Heartbeats executam turnos completos de agente. Intervalos mais curtos consomem mais tokens. Para reduzir custos:

• Use isolatedSession: true para evitar enviar todo o histórico da conversa (~100K tokens para ~2-5K por execução).
• Use lightContext: true para limitar arquivos de bootstrap apenas a HEARTBEAT.md.
• Defina um model mais barato (por exemplo, ollama/llama3.2:1b).
• Mantenha HEARTBEAT.md pequeno.
• Use target: "none" se quiser apenas atualizações de estado internas.

Estouro de contexto após Heartbeat

Se um Heartbeat anteriormente deixou uma sessão existente em um modelo local menor, por exemplo, um modelo Ollama com janela de 32k, e o próximo turno da sessão principal relatar estouro de contexto, redefina o modelo de runtime da sessão de volta para o modelo primário configurado. A mensagem de redefinição do OpenClaw destaca isso quando o último modelo de runtime corresponde ao heartbeat.model configurado.

Heartbeats atuais preservam o modelo de runtime existente da sessão compartilhada depois que a execução termina. Você ainda pode usar isolatedSession: true para executar Heartbeats em uma sessão nova, combiná-lo com lightContext: true para o menor prompt, ou escolher um modelo de Heartbeat com uma janela de contexto grande o suficiente para a sessão compartilhada.

Relacionado

• Automação — todos os mecanismos de automação em resumo
• Tarefas em segundo plano — como o trabalho desacoplado é rastreado
• Fuso horário — como o fuso horário afeta o agendamento de heartbeat
• Solução de problemas — depuração de problemas de automação