OpenClaw Cron Task Plugin Configuration

Overview

OpenClaw's built-in cron tool allows AI agents to create, manage, and execute scheduled tasks. Whether it's periodic data scraping, recurring report generation, or timed message reminders, the cron tool can handle it all. As one of the built-in tools in the seven-stage tool pipeline, it is deeply integrated with OpenClaw's session system and messaging channels.

Cron Tool Architecture

The cron tool runs within the Pi SDK embedding layer, leveraging a system-level scheduler to manage tasks. Each scheduled task is essentially a predefined agent action that creates a new agent session upon triggering.

How It Differs from Traditional Cron

Traditional cron executes fixed shell commands, whereas OpenClaw's cron executes AI agent actions. This means scheduled tasks can involve intelligent decision-making — for example, "Check the weather every morning at 9 AM, and if rain is forecasted, remind me to bring an umbrella." The AI agent will decide whether to send a reminder based on the actual weather conditions.

Basic Configuration

Enabling the Cron Tool

tools:
  cron:
    enabled: true
    maxTasks: 50
    minInterval: 60
    storage: /data/openclaw/cron
    timezone: "Asia/Shanghai"

Parameter Reference

maxTasks: Maximum number of scheduled tasks the system allows
minInterval: Minimum execution interval (in seconds) to prevent overly frequent tasks
storage: Persistent storage path for task definitions
timezone: Default timezone setting

Creating Scheduled Tasks

Via Conversation

Users can create scheduled tasks directly through natural language conversation with the AI agent. For example:

"Send me a news digest every morning at 8 AM"
"Remind me about the weekly meeting every Monday at 2 PM"
"Check a website for price changes every 6 hours"

The AI agent will parse the user's intent and convert it into a cron expression and execution action.

Cron Expressions

OpenClaw supports standard five-field cron expressions:

Minute Hour Day Month DayOfWeek

Extended syntax is also supported:

@hourly — Execute every hour
@daily — Execute daily (at midnight)
@weekly — Execute weekly
@monthly — Execute monthly
*/N — Execute every N units

Task Definition Structure

Each scheduled task contains the following information:

{
  "id": "task-uuid",
  "name": "Daily News Digest",
  "schedule": "0 8 * * *",
  "channelId": "discord-channel-123",
  "userId": "user-456",
  "action": "Search for today's trending news, generate a digest, and send it to the channel",
  "enabled": true,
  "createdAt": "2026-03-14T10:00:00Z",
  "lastRun": null,
  "nextRun": "2026-03-15T08:00:00Z"
}

Task Execution Flow

When a scheduled task triggers, the system performs the following steps:

Session Creation: A new agent session is created for the task
Context Restoration: Channel information and user preferences associated with the task are loaded
System Prompt Construction: buildAgentSystemPrompt() is called to generate an appropriate system prompt
Tool Preparation: Available tools are prepared through the seven-stage pipeline
Action Execution: The AI agent executes the predefined action
Result Distribution: Execution results are sent to the designated channel
Status Update: The task's lastRun and nextRun records are updated

Task Management

Viewing the Task List

Users can query their current scheduled tasks through conversation: "Show me all my scheduled tasks." The AI agent will list all tasks associated with the user along with their status.

Modifying and Deleting

Tasks can be modified at any time — you can change the execution time, action content, or target channel. You can also temporarily disable a task without deleting it, making it easy to re-enable later.

Execution History

The result of each task execution is recorded, including execution time, success status, output content, and resource consumption. Users can review the history to evaluate task effectiveness.

Collaboration with Other Tools

The power of the cron tool lies in its ability to trigger operations using any other available tools:

cron + browser: Periodically capture webpage snapshots and monitor page changes
cron + web: Periodically call APIs to fetch data updates
cron + messaging: Periodically send notifications to multiple channels
cron + sessions: Periodically clean up expired session data

Error Handling and Retries

Retry Strategy

tools:
  cron:
    retry:
      maxAttempts: 3
      backoff: exponential
      initialDelay: 60
      maxDelay: 3600

When a task execution fails, the system will automatically retry according to the configured retry strategy. The exponential backoff strategy ensures that frequent retries don't overburden the system.

Failure Notifications

Tasks that fail consecutively will trigger alert notifications. Administrators can configure notification methods (channel messages, email, etc.) and trigger thresholds.

Resource Control

To prevent scheduled tasks from consuming excessive resources, OpenClaw provides multi-dimensional limits:

Concurrency Limit: Maximum number of tasks executing simultaneously
Execution Duration Limit: Maximum execution time for a single task
Frequency Limit: Minimum execution interval for the same task
Quota Management: Maximum number of tasks each user can create

Persistence

Cron task definitions are persisted using JSONL format. The system periodically performs compaction on task data, merging historical records to manage storage space. This is consistent with OpenClaw's session persistence mechanism.

Summary

OpenClaw's cron tool combines traditional scheduled tasks with the intelligent decision-making capabilities of AI agents. This means scheduled tasks are no longer limited to mechanical repetitive execution — they can respond flexibly based on real-time conditions. Making good use of this tool can significantly improve the efficiency of automated operations and information gathering.