在 OpenClaw 中，定时任务（Cron Job）是实现自动化工作流的核心组件。无论是每天早晨推送 GitHub 热榜、定期执行系统检查，还是触发一次性的 Agent 任务，都离不开对 Cron 配置的精细掌控。
OpenClaw 的 Cron 配置并非简单的 Crontab 字符串，而是一个结构化的 JSON 对象，它涵盖了调度策略、执行环境、任务内容、结果交付和状态追踪五大维度。本文将带你逐层拆解这些字段，并提供可直接复用的配置范例。
一个完整的 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 错峰延迟（毫秒）。在集群环境或多个任务同时触发时，设置此值（如 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。 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”: , // 1小时 = 毫秒 “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": // 错峰 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（如即 10 分钟浮动），让系统负载更平滑。 - 静默调试：配置新任务时，可先将
delivery.mode设为"none"，通过日志确认无报错后，再改为"announce"推送到群聊。 - 错误恢复：利用
consecutiveErrors结合 Webhook 搭建简单的监控告警，当任务连续失败时通知运维人员。
OpenClaw 的 Cron 配置远不止一个时间字符串，它是一个麻雀虽小五脏俱全的迷你调度引擎。通过合理搭配 schedule 的灵活性与 payload 的智能性，再辅以 delivery 的连通能力，你完全可以将 OpenClaw 打造成一个 7x24 小时待命的个人 AI 管家。
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容，请联系我们，一经查实，本站将立刻删除。
如需转载请保留出处：https://51itzy.com/kjqy/253149.html