Skill: lsj210001/openclaw-automation-architecture (version 1.0.0)

--- 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.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)