<!-- source: https://deepwiki.com/openclaw/openclaw/3.7-automation-and-cron -->

# Automation & Cron

- packages/gateway-protocol/src/cron-validators.test.ts
- packages/gateway-protocol/src/schema/cron.ts
- src/agents/session-suspension.test.ts
- src/agents/session-suspension.ts
- src/agents/tool-error-summary.ts
- src/agents/tools/cron-tool.schema.test.ts
- src/agents/tools/cron-tool.test.ts
- src/agents/tools/cron-tool.ts
- src/commands/doctor-cron.ts
- src/config/sessions/store.runtime.ts
- src/cron/delivery-plan.test.ts
- src/cron/delivery-plan.ts
- src/cron/delivery-preview.test.ts
- src/cron/delivery-preview.ts
- src/cron/delivery.test.ts
- src/cron/isolated-agent.direct-delivery-core-channels.test.ts
- src/cron/isolated-agent.helpers.test.ts
- src/cron/isolated-agent.mocks.ts
- src/cron/isolated-agent.model-formatting.test.ts
- src/cron/isolated-agent.model-preflight.test.ts
- src/cron/isolated-agent/delivery-dispatch.double-announce.test.ts
- src/cron/isolated-agent/delivery-dispatch.named-agent.test.ts
- src/cron/isolated-agent/delivery-dispatch.ts
- src/cron/isolated-agent/helpers.ts
- src/cron/isolated-agent/model-selection.ts
- src/cron/isolated-agent/run-delivery.runtime.ts
- src/cron/isolated-agent/run-executor.ts
- src/cron/isolated-agent/run-fallback-policy.test.ts
- src/cron/isolated-agent/run-fallback-policy.ts
- src/cron/isolated-agent/run-model-selection.runtime.ts
- src/cron/isolated-agent/run.diagnostic-events.test.ts
- src/cron/isolated-agent/run.fast-mode.test.ts
- src/cron/isolated-agent/run.message-tool-policy.test.ts
- src/cron/isolated-agent/run.payload-fallbacks.test.ts
- src/cron/isolated-agent/run.runtime-plugins.test.ts
- src/cron/isolated-agent/run.session-key-isolation.test.ts
- src/cron/isolated-agent/run.suite-helpers.ts
- src/cron/isolated-agent/run.test-harness.ts
- src/cron/isolated-agent/run.ts
- src/cron/normalize.test.ts
- src/cron/normalize.ts
- src/cron/run-diagnostics.test.ts
- src/cron/run-diagnostics.ts
- src/cron/run-log.error-reason.test.ts
- src/cron/run-log.test.ts
- src/cron/run-log.ts
- src/cron/run-log/sqlite-store.ts
- src/cron/service.every-jobs-fire.test.ts
- src/cron/service.get-job.test.ts
- src/cron/service.issue-16156-list-skips-cron.test.ts
- src/cron/service.issue-regressions.test.ts
- src/cron/service.jobs.test.ts
- src/cron/service.main-job-passes-heartbeat-target-last.test.ts
- src/cron/service.restart-catchup.test.ts
- src/cron/service.runs-one-shot-main-job-disables-it.test.ts
- src/cron/service.test-harness.ts
- src/cron/service/jobs.apply-patch.test.ts
- src/cron/service/jobs.ts
- src/cron/service/ops.test.ts
- src/cron/service/state.ts
- src/cron/service/store.load-missing-session-target.test.ts
- src/cron/service/store.test.ts
- src/cron/service/store.ts
- src/cron/service/task-ledger.ts
- src/cron/service/timer.regression.test.ts
- src/cron/service/timer.test.ts
- src/cron/service/timer.ts
- src/cron/store.test.ts
- src/cron/store.ts
- src/cron/store/delivery-codec.ts
- src/cron/store/failure-alert-codec.ts
- src/cron/store/payload-codec.ts
- src/cron/store/row-codec.ts
- src/cron/store/scalar-codec.ts
- src/cron/store/schema.ts
- src/cron/store/state-codec.ts
- src/cron/types.ts
- src/gateway/server-cron.test.ts
- src/gateway/server-cron.ts
- src/gateway/server-methods/cron.ts
- src/gateway/server-methods/cron.validation.test.ts
- src/gateway/server.cron.test.ts
- src/infra/heartbeat-wake.test.ts
- src/infra/heartbeat-wake.ts
- src/infra/outbound/agent-delivery.test.ts
- src/infra/outbound/bound-delivery-router.test.ts
- src/infra/outbound/message-action-runner.poll.test.ts
- src/infra/outbound/outbound-session.test-helpers.ts
- src/infra/outbound/outbound-session.test.ts
- src/infra/outbound/outbound-session.ts
- src/poll-params.test.ts
- src/poll-params.ts
- src/state/openclaw-state-db.test.ts

