cron-helper

SKILL.md

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.