---
read_when:
    - Ajustando a cadência ou as mensagens de heartbeat
    - Decidindo entre heartbeat e cron para tarefas agendadas
summary: Mensagens de polling de heartbeat e regras de notificação
title: Heartbeat
x-i18n:
    generated_at: "2026-04-11T02:44:47Z"
    model: gpt-5.4
    provider: openai
    source_hash: e4485072148753076d909867a623696829bf4a82dcd0479b95d5d0cae43100b0
    source_path: gateway/heartbeat.md
    workflow: 15
---

# Heartbeat (Gateway)

> **Heartbeat ou Cron?** Consulte [Automação e tarefas](/pt-BR/automation) para orientações sobre quando usar cada um.

O heartbeat executa **turnos periódicos do agente** na sessão principal para que o modelo possa
apontar qualquer coisa que precise de atenção sem enviar spam para você.

Heartbeat é um turno agendado da sessão principal — ele **não** cria registros de [tarefas em segundo plano](/pt-BR/automation/tasks).
Os registros de tarefa são para trabalho desacoplado (execuções de ACP, subagentes, jobs cron isolados).

Solução de problemas: [Tarefas agendadas](/pt-BR/automation/cron-jobs#troubleshooting)

## Início rápido (iniciante)

1. Deixe os heartbeats ativados (o padrão é `30m`, ou `1h` para autenticação por OAuth/token da Anthropic, incluindo reutilização da Claude CLI) ou defina sua própria cadência.
2. Crie uma pequena checklist em `HEARTBEAT.md` ou um bloco `tasks:` no workspace do agente (opcional, mas recomendado).
3. Decida para onde as mensagens de heartbeat devem ir (`target: "none"` é o padrão; defina `target: "last"` para rotear para o último contato).
4. Opcional: ative a entrega do raciocínio do heartbeat para maior transparência.
5. Opcional: use um contexto de bootstrap leve se as execuções de heartbeat precisarem apenas de `HEARTBEAT.md`.
6. Opcional: ative sessões isoladas para evitar enviar o histórico completo da conversa a cada heartbeat.
7. Opcional: restrinja os heartbeats ao horário ativo (hora local).

Exemplo de configuração:

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // entrega explícita ao último contato (o padrão é "none")
        directPolicy: "allow", // padrão: permite destinos diretos/DM; defina "block" para suprimir
        lightContext: true, // opcional: injeta apenas HEARTBEAT.md a partir dos arquivos de bootstrap
        isolatedSession: true, // opcional: sessão nova a cada execução (sem histórico de conversa)
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // opcional: envia também uma mensagem separada `Reasoning:`
      },
    },
  },
}
```

## Padrões

- Intervalo: `30m` (ou `1h` quando o modo de autenticação detectado é OAuth/token da Anthropic, incluindo reutilização da Claude CLI). Defina `agents.defaults.heartbeat.every` ou `agents.list[].heartbeat.every`; use `0m` para desativar.
- Corpo do prompt (configurável em `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.`
- O prompt de heartbeat é enviado **literalmente** como a mensagem do usuário. O prompt
  do sistema inclui uma seção “Heartbeat” somente quando os heartbeats estão ativados para o
  agente padrão, 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 bootstrap para que o modelo não veja instruções exclusivas de heartbeat.
- Horário ativo (`heartbeat.activeHours`) é verificado no fuso horário configurado.
  Fora da janela, os heartbeats são ignorados até o próximo tick dentro da janela.

## 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 pendentes (caixa de entrada, calendário, lembretes, trabalho enfileirado) e sinalizar qualquer coisa urgente.
- **Check-in humano**: “Checkup sometimes on your human during day time” incentiva uma
  mensagem ocasional e leve de “precisa de algo?”, mas evita spam noturno
  usando seu fuso horário local configurado (consulte [/concepts/timezone](/pt-BR/concepts/timezone)).

Heartbeat pode reagir a [tarefas em segundo plano](/pt-BR/automation/tasks) 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, “verificar estatísticas do Gmail PubSub”
ou “verificar a integridade do gateway”), 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`**.
- Durante execuções de heartbeat, o OpenClaw trata `HEARTBEAT_OK` como confirmação quando ele aparece
  no **início ou no fim** da resposta. O token é removido e a resposta é
  descartada se o conteúdo restante for **≤ `ackMaxChars`** (padrão: 300).
