⏰ OpenClaw Cron 定时任务完全指南

让AI Agent 24/7自动运行 — 从定时提醒到复杂工作流调度

📋 目录

🎯 Cron基础概念

OpenClaw的cron系统由三个核心组件构成：

快速示例

// 设置一个5分钟后的提醒
cron({
  action: "add",
  job: {
    name: "喝水提醒",
    schedule: { kind: "at", at: "2026-06-08T01:10:00+08:00" },
    payload: { kind: "systemEvent", text: "⏰ 提醒：该喝水了！" }
  }
})

// 设置每天早上8点的日报任务
cron({
  action: "add",
  job: {
    name: "每日AI日报",
    schedule: { kind: "cron", expr: "0 8 * * *", tz: "Asia/Shanghai" },
    payload: {
      kind: "agentTurn",
      message: "生成今日AI新闻日报并发布到网站"
    },
    delivery: { mode: "announce" }
  }
})

📅 调度类型详解

类型一：一次性（at）

// 在指定时间执行一次
schedule: {
  kind: "at",
  at: "2026-06-08T14:30:00+08:00"   // ISO-8601格式
}

类型二：周期性（every）

// 每隔固定时间执行
schedule: {
  kind: "every",
  everyMs: 3600000,    // 每1小时（毫秒）
  anchorMs: 1686201600000  // 可选：锚定起始时间
}

// 常用间隔
// 5分钟: 300000
// 1小时: 3600000
// 6小时: 21600000
// 24小时: 86400000

类型三：Cron表达式（cron）

// 标准cron表达式
schedule: {
  kind: "cron",
  expr: "0 8 * * *",           // 每天早上8点
  tz: "Asia/Shanghai"          // 时区
}

// 常用cron表达式
// "0 8 * * *"       → 每天08:00
// "0 9 * * 1-5"     → 工作日09:00
// "0 */2 * * *"     → 每2小时
// "30 18 * * 5"     → 每周五18:30
// "0 0 1 * *"       → 每月1号00:00
// "0 8,12,18 * * *" → 每天8点、12点、18点

📦 任务类型

systemEvent — 系统事件

// 注入一条系统事件到主会话
payload: {
  kind: "systemEvent",
  text: "⏰ 提醒：14:00有SEO策略会议"
}

// 适用场景：
// - 定时提醒
// - 系统通知
// - 触发Agent响应

agentTurn — Agent执行

// 让Agent执行一个完整任务
payload: {
  kind: "agentTurn",
  message: "搜索今天的AI热点新闻，生成日报并发布到网站",
  model: "gpt-4o",           // 可选：指定模型
  thinking: "medium",        // 可选：思考深度
  timeoutSeconds: 600,       // 可选：超时时间（10分钟）
  lightContext: true          // 可选：轻量上下文
}

// 适用场景：
// - 定时内容生成
// - 自动化数据采集
// - 周期性报告

📬 结果投递

// 发送到飞书群
delivery: {
  mode: "announce",
  channel: "feishu",
  to: "oc_c942dfd09730eb94bf838c6519c115e9"
}

// Webhook投递
delivery: {
  mode: "webhook",
  to: "https://your-server.com/webhook"
}

// 发送到当前对话
delivery: {
  mode: "announce"
}

🔧 任务管理

查看所有任务

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

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

获取任务详情

cron({
  action: "get",
  jobId: "0d3d9265-8cd6-4069-aa52-d32c33a30580"
})

更新任务

// 修改调度时间
cron({
  action: "update",
  jobId: "0d3d9265-8cd6-4069-aa52-d32c33a30580",
  patch: {
    schedule: { kind: "cron", expr: "0 9 * * *", tz: "Asia/Shanghai" }
  }
})

// 禁用任务
cron({
  action: "update",
  jobId: "0d3d9265-8cd6-4069-aa52-d32c33a30580",
  patch: { enabled: false }
})

手动触发

// 立即执行一次
cron({
  action: "run",
  jobId: "0d3d9265-8cd6-4069-aa52-d32c33a30580"
})

查看执行历史

cron({
  action: "runs",
  jobId: "0d3d9265-8cd6-4069-aa52-d32c33a30580"
})

删除任务

cron({
  action: "remove",
  jobId: "0d3d9265-8cd6-4069-aa52-d32c33a30580"
})

🔥 实战案例

案例一：每日SEO巡检

cron({
  action: "add",
  job: {
    name: "每日SEO巡检",
    schedule: { kind: "cron", expr: "0 2 * * *", tz: "Asia/Shanghai" },
    payload: {
      kind: "agentTurn",
      message: "执行每日SEO巡检：1)检查死链 2)验证sitemap 3)检查meta标签 4)生成报告",
      timeoutSeconds: 1800
    },
    delivery: {
      mode: "announce",
      channel: "feishu",
      to: "oc_xxx"
    }
  }
})

案例二：竞品监控

cron({
  action: "add",
  job: {
    name: "竞品动态监控",
    schedule: { kind: "cron", expr: "0 9,15,21 * * *", tz: "Asia/Shanghai" },
    payload: {
      kind: "agentTurn",
      message: "搜索竞品网站(futuretools.io, thereisanaiforthat.com)的最新动态，分析变化并生成简报"
    },
    delivery: { mode: "announce" }
  }
})

案例三：定时内容生成

// 每天早上6点生成踩坑实录
cron({
  action: "add",
  job: {
    name: "妙趣踩坑实录",
    schedule: { kind: "cron", expr: "0 6 * * *", tz: "Asia/Shanghai" },
    payload: {
      kind: "agentTurn",
      message: "搜索本周AI开发者的踩坑故事，用妙趣风格（周星驰+王家卫）写一篇踩坑实录，保存到网站"
    },
    delivery: {
      mode: "announce",
      channel: "feishu",
      to: "oc_xxx"
    }
  }
})

案例四：一次性提醒

// 使用qqbot_remind快捷方式
qqbot_remind({
  action: "add",
  content: "下午2点有SEO策略会议",
  time: "2026-06-08T13:45:00+08:00"
})

// 或使用cron
cron({
  action: "add",
  job: {
    name: "会议提醒",
    schedule: { kind: "at", at: "2026-06-08T13:45:00+08:00" },
    payload: { kind: "systemEvent", text: "⏰ 提醒：15分钟后有SEO策略会议" }
  }
})

❓ 常见问题