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

2. Choose a job name

Format: \x3Cagent-id>-\x3Cpurpose> in kebab-case.

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

3. Choose a schedule

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

4. Create the job

Main session (task needs conversational context):

openclaw cron add \
  --name "\x3Cagent-id>-\x3Cpurpose>" \
  --every "\x3Cinterval>" \
  --session main \
  --system-event "\x3Cinstruction text>" \
  --wake now

Isolated (standalone task):

openclaw cron add \
  --name "\x3Cagent-id>-\x3Cpurpose>" \
  --cron "\x3Cexpr>" \
  --tz "\x3Ctimezone>" \
  --session isolated \
  --message "\x3Cinstruction text>" \
  --agent \x3Cagent-id> \
  --announce \
  --channel \x3Cchannel> \
  --to "\x3Ctarget>"

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

openclaw cron add \
  --name "\x3Cagent-id>-\x3Cpurpose>" \
  --every "\x3Cinterval>" \
  --session isolated \
  --message "\x3Cself-contained instruction>" \
  --light-context \
  --announce

One-shot reminder:

openclaw cron add \
  --name "reminder-\x3Cpurpose>" \
  --at "\x3Ctime>" \
  --session isolated \
  --message "\x3Creminder text>" \
  --announce \
  --delete-after-run

5. Bind to an agent

Always use --agent \x3Cagent-id> for agent-specific jobs.

6. Set delivery mode

• Announce (most jobs): --announce --channel \x3Cch> --to "\x3Ctarget>"
• Webhook: --webhook \x3Curl>
• None: omit delivery flags

7. Document in the agent's AGENTS.md

## Scheduled Tasks

| Job | Schedule | Message | Action |
|---|---|---|---|
| `\x3Cjob-name>` | `\x3Cschedule>` | `\x3Cmessage>` | \x3Cwhat 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/\x3Cskill-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

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

Post-Creation Checklist

• Job name follows \x3Cagent-id>-\x3Cpurpose> 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 \x3CjobId>
• 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/\x3Cname>/ with scripts in its scripts/ subdir
• No ad-hoc files or directories created at workspace root (see conventions/skills.md)