AgentSkillsCN

openclaw-cron

管理OpenClaw的Cron任务——创建、编辑、调试并排查计划任务代理。当用户询问关于Cron任务、计划任务、定时自动化，或在诊断Cron错误时（例如“模型不被允许”、“作业失败”、“错过运行”），可使用此功能。

SKILL.md
--- frontmatter
name: openclaw-cron
description: Manage OpenClaw cron jobs — create, edit, debug, and troubleshoot scheduled agent tasks. Use when the user asks about cron jobs, scheduled tasks, timed automation, or when diagnosing cron errors (e.g. "model not allowed", job failures, missed runs).

OpenClaw Cron

Gateway-internal scheduler that persists jobs, wakes agents on schedule, and optionally delivers output to chat.

CLI Quick Reference

CommandUsagePurpose
listopenclaw cron listShow all jobs
statusopenclaw cron statusScheduler status
addopenclaw cron add --name "..." ...Create a job
editopenclaw cron edit <jobId> ...Patch job fields
runopenclaw cron run <jobId>Force-run now
run --dueopenclaw cron run <jobId> --dueRun only if schedule is due
runsopenclaw cron runs --id <jobId> --limit NView run history
enableopenclaw cron enable <jobId>Enable a job
disableopenclaw cron disable <jobId>Disable a job
rmopenclaw cron rm <jobId>Delete a job

Creating Jobs

One-shot (main session)

bash
openclaw cron add --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main --system-event "Check battery" \
  --wake now --delete-after-run

Recurring isolated with delivery

bash
openclaw cron add --name "Morning brief" \
  --cron "0 7 * * *" --tz "Asia/Taipei" \
  --session isolated --message "Summarize updates." \
  --announce --channel telegram --to "YOUR_TELEGRAM_ID"

Key add / edit flags

FlagDescription
--nameJob name
--atOne-shot ISO 8601 timestamp
--cron5-field cron expression
--everyFixed interval (ms)
--tzIANA timezone (default: host tz)
--sessionmain or isolated
--system-eventText payload for main sessions
--messageText prompt for isolated sessions
--modelModel override (e.g. opus, google/gemini-2.5-flash)
--thinkingThinking level: off|minimal|low|medium|high|xhigh
--announceEnable summary delivery
--channelTarget: telegram|whatsapp|slack|discord|signal|imessage|mattermost
--toChannel-specific recipient
--agentBind to specific agent
--clear-agentRemove agent binding (edit only)
--wakenow or next-heartbeat
--delete-after-runAuto-remove one-shot jobs after completion

Editing Jobs

Two approaches:

1. CLI edit (preferred for single fields)

bash
openclaw cron edit <jobId> --message "New prompt" --model "opus"

2. Direct file edit (for fields not exposed by CLI)

Edit ~/.openclaw/cron/jobs.json directly, then restart gateway:

bash
# After editing jobs.json:
openclaw gateway restart && sleep 5 && openclaw health

Job JSON structure — see references/job-schema.md for full schema and examples.

Debugging Failed Jobs

  1. •

    Check run history:

    bash
    openclaw cron runs --id <jobId> --limit 5

    Returns JSON with status, error, durationMs.

  2. •

    Check gateway logs:

    bash
    tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
  3. •

    Check session JSONL (isolated runs): Sessions are stored at ~/.openclaw/agents/<agentId>/sessions/. Isolated cron runs use session key cron:<jobId>.

  4. •

    Common errors:

    • •model not allowed: <model> → Remove or fix model override in payload
    • •429 / RESOURCE_EXHAUSTED → Rate limit hit, check fallback chain
    • •gateway timeout → CLI timeout (30s default), job may still be running in background

Storage Paths

FilePath
Job definitions~/.openclaw/cron/jobs.json
Run history~/.openclaw/cron/runs/<jobId>.jsonl
Gateway logs/tmp/openclaw/openclaw-YYYY-MM-DD.log
Session logs~/.openclaw/agents/<agentId>/sessions/