Heartbeat

Heartbeat esegue turni periodici dell'agente nella sessione principale, così il modello può evidenziare qualsiasi cosa richieda attenzione senza inondarti di messaggi.

Heartbeat è un turno programmato della sessione principale: non crea record di attività in background. I record delle attività sono per il lavoro separato (esecuzioni ACP, subagenti, processi cron isolati).

Risoluzione dei problemi: Attività pianificate

# Avvio rapido (principiante)

Configurazione di esempio:

{
  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 subagent or nested lanes are busy
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

# Valori predefiniti

• Intervallo: 30m (o 1h quando la modalità di autenticazione rilevata è l'autenticazione OAuth/token di Anthropic, incluso il riuso della Claude CLI). Imposta agents.defaults.heartbeat.every o agents.list[].heartbeat.every per agente; usa 0m per disabilitare.
• Corpo del prompt (configurabile tramite 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.
• Il prompt di Heartbeat viene inviato letteralmente come messaggio dell'utente. Il prompt di sistema include una sezione "Heartbeat" solo quando gli Heartbeat sono abilitati per l'agente predefinito, e l'esecuzione viene contrassegnata internamente.
• Quando gli Heartbeat sono disabilitati con 0m, anche le esecuzioni normali omettono HEARTBEAT.md dal contesto di bootstrap, così il modello non vede istruzioni destinate solo a Heartbeat.
• Gli orari attivi (heartbeat.activeHours) vengono controllati nel fuso orario configurato. Fuori dalla finestra, gli Heartbeat vengono saltati fino al tick successivo all'interno della finestra.
• Gli Heartbeat vengono rinviati automaticamente mentre il lavoro cron è attivo o in coda. Imposta heartbeat.skipWhenBusy: true per rinviare anche su corsie di lavoro particolarmente occupate (subagente o lavoro di comandi annidati); questo è utile per Ollama locale e altri host vincolati a un singolo runtime.

# A cosa serve il prompt di Heartbeat

Il prompt predefinito è volutamente ampio:

• Attività in background: "Consider outstanding tasks" invita l'agente a rivedere i follow-up (posta in arrivo, calendario, promemoria, lavoro in coda) e a evidenziare qualsiasi cosa urgente.
• Controllo con la persona: "Checkup sometimes on your human during day time" invita a inviare occasionalmente un messaggio leggero del tipo "ti serve qualcosa?", ma evita lo spam notturno usando il fuso orario locale configurato (vedi Fuso orario).

Heartbeat può reagire alle attività in background completate, ma un'esecuzione di Heartbeat di per sé non crea un record di attività.

Se vuoi che Heartbeat faccia qualcosa di molto specifico (ad es. "controlla le statistiche Gmail PubSub" o "verifica lo stato del Gateway"), imposta agents.defaults.heartbeat.prompt (o agents.list[].heartbeat.prompt) su un corpo personalizzato (inviato letteralmente).

# Contratto di risposta

• Se niente richiede attenzione, rispondi con HEARTBEAT_OK.
• Le esecuzioni Heartbeat con strumenti disponibili possono invece chiamare heartbeat_respond con notify: false per nessun aggiornamento visibile, oppure notify: true più notificationText per un avviso. Quando presente, la risposta strutturata dello strumento ha la precedenza sul fallback testuale.
• Durante le esecuzioni Heartbeat, OpenClaw considera HEARTBEAT_OK come una conferma quando appare all'inizio o alla fine della risposta. Il token viene rimosso e la risposta viene scartata se il contenuto rimanente è ≤ ackMaxChars (valore predefinito: 300).
• Se HEARTBEAT_OK appare nel mezzo di una risposta, non viene trattato in modo speciale.
• Per gli avvisi, non includere HEARTBEAT_OK; restituisci solo il testo dell'avviso.

Fuori dagli Heartbeat, un HEARTBEAT_OK accidentale all'inizio/fine di un messaggio viene rimosso e registrato; un messaggio che contiene solo HEARTBEAT_OK viene scartato.

# Configurazione

{
  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)
        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 subagent/nested lanes
        target: "last", // default: none | options: 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
      },
    },
  },
}

