OpenClaw Two-Tier Processing: Cost-Efficient Heartbeat Design

Introduction

OpenClaw's Heartbeat Engine wakes the agent every 30 minutes by default. If every heartbeat cycle invoked a full LLM call, API costs would quickly become prohibitive — 48 cycles per day × 1,000+ tokens each = significant monthly spend. The two-tier processing strategy solves this by prioritizing cheap, deterministic scripts over expensive LLM reasoning.

This design isn't just a cost optimization — it's an architectural principle. Most proactive tasks don't require language model reasoning. "Is the website returning 200?" is a simple HTTP check. "Did I receive emails from these 5 senders?" is a deterministic IMAP query. "Is the stock price above my threshold?" is a numeric comparison. Only when scripts detect something requiring analysis, summarization, or judgment should the LLM be invoked. Two-tier processing embodies that insight.

The API Cost Problem

Without optimization, a 30-minute heartbeat with 10 tasks could consume 10,000+ tokens per cycle. At $3 per million tokens (Claude), that's ~$4.50/day or ~$135/month just for heartbeat — before any interactive conversations. For power users running multiple agents, costs scale rapidly.

The insight: most heartbeat tasks don't require LLM reasoning. "Is the website returning 200?" is a simple HTTP check. "Did I receive emails from these 5 senders?" is a deterministic IMAP query. Only when scripts detect something requiring analysis should the LLM be invoked.

Consider a user running three agents (personal, work, side project). Each has 8 Heartbeat tasks. Without two-tier: 3 × 8 × 48 cycles/day × ~2,000 tokens = 2.3M tokens/day. At $3/M, that's ~$210/month in Heartbeat alone. With two-tier, most cycles complete with zero LLM calls. Real-world reports: 70–90% cost reduction.

The Two-Tier Strategy

OpenClaw's two-tier processing works as follows:

1. Tier 1 (Cheap): Deterministic scripts run first — HTTP checks, file reads, database queries, API polls. These use minimal or zero LLM tokens.
2. Condition check: Scripts output structured results (e.g., "website_down: true" or "new_emails: 3").
3. Tier 2 (Expensive): Only if conditions warrant reasoning does the system escalate to the LLM. "Summarize these 3 emails" or "Analyze why the server might be down."

Result: Many heartbeat cycles complete with zero LLM calls. When the website is up, emails are routine, and no thresholds are crossed, the agent "wakes," runs scripts, finds nothing to report, and goes back to sleep — all without touching the LLM.

The elegance is in the flow. Tier 1 is fast (seconds) and cheap (pennies or free). Tier 2 is slower and costs tokens — but it's invoked only when there's something worth saying. You pay for value, not for idle checks.

Tier 1: Deterministic Scripts

Tier 1 scripts are typically:

• Shell scripts: curl -s -o /dev/null -w "%{http_code}" https://mysite.com — returns 200 or 500. No LLM needed.
• Python/Node snippets: IMAP checks, calendar queries, file existence tests. Output structured JSON or key-value pairs.
• API calls: Stock price fetch, weather check, RSS feed parse. Compare to thresholds; output "alert: true" or "alert: false."

These run in the agent's execution environment. Output is parsed for trigger conditions. If "website returns 200" → no escalation. If "website returns 500" → escalate to LLM for alert and optional diagnosis.

Best practice: Keep Tier 1 scripts pure. No side effects beyond reading. No sending notifications. The script's job is to gather data and output a structured result. The LLM (when invoked) handles communication.

Tier 2: LLM Escalation

LLM escalation occurs when:

• Scripts detect a condition requiring human-readable explanation
• Summarization is needed (e.g., "summarize these 5 articles")
• Decision logic is ambiguous (e.g., "is this email urgent?")
• Natural language output is required (e.g., "draft a brief for the user")

The agent receives the script output as context and produces a natural language response. This response is then delivered to the user via the configured messaging channel.

Important: Tier 2 receives only the relevant script output — not the full memory tree. This keeps token usage bounded. The agent sees "website_down: true, status_code: 500, response_time_ms: 3200" and composes: "Your site mysite.com returned 500. Response time was 3.2s. Consider checking logs." Concise, actionable, token-efficient.

Configuration

Two-tier processing is enabled by default in OpenClaw. Key config options:

heartbeat:
  two_tier: true
  tier1_script_dir: "./scripts/heartbeat"
  escalate_threshold: "any_alert"  # or "always", "never"

escalate_threshold controls when Tier 2 triggers. "any_alert" means escalate only when Tier 1 scripts produce alerts. "always" forces LLM on every cycle (expensive). "never" suppresses LLM entirely (scripts only — useful for pure monitoring with external alerting).

Place Tier 1 scripts in tier1_script_dir. Each script should exit 0 and print structured output to stdout. The runtime parses this output and checks for alert conditions defined in HEARTBEAT.md.

Real-World Examples

Server monitoring: Tier 1 checks HTTP status, disk usage, process list. Escalates only when status != 200 or disk > 90%. LLM drafts the alert message. Result: 47 of 48 daily cycles use zero LLM tokens.

Email digest: Tier 1 fetches unread count and sender list. If count > 0, escalates to LLM for summarization. If count = 0, no LLM call. A user with typically empty inbox pays for LLM only on days with mail.

Price alert: Tier 1 fetches current price, compares to threshold. Escalates only when threshold crossed. LLM formats the notification. No LLM calls when the market is quiet.

Calendar conflict check: Tier 1 queries calendar API for overlapping events. Escalates only when conflicts exist. LLM suggests resolution. Most days: no conflicts, no LLM.

Community reports: two-tier design typically reduces Heartbeat API costs by 70–90% compared to full-LLM cycles.

Cost Breakdown: Before and After

Assume: 48 Heartbeat cycles/day, 8 tasks per cycle, Claude at $3/M input and $15/M output.

Without two-tier: Every cycle runs all 8 tasks through the LLM. ~2,000 tokens/cycle × 48 = 96K tokens/day. ~$0.30/day, ~$9/month for one agent. With 3 agents: ~$27/month.

With two-tier: Tier 1 runs every cycle (negligible cost). Tier 2 escalates on average 5 times/day (alerts, digests, etc.). 5 × 1,500 tokens = 7.5K tokens/day. ~$0.02/day, ~$0.60/month per agent. With 3 agents: ~$1.80/month.

Savings: ~93%. The exact numbers depend on your task mix, but the principle holds: deterministic checks are cheap; reserve the LLM for when it adds value.

Designing Tasks for Two-Tier

When adding a new Heartbeat task, ask: "Can a script do the condition check?" If yes, put it in Tier 1. If the task requires reading comprehension, summarization, or judgment, that's Tier 2 — but only after Tier 1 has determined that Tier 2 is needed.

Anti-pattern: "Check my email and summarize." Without two-tier, every cycle would fetch and summarize. With two-tier: Tier 1 fetches and counts. If count = 0, done. If count > 0, Tier 2 summarizes. Same outcome, fraction of the cost.

See Heartbeat Engine for task configuration and OpenClaw pricing for full cost guidance.

Wrapping Up

OpenClaw's two-tier processing is essential for cost-efficient proactive automation. Use deterministic scripts for condition checks; reserve the LLM for tasks that genuinely require reasoning. The result: an agent that wakes every 30 minutes, checks everything that matters, and speaks up only when there's something to say — without breaking the bank. See Heartbeat Engine and OpenClaw pricing for more.