Cron Helper Skill

Purpose: Guides me to use openclaw cron CLI for time-based tasks and send logs on create/remove.

When to use:

User asks for periodic/reminder tasks
User mentions "remind me every X"
User needs scheduled background checks
User wants agent to perform a task at a specific time

Core Principle

Always prefer cron over manual timing.

Reason: I lack an internal clock. Manual "track time yourself" fails because I can get absorbed in reading/thinking and lose track of time. Cron is an external clock that works reliably.

Main vs Isolated Session

Isolated Session (RECOMMENDED for tasks) ✅ Best Practice

Use --session isolated when you want the agent to actually perform a task:

Agent receives the message and executes it
Can use tools (exec, read, message, etc.)
Can deliver output to a channel
Does not pollute main conversation history

Format:

openclaw cron add \
  --name "job_name" \
  --cron "0 9 * * *" \
  --session isolated \
  --message "Task instructions for the agent" \
  --deliver \
  --channel feishu

Main Session (simple notifications only)

Use --session main with --system-event for simple notifications only:

Just displays a message in main chat
Agent does NOT execute any tasks
No tool calls, no delivery

Format:

openclaw cron add \
  --name "reminder" \
  --at "+30m" \
  --session main \
  --system-event "Reminder: check email"

How I Should Respond

Step 1: Detect the request

Keywords: "every", "remind", "schedule", "定时", "每小时/每天/每周", "在X分钟后执行"

Step 2: Ask for details

Get from user:

What - task description or notification message
When - schedule (e.g., "every 2 hours", "at 9am daily", "in 10 minutes")
Delivery - does output need to be sent to a chat? (default: no)
Name - job name (optional, auto-generated if not provided)

Step 3: Create cron job

For agent tasks (RECOMMENDED):

openclaw cron add \
  --name "task_name" \
  --at "+10m" \
  --session isolated \
  --message "Your task instructions here" \
  --deliver \
  --channel feishu

For simple reminders:

openclaw cron add \
  --name "reminder" \
  --at "+10m" \
  --session main \
  --system-event "Your reminder message"

Remove a cron job:

openclaw cron rm <job_id>

List all cron jobs:

openclaw cron list

Other useful commands:

openclaw cron status          # 查看调度器状态
openclaw cron run <job_id>    # 立即触发任务
openclaw cron enable <job_id> # 启用任务
openclaw cron disable <job_id> # 禁用任务
openclaw cron runs <job_id>   # 查看执行历史

Delivery Options

When using --session isolated, you can deliver output to a chat:

Option	Description
`--deliver`	Enable delivery (required for channel output)
`--channel <name>`	Channel: feishu, telegram, slack, whatsapp, etc.
`--to <dest>`	Channel-specific target (chat ID, phone, etc.)
`--post-mode full`	Post full output instead of summary

Examples:

# Deliver to Feishu
--deliver --channel feishu

# Deliver to Telegram
--deliver --channel telegram --to "-1001234567890"

# Deliver with full output
--deliver --channel feishu --post-mode full

Common Options

Option	Description
`--cron <expr>`	Cron expression (5-field or 6-field with seconds)
`--every <duration>`	Run every duration (e.g., 10m, 1h)
`--at <when>`	Run once at time (ISO or +duration, supports m/s)
`--tz <iana>`	Timezone (default: local)
`--session main\|isolated`	Target session (default: main)
`--system-event <text>`	System event payload (main session only)
`--message <text>`	Agent message payload (isolated session only)
`--delete-after-run`	Delete one-shot job after success
`--disabled`	Create job in disabled state

Step 4: Send log

On CREATE/REMOVE only:

After creating or removing cron jobs, send ONE log with the exact command:

Log format:

# 新增任务
[HH:MM] CRON ✅
$ openclaw cron add \
  --name "job_name" \
  --at "+10m" \
  --session isolated \
  --message "task description" \
  --deliver \
  --channel feishu

# 删除任务
[HH:MM] CRON ❌
$ openclaw cron rm <job_id>

Examples:

# 新增
[21:30] CRON ✅
$ openclaw cron add \
  --name "daily-summary" \
  --cron "0 9 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "总结今天的工作" \
  --deliver \
  --channel feishu

# 删除
[21:41] CRON ❌
$ openclaw cron rm 983a0f0e-0976-414a-b3d0-fd09c533e301

Key points:

Send log ONLY on create/remove, NOT on execution
Keep it minimal: One command block, no extra text

Cron → Human mapping (五位 - 分时日月周):

*/5 * * * * → 每5分钟
*/30 * * * * → 每30分钟
0 * * * * → 每1小时
0 */2 * * * → 每2小时
0 9 * * * → 每天1次(09:00)
0 10,22 * * * → 每天2次(10:00,22:00)
0 9 * * 1 → 每周1次(周一09:00)

Cron → Human mapping (六位 - 秒分时日月周):

*/1 * * * * * → 每1秒
*/5 * * * * * → 每5秒
*/30 * * * * * → 每30秒

Best Practice Summary

Use Case	Session	Payload	Delivery
Agent performs task	`isolated`	`--message`	`--deliver` ✅
Simple notification	`main`	`--system-event`	❌

Rule of thumb: If you want the agent to do something (use tools, send messages), use --session isolated + --message.

What NOT To Do

❌ Don't say "I'll set a reminder myself" ❌ Don't try to track time manually ❌ Don't use --system-event when you need the agent to execute tasks ❌ Don't forget --deliver when you need output sent to chat ❌ Don't send execution logs (only log on create/remove)

✅ Always use the openclaw cron CLI ✅ Use --session isolated for agent tasks ✅ Use --session main for simple notifications only ✅ Send log on create/remove only ✅ Keep log simple and clean

Common Schedule Patterns

五位 Cron（分时日月周）

Frequency	Cron Expression	CLI Flag
Every 5 min	`/5 * * *`	`--cron "/5 * * *"`
Every 30 min	`/30 * * *`	`--cron "/30 * * *"`
Every hour	`0 * * * *`	`--cron "0 * * * *"`
Every 2 hours	`0 /2 * *`	`--cron "0 /2 * *"`
Daily at 9am	`0 9 * * *`	`--cron "0 9 * * *"`
Twice daily (10am, 10pm)	`0 10,22 * * *`	`--cron "0 10,22 * * *"`
Weekly (Monday 9am)	`0 9 * * 1`	`--cron "0 9 * * 1"`

六位 Cron（秒分时日月周）

Frequency	Cron Expression	CLI Flag
Every 1 second	`/1 * * * *`	`--cron "/1 * * * *"`
Every 5 seconds	`/5 * * * *`	`--cron "/5 * * * *"`
Every 30 seconds	`/30 * * * *`	`--cron "/30 * * * *"`

Duration flags:

Frequency	CLI Flag
Every 10 minutes	`--every "10m"`
Every 2 hours	`--every "2h"`
Once in 20 minutes	`--at "+20m"`
Once in 20 seconds	`--at "+20s"`

Loaded automatically when skill is installed.

cron-helper