# Ambito e precedenza

• agents.defaults.heartbeat imposta il comportamento globale di Heartbeat.
• agents.list[].heartbeat viene unito sopra; se un agente ha un blocco heartbeat, solo quegli agenti eseguono Heartbeat.
• channels.defaults.heartbeat imposta i valori predefiniti di visibilità per tutti i canali.
• channels.<channel>.heartbeat sovrascrive i valori predefiniti del canale.
• channels.<channel>.accounts.<id>.heartbeat (canali multi-account) sovrascrive le impostazioni per canale.

# Heartbeat per agente

Se una voce agents.list[] include un blocco heartbeat, solo quegli agenti eseguono gli Heartbeat. Il blocco per agente viene unito sopra agents.defaults.heartbeat (quindi puoi impostare valori predefiniti condivisi una sola volta e sovrascriverli per singolo agente).

Esempio: due agenti, solo il secondo agente esegue gli Heartbeat.

{
  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.",
        },
      },
    ],
  },
}

# Esempio di ore attive

Limita gli Heartbeat all'orario lavorativo in un fuso orario specifico:

{
  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
        },
      },
    },
  },
}

Fuori da questa finestra (prima delle 9:00 o dopo le 22:00 nel fuso orario orientale), gli Heartbeat vengono saltati. Il successivo tick pianificato all'interno della finestra verrà eseguito normalmente.

# Configurazione 24/7

Se vuoi che gli Heartbeat vengano eseguiti tutto il giorno, usa uno di questi schemi:

• Ometti completamente activeHours (nessuna restrizione della finestra temporale; questo è il comportamento predefinito).
• Imposta una finestra di un'intera giornata: activeHours: { start: "00:00", end: "24:00" }.

# Esempio multi-account

Usa accountId per puntare a un account specifico sui canali multi-account come 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" },
      },
    },
  },
}

# Note sui campi

everystring

Intervallo Heartbeat (stringa di durata; unita predefinita = minuti).

modelstring

Override opzionale del modello per le esecuzioni Heartbeat (provider/model).

includeReasoningboolean

Quando abilitato, consegna anche il messaggio separato Reasoning: quando disponibile (stessa forma di /reasoning on).

lightContextboolean

Quando e true, le esecuzioni Heartbeat usano un contesto di bootstrap leggero e conservano solo HEARTBEAT.md dai file di bootstrap del workspace.

isolatedSessionboolean

Quando e true, ogni Heartbeat viene eseguito in una sessione nuova, senza cronologia precedente della conversazione. Usa lo stesso schema di isolamento di Cron sessionTarget: "isolated". Riduce drasticamente il costo in token per Heartbeat. Combinalo con lightContext: true per il massimo risparmio. L'instradamento della consegna usa comunque il contesto della sessione principale.

skipWhenBusyboolean

Quando e true, le esecuzioni Heartbeat vengono posticipate sulle corsie particolarmente occupate: lavoro di subagenti o comandi annidati. Le corsie Cron posticipano sempre i Heartbeat, anche senza questo flag, quindi gli host di modelli locali non eseguono prompt Cron e Heartbeat contemporaneamente.

sessionstring

Chiave di sessione opzionale per le esecuzioni Heartbeat.

• main (predefinito): sessione principale dell'agente.
• Chiave di sessione esplicita (copiala da openclaw sessions --json o dalla CLI delle sessioni).
• Formati delle chiavi di sessione: consulta Sessioni e Gruppi.

targetstring

• last: recapita all'ultimo canale esterno usato.
• canale esplicito: qualsiasi canale configurato o id di plugin, ad esempio discord, matrix, telegram o whatsapp.
• none (predefinito): esegui l'Heartbeat ma non recapitarlo esternamente.