- Se `HEARTBEAT_OK` aparecer no **meio** de uma resposta, ele não é tratado
  de forma especial.
- Para alertas, **não** inclua `HEARTBEAT_OK`; retorne apenas o texto do alerta.

Fora dos heartbeats, um `HEARTBEAT_OK` solto no início/fim de uma mensagem é removido
e registrado em log; uma mensagem que seja apenas `HEARTBEAT_OK` é descartada.

## Configuração

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // padrão: 30m (0m desativa)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // padrão: false (entrega uma mensagem separada `Reasoning:` quando disponível)
        lightContext: false, // padrão: false; true mantém apenas HEARTBEAT.md dos arquivos de bootstrap do workspace
        isolatedSession: false, // padrão: false; true executa cada heartbeat em uma sessão nova (sem histórico de conversa)
        target: "last", // padrão: none | opções: last | none | <channel id> (core ou plugin, por exemplo "bluebubbles")
        to: "+15551234567", // opcional: substituição específica de canal
        accountId: "ops-bot", // opcional: id de canal com várias contas
        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, // número máximo de caracteres permitidos após 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** 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 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 sobre `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.

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // entrega explícita ao último contato (o padrão é "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:

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // entrega explícita ao último contato (o padrão é "none")
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // opcional; usa seu userTimezone se definido, caso contrário usa o fuso do host
        },
      },
    },
  },
}
```

Fora dessa 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 você quiser que os 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" }`.

Não defina o mesmo horário para `start` e `end` (por exemplo, `08:00` a `08:00`).
Isso é tratado como uma janela de largura zero, então os heartbeats sempre são ignorados.

### Exemplo com várias contas

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

```json5
{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // opcional: roteia para um tópico/thread específico
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}
```

### Observações sobre os campos

- `every`: intervalo do heartbeat (string de duração; unidade padrão = minutos).
- `model`: substituição opcional de modelo para execuções de heartbeat (`provider/model`).
- `includeReasoning`: quando ativado, também entrega a mensagem separada `Reasoning:` quando disponível (mesmo formato de `/reasoning on`).
- `lightContext`: quando verdadeiro, as execuções de heartbeat usam contexto de bootstrap leve e mantêm apenas `HEARTBEAT.md` dos arquivos de bootstrap do workspace.
- `isolatedSession`: quando verdadeiro, cada heartbeat é executado em uma sessão nova sem histórico anterior de conversa. Usa o mesmo padrão de isolamento do cron `sessionTarget: "isolated"`. Reduz drasticamente o custo em tokens por heartbeat. Combine com `lightContext: true` para máxima economia. O roteamento de entrega ainda usa o contexto da sessão principal.
- `session`: chave de sessão opcional para execuções de heartbeat.
  - `main` (padrão): sessão principal do agente.
  - Chave de sessão explícita (copie de `openclaw sessions --json` ou da [CLI de sessões](/cli/sessions)).
  - Formatos de chave de sessão: consulte [Sessões](/pt-BR/concepts/session) e [Grupos](/pt-BR/channels/groups).
- `target`:
  - `last`: entrega no último canal externo usado.
  - canal explícito: qualquer canal ou id de plugin configurado, por exemplo `discord`, `matrix`, `telegram` ou `whatsapp`.
  - `none` (padrão): executa o heartbeat, mas **não entrega** externamente.
- `directPolicy`: controla o comportamento de entrega direta/DM:
  - `allow` (padrão): permite entrega direta/DM de heartbeat.
  - `block`: suprime a entrega direta/DM (`reason=dm-blocked`).