OpenClaw features a built-in automation engine managing scheduled tasks, recurring agent turns, and proactive "heartbeat" interactions. This system is centered around the Gateway's internal scheduler, which handles persistent job storage, scheduling logic, and execution across different session scopes [src/gateway/server-cron.ts121-124](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-cron.ts#L121-L124)

## 1. Cron Job Architecture

The Gateway's cron system supports multiple job types and session targets, allowing agents to perform background tasks or initiate conversations autonomously [src/cron/types.ts47-50](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/types.ts#L47-L50) Job definitions persist at a location defined in the configuration, typically `cron.json` [src/gateway/server-cron.ts123](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-cron.ts#L123-L123)

### 1.1 Job Types and Session Targets

Jobs are categorized by their `sessionTarget`, which determines the execution context and workspace isolation [src/cron/types.ts47](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/types.ts#L47-L47)

### 1.2 Scheduling Syntax

OpenClaw supports three scheduling kinds [src/cron/normalize.ts58](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/normalize.ts#L58-L58):

- at : One-shot timestamp (ISO 8601).
- every : Fixed interval execution based on everyMs src/cron/normalize.ts 82
- cron : Standard cron expressions with optional tz (IANA timezone) for wall-clock scheduling src/cron/normalize.ts 108-112

**Staggering and Jitter**
To prevent resource spikes, jobs using `cron` expressions can include a `staggerMs` window [src/cron/normalize.ts88](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/normalize.ts#L88-L88) The system calculates a deterministic offset based on the `jobId` to ensure the job always fires at the same relative offset within its window [src/cron/service/jobs.ts95-116](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/service/jobs.ts#L95-L116)

Sources: [src/gateway/server-cron.ts121-186](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-cron.ts#L121-L186) [src/cron/types.ts47-50](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/types.ts#L47-L50) [src/cron/normalize.ts55-115](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/normalize.ts#L55-L115) [src/cron/service/jobs.ts95-116](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/service/jobs.ts#L95-L116)

## 2. Isolated Agent Runner

Isolated session cron jobs facilitate background agent tasks using a unique session to avoid polluting the main conversation memory [src/cron/isolated-agent/run.ts174](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/run.ts#L174-L174)

### 2.1 Execution Lifecycle

The isolated runner prepares a complete agent environment for each run [src/cron/isolated-agent/run.ts195-210](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/run.ts#L195-L210)

1. Session Resolution : resolveCronAgentSessionKey src/cron/isolated-agent/run.ts 94 assigns a distinct session key.
2. Model Selection : resolveCronModelSelection src/cron/isolated-agent/run.ts 56 determines the LLM to use, checking payload overrides before falling back to agent defaults.
3. Preflight & Fallbacks : If the primary model fails, the system attempts resolveCronPreflightCandidates src/cron/isolated-agent/run.ts 58 to find viable alternatives.
4. Tool Policy : The runner manages tool restrictions via expandToolGroups src/cron/isolated-agent/run.ts 6 It can explicitly allow or deny tools based on the toolsAllow field in the payload src/agents/tools/cron-tool.ts 144
5. Agent Turn : createCronPromptExecutor src/cron/isolated-agent/run-executor.ts 119 invokes the agent, managing the runWithModelFallback loop src/cron/isolated-agent/run-executor.ts 183
6. Teardown : The runner disposes of bundled MCP runtime instances via retireRolledCronSessionMcpRuntime src/cron/isolated-agent/run.ts 170-191

### 2.2 Delivery Dispatch

The `dispatchCronDelivery` function manages how agent output reaches the user or external systems [src/cron/isolated-agent/delivery-dispatch.ts154](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/delivery-dispatch.ts#L154-L154)

- Announce : Delivers a summary to a target channel (Telegram, Discord, etc.) src/agents/tools/cron-tool.ts 54
- Webhook : Jobs can post results to external HTTP endpoints src/agents/tools/cron-tool.ts 54
- Suppression : If the agent return is identified as a heartbeat-only response via isHeartbeatOnlyResponse src/cron/isolated-agent/run.ts 52 outbound delivery may be suppressed.
- Subagent Awareness : The dispatcher checks expectsSubagentFollowup and isLikelyInterimCronMessage src/cron/isolated-agent/delivery-dispatch.double-announce.test.ts 130-133 to prevent premature or duplicate notifications during long-running subagent tasks.

Sources: [src/cron/isolated-agent/run.ts56-191](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/run.ts#L56-L191) [src/cron/isolated-agent/run-executor.ts119-183](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/run-executor.ts#L119-L183) [src/agents/tools/cron-tool.ts54-144](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/tools/cron-tool.ts#L54-L144) [src/cron/isolated-agent/delivery-dispatch.ts154](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/delivery-dispatch.ts#L154-L154)

## 3. Heartbeat Integration

Heartbeats are periodic main-session turns that allow the agent to surface items needing attention [src/infra/heartbeat-wake.ts5](https://github.com/openclaw/openclaw/blob/fbdf5937/src/infra/heartbeat-wake.ts#L5-L5)

### 3.1 Heartbeat Logic and Wake-ups

The Gateway manages periodic proactive turns through a heartbeat runner [src/gateway/server-cron.ts24-25](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-cron.ts#L24-L25)

### 3.2 Code to Entity Mapping: Heartbeat

```

```

Sources: [src/gateway/server-cron.ts24-26](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-cron.ts#L24-L26) [src/infra/heartbeat-wake.ts5-10](https://github.com/openclaw/openclaw/blob/fbdf5937/src/infra/heartbeat-wake.ts#L5-L10)

## 4. Execution Safety and Reliability

### 4.1 Watchdogs and Timeouts

The system uses a watchdog mechanism to ensure jobs do not hang indefinitely [src/cron/service/timer.ts149-158](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/service/timer.ts#L149-L158)

- executeJobCoreWithTimeout : Wraps job execution with a wall-clock timeout src/cron/service/timer.ts 120
- Phase Tracking : For isolated runs, the watchdog tracks setup phases (e.g., model preflight) separately from the actual agent turn to provide better diagnostics on failure src/cron/service/timer.ts 139-153

### 4.2 Error Backoff

When a job fails, the system applies an exponential backoff schedule to prevent "spamming" failing providers [src/cron/service/jobs.ts43-49](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/service/jobs.ts#L43-L49)

- resolveJobErrorBackoffUntilMs : Calculates the next allowed run time based on the number of consecutiveErrors src/cron/service/jobs.ts 75-93

### 4.3 Process Cleanup

To prevent resource leaks, the system performs lifecycle cleanup for browser sessions and sub-processes associated with cron session keys [src/gateway/server-cron.ts4](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-cron.ts#L4-L4)

Sources: [src/cron/service/timer.ts120-158](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/service/timer.ts#L120-L158) [src/cron/service/jobs.ts43-93](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/service/jobs.ts#L43-L93) [src/gateway/server-cron.ts4](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-cron.ts#L4-L4)

## 5. System Architecture

This diagram illustrates the data flow from a cron trigger through execution to delivery.

```

```

Sources: [src/cron/service/store.ts65-66](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/service/store.ts#L65-L66) [src/cron/service/timer.ts120](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/service/timer.ts#L120-L120) [src/cron/isolated-agent/run.ts93-111](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/run.ts#L93-L111) [src/cron/isolated-agent/run-executor.ts119-183](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/run-executor.ts#L119-L183) [src/cron/isolated-agent/delivery-dispatch.ts154](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/delivery-dispatch.ts#L154-L154)

## 6. Code to Entity Mapping: Delivery

The delivery system maps high-level "announce" or "webhook" requests to specific outbound infrastructure.

```

```

Sources: [src/cron/isolated-agent/run.ts33-50](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/run.ts#L33-L50) [src/cron/isolated-agent/helpers.ts52](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/helpers.ts#L52-L52) [src/cron/isolated-agent/delivery-dispatch.ts154](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cron/isolated-agent/delivery-dispatch.ts#L154-L154)
