Your agent can now talk to you on any channel. Today it learns to act without being asked. HEARTBEAT.md is the file that transforms your agent from a chatbot into an autonomous system — running tasks, sending briefings, and monitoring your world while you sleep.
Reactive vs proactive. What changes when your agent acts without waiting for input.
How the tick cycle works, when HEARTBEAT.md is read, and what happens next.
File format, what to write, what not to write, and the silence rule.
The most common first automation. How to write it correctly so it runs once and stays quiet.
System checks, news summaries, and recurring research tasks — built step by step.
How your agent knows what time it is and how to write time-conditional instructions.
Token burn risk, how to keep HEARTBEAT.md lean, and the model choice that prevents runaway costs.
Reading the heartbeat log, verifying tasks ran, and fixing a silent agent.
You ask → agent responds. You send a Telegram message → agent replies. Every interaction starts with you. The agent is always waiting. Nothing happens unless you initiate it.
The Gateway ticks on a schedule. On each tick it reads HEARTBEAT.md, decides what to do, takes action, and delivers results to your channels. You wake up to a briefing you never asked for. That’s the shift.
This is the difference between a chatbot and an autonomous agent. HEARTBEAT.md is what makes the difference concrete.
Set model in the heartbeat config to a cheap model (Haiku / GPT-4o Mini). Without an explicit override, heartbeat uses your default agent model. Set lightContext: true and isolatedSession: true to minimize token load per tick.
How often the tick fires. Which model runs it. target controls delivery ("last" = last active channel). lightContext + isolatedSession keep token costs low.
What the agent does on each tick. Plain English bullet points — no special syntax. The agent reads this as its task list for the run. HEARTBEAT.md has no scheduling power of its own.
cron, intervals) — that’s openclaw.jsonYour agent sends you a message every 30 minutes confirming there’s nothing to report. Your phone buzzes 48 times a day. You turn off notifications. Your agent is now useless for alerts because you stopped looking. This is the most common beginner mistake.
Your agent only reaches out when it has something real to tell you. The channels stay quiet. When a message arrives, you pay attention because you know it’s signal, not noise. The silence rule is what makes proactive alerts valuable.
Under the hood, OpenClaw uses a HEARTBEAT_OK token. When the agent replies with HEARTBEAT_OK, the Gateway strips and drops the message (up to ackMaxChars, default 300). The silence rule in your HEARTBEAT.md causes the agent to emit this token, which the Gateway suppresses.
Tell the agent to mark the briefing as sent in memory after sending. Without this, every tick in the 8:00–8:30 window triggers another briefing. You’d get three or four messages in thirty minutes.
You wake up. Telegram has one message. Good morning, today is Wednesday, here are your three priorities, you have a 2pm call, it’s sunny and 68°F. Done. Your day starts with context.
Haiku 4.5 ($1/$5 per M tokens) or GPT-4o Mini ($0.15/$0.60 per M). Weather is a web search. Calendar is a tool call. Typical briefing: ~$0.006 on Haiku 4.5, ~$0.001 on GPT-4o Mini.
On each tick, the agent reads your MEMORY.md, looks for tasks with due dates, calculates time remaining, and only alerts you when the threshold is crossed. Two hours before a deadline, your phone buzzes. Not before.
Tell your agent via any channel: “Add to my task list: review the contract by 3pm tomorrow.” The agent writes it to MEMORY.md. The heartbeat loop picks it up on the next tick automatically.
These tasks require tool access: shell execution for disk/CPU checks, process status for service monitoring. Make sure the relevant tools are enabled in your agent config. Shell tool is off by default — enable it explicitly.
System monitoring usually warrants a shorter heartbeat interval — 15m or 30m. For a morning briefing only, 60m is fine. Tune your interval to match your most time-sensitive task.
For critical infrastructure, dedicated monitoring tools (Datadog, Prometheus) are more reliable. Use heartbeat monitoring for personal projects and convenience alerts, not production SLA requirements.
Replace AI and crypto with whatever you track. Competitors, industry news, stock tickers, arxiv papers, GitHub releases. The agent runs a web search on each tick that matches the time condition, summarizes, and delivers.
Web search + summarization into 5 bullets works well with Haiku. If you want deeper analysis or synthesis across multiple sources, use an escalation directive: “use the premium model for this task.”
| Intent | How to Write It | Watch Out For |
|---|---|---|
| Once per day at a time | “If it is 8am and briefing not sent today” | Missing the “not sent today” guard → repeats every tick |
| Every tick, always | “Check pending tasks” (no time condition) | Token burn if the check is expensive |
| Weekdays only | “If it is a weekday morning…” | Agent infers from system date — verify timezone is set correctly |
| Only on an event | “If a task is overdue…” | Condition must be checkable from memory or a tool call |
| Interval within day | “Every 4 hours, check…” | Set heartbeat interval ≤ 4h in openclaw.json first |
The agent uses the system timezone of the machine running the Gateway. If your server is in UTC and you’re in New York, write times in UTC or specify your timezone explicitly: “at 8am Eastern Time.”
This covers morning briefing, evening news, and deadline alerts. Three distinct automations. 14 lines. Token cost per tick when nothing fires: near zero — the agent reads the file, evaluates each condition, finds nothing to do, and exits silently.
lightContext + isolatedSession on Haiku: ~$0.001/tick. Without those flags, context loading alone can cost 10× more.Use Haiku / GPT-4o Mini for heartbeat. Keep HEARTBEAT.md under 25 lines. Use time conditions so most ticks are silent. Only escalate to the primary model for tasks that need it.
Heartbeat model set to Opus or GPT-4o. HEARTBEAT.md that runs web searches on every tick unconditionally. Forgetting the silence rule. Not checking the heartbeat log after first setup.
HEARTBEAT.md tells the agent what to do. Your channels from Day 5 determine where the output lands. The two systems are designed to work together.
Best for heartbeat delivery. Push notifications on mobile. Most users route all heartbeat alerts here. Specify: “send to Telegram” in HEARTBEAT.md.
Works identically. Specify: “send to WhatsApp.” Use if WhatsApp is your primary phone app. Reliable delivery on iOS and Android.
Every heartbeat run is logged in the Dashboard. Even silent ticks appear in the log. Open WebChat and check the Heartbeat tab to verify your setup is running.
The target key in your heartbeat config controls the default delivery channel. Set it to "last" (your last active channel), a specific channel name, or "none". You can also write channel directives in HEARTBEAT.md itself: “send to Telegram.”
Open the Dashboard at localhost:18789 and navigate to the Heartbeat tab. Every tick is logged with a timestamp, status (silent / action taken / error), and the agent’s reasoning. This is the first place to check.
Stream all Gateway logs (including heartbeat) in real time with logs --follow. View the last heartbeat run’s output with system heartbeat last.
Use openclaw system heartbeat enable / disable to toggle the heartbeat. Check openclaw system heartbeat last to review the most recent tick’s output and verify behavior.
Create ~/.openclaw/workspace/HEARTBEAT.md with at least two tasks: a morning briefing and a silence rule. Keep it under 20 lines. Set the heartbeat interval to 30m in openclaw.json. Set lightContext: true and isolatedSession: true.
Enable the heartbeat with openclaw system heartbeat enable and wait for the first tick. Run openclaw system heartbeat last to review its output. Confirm the agent evaluated your conditions and stayed silent (since it’s not 8am).
Let the heartbeat run overnight. Tomorrow morning, check Telegram before you open anything else. Your briefing should be there. If it is, your autonomous agent is live. If not, check the heartbeat log and debug.
Add a second automation to your HEARTBEAT.md: a pending task check, a news summary, or a system check — your choice. Verify it works with openclaw system heartbeat last after the next tick. Keep the total file under 25 lines.
Your agent is autonomous and proactive. But right now it has no identity — it’s just a generic AI. On Day 7 you write SOUL.md: the file that defines who your agent is, how it thinks, what it values, and how it speaks. This is what separates a useful tool from a truly personal agent.