OpenClaw

OpenClaw Heartbeat & Automation👨‍💻

OpenClaw automation lets agents act on their own, without waiting for a user message. HEARTBEAT.md defines periodic check-ins where the agent wakes up, performs tasks, and reports results. Cron jobs schedule one-off or recurring commands. Event hooks trigger agent actions in response to system events. Webhooks let external services push data into agent conversations. Together, these mechanisms turn OpenClaw from a reactive chat system into a proactive automation platform.

Key Takeaways

  • 1HEARTBEAT.md defines what an agent does during periodic check-ins. The agent 'wakes up' on a schedule, follows the instructions in HEARTBEAT.md, and sends results to designated channels. This is how agents monitor servers, check for updates, or generate daily reports.
  • 2Cron jobs use standard cron syntax to schedule tasks. They can trigger agent actions, run shell commands, or send messages at specific times. Cron and heartbeat serve different purposes: heartbeat is agent-driven (the agent decides what to do), cron is schedule-driven (a specific command runs).
  • 3Event hooks fire agent actions in response to system events: new messages, session creation, channel connection/disconnection, agent errors. Hooks let you build reactive workflows without polling.
  • 4Webhooks expose HTTP endpoints that external services (GitHub, CI/CD, monitoring) can POST to, triggering agent actions. A GitHub webhook can notify your agent about new PRs, and the agent can review the code automatically.
  • 5Multi-agent orchestration uses the agent-router tool to pass messages between agents. An orchestrator agent can coordinate multiple specialist agents in sequence or parallel, building complex workflows.
  • 6Automation actions are logged and can be monitored via the CLI or Control UI. Set up alerting for failed automations so you know when a heartbeat check or cron job does not complete.

Master openclaw heartbeat & automation

Take the OpenClaw Automation & Workflows course with hands-on lessons and challenges.

Examples

HEARTBEAT.md for daily server health checks

markdown

This HEARTBEAT.md instructs the agent to perform health checks every 6 hours. The agent runs the checks using its configured tools (health-checker, ssh-executor), generates a summary, and sends it to the broadcast group. Escalation rules ensure critical issues get human attention immediately.

Cron job configuration

bash

Cron jobs use standard cron syntax. The first job runs at 2 AM daily and tells the deployer agent to perform a database backup. The second runs at 9 AM every Monday and triggers a weekly report. Unlike heartbeat (which is agent-directed), cron jobs send a specific message to a specific agent at scheduled times.

Event hooks for reactive workflows

json

Hooks fire in response to system events. The onNewMessage hook detects messages containing '#urgent' on Discord and routes them to the triage agent with high priority. The onChannelDisconnect hook sends an alert when any channel goes offline. The onAgentError hook notifies ops when an agent encounters an error.

Webhook endpoint for external integrations

bash

This creates a webhook endpoint that forwards GitHub PR events to the code-reviewer agent. When a new PR is opened, GitHub sends a POST request to the webhook URL, the Gateway verifies the signature using the shared secret, and the code-reviewer agent receives the PR data as a message it can process and respond to.

Heartbeat vs cron: choosing the right automation

bash

Heartbeat is for tasks where the agent needs to assess the situation and decide what to do. Cron is for tasks where the exact action is known in advance. Use heartbeat when you want the agent to think. Use cron when you just need something to run on schedule.

Common Mistakes

Mistake:

Setting heartbeat intervals too short (every minute) without considering the cost of model API calls for each check-in

Fix:

Each heartbeat invocation costs tokens. A 6-hour or daily interval is appropriate for most monitoring tasks. If you need minute-level checks, use a cron job with a shell command instead of an agent heartbeat.

Mistake:

Creating webhook endpoints without configuring a shared secret, allowing anyone to trigger agent actions by POSTing to the URL

Fix:

Always configure a webhook secret and validate signatures on incoming requests. Without this, anyone who discovers the URL can inject messages into your agent's conversation.

Mistake:

Building complex multi-step workflows entirely in HEARTBEAT.md instead of splitting them into separate agents with orchestration

Fix:

For workflows with more than 3-4 steps, use multi-agent orchestration. An orchestrator agent coordinates specialist agents, each responsible for one step. This is more reliable and easier to debug than a single long heartbeat.

Mistake:

Not monitoring failed automations, causing silent failures when a cron job or heartbeat stops working

Fix:

Set up alerting for automation failures. Use the onAgentError hook to notify ops when an agent errors during a scheduled task. Check `openclaw cron list` and `openclaw logs` regularly.

Best Practices

  • Use heartbeat for tasks requiring judgment (monitoring, health checks, adaptive actions). Use cron for fixed routines (backups, reports, data syncs).
  • Keep HEARTBEAT.md focused on what to check and how to report. Include escalation rules for critical findings so the agent knows when to involve humans.
  • Always validate webhook signatures with a shared secret. Rotate secrets periodically and store them in environment variables.
  • Log all automation actions. Use `openclaw logs --filter automation` to review what your agents have been doing autonomously.
  • Start with conservative intervals (daily, every 6 hours) and decrease only when you need faster feedback. Each heartbeat and cron invocation has a cost.
  • Test automations manually before scheduling them. Send the same message a heartbeat would generate and verify the agent produces the expected response.

Summary

OpenClaw automation turns agents into proactive workers. HEARTBEAT.md defines periodic agent check-ins for tasks requiring judgment. Cron jobs schedule fixed commands at specific times. Event hooks react to system events (messages, disconnects, errors). Webhooks let external services trigger agent actions. Use heartbeat for adaptive tasks, cron for fixed routines, and always validate webhook signatures. Monitor automation logs and set up alerting for failures.

Practice OpenClaw with hands-on challenges

Learn openclaw heartbeat & automation hands-on in your IDE

Interactive lessons and challenges on Stanza, practice in VS Code, Cursor, or the web.

Related Concepts

Openclaw AgentsOpenclaw ToolsOpenclaw Multi Agent RoutingOpenclaw Sessions Memory

Related Cheatsheets

Openclaw Cli Cheatsheet

Master OpenClaw with Stanza

Interactive lessons and challenges, right in your code editor.

Check the free courses. No credit card.