"cron 工具详解：定时任务配置"

龙虾学堂2026年5月7日

"掌握 OpenClaw cron 工具，学会配置定时任务、周期性检查和一次性提醒，让 Agent 自动执行重复性工作。"

cron 工具详解：定时任务配置

本文聚焦：cron 任务类型 + schedule 配置语法

前置知识：启动 Gateway 相关阅读：什么是子智能体

知识点 1：cron 能做什么

OpenClaw 的 cron 工具让 Agent 拥有了"时间感知"能力。你可以把它理解为 Agent 的闹钟和日程表。

三种任务类型

类型	用途	典型场景
定时检查 (every)	周期性执行	每小时检查邮件、每天备份数据
定点执行 (at)	一次性任务	20 分钟后提醒我、明天上午 9 点发送报告
Cron 表达式 (cron)	复杂周期	每周一 9:00、每月 1 号

核心约束（重要！）

cron 任务有两个关键约束，理解它们是正确使用的前提：

┌─────────────────────────────────────────────────────────┐
│  sessionTarget="main"  →  payload.kind="systemEvent"   │
│  sessionTarget="isolated" → payload.kind="agentTurn"   │
└─────────────────────────────────────────────────────────┘

main：任务在主会话中执行，适合状态检查、汇总报告（需要上下文）
isolated：任务在独立会话中执行，适合独立任务、耗时操作（不污染主会话）

实际例子

场景 1：每小时检查未读邮件

{
  "schedule": { "kind": "every", "everyMs": 3600000 },
  "payload": {
    "kind": "systemEvent",
    "text": "检查邮箱，汇总未读邮件"
  },
  "sessionTarget": "main"
}

场景 2：20 分钟后提醒

{
  "schedule": { "kind": "at", "at": "2026-03-11T10:30:00+08:00" },
  "payload": {
    "kind": "systemEvent",
    "text": "⏰ 提醒：会议时间到了"
  },
  "sessionTarget": "main"
}

知识点 2：schedule 配置详解

1. Every - 周期性任务

最简单的定时模式，按固定间隔重复执行。

{
  "schedule": {
    "kind": "every",
    "everyMs": 3600000,      // 间隔毫秒数（1小时 = 3600000ms）
    "anchorMs": 1703275200000 // 可选：起始锚点时间戳
  }
}

常用间隔参考：

间隔	毫秒值	说明
5 分钟	`300000`	高频检查
15 分钟	`900000`	中等频率
1 小时	`3600000`	常规检查
6 小时	`21600000`	低频检查
1 天	`86400000`	日报/日检

代码示例：

// 创建每 30 分钟检查一次的任务
{
  "name": "heartbeat-check",
  "schedule": { "kind": "every", "everyMs": 1800000 },
  "payload": {
    "kind": "systemEvent",
    "text": "执行心跳检查：查看邮件、日历、通知"
  },
  "sessionTarget": "main",
  "enabled": true
}

2. At - 一次性任务

在指定时间点执行一次，执行后自动从调度器中移除。

{
  "schedule": {
    "kind": "at",
    "at": "2026-03-11T14:30:00+08:00"  // ISO-8601 格式，带时区
  }
}

时间格式要点：

必须使用 ISO-8601 格式
强烈建议带时区（+08:00 表示东八区）
不带时区默认按 UTC 处理，容易出错

实用技巧 - 计算未来时间：

// 当前时间 + 20 分钟
const now = new Date();
const future = new Date(now.getTime() + 20 * 60 * 1000);
const isoString = future.toISOString();  // "2026-03-11T12:34:56.789Z"

// 转换为带时区的格式（东八区）
// 注：这是简化示例，生产环境建议使用 date-fns-tz 或 moment-timezone
const withTimezone = isoString.replace('Z', '+08:00');

3. Cron 表达式 - 复杂周期

使用类 Unix cron 表达式，支持分钟级精度的复杂调度。

