Heartbeat

Heartbeat esegue turni periodici dell'agente nella sessione principale, così il modello può far emergere tutto ciò che richiede attenzione senza inviarti spam.

Heartbeat è un turno pianificato della sessione principale: non crea record di attività in background. I record delle attività sono per lavoro distaccato (esecuzioni ACP, subagenti, job Cron isolati).

Risoluzione dei problemi: Attività pianificate

Avvio rapido (principianti)

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

Valori predefiniti

• Intervallo: 30m (o 1h quando la modalità di autenticazione rilevata è Anthropic OAuth/token, incluso il riuso di 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.
• Timeout: i turni heartbeat senza valore impostato usano agents.defaults.timeoutSeconds quando è configurato. Altrimenti usano la cadenza heartbeat con un limite massimo di 600 secondi. Imposta agents.defaults.heartbeat.timeoutSeconds o agents.list[].heartbeat.timeoutSeconds per agente per lavoro heartbeat più lungo.
• Il prompt heartbeat viene inviato verbatim 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 è 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 solo per heartbeat.
• Gli orari attivi (heartbeat.activeHours) vengono verificati nel fuso orario configurato. Fuori dalla finestra, gli heartbeat vengono saltati fino al tick successivo dentro la finestra.
• Gli heartbeat vengono rinviati automaticamente mentre il lavoro Cron è attivo o in coda. Imposta heartbeat.skipWhenBusy: true per rinviare anche un agente sulle sue lane di subagente con chiave di sessione o di comandi annidati; gli agenti fratelli non vengono più messi in pausa solo perché un altro agente ha lavoro di subagente in corso.

A cosa serve il prompt heartbeat

Il prompt predefinito è intenzionalmente ampio:

• Attività in background: "Consider outstanding tasks" spinge l'agente a rivedere follow-up (posta in arrivo, calendario, promemoria, lavoro in coda) e a far emergere tutto ciò che è urgente.
• Check-in umano: "Checkup sometimes on your human during day time" spinge un messaggio leggero occasionale del tipo "ti serve qualcosa?", ma evita spam notturno usando il fuso orario locale configurato (vedi Fuso orario).

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

Se vuoi che un heartbeat faccia qualcosa di molto specifico (ad esempio "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 verbatim).

Contratto di risposta

• Se nulla 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 precedenza sul fallback testuale.
• Durante le esecuzioni heartbeat, OpenClaw tratta HEARTBEAT_OK come ack quando appare all'inizio o alla fine della risposta. Il token viene rimosso e la risposta viene scartata se il contenuto rimanente è ≤ ackMaxChars (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 nei log; 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 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      },    },  },}

Ambito e precedenza

• agents.defaults.heartbeat imposta il comportamento heartbeat globale.
• 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 heartbeat. Il blocco per agente viene unito sopra agents.defaults.heartbeat (così puoi impostare una volta i valori predefiniti condivisi e sovrascriverli per agente).

Esempio: due agenti, solo il secondo agente esegue 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 orari attivi

Limita gli heartbeat agli orari lavorativi 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 Eastern), gli heartbeat vengono saltati. Il successivo tick pianificato dentro la finestra verrà eseguito normalmente.

Configurazione 24/7

Se vuoi che gli heartbeat vengano eseguiti tutto il giorno, usa uno di questi pattern:

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

Esempio multi-account

Usa accountId per indirizzare un account specifico su 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

Comportamento di consegna

Controlli di visibilità

Per impostazione predefinita, gli acknowledgment HEARTBEAT_OK vengono soppressi 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 → valori predefiniti del canale → valori predefiniti integrati.

Che cosa fa ogni flag

• showOk: invia un acknowledgment 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 indicatore per le superfici di stato dell'interfaccia utente.

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

Esempi per-canale e 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

Pattern comuni

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

Sull'harness Codex nativo, il contenuto di HEARTBEAT.md non viene iniettato nel turno. Se il file esiste e ha contenuto non composto solo da spazi, le istruzioni della modalità collaborazione Heartbeat indirizzano Codex al file e gli dicono di leggerlo prima di procedere.

Se HEARTBEAT.md esiste ma è di fatto vuoto (solo righe vuote, commenti Markdown/HTML, intestazioni Markdown come # Heading, marcatori fence o stub di checklist vuoti), 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 che cosa fare.

Tienilo minuscolo (breve checklist o promemoria) per evitare gonfiamento del 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 all'interno dello stesso Heartbeat.

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 solo file Heartbeat contenga diversi controlli periodici senza pagarli tutti a ogni tick.

L'agente può aggiornare HEARTBEAT.md?

Sì — se glielo chiedi.

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

• "Aggiorna HEARTBEAT.md per aggiungere un controllo calendario giornaliero."
• "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, ad esempio: "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 agente.

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

Consegna del ragionamento (opzionale)

Per impostazione predefinita, gli Heartbeat consegnano solo il payload finale "answer".

Se vuoi trasparenza, abilita:

• agents.defaults.heartbeat.includeReasoning: true

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

Consapevolezza dei costi

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

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

Overflow del contesto dopo Heartbeat

Se in precedenza un Heartbeat ha lasciato una sessione esistente su un modello locale più piccolo, per 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 nuova sessione, 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 — tutti i meccanismi di automazione in sintesi
• Attività in background — come viene tracciato il lavoro scollegato
• Fuso orario — come il fuso orario influisce sulla pianificazione degli Heartbeat
• Risoluzione dei problemi — debug dei problemi di automazione