⏰ OpenClaw Cron 定时任务教程

什么是 OpenClaw Cron？

OpenClaw 的 Cron 系统是一个内置的任务调度器，允许你设置定时任务让 AI Agent 自动执行。它支持 cron 表达式、一次性定时、周期性间隔等多种调度方式，是实现自动化运营的核心能力。

Cron vs 传统 crontab

特性	OpenClaw Cron	传统 crontab
执行者	AI Agent（智能理解任务）	Shell 脚本（机械执行）
任务描述	自然语言	Shell 命令
错误处理	Agent 自主判断和重试	需要脚本编写错误处理
通知	自动推送到聊天频道	需要额外配置
上下文	支持上下文传递	无状态

核心概念

调度类型（Schedule Kind）

类型	说明	使用场景
at	一次性定时执行	提醒、延迟任务
every	固定间隔重复	轮询、监控
cron	Cron 表达式	定时报告、定期任务

负载类型（Payload Kind）

类型	说明	会话目标
systemEvent	注入系统事件文本	main（主会话）
agentTurn	执行 Agent 对话	isolated / current / session:*

基础用法：创建简单提醒

一次性提醒（使用 qqbot_remind）

// 5分钟后提醒
qqbot_remind({
  action: "add",
  content: "该喝水了！💧",
  time: "5m"
})

// 每天早上8点提醒
qqbot_remind({
  action: "add",
  content: "早上好！查看今日AI新闻日报",
  time: "0 8 * * *"
})

使用 Cron 工具创建定时任务

// 每天早上8点执行新闻日报生成
cron({
  action: "add",
  job: {
    name: "daily-ai-news",
    schedule: {
      kind: "cron",
      expr: "0 8 * * *",
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: "生成今日AI新闻日报，搜索最新的AI行业新闻，生成HTML页面并发布到网站。"
    },
    sessionTarget: "isolated",
    delivery: { mode: "announce" }
  }
})

Cron 表达式速查

表达式	含义
0 8 * * *	每天早上 8:00
0 */2 * * *	每 2 小时
0 9 * * 1-5	工作日早上 9:00
30 1 * * 0	每周日凌晨 1:30
0 0 1 * *	每月1号 00:00
*/15 * * * *	每 15 分钟
0 8,12,18 * * *	每天 8:00, 12:00, 18:00

实战案例

案例1：每日营销报告

cron({
  action: "add",
  job: {
    name: "daily-marketing-report",
    schedule: {
      kind: "cron",
      expr: "0 22 * * *",
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: "生成今日营销报告：1) 统计今日网站访问量 2) 分析热门页面 3) 汇总社区互动数据 4) 生成HTML报告"
    },
    sessionTarget: "isolated",
    delivery: { mode: "announce" }
  }
})

案例2：竞品监控（每4小时）

cron({
  action: "add",
  job: {
    name: "competitor-monitor",
    schedule: {
      kind: "cron",
      expr: "0 */4 * * *",
      tz: "Asia/Shanghai"
    },
    payload: {
      kind: "agentTurn",
      message: "监控竞品动态：检查 futuretools.io, thereisanaiforthat.com, futurepedia.io 的最新变化，发现重大更新时通知。"
    },
    sessionTarget: "isolated",
    delivery: { mode: "announce" }
  }
})

案例3：固定间隔轮询

cron({
  action: "add",
  job: {
    name: "rss-check",
    schedule: {
      kind: "every",
      everyMs: 7200000  // 每2小时（毫秒）
    },
    payload: {
      kind: "agentTurn",
      message: "检查RSS订阅源是否有新内容，发现新文章时聚合到网站。"
    },
    sessionTarget: "isolated"
  }
})

管理定时任务

查看所有任务

// 列出所有任务
cron({ action: "list" })

// 包含已禁用的任务
cron({ action: "list", includeDisabled: true })

获取任务详情

cron({
  action: "get",
  jobId: "daily-ai-news"
})

更新任务

// 修改执行时间
cron({
  action: "update",
  jobId: "daily-ai-news",
  patch: {
    schedule: {
      kind: "cron",
      expr: "0 9 * * *",  // 改为9点执行
      tz: "Asia/Shanghai"
    }
  }
})

// 禁用任务
cron({
  action: "update",
  jobId: "daily-ai-news",
  patch: { enabled: false }
})

手动触发任务

cron({
  action: "run",
  jobId: "daily-ai-news"
})

删除任务

cron({
  action: "remove",
  jobId: "daily-ai-news"
})

会话目标详解

sessionTarget	payload.kind	说明
main	systemEvent	注入主会话，触发主Agent处理
isolated	agentTurn	独立会话执行，不干扰主会话
current	agentTurn	绑定到创建时的当前会话
session:xxx	agentTurn	指定特定会话执行

错误告警配置

cron({
  action: "add",
  job: {
    name: "critical-monitor",
    schedule: { kind: "cron", expr: "*/5 * * * *" },
    payload: {
      kind: "agentTurn",
      message: "检查服务器状态..."
    },
    sessionTarget: "isolated",
    failureAlert: {
      after: 3,           // 连续失败3次后告警
      cooldownMs: 300000,  // 告警冷却5分钟
      mode: "announce"
    }
  }
})

最佳实践

• 时区设置：始终指定 tz: "Asia/Shanghai"，避免时区混淆
• 任务命名：使用有意义的名称，如 "daily-news-report" 而非 "task1"
• 合理间隔：避免过于频繁的执行（如每分钟），除非确实需要
• 错误处理：为关键任务配置 failureAlert
• 定期审查：定期使用 cron({ action: "list" }) 检查所有任务