{
  "schedule": {
    "kind": "cron",
    "expr": "0 9 * * 1",        // 每周一 9:00
    "tz": "Asia/Shanghai"       // 时区（可选但建议指定）
  }
}

Cron 表达式格式：

┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日期 (1-31)
│ │ │ ┌───────────── 月份 (1-12)
│ │ │ │ ┌───────────── 星期 (0-7, 0和7都是周日)
│ │ │ │ │
* * * * *

常用表达式示例：

需求	表达式	说明
每小时整点	`0 * * * *`	每小时的第 0 分钟
每天 9:00	`0 9 * * *`	每天早上 9 点
每周一 9:00	`0 9 * * 1`	每周一开始工作
每月 1 号 9:00	`0 9 1 * *`	月初报告
工作日 9-18 点	`0 9-18 * * 1-5`	工作时间每小时

4. 任务 Payload 类型

systemEvent - 系统事件（sessionTarget: main）

向主会话注入一条系统消息，Agent 会像收到用户消息一样处理它。

{
  "payload": {
    "kind": "systemEvent",
    "text": "执行每日检查：邮件、日历、GitHub 通知"
  }
}

特点：

可以访问主会话的上下文和历史
适合需要"记忆"的连续性任务
输出会直接发送到绑定的聊天频道

agentTurn - 独立 Agent 执行（sessionTarget: isolated）

在独立会话中运行 Agent，相当于派一个"临时工"去完成任务。

{
  "payload": {
    "kind": "agentTurn",
    "message": "分析过去 24 小时的系统日志，生成摘要报告",
    "model": "bailian/kimi-k2.5",
    "thinking": "medium",
    "timeoutSeconds": 300
  }
}

特点：

完全隔离，不影响主会话
可以指定不同的模型和思考级别
适合耗时、独立、可能失败的任务

实践建议

1. 选择合适的 sessionTarget

需要上下文连续性  →  main + systemEvent
独立/耗时/可能失败  →  isolated + agentTurn

2. 时区处理

始终显式指定时区，避免跨时区部署时的混乱：

// ✅ 推荐：带时区
{ "at": "2026-03-11T09:00:00+08:00" }
{ "tz": "Asia/Shanghai" }

// ❌ 避免：依赖默认 UTC
{ "at": "2026-03-11T09:00:00" }  // 会被解析为 UTC

3. 任务命名规范

使用有意义的名称，方便后续管理：

✅  good: "daily-email-check", "weekly-report", "reminder-meeting"
❌  bad:  "job1", "cron-task", "test"

4. 避免过度调度

不要设置过于频繁的任务（如每分钟）
考虑 API 限流和成本
长时间任务要设置合理的 timeout

5. 监控任务执行

通过 cron 相关命令查看任务执行历史：

# 列出所有 cron 任务
openclaw cron list

# 查看特定任务的执行记录
openclaw cron runs --jobId <job-id>

注：具体命令请以 openclaw cron --help 输出为准。

完整配置示例

{
  "name": "daily-summary",
  "schedule": {
    "kind": "cron",
    "expr": "0 18 * * *",
    "tz": "Asia/Shanghai"
  },
  "payload": {
    "kind": "systemEvent",
    "text": "生成每日总结：检查今日邮件、日历事件、待办事项"
  },
  "sessionTarget": "main",
  "enabled": true
}

这个任务每天 18:00（上海时间）执行，向主会话发送总结指令。

常见问题

Q: 任务执行时间重叠怎么办？ 如果上次任务还未完成，下次触发时间已到，OpenClaw 会根据配置决定是跳过、排队还是并发执行。建议为长时间任务设置合理的 timeout。

Q: 任务配置会持久化吗？ 是的，cron 任务配置会保存在 OpenClaw 的配置存储中，重启 Gateway 后自动恢复。

Q: 如何禁用或删除任务？ 可以通过 API 将任务的 enabled 字段设为 false 来禁用，删除任务则需要调用 cron remove 命令。