在 OpenClaw 中，定时任务（Cron Job）是实现自动化工作流的核心组件。无论是每天早晨推送 GitHub 热榜、定期执行系统检查，还是触发一次性的 Agent 任务，都离不开对 Cron 配置的精细掌控。
OpenClaw 的 Cron 配置并非简单的 Crontab 字符串，而是一个结构化的 JSON 对象，它涵盖了调度策略、执行环境、任务内容、结果交付和状态追踪五大维度。本文将带你逐层拆解这些字段，并提供可直接复用的配置范例。
🔧 Cron Job 配置字段全景
一个完整的 Cron Job 配置由六个主要区块构成，下面逐一详解。
一、基础信息字段
这部分定义了任务的元数据，用于标识和管理。
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 任务的唯一标识符（UUID 格式），由系统自动生成，无需手动填写。 |
name |
string | 任务名称（可选但强烈建议填写）。清晰命名有助于在日志或管理后台快速识别任务，如 "GitHub 每日热榜 Top 5 推送"。 |
enabled |
boolean | 是否启用该任务。默认值为 true。若想临时暂停某个定时任务，将其设为 false 即可，无需删除配置。 |
createdAtMs |
number | 任务创建时的 Unix 时间戳（毫秒），系统自动记录。 |
updatedAtMs |
number | 任务最后一次修改的 Unix 时间戳（毫秒），用于追踪配置变更。 |
二、调度配置（schedule 对象）
这是定时任务的“心脏”，决定了任务何时被触发。
| 字段 | 类型 | 作用详解 |
|---|---|---|
kind |
string | 调度类型，支持三种模式： - "cron"：使用标准 Cron 表达式。- "every"：固定时间间隔重复执行。- "at"：一次性定时执行。 |
expr |
string | 当 kind 为 "cron" 时必填。标准的 Cron 表达式字符串，例如 "0 8 * * *"。 |
tz |
string | 当 kind 为 "cron" 时强烈建议填写。指定时区，如 "Asia/Shanghai"。若不填，系统默认使用 UTC 时间，可能导致任务在非预期时间执行。 |
staggerMs |
number | 错峰延迟（毫秒）。在集群环境或多个任务同时触发时，设置此值（如 120000 表示 2 分钟）可让任务在指定时间点附近随机浮动执行，有效避免 CPU 或网络资源的瞬时尖峰。 |
Cron 表达式速查表：
0 8 * * * # 每天上午 8:00
30 22 * * 5 # 每周五晚上 22:30
0 12 1 * * # 每月 1 号中午 12:00
0 */2 * * * # 每 2 小时执行一次
三、执行配置
决定了任务在哪里执行以及以何种唤醒策略启动。
| 字段 | 类型 | 作用 |
|---|---|---|
sessionTarget |
string | 运行环境（沙箱）： - "isolated"：独立会话（推荐）。任务在全新的干净上下文运行，互不干扰。- "main"：主会话（受限，仅支持 systemEvent 类型）。- "current"：依附于当前活跃会话。- "session:<id>"：指定具体的会话 ID。 |
wakeMode |
string | 唤醒模式： - "now"：到达触发时间后立即执行（默认）。- "next-heartbeat"：等到下一次系统心跳周期再执行，用于对实时性要求不高的后台批量任务。 |
四、任务内容（payload 对象）
定义任务具体做什么。根据 kind 字段分为两种类型：
类型 1：agentTurn （最常用）
让 AI Agent 执行自然语言指令。
| 字段 | 类型 | 作用 |
|---|---|---|
kind |
string | 固定值 "agentTurn"。 |
message |
string | 核心指令。用自然语言描述希望 Agent 完成的工作，例如：“联网搜索最新的 AI 新闻并总结 3 个要点”。 |
timeoutSeconds |
number | 超时时间（秒）。防止任务死循环。简单查询建议 60-120 秒，复杂爬取或推理建议设为 300-600 秒。 |
model |
string | 可选，指定覆盖默认配置的 AI 模型名称。 |
类型 2：systemEvent
触发系统级事件，通常用于与主进程交互。
| 字段 | 类型 | 作用 |
|---|---|---|
kind |
string | 固定值 "systemEvent"。 |
text |
string | 发送给系统的事件文本内容。 |
五、交付配置（delivery 对象）
定义任务执行结果如何通知用户。
| 字段 | 类型 | 作用 |
|---|---|---|
mode |
string | 交付模式： - "announce"：将 Agent 的回复直接发送到绑定的聊天窗口（如飞书、微信）。- "webhook"：向指定 URL 发送 HTTP POST 请求。- "none"：静默执行，仅记录日志。 |
to |
string | （可选）接收者的唯一标识符，如飞书的 open_id。 |
channel |
string | （可选）消息渠道标识，如 "feishu"。 |
bestEffort |
boolean | 若设为 true，即便推送消息失败（如网络抖动），系统也会将该任务标记为“已完成”而非“错误”。适用于对送达率要求不苛刻的辅助任务。 |
六、状态追踪（state 对象）
此部分为只读字段，由系统自动维护，记录了任务的实时运行轨迹。
| 字段 | 类型 | 作用 |
|---|---|---|
nextRunAtMs |
number | 下次执行时间（毫秒时间戳）。 |
lastRunAtMs |
number | 上次执行时间（毫秒时间戳）。 |
lastRunStatus |
string | 上次执行状态："ok" / "error"。 |
lastError |
string | 上次错误的详细信息，便于快速定位问题。 |
lastDurationMs |
number | 上次执行耗时（毫秒）。 |
runningAtMs |
number | 正在运行的时间戳（运行中时出现）。 |
consecutiveErrors |
number | 连续错误次数，用于智能熔断。 |
lastDeliveryStatus |
string | 上次交付状态："delivered" / "not-delivered" / "none"。 |
lastDelivered |
boolean | 上次是否成功交付（true 或 false）。 |
📋 调度类型深度解析
针对 schedule 对象的三种 kind，这里给出具体的配置范例：
1. Cron 表达式调度（最灵活）
适用于固定时刻的周期性任务，如“工作日早上 8:30”。
{"kind": "cron","expr": "30 8 * * 1-5","tz": "Asia/Shanghai"
}
2. 固定间隔调度
适用于“每隔 N 秒/分/小时”执行一次的后台巡检任务。
{"kind": "every", "everyMs": 3600000, // 1小时 = 3600000 毫秒"anchorMs": 0 // 可选，用于对齐整点基准时间
}
3. 一次性调度
适用于会议提醒或定时发送的预告。
{"kind": "at","at": "2026-04-08T14:30:00+08:00"
}
🎯 配置实战示例
将上述字段组合起来，就能得到功能强大的自动化任务。
示例 1：每日 AI 情报推送（agentTurn 模式）
该配置每天 8:00 启动一个独立会话，让 AI 去搜索热点并推送结果，设置 5 分钟超时以防卡住。
{"name": "GitHub热榜推送","enabled": true,"schedule": {"kind": "cron", "expr": "0 8 * * *", "tz": "Asia/Shanghai","staggerMs": 120000 // 错峰 2 分钟},"sessionTarget": "isolated","payload": {"kind": "agentTurn","message": "访问 github.com/trending，获取今日热榜前 5 个项目，用中文简要介绍其功能并推送到群聊。","timeoutSeconds": 300},"delivery": {"mode": "announce"}
}
示例 2：整点报时提醒（systemEvent 模式）
利用系统事件在主会话中输出简单提示。
{"name": "整点健康提醒","schedule": {"kind": "cron", "expr": "0 10-22 * * *" // 每天 10 点到 22 点整点},"payload": {"kind": "systemEvent", "text": "🔔 整点了，站起来眺望远方，休息一下眼睛吧。"},"sessionTarget": "current"
}
⚠️ 避坑指南与限制说明
- 会话隔离限制：当
sessionTarget设置为"main"时，payload.kind必须是"systemEvent"，不能直接调用 Agent。如需调用 Agent，务必使用"isolated"。 - 时区陷阱：如果你写
expr: "0 8 * * *"却忘记设置tz: "Asia/Shanghai"，任务将在 UTC 时间 8:00（即北京时间 16:00）执行。 - 超时保护：默认超时较短，如果你让 Agent 访问外部网站或处理长文本，务必将
timeoutSeconds调大（例如 600）。 - 交付默认行为：若
delivery.mode为空，系统会根据负载类型自动判断——agentTurn默认发送消息，systemEvent默认不发送。 - 熔断机制：请定期关注
state.consecutiveErrors。若该值大于 3，通常意味着指令无法被 AI 理解或外部依赖失效，需介入调整。
🛠️ 进阶优化建议
- 错峰执行：如果有一批任务都挤在 00:00 执行，建议给它们分配随机的
staggerMs（如600000即 10 分钟浮动），让系统负载更平滑。 - 静默调试：配置新任务时，可先将
delivery.mode设为"none"，通过日志确认无报错后，再改为"announce"推送到群聊。 - 错误恢复：利用
consecutiveErrors结合 Webhook 搭建简单的监控告警，当任务连续失败时通知运维人员。
总结
OpenClaw 的 Cron 配置远不止一个时间字符串，它是一个麻雀虽小五脏俱全的迷你调度引擎。通过合理搭配 schedule 的灵活性与 payload 的智能性，再辅以 delivery 的连通能力，你完全可以将 OpenClaw 打造成一个 7x24 小时待命的个人 AI 管家。