- `to`: substituição opcional de destinatário (id específico do canal, por exemplo E.164 para WhatsApp ou id de chat do Telegram). Para tópicos/threads do Telegram, use `<chatId>:topic:<messageThreadId>`.
- `accountId`: id de conta opcional para canais com várias contas. Quando `target: "last"`, o id da conta se aplica ao último canal resolvido se ele oferecer suporte a contas; caso contrário, é ignorado. Se o id da conta não corresponder a uma conta configurada para o canal resolvido, a entrega será ignorada.
- `prompt`: substitui o corpo padrão do prompt (não é mesclado).
- `ackMaxChars`: número máximo de caracteres permitidos após `HEARTBEAT_OK` antes da entrega.
- `suppressToolErrorWarnings`: quando verdadeiro, suprime payloads de aviso de erro de ferramenta durante execuções de heartbeat.
- `activeHours`: restringe execuções de heartbeat a uma janela de tempo. Objeto com `start` (HH:MM, inclusivo; use `00:00` para início do dia), `end` (HH:MM exclusivo; `24:00` é permitido para fim do dia) e `timezone` opcional.
  - Omitido ou `"user"`: usa seu `agents.defaults.userTimezone` se definido; caso contrário, usa o fuso horário do sistema host.
  - `"local"`: sempre usa o fuso horário do sistema host.
  - Qualquer identificador IANA (por exemplo, `America/New_York`): usado diretamente; se for inválido, recorre ao comportamento `"user"` acima.
  - `start` e `end` não devem ser iguais para uma janela ativa; valores iguais são tratados como largura zero (sempre fora da janela).
  - Fora da janela ativa, os heartbeats são ignorados até o próximo tick dentro da janela.

## Comportamento de entrega

- Os heartbeats são executados por padrão na sessão principal do agente (`agent:<id>:<mainKey>`),
  ou em `global` quando `session.scope = "global"`. Defina `session` para substituir por uma
  sessão específica de canal (Discord/WhatsApp/etc.).
- `session` afeta apenas o contexto da execução; a entrega é controlada por `target` e `to`.
- Para entregar a um canal/destinatário específico, defina `target` + `to`. Com
  `target: "last"`, a entrega usa o último canal externo dessa sessão.
- As entregas de heartbeat permitem destinos diretos/DM por padrão. Defina `directPolicy: "block"` para suprimir envios para destinos diretos enquanto ainda executa o turno de heartbeat.
- Se a fila principal estiver ocupada, o heartbeat será ignorado e tentado novamente mais tarde.
- Se `target` não resolver para nenhum destino externo, a execução ainda acontece, mas nenhuma
  mensagem de saída é enviada.
- Se `showOk`, `showAlerts` e `useIndicator` estiverem todos desativados, a execução será ignorada antecipadamente como `reason=alerts-disabled`.
- Se apenas a entrega de alertas estiver desativada, o OpenClaw ainda poderá executar o heartbeat, atualizar timestamps de tarefas vencidas, restaurar o timestamp de inatividade da sessão e suprimir o payload de alerta externo.
- Respostas exclusivas de heartbeat **não** mantêm a sessão ativa; o último `updatedAt`
  é restaurado para que a expiração por inatividade se comporte normalmente.
- [Tarefas em segundo plano](/pt-BR/automation/tasks) desacopladas podem enfileirar um evento do sistema e despertar o heartbeat quando a sessão principal precisar perceber algo rapidamente. Esse despertar não faz com que a execução de heartbeat se torne uma tarefa em segundo plano.

## 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:

```yaml
channels:
  defaults:
    heartbeat:
      showOk: false # Oculta HEARTBEAT_OK (padrão)
      showAlerts: true # Mostra mensagens de alerta (padrão)
      useIndicator: true # Emite eventos de indicador (padrão)
  telegram:
    heartbeat:
      showOk: true # Mostra confirmações OK no Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Suprime a entrega de alertas para esta conta
```

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

### O que cada flag faz

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

Se **todas as três** estiverem como false, o OpenClaw ignora completamente a execução de heartbeat (sem chamada ao modelo).

### Exemplos por canal versus por conta

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

### Padrões comuns

| Objetivo                                 | Configuração                                                                             |
| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| Comportamento padrão (OKs silenciosos, alertas ativados) | _(nenhuma configuração necessária)_                                                      |
| Totalmente silencioso (sem mensagens, sem indicador) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |
| Somente indicador (sem mensagens)        | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }`  |
| OKs em apenas um canal                   | `channels.telegram.heartbeat: { showOk: true }`                                          |

## `HEARTBEAT.md` (opcional)

Se existir um arquivo `HEARTBEAT.md` no workspace, o prompt padrão informa ao
agente para lê-lo. Pense nele como sua “checklist de heartbeat”: pequena, estável e
segura para incluir 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.

Se `HEARTBEAT.md` existir, mas estiver efetivamente vazio (apenas linhas em branco e cabeçalhos
Markdown como `# Heading`), o OpenClaw ignora a execução de heartbeat para economizar chamadas de API.
Essa ignorada é relatada como `reason=empty-heartbeat-file`.
Se o arquivo estiver ausente, o heartbeat ainda é executado e o modelo decide o que fazer.