directPolicy"allow" | "block"

Controlla il comportamento di recapito diretto/DM. allow: consente il recapito diretto/DM dell'Heartbeat. block: sopprime il recapito diretto/DM (reason=dm-blocked).

tostring

Override facoltativo del destinatario (id specifico del canale, ad esempio E.164 per WhatsApp o un id chat di Telegram). Per argomenti/thread di Telegram, usa <chatId>:topic:<messageThreadId>.

accountIdstring

Id account facoltativo per canali multi-account. Quando target: "last", l'id account si applica all'ultimo canale risolto se supporta gli account; altrimenti viene ignorato. Se l'id account non corrisponde a un account configurato per il canale risolto, il recapito viene saltato.

promptstring

Sostituisce il corpo del prompt predefinito (non viene unito).

ackMaxCharsnumber

Numero massimo di caratteri consentiti dopo HEARTBEAT_OK prima della consegna.

suppressToolErrorWarningsboolean

Quando è true, sopprime i payload di avviso per errori degli strumenti durante le esecuzioni heartbeat.

activeHoursobject

Limita le esecuzioni heartbeat a una finestra temporale. Oggetto con start (HH:MM, inclusivo; usa 00:00 per l'inizio della giornata), end (HH:MM esclusivo; 24:00 consentito per la fine della giornata) e timezone opzionale.

• Omesso o "user": usa il tuo agents.defaults.userTimezone se impostato, altrimenti ripiega sul fuso orario del sistema host.
• "local": usa sempre il fuso orario del sistema host.
• Qualsiasi identificatore IANA (es. America/New_York): usato direttamente; se non valido, ripiega sul comportamento "user" sopra.
• start ed end non devono essere uguali per una finestra attiva; valori uguali sono trattati come larghezza zero (sempre fuori dalla finestra).
• Fuori dalla finestra attiva, gli heartbeat vengono saltati fino al tick successivo dentro la finestra.

# Comportamento di consegna

# Controlli di visibilità

Per impostazione predefinita, le conferme HEARTBEAT_OK vengono soppresse mentre il contenuto degli avvisi viene consegnato. Puoi regolarlo per canale o per account:

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

Precedenza: per-account → per-canale → impostazioni predefinite del canale → impostazioni predefinite integrate.

# Che cosa fa ogni flag

• showOk: invia una conferma HEARTBEAT_OK quando il modello restituisce una risposta solo OK.
• showAlerts: invia il contenuto dell'avviso quando il modello restituisce una risposta non OK.
• useIndicator: emette eventi indicatori per le superfici di stato dell'interfaccia.

Se tutti e tre sono false, OpenClaw salta completamente l'esecuzione heartbeat (nessuna chiamata al modello).

# Esempi per-canale vs per-account

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

# Schemi comuni

Obiettivo	Config
Comportamento predefinito (OK silenziosi, avvisi attivi)	(nessuna configurazione necessaria)
Completamente silenzioso (nessun messaggio, nessun indicatore)	channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }
Solo indicatore (nessun messaggio)	channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }
OK in un solo canale	channels.telegram.heartbeat: { showOk: true }

# HEARTBEAT.md (opzionale)

Se nel workspace esiste un file HEARTBEAT.md, il prompt predefinito dice all'agente di leggerlo. Consideralo la tua "checklist heartbeat": piccola, stabile e sicura da includere ogni 30 minuti.

Nelle esecuzioni normali, HEARTBEAT.md viene iniettato solo quando la guida heartbeat è abilitata per l'agente predefinito. Disabilitare la cadenza heartbeat con 0m o impostare includeSystemPromptSection: false lo omette dal normale contesto di bootstrap.

