Create Cron Job#

Set up a scheduled task per conventions/cron.md. Read the convention first.

Need a periodic check instead? Consider HEARTBEAT.md — see "Cron vs Heartbeat" in conventions/cron.md.

Before You Start#

Determine:

• Which agent handles the job
• Main session (needs conversation context) or isolated (standalone)
• Delivery mode (announce, webhook, none)

Steps#

1. Choose the execution mode#

QuestionIf yesIf noDoes the task need recent conversation context?Main sessionIsolatedDoes the agent need its AGENTS.md/SOUL.md?Isolated (normal)Isolated + lightContextIs this a one-shot reminder?--at with --delete-after-runRecurring schedule

2. Choose a job name#

Format: <agent-id>-<purpose> in kebab-case.

Examples: auditor-daily-report, archivist-daily-backup, reminder-standup-meeting

3. Choose a schedule#

PatternCLI flagExampleCron expression--cron``--cron "0 7 * * *" (7 AM daily)Fixed interval--every``--every "4h"One-shot (relative)--at``--at "20m"One-shot (absolute)--at``--at "2026-03-15T09:00:00Z"

Always set timezone for cron expressions: --tz "America/Los_Angeles"

4. Create the job#

Main session (task needs conversational context):

bash

openclaw cron add \
  --name "<agent-id>-<purpose>" \
  --every "<interval>" \
  --session main \
  --system-event "<instruction text>" \
  --wake now

Isolated (standalone task):

bash

openclaw cron add \
  --name "<agent-id>-<purpose>" \
  --cron "<expr>" \
  --tz "<timezone>" \
  --session isolated \
  --message "<instruction text>" \
  --agent <agent-id> \
  --announce \
  --channel <channel> \
  --to "<target>"

Isolated + lightweight context (simple, self-contained chore):

bash

openclaw cron add \
  --name "<agent-id>-<purpose>" \
  --every "<interval>" \
  --session isolated \
  --message "<self-contained instruction>" \
  --light-context \
  --announce

One-shot reminder:

bash

openclaw cron add \
  --name "reminder-<purpose>" \
  --at "<time>" \
  --session isolated \
  --message "<reminder text>" \
  --announce \
  --delete-after-run

5. Bind to an agent#

Always use --agent <agent-id> for agent-specific jobs.

6. Set delivery mode#

• Announce (most jobs): --announce --channel <ch> --to "<target>"
• Webhook: --webhook <url>
• None: omit delivery flags

7. Document in the agent's AGENTS.md#

markdown

## Scheduled Tasks

| Job | Schedule | Message | Action |
|---|---|---|---|
| `<job-name>` | `<schedule>` | `<message>` | <what the agent does> |

8. Create a skill if the job uses scripts#

If the cron job executes scripts (not just a self-contained message), create a skill using the create-skill skill:

• Scripts live in workspace/skills/<skill-name>/scripts/, not in ad-hoc workspace directories
• The skill makes the capability discoverable for on-demand use, not just cron
• Description should cover both automated (cron) and on-demand (user request) triggers
• See "Workspace File Placement" in conventions/skills.md for where files belong

Skip if the cron job's message is fully self-contained (no external scripts or supporting files).

9. Test the job#

bash

openclaw cron run <jobId>           # Force immediate execution
openclaw cron list                  # Verify job exists
openclaw cron runs --id <jobId>     # Check run history

Post-Creation Checklist#

• Job name follows <agent-id>-<purpose> kebab-case convention
• Timezone set for cron expressions ( --tz)
• Explicit --agent binding for agent-specific jobs
• Delivery mode set (announce/webhook/none)
• Channel and target specified for announce delivery
• Agent's AGENTS.md updated with Scheduled Tasks entry
• Job tested with openclaw cron run <jobId>
• No duplicate: checked that no system crontab or existing job covers the same task
• One-shot reminders use --delete-after-run
• If job uses scripts: skill created in workspace/skills/<name>/ with scripts in its scripts/ subdir
• No ad-hoc files or directories created at workspace root (see conventions/skills.md)