OpenClaw Automation Architecture

---

name: openclaw-automation-architecture description: Design OpenClaw-native automation systems using cron, HEARTBEAT.md, spawned sessions, specialist-agent delegation, first-class tools, MCPs, and local scripts. Use when the user wants to automate a workflow, set up reminders, schedule recurring reports, monitor topics, build alerting pipelines, design agent orchestration, choose between cron vs heartbeat vs spawned session vs script vs MCP vs Zapier/Make/n8n, or replace brittle no-code flows with an OpenClaw-first architecture. Trigger on requests like "automate this", "build a workflow", "set up a cron", "heartbeat task", "reminder", "scheduled report", "monitor this", "alert me when", "pipeline", "agent orchestration", "Zapier", "Make", "n8n", "save time", or "OpenClaw automation".

---

OpenClaw Automation Architecture

Overview

Design automations around OpenClaw's native primitives first. Reach for external workflow tools only when the job truly depends on third-party app glue, webhooks, or auth patterns that OpenClaw cannot cover cleanly.

Read references/decision-matrix.md when choosing the execution plane. Read references/patterns.md when the user needs a ready-made workflow pattern.

Core Doctrine

Prefer OpenClaw-native building blocks before Zapier, Make, or n8n.

Prefer small reliable systems over giant brittle flows.

Separate trigger, execution, state, delivery, and recovery.

Pick the cheapest primitive that can do the job well.

Do not ask the user to choose among primitives unless the trade-off materially affects behavior, cost, or reliability.

Quick Selection

Use this order:

1. Direct tool call now — when the user wants an immediate result, not automation. 2. cron — when timing matters or the task must run independently. 3. HEARTBEAT.md — when the task is periodic housekeeping, context-aware maintenance, or a drift-tolerant batch check. 4. Spawned session / specialist agent — when the run is heavy, multi-step, or belongs to a dedicated role. 5. Local script / MCP — when the same deterministic operation will repeat. 6. External workflow platforms — only if native OpenClaw building blocks are not enough.

Execution Plane Rules

Use cron when time is the product

Reach for cron when the user wants:

one-shot reminders

daily or weekly reports

scheduled monitoring

isolated runs that should survive chat silence

model-isolated or context-isolated jobs

Rules:

Use payload.kind="systemEvent" only for sessionTarget="main".

Use payload.kind="agentTurn" for isolated jobs.

If the run should notify a specific chat or recipient, prefer delivery.mode="announce" with channel / to instead of sending messages manually inside the run.

Write reminder text so it reads naturally when fired, including enough context to make sense later.

Use HEARTBEAT.md when drift is fine and context helps

Reach for heartbeat when the task is:

maintenance

periodic review

memory consolidation

cheap-gate checks followed by optional deeper work

work that benefits from current conversation context

Do not use heartbeat for:

precise alarms

externally visible SLAs

high-frequency fan-out jobs

anything that must run exactly on time

Use spawned sessions when the work is a real job, not a callback

Spawn a session when the task is:

long-running research

coding or refactoring

multi-file content production

specialist work for research, writing, trading, planning, or similar roles

better handled by ACP harnesses such as Codex or Claude Code

Rules:

If the user explicitly asks for Codex / Claude Code / Gemini in that style, use ACP harness intent.

Do not wrap ACP intent in local shell hacks.

Do not poll spawned workers in loops; let completion be push-based.

Use a script or MCP when determinism matters

Create or reuse a local script / MCP when:

the same transformation repeats

the work is fragile and should not rely on free-form reasoning every time

the workflow needs stable parsing, normalization, or batching

the task already maps to an external API or local tool cleanly

Examples:

feed normalization

CSV enrichment

content post-processing

quote/fundamental data pulls

knowledge-base ingest

Use Zapier / Make / n8n only as the edge adapter

Escalate to external workflow tools only when you need:

third-party app auth not covered by tools or MCPs

webhook-first integrations across SaaS products

drag-and-drop ops handoff for nontechnical collaborators

app connectors that would be slower to recreate locally than to consume externally

Treat them as adapters, not the brain.

Design Workflow

For every automation, define these five pieces in order.

1. Outcome

State the business result in one sentence.

Example:

"Alert me when a paper release maps to a stock or theme I track."

"Every morning, produce a shortlist and draft one article."

2. Trigger

Pick one:

user request now

schedule

heartbeat poll

new file / new data arrival

external event / webhook

If the trigger is weak or noisy, add a cheap gate before expensive work.

3. Execution plane

Choose one primary plane:

direct tool call

cron main-session reminder/event

cron isolated agent run

heartbeat task

spawned specialist agent

deterministic script / MCP

Do not mix planes unless there is a clear handoff.

4. State and dedup

Always decide:

where state lives

how duplicates are prevented

what counts as success

what can be retried safely

Typical state locations:

JSON state file in workspace

curated memory file

append-only log

project artifact such as today-briefing.md

5. Delivery and recovery

Define:

where the result goes

how failures surface

when to stay silent vs notify

what the fallback is

Prefer a single notification path. Split success and failure channels only when necessary.

Architecture Patterns

Pattern A: Monitor → Filter → Notify

Use for news, prices, releases, topic monitoring, and alerts.

Structure: 1. scheduled trigger 2. fetch candidates 3. deduplicate 4. score importance 5. announce only if threshold met 6. save medium-priority items for digest

Pattern B: Collect → Distill → Produce

Use for content factories and report generation.

Structure: 1. collector gathers raw material 2. artifact file stores shortlist or briefing 3. producer turns artifact into final output 4. optional review or delivery step

Pattern C: Ingest → Normalize → Index

Use for RAG and knowledge pipelines.

Structure: 1. detect source 2. extract text/content 3. normalize metadata 4. chunk/index 5. optionally summarize or tag

Pattern D: Scan → Decide → Act

Use for operations checks and maintenance.

Structure: 1. cheap gate 2. deeper scan only if needed 3. deterministic decision rule where possible 4. action or alert

Pattern E: Fan-out specialist work

Use when the user asks for one outcome that naturally decomposes.

Structure: 1. orchestrator defines subtasks 2. delegate by specialty 3. collect outputs into one artifact 4. synthesize once at the top

Guardrails

Do not automate a bad process. Simplify first.

Do not add an external platform if cron + tools + scripts already solve it.

Do not build giant all-in-one jobs when two small jobs with a file handoff are clearer.

Do not rely on repeated polling if eventing or longer waits work.

Do not send external messages without approval when approval is required.

Do not put business logic only in your head; store it in files, prompts, scripts, or config.

Do not make every failure page the user. Some failures should log quietly and retry later.

Output Expectations

When helping with an automation request, produce a concrete recommendation in this shape:

1. Best execution plane 2. Why this plane wins 3. State + dedup plan 4. Failure handling 5. Whether native OpenClaw is enough or an external workflow tool is justified

If the user asks to actually build it, implement the smallest end-to-end version first.

Example Requests

"Set up a daily report in OpenClaw."

"Should this be a cron job or a heartbeat task?"

"Help me replace this Zapier flow with native OpenClaw automation."

"Design an alerting pipeline for topic monitoring."

"How should I split this across agents, scripts, and scheduled jobs?"

References

Use references/decision-matrix.md for primitive selection and anti-patterns.

Use references/patterns.md for ready-made workflow templates in OpenClaw terms.