From e682b72154ccee277231cebf352ed00cb3750989 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Mon, 30 Mar 2026 19:07:18 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Batch=201=20=E2=80=94=20create=20automa?= =?UTF-8?q?tion=20hub=20+=20add=20Related=20sections?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New page: docs/automation/index.md — single entry point for all automation mechanisms (heartbeat, cron, tasks, hooks, standing-orders, webhooks) with a decision flowchart and comparison table. Add "Related" sections to 5 high-traffic pages that were dead ends: - gateway/heartbeat.md → links to tasks, cron-vs-heartbeat, timezone, troubleshooting - concepts/session.md → links to multi-agent, tasks, channel-routing - concepts/multi-agent.md → links to channel-routing, subagents, ACP, presence, session - concepts/agent-loop.md → links to tools, hooks, compaction, exec-approvals, thinking - concepts/timezone.md → links to heartbeat, cron-jobs, date-time Add automation/index to Mintlify nav as first item in Automation group. --- docs/automation/index.md | 73 ++++++++++++++++++++++++++++++++++++ docs/concepts/agent-loop.md | 8 ++++ docs/concepts/multi-agent.md | 8 ++++ docs/concepts/session.md | 3 ++ docs/concepts/timezone.md | 6 +++ docs/docs.json | 1 + docs/gateway/heartbeat.md | 8 ++++ 7 files changed, 107 insertions(+) create mode 100644 docs/automation/index.md diff --git a/docs/automation/index.md b/docs/automation/index.md new file mode 100644 index 00000000000..49dd7922372 --- /dev/null +++ b/docs/automation/index.md @@ -0,0 +1,73 @@ +--- +summary: "Overview of all automation mechanisms: heartbeat, cron, tasks, hooks, webhooks, and more" +read_when: + - Deciding how to automate work with OpenClaw + - Choosing between heartbeat, cron, hooks, and webhooks + - Looking for the right automation entry point +title: "Automation Overview" +--- + +# Automation + +OpenClaw provides several automation mechanisms, each suited to different use cases. This page helps you choose the right one. + +## Quick decision guide + +``` +Do you need something to run on a schedule? + YES → Is exact timing critical? + YES → Cron (isolated) + NO → Can it batch with other checks? + YES → Heartbeat + NO → Cron + NO → Continue... + +Do you need to react to an event (message, tool call, session change)? + YES → Hooks (or plugin hooks) + +Do you need to receive external HTTP events? + YES → Webhooks + +Do you want persistent instructions the agent always follows? + YES → Standing Orders + +Do you want to track what background work happened? + → Background Tasks (automatic for cron, ACP, subagents) +``` + +## Mechanisms at a glance + +| Mechanism | What it does | Runs in | Creates task record | +|---|---|---|---| +| [Heartbeat](/gateway/heartbeat) | Periodic main-session turn — batches multiple checks | Main session | No | +| [Cron](/automation/cron-jobs) | Scheduled jobs with precise timing | Main or isolated session | Yes (all types) | +| [Background Tasks](/automation/tasks) | Tracks detached work (cron, ACP, subagents, CLI) | N/A (ledger) | N/A | +| [Hooks](/automation/hooks) | Event-driven scripts triggered by agent lifecycle events | Hook runner | No | +| [Standing Orders](/automation/standing-orders) | Persistent instructions injected into the system prompt | Main session | No | +| [Webhooks](/automation/webhook) | Receive inbound HTTP events and route to the agent | Gateway HTTP | No | + +### Specialized automation + +| Mechanism | What it does | +|---|---| +| [Gmail PubSub](/automation/gmail-pubsub) | Real-time Gmail notifications via Google PubSub | +| [Polling](/automation/poll) | Periodic data source checks (RSS, APIs, etc.) | +| [Auth Monitoring](/automation/auth-monitoring) | Credential health and expiry alerts | + +## How they work together + +The most effective setups combine multiple mechanisms: + +1. **Heartbeat** handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes. +2. **Cron** handles precise schedules (daily reports, weekly reviews) and one-shot reminders. +3. **Hooks** react to specific events (tool calls, session resets, compaction) with custom scripts. +4. **Standing Orders** give the agent persistent context ("always check the project board before replying"). +5. **Background Tasks** automatically track all detached work so you can inspect and audit it. + +See [Cron vs Heartbeat](/automation/cron-vs-heartbeat) for a detailed comparison of the two scheduling mechanisms. + +## Related + +- [Cron vs Heartbeat](/automation/cron-vs-heartbeat) — detailed comparison guide +- [Troubleshooting](/automation/troubleshooting) — debugging automation issues +- [Configuration Reference](/gateway/configuration-reference) — all config keys diff --git a/docs/concepts/agent-loop.md b/docs/concepts/agent-loop.md index b7ddabeb293..8047616c496 100644 --- a/docs/concepts/agent-loop.md +++ b/docs/concepts/agent-loop.md @@ -156,3 +156,11 @@ See [Plugin hooks](/plugins/architecture#provider-runtime-hooks) for the hook AP - AbortSignal (cancel) - Gateway disconnect or RPC timeout - `agent.wait` timeout (wait-only, does not stop agent) + +## Related + +- [Tools](/tools) — available agent tools +- [Hooks](/automation/hooks) — event-driven scripts triggered by agent lifecycle events +- [Compaction](/concepts/compaction) — how long conversations are summarized +- [Exec Approvals](/tools/exec-approvals) — approval gates for shell commands +- [Thinking](/tools/thinking) — thinking/reasoning level configuration diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md index eda035e72a4..d840fd2a0f5 100644 --- a/docs/concepts/multi-agent.md +++ b/docs/concepts/multi-agent.md @@ -550,3 +550,11 @@ If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`. For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent. See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for detailed examples. + +## Related + +- [Channel Routing](/channels/channel-routing) — how messages route to agents +- [Sub-Agents](/tools/subagents) — spawning background agent runs +- [ACP Agents](/tools/acp-agents) — running external coding harnesses +- [Presence](/concepts/presence) — agent presence and availability +- [Session](/concepts/session) — session isolation and routing diff --git a/docs/concepts/session.md b/docs/concepts/session.md index d0c971c655d..fd01c5762fe 100644 --- a/docs/concepts/session.md +++ b/docs/concepts/session.md @@ -111,3 +111,6 @@ Preview with `openclaw sessions cleanup --dry-run`. - [Session Tools](/concepts/session-tool) -- agent tools for cross-session work - [Session Management Deep Dive](/reference/session-management-compaction) -- store schema, transcripts, send policy, origin metadata, and advanced config +- [Multi-Agent](/concepts/multi-agent) — routing and session isolation across agents +- [Background Tasks](/automation/tasks) — how detached work creates task records with session references +- [Channel Routing](/channels/channel-routing) — how inbound messages are routed to sessions diff --git a/docs/concepts/timezone.md b/docs/concepts/timezone.md index ef1c9053f83..36465ffb2f1 100644 --- a/docs/concepts/timezone.md +++ b/docs/concepts/timezone.md @@ -89,3 +89,9 @@ The system prompt includes: You can control the prompt format with `agents.defaults.timeFormat` (`auto` | `12` | `24`). See [Date & Time](/date-time) for the full behavior and examples. + +## Related + +- [Heartbeat](/gateway/heartbeat) — active hours use timezone for scheduling +- [Cron Jobs](/automation/cron-jobs) — cron expressions use timezone for scheduling +- [Date & Time](/date-time) — full date/time behavior and examples diff --git a/docs/docs.json b/docs/docs.json index 49dbca45ff7..dd8a53fd756 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1114,6 +1114,7 @@ { "group": "Automation", "pages": [ + "automation/index", "automation/hooks", "automation/standing-orders", "automation/cron-jobs", diff --git a/docs/gateway/heartbeat.md b/docs/gateway/heartbeat.md index 22fedfc1b73..73e27f406c6 100644 --- a/docs/gateway/heartbeat.md +++ b/docs/gateway/heartbeat.md @@ -397,3 +397,11 @@ Heartbeats run full agent turns. Shorter intervals burn more tokens. To reduce c - Set a cheaper `model` (e.g. `ollama/llama3.2:1b`). - Keep `HEARTBEAT.md` small. - Use `target: "none"` if you only want internal state updates. + +## Related + +- [Automation Overview](/automation) — all automation mechanisms at a glance +- [Cron vs Heartbeat](/automation/cron-vs-heartbeat) — when to use each +- [Background Tasks](/automation/tasks) — how detached work is tracked +- [Timezone](/concepts/timezone) — how timezone affects heartbeat scheduling +- [Troubleshooting](/automation/troubleshooting) — debugging automation issues