Openclaw: Cron ⚔️ Heartbeat

Both systems are just different ways to trigger an Agent Turn (an LLM inference call). The difference is in the Gateway Orchestration and the Context Injection.

1. The Heartbeat: The "Main Loop"

Architecture: Periodic Polling (Stateful)

• Where it lives: The Heartbeat is a fixed timer running inside the Main Session event loop.
• The Technical Flow:
  1. Every 30m, the Gateway injects a System Event into the message history.
  2. The Gateway gathers the current Main Session context (your last 50 messages, files, current project state).
  3. It appends the content of HEARTBEAT.md as a prompt.
  4. It sends the entire history + heartbeat prompt to the LLM.
• Key Characteristic: It is Cumulative. The LLM knows what you just said because the Heartbeat happens inside your existing chat window.

2. The Cron: The "Sidecar Runner"

Architecture: Scheduler (Stateless by default)

• Where it lives: A standalone scheduler (croner) that monitors ~/.openclaw/cron/jobs.json.
• The Technical Flow (Isolated Mode):
  1. The timer hits 0.
  2. The Gateway creates a New, Empty Session (e.g., cron:job-123).
  3. It injects a specific message (e.g., "Generate report").
  4. It sends only that message to the LLM.
  5. Once the LLM finishes, the Gateway extracts the "Summary" and sends it to your output channel (Telegram/Slack).
  6. The session is discarded.
• Key Characteristic: It is Isolated. The LLM has zero knowledge of your current conversation unless you explicitly pass it in.

Comparison Table: Technical Specs

Feature	Heartbeat	Cron (Isolated)
Trigger	Gateway internal interval	croner library (Unix-style)
Process	Part of the main agent thread	Spawns a dedicated agent turn
Context	Full (History + Workspace)	Minimal (Lightweight context)
State	Persistent in Main Session	Ephemeral (Wiped after run)
Timing	Approximate (± mins)	Precise (Staggered by 0-5m)
Outcome	Appears in your main chat	Delivered via "Announce" mode

"Is Cron just a Python script?"

No. If you want to run a "Python script" without an AI, you don't use OpenClaw Cron; you use a standard Linux Crontab.

In OpenClaw, a Cron Job is a Scheduled Prompt. The "Task" it does is:

1. Wake up the Agent.
2. Tell the Agent: "Go execute this specific Tool/Prompt."
3. The Agent uses its reasoning to decide how to call the tool (e.g., exec_tool, Google Search).

Why does Heartbeat exist if we have Cron?

Token Efficiency. If you have 10 things to check (Weather, Gmail, GitHub, Jira, Calendar), and you use Cron, you are starting 10 separate LLM calls. That's 10x the "cold start" token overhead.

With Heartbeat, the Gateway sends one prompt: "Here is a list of 10 things to check. Do them all now." The LLM processes all 10 in a single inference pass, which is significantly cheaper and faster for "background awareness."

Summary for the Architect:

• Heartbeat = A "Checklist" injected into the Main Process to maintain background awareness.
• Cron = A "Lambda Function" that wakes up a Sub-Process to do a specific job and then dies.