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.