​

Heartbeat (Gateway)

Heartbeat vs Cron? Veja Cron vs Heartbeat para orientações sobre quando usar cada um.

​

Início rápido (iniciante)

1. Deixe os heartbeats habilitados (o padrão é 30m, ou 1h para Anthropic OAuth/setup-token) ou defina sua própria cadência.
2. Crie uma pequena checklist HEARTBEAT.md no workspace do agente (opcional, mas recomendado).
3. Decida para onde as mensagens de heartbeat devem ir (target: "last" é o padrão).
4. Opcional: habilite a entrega de raciocínio do heartbeat para transparência.
5. Opcional: restrinja os heartbeats a horas ativas (hora local).

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

​

Padrões

• Intervalo: 30m (ou 1h quando Anthropic OAuth/setup-token é o modo de autenticação detectado). Defina agents.defaults.heartbeat.every ou por agente agents.list[].heartbeat.every; use 0m para desabilitar.
• Corpo do prompt (configurável via 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 verbatim como a mensagem do usuário. O prompt do sistema inclui uma seção “Heartbeat” e a execução é sinalizada internamente.
• Horas ativas (heartbeat.activeHours) são verificadas 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

• Tarefas em segundo plano: “Consider outstanding tasks” incentiva o agente a revisar acompanhamentos (caixa de entrada, calendário, lembretes, trabalho em fila) e trazer à tona 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 (veja /concepts/timezone).

​

Contrato de resposta

• Se nada precisar de atenção, responda com HEARTBEAT_OK.
• Durante execuções de heartbeat, o OpenClaw trata HEARTBEAT_OK como um ack quando 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, não é tratado de forma especial.
• Para alertas, não inclua HEARTBEAT_OK; retorne apenas o texto do alerta.

​

Configuração

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // default: 30m (0m disables)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
        target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        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 mescla por cima; se algum agente tiver um bloco heartbeat, apenas esses agentes executam heartbeats.
• channels.defaults.heartbeat define padrões de visibilidade para todos os canais.
• channels.<channel>.heartbeat sobrescreve os padrões do canal.
• channels.<channel>.accounts.<id>.heartbeat (canais multi-conta) sobrescreve configurações por canal.

​

Heartbeats por agente

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          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 horas ativas

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

​

Exemplo multi-conta

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

Notas de campo

• every: intervalo do heartbeat (string de duração; unidade padrão = minutos).
• model: sobrescrita opcional do modelo para execuções de heartbeat (provider/model).
• includeReasoning: quando habilitado, também entrega a mensagem separada Reasoning: quando disponível (mesmo formato de /reasoning on).
• 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).
  • Formatos de chave de sessão: veja Sessões e Grupos.
• target:
  • last (padrão): entrega para o último canal externo usado.
  • canal explícito: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
  • none: executa o heartbeat, mas não entrega externamente.
• to: sobrescrita opcional do destinatário (id específico do canal, por exemplo E.164 para WhatsApp ou um chat id do Telegram).
• accountId: id de conta opcional para canais multi-conta. Quando target: "last", o id da conta se aplica ao último canal resolvido se ele suportar contas; caso contrário, é ignorado. Se o id da conta não corresponder a uma conta configurada para o canal resolvido, a entrega é ignorada.
• prompt: sobrescreve o corpo padrão do prompt (não mescla).
• ackMaxChars: máximo de caracteres permitidos após HEARTBEAT_OK antes da entrega.
• activeHours: restringe execuções de heartbeat a uma janela de tempo. Objeto com start (HH:MM, inclusivo), end (HH:MM exclusivo; 24:00 permitido para fim de dia) e timezone opcional.
  • Omitido ou "user": usa seu agents.defaults.userTimezone se definido; caso contrário, recorre ao fuso horário do sistema do host.
  • "local": sempre usa o fuso horário do sistema do host.
  • Qualquer identificador IANA (por exemplo, America/New_York): usado diretamente; se inválido, recorre ao comportamento "user" acima.
  • 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 na sessão principal do agente por padrão (agent:<id>:<mainKey>), ou global quando session.scope = "global". Defina session para sobrescrever para uma sessão de canal específica (Discord/WhatsApp/etc.).
• session afeta apenas o contexto de 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.
• Se a fila principal estiver ocupada, o heartbeat é ignorado e tentado novamente mais tarde.
• Se target resolver para nenhum destino externo, a execução ainda acontece, mas nenhuma mensagem de saída é enviada.
• Respostas somente de heartbeat não mantêm a sessão ativa; o último updatedAt é restaurado para que a expiração por inatividade se comporte normalmente.

​

Controles de visibilidade

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

​

O que cada flag faz

• showOk: envia um reconhecimento HEARTBEAT_OK quando o modelo retorna uma resposta apenas OK.
• showAlerts: envia o conteúdo do alerta quando o modelo retorna uma resposta não-OK.
• useIndicator: emite eventos indicadores para superfícies de status da UI.

​

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)

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

​

O agente pode atualizar o HEARTBEAT.md?

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

​

Despertar manual (sob demanda)

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

​

Entrega de raciocínio (opcional)

• agents.defaults.heartbeat.includeReasoning: true

​

Consciência de custo