heartbeat usecase

[open bane]

what is usual usecase of HEARTBEAT.md?

[hidden wave]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[wooden umbra]

Usually, HEARTBEAT.md is a tiny checklist/prompt for periodic heartbeat runs.

Common use cases:

• Light proactive checks: inbox, calendar, notifications, urgent follow-ups
• Batching small recurring checks into one heartbeat turn
• Simple interval tasks via a tasks: block, like “check email every 30m” and “scan calendar every 2h”

A few good rules:

• Keep it small and stable
• Use it when timing can be approximate
• Use cron instead if you need exact timing, like “9:00 every Monday”

Nice detail: if HEARTBEAT.md is basically empty, OpenClaw can skip the heartbeat API call to save tokens.

Docs: https://docs.openclaw.ai/gateway/heartbeat

If you want, I can also show a good real-world HEARTBEAT.md example.

[open bane]

but what usually user uses it ?

[wooden umbra]

Usually, users use it for simple proactive housekeeping.

Most common patterns:

• Inbox triage: “check for urgent unread email/messages”
• Calendar scan: “look for upcoming meetings or things needing prep”
• Follow-up reminders: “if something is blocked, remind me later”
• Light health/status checks: gateway/service/channel status
• Daily check-ins: “send me a brief nudge if there’s anything important”

Honestly, a lot of users either:

1. leave it empty, or
2. put 2 to 5 tiny recurring checks in it.

So the usual use is not “big automation”, it’s more like:

“Every so often, quickly look around and tell me if something needs attention.”

If you want, I can give you a realistic HEARTBEAT.md example that matches how most people use it.

[open bane]

what accounts needed?

[wooden umbra]

No special heartbeat account is needed.

What you need depends on what the heartbeat is checking:

• Just local reminders / internal notes → no extra account
• Gmail / Calendar / Drive → connect a Google account
• Discord / Telegram / WhatsApp checks → that channel/account must already be connected
• Weather / simple web checks → often no account at all
• Home Assistant → Home Assistant access/config

So, HEARTBEAT.md itself is just instructions.
The needed accounts are only the ones for the services you want the agent to read or act on.

If you want, tell me what you want heartbeat to do, and I can tell you exactly which accounts are needed.

[open bane]

what exactly needed to add google account what command need to run

[wooden umbra]

If you mean Gmail / Calendar / Drive for heartbeat checks, the usual path is gog OAuth setup, not a generic openclaw add-google-account command.

Run these once:

gog auth credentials /path/to/client_secret.json
gog auth add [e-mail] --services gmail,calendar
gog auth list

If you also want Drive / Contacts / Sheets / Docs:

gog auth add [e-mail] --services gmail,calendar,drive,contacts,sheets,docs

What you need first:

• a Google account
• a Google OAuth client secret JSON from Google Cloud

Nice optional helper:

export GOG_ACCOUNT=[e-mail]

Then your heartbeat can use that account for Gmail/Calendar checks.

Small clarification, if you meant Gemini model auth instead of Gmail/Calendar access, that’s a different setup, usually via openclaw onboard or openclaw configure --section model.

Docs:

• Heartbeat: https://docs.openclaw.ai/gateway/heartbeat
• gog: https://gogcli.sh

If you want, I can show the exact Google Cloud steps to get the client_secret.json.

[open bane]

ok how should the hearbet created what prompt to say

[wooden umbra]

Easiest way, don’t overthink the prompt. Usually you keep the default heartbeat prompt, and put your real instructions in HEARTBEAT.md.

1) Turn heartbeat on

openclaw config set agents.defaults.heartbeat.every "30m"

2) Put this in ~/.openclaw/workspace/HEARTBEAT.md

tasks:

- name: inbox-triage
  interval: 30m
  prompt: "Check Gmail for urgent unread emails. Only alert me if something is time sensitive."

- name: calendar-scan

  interval: 2h
  prompt: "Check my upcoming calendar events and tell me if anything needs prep."

# Additional instructions

- Keep alerts short.
- If nothing needs attention, reply HEARTBEAT_OK.

3) If you want to ask the agent in chat instead

Say something like:

Create HEARTBEAT.md so heartbeat checks Gmail every 30 minutes and calendar every 2 hours. Keep alerts short, and reply HEARTBEAT_OK when nothing needs attention.

That’s the normal pattern.

Docs: https://docs.openclaw.ai/gateway/heartbeat

If you want, I can give you:

1. a Gmail-only heartbeat, or
2. a Gmail + Calendar + follow-up reminders version.

[open bane]

how about others

[wooden umbra]

Yep, same idea for others too. Just change the task prompt.

Examples:

tasks:

- name: discord-mentions
  interval: 30m
  prompt: "Check for important Discord mentions or replies. Only alert me if action is needed."

- name: task-followups
  interval: 2h
  prompt: "Look for blocked tasks or pending follow-ups. Summarize only the important ones."

- name: weather-check

  interval: 6h
  prompt: "Check weather only if there is something notable today, like rain or extreme heat."

- name: system-health
  interval: 1h
  prompt: "Check gateway/system health and alert me only if something looks broken."

Common “other” heartbeat uses:

• Discord / Telegram / Slack mentions
• follow-up reminders
• task backlog scan
• system / gateway health
• weather
• daily nudges like “anything urgent today?”

So basically:
service/account changes, but heartbeat format stays the same.

If you want, I can make you a full example for:

1. personal assistant,
2. dev/system monitoring, or
3. business/workflow use.