Se HEARTBEAT.md esiste ma è di fatto vuoto (solo righe vuote e intestazioni markdown come # Heading), OpenClaw salta l'esecuzione heartbeat per risparmiare chiamate API. Quel salto viene segnalato come reason=empty-heartbeat-file. Se il file manca, l'heartbeat viene comunque eseguito e il modello decide cosa fare.

Mantienilo minuscolo (breve checklist o promemoria) per evitare di gonfiare il prompt.

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

# Blocchi tasks:

HEARTBEAT.md supporta anche un piccolo blocco strutturato tasks: per controlli basati su intervalli dentro l'heartbeat stesso.

Esempio:

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.

La modalità attività è utile quando vuoi che un unico file heartbeat contenga diversi controlli periodici senza pagare per tutti a ogni tick.

# L'agente può aggiornare HEARTBEAT.md?

Sì, se glielo chiedi.

HEARTBEAT.md è semplicemente un file normale nel workspace dell'agente, quindi puoi dire all'agente (in una chat normale) qualcosa come:

• "Aggiorna HEARTBEAT.md per aggiungere un controllo giornaliero del calendario."
• "Riscrivi HEARTBEAT.md in modo che sia più breve e focalizzato sui follow-up della posta in arrivo."

Se vuoi che questo avvenga proattivamente, puoi anche includere una riga esplicita nel tuo prompt heartbeat come: "Se la checklist diventa obsoleta, aggiorna HEARTBEAT.md con una migliore."

# Risveglio manuale (su richiesta)

Puoi accodare un evento di sistema e attivare un heartbeat immediato con:

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

Se più agenti hanno heartbeat configurato, un risveglio manuale esegue immediatamente ciascuno di quegli heartbeat degli agenti.

Usa --mode next-heartbeat per attendere il prossimo tick pianificato.

# Consegna del ragionamento (opzionale)

Per impostazione predefinita, gli heartbeat consegnano solo il payload finale di "risposta".

Se vuoi trasparenza, abilita:

• agents.defaults.heartbeat.includeReasoning: true

Quando abilitato, gli heartbeat consegneranno anche un messaggio separato con prefisso Reasoning: (stessa forma di /reasoning on). Questo può essere utile quando l'agente gestisce più sessioni/codex e vuoi vedere perché ha deciso di contattarti, ma può anche esporre più dettagli interni di quanto desideri. Preferisci mantenerlo disattivato nelle chat di gruppo.

# Consapevolezza dei costi

Gli heartbeat eseguono turni completi dell'agente. Intervalli più brevi consumano più token. Per ridurre i costi:

• Usa isolatedSession: true per evitare di inviare tutta la cronologia della conversazione (da circa 100K token a circa 2-5K per esecuzione).
• Usa lightContext: true per limitare i file di bootstrap al solo HEARTBEAT.md.
• Imposta un model più economico (es. ollama/llama3.2:1b).
• Mantieni piccolo HEARTBEAT.md.
• Usa target: "none" se vuoi solo aggiornamenti di stato interni.

# Overflow del contesto dopo heartbeat

Se in precedenza un heartbeat ha lasciato una sessione esistente su un modello locale più piccolo, ad esempio un modello Ollama con una finestra da 32k, e il turno successivo della sessione principale segnala overflow del contesto, reimposta il modello runtime della sessione sul modello primario configurato. Il messaggio di reset di OpenClaw lo segnala quando l'ultimo modello runtime corrisponde a heartbeat.model configurato.

Gli heartbeat attuali preservano il modello runtime esistente della sessione condivisa dopo il completamento dell'esecuzione. Puoi comunque usare isolatedSession: true per eseguire gli heartbeat in una sessione nuova, combinarlo con lightContext: true per il prompt più piccolo, oppure scegliere un modello heartbeat con una finestra di contesto abbastanza grande per la sessione condivisa.

# Correlati

• Automazione e attività — tutti i meccanismi di automazione a colpo d'occhio
• Attività in background — come viene tracciato il lavoro scollegato
• Fuso orario — come il fuso orario influisce sulla pianificazione heartbeat
• Risoluzione dei problemi — debug dei problemi di automazione