Mantenha-o pequeno (checklist curta ou lembretes) para evitar inflar o prompt.

Exemplo de `HEARTBEAT.md`:

```md
# Checklist de heartbeat

- Verificação rápida: há algo urgente nas caixas de entrada?
- Se for durante o dia, faça um check-in leve se nada mais estiver pendente.
- Se uma tarefa estiver bloqueada, anote _o que está faltando_ e pergunte ao Peter na próxima vez.
```

### 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:

```md
tasks:

- name: inbox-triage
  interval: 30m
  prompt: "Verifique se há emails urgentes não lidos e sinalize qualquer coisa sensível ao tempo."
- name: calendar-scan
  interval: 2h
  prompt: "Verifique se há reuniões próximas que precisam de preparação ou acompanhamento."

# Instruções adicionais

- Mantenha os alertas curtos.
- Se nada precisar de atenção após todas as tarefas vencidas, responda HEARTBEAT_OK.
```

Comportamento:

- O OpenClaw analisa o bloco `tasks:` e verifica cada tarefa em relação ao seu próprio `interval`.
- Somente as tarefas **vencidas** são incluídas no prompt de heartbeat desse tick.
- Se nenhuma tarefa estiver vencida, o heartbeat é totalmente ignorado (`reason=no-tasks-due`) para evitar uma chamada desnecessária ao modelo.
- O conteúdo que não for de tarefa em `HEARTBEAT.md` é preservado e anexado como contexto adicional após a lista de tarefas vencidas.
- Os timestamps da última execução das tarefas são armazenados no estado da sessão (`heartbeatTaskState`), então os intervalos sobrevivem a reinicializações normais.
- Os timestamps das tarefas só são avançados depois que uma execução de heartbeat completa seu fluxo normal de resposta. Execuções ignoradas por `empty-heartbeat-file` / `no-tasks-due` não marcam tarefas como concluídas.

O modo de tarefa é útil quando você quer que um único 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 do calendário.”
- “Reescreva `HEARTBEAT.md` para que fique mais curto e focado em acompanhamentos da caixa de entrada.”

Se você quiser que isso aconteça proativamente, também pode incluir uma linha explícita no
seu prompt de heartbeat, como: “Se a checklist ficar desatualizada, atualize `HEARTBEAT.md`
com uma versão melhor.”

Observação de segurança: não coloque segredos (chaves de API, números de telefone, tokens privados) em
`HEARTBEAT.md` — ele passa a fazer parte do contexto do prompt.

## Despertar manual (sob demanda)

Você pode enfileirar um evento do sistema e disparar um heartbeat imediato com:

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

Se vários agentes tiverem `heartbeat` configurado, um despertar manual executará imediatamente os
heartbeats de cada um desses agentes.

Use `--mode next-heartbeat` para esperar pelo próximo tick agendado.

## Entrega de raciocínio (opcional)

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

Se você quiser transparência, ative:

- `agents.defaults.heartbeat.includeReasoning: true`

Quando ativado, os heartbeats também entregam uma mensagem separada prefixada com
`Reasoning:` (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
você — mas também pode expor mais detalhes internos do que você deseja. Prefira manter
isso desativado em chats de grupo.

## Atenção aos custos

Heartbeats executam turnos completos do agente. Intervalos mais curtos consomem mais tokens. Para reduzir o custo:

- Use `isolatedSession: true` para evitar enviar o histórico completo da conversa (~100 mil tokens reduzidos para ~2–5 mil por execução).
- Use `lightContext: true` para limitar os 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 você quiser apenas atualizações de estado internas.

## Relacionado

- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em um relance
- [Tarefas em segundo plano](/pt-BR/automation/tasks) — como o trabalho desacoplado é rastreado
- [Fuso horário](/pt-BR/concepts/timezone) — como o fuso horário afeta o agendamento de heartbeat
- [Solução de problemas](/pt-BR/automation/cron-jobs#troubleshooting) — depuração de problemas de automação
