夜雨聆风定时任务本来是挺简单的事，但是使用 OpenClaw 我并没有一次性成功，亲测下来，bug 太多了。OpenClaw 默认推荐的定时任务方式是 agentTurn + isolated，我用“每天晚上8点提醒我记日记、散步”这个极简单的例子做了个测试，没成功。不用AI、不用OpenClaw，这个本身是个太过简单的定时任务。但是用 OpenClaw 居然挂了。翻了一下 OpenClaw issue区，就这个定时的 bug 已经积累了一堆 issue 没有解决。用 AI 写的 OpenClaw，用起来不太爽。
受不了了，自己去看官方文档做个梳理。
OpenClaw 定时任务全景梳理
OpenClaw 如何实现定时任务，核心有两类机制：
1. Cron Jobs：精确定时调度 2. Heartbeat：周期性巡检 / 轮询
如果从“实际怎么落地”来分，Cron 内部又分出多种执行方式，如下：
| Cron + main | ||||||
| Cron + isolated | ||||||
| Cron + current | ||||||
| Cron + session:custom-id | ||||||
| Heartbeat | ||||||
| Webhook 触发 |
实操闭坑：先区分“调度机制”和“执行方式”
定时任务混乱，来自把这两层混在一起：
1. 调度机制
是指“什么时候触发”。在 OpenClaw，真正负责“按时间触发”的主要是：
• Cron Jobs • Heartbeat
2. 执行方式
这是“触发后在哪里运行”。
对于 Cron，官方文档明确列出这些 sessionTarget：
• main• isolated• current• session:custom-id
一、Cron：OpenClaw 的标准精确定时方案
文档：https://docs.openclaw.ai/automation/cron-jobs
OpenClaw 对 Cron 的定义可以概括为：
• 它运行在 Gateway 内部，不是跑在模型“脑子里” • 作业会持久化保存，Gateway 重启后不会丢 • 适合： • “每天早上 7 点运行” • “20 分钟后提醒我” • “每周固定时间跑一次分析”
Cron 支持的调度形态
schedule.kind 有三种：
A. at
一次性任务。适合：
• 20 分钟后提醒我 • 今晚 8 点提醒我做某事
B. every
固定间隔重复。适合：
• 每隔 1 小时运行一次 • 每隔 10 分钟轮询一次
C. cron
标准 cron 表达式。适合：
• 每天 07:00 • 每周一 09:30 • 每月 1 号凌晨执行
Cron 的 4 种运行方式
A. sessionTarget: "main"
含义：把一个 systemEvent 放入主会话，并在下一次 heartbeat时运行。
特点：
• 共享主会话上下文 • 更适合“提醒类 / 主会话要知道的事” • 不是完全独立执行
适合场景举例：
• “提醒我今天记得联系 X” • “在主会话里插入一个系统事件，让 agent 后续处理”
B. sessionTarget: "isolated"
含义：启动一个独立的 agent turn 来执行任务。
特点：
• 独立上下文 • 不污染主会话 • 更适合复杂任务、长任务 • 会跑在 cron:<jobId>或自定义 session 上
适合：
• 每天生成日报 • 定时抓取数据并总结 • 跑一段独立分析流程 • 想给定时任务指定不同模型
这也是大多数“AI 型定时任务”更推荐的方式。也是 OpenClaw 执行定时任务的默认推荐方式。但是我自己体验，无法成功执行，有bug。下文补充。
C. sessionTarget: "current"
含义：绑定到创建这个 cron 的当前会话。
特点：
• 适合“这个计划任务就是属于当前对话线程” • 比 main更局部，比isolated更连续
D. sessionTarget: "session:custom-id"
含义：绑定到一个持久命名会话。
特点：
• 多次运行之间保留上下文 • 适合长期项目、连续工作流
适合：
• 每天都在同一条“项目会话”里追加分析 • 长期跟踪某个对象，保留历史上下文
Cron 的 payload 区分
• 主会话（ main：“把一条系统事件塞给主会话”）通常对应payload.kind = "systemEvent"• 独立执行（ isolated：“真的启动一次独立 agent 执行任务”）通常对应payload.kind = "agentTurn"
合起来，sessionTarget: "isolated" + payload.kind: "agentTurn" 的意思就是： 这个定时任务触发时，OpenClaw 会启动一个独立 agent 会话，按你写的任务说明认真执行一轮。
打个比方：
• main + systemEvent
= “给主会话丢一张便签，等它按主会话节奏处理”• isolated + agentTurn
= “专门拉起一个独立助手，单独干这件事”
Cron 的 delivery
• isolated 的 cron add默认会 announce 投递• 可以 --no-deliver静默执行• 也支持 delivery.mode = "webhook"
所以 Cron 不只是“调度”，还内置了一层“结果怎么投递”。
二、Heartbeat：OpenClaw 的周期性巡检机制
文档：https://docs.openclaw.ai/automation/cron-vs-heartbeat
Heartbeat 不是拿来做“09:00 整准时提醒”的。
官方文档给它的定位：
• 主会话里的周期性 awareness loop • 用来批量检查多项内容 • 更低开销 • 更依赖上下文
Heartbeat 适合什么
官方文档里举的典型例子：
• 每 30 分钟检查 inbox • 监控 calendar upcoming events • 后台项目健康检查
Heartbeat 的优势
• 一次心跳可以合并多项检查 • 比多个独立 cron 更省调用成本 • 共享主会话上下文，判断更自然 • 更适合“发现异常再提醒”，而不是“固定点触发一件事”
6.3 Heartbeat 不适合什么
官方建议，以下更应该用 Cron：
• 9 点准时发日报 • 20 分钟后提醒我 • 每周固定时间跑深度分析
所以，Heartbeat 是巡检，不是精确定时器。
三、Webhook：不是定时器，但常与自动化串联
文档：https://docs.openclaw.ai/automation/webhook
Webhook 本身不是按时间触发，而是外部事件触发。
它的作用是：
• Gateway 暴露一个小型 HTTP endpoint • 外部系统推送事件进来 • 再由 OpenClaw 路由给 agent
适合：
• GitHub / GitLab 事件 • 第三方系统回调 • 外部服务通知
为什么要在这篇文章里提它？
因为实际自动化设计里，常见模式是：
• 定时巡检 → 用 Heartbeat • 精确定时 → 用 Cron • 外部事件驱动 → 用 Webhook
三者通常会一起构成完整自动化系统。
四、如何选择
at | ||
session:custom-id | ||
可以直接跟 OpenClaw 说，以“Cron + isolated”方式帮我创建一个定时任务：每天9点xxx
五、GitHub issue / PR：和定时任务相关的问题
下面是我根据 OpenClaw GitHub issue / PR 搜到的结果做的现状总结。帮助理解目前 OpenClaw 以上机制的现存问题。
1、 队列 / lane / timeout 问题
代表问题 1
• bug(cron): job timeout includes cron-lane queue wait time• 链接：https://github.com/openclaw/openclaw/issues/41783
核心问题：
• isolated cron job 可能先在 cron lane 里排队 • 超时计时却可能在真正执行前就开始算 • 结果就是“任务还没认真跑，就超时了”
这类问题影响：
• 长任务 • 高并发 cron • isolated 任务更明显
代表问题 2
• Cron: isolate cron run session lanes• 链接：https://github.com/openclaw/openclaw/pull/44573
这个 PR 的核心点：
• isolated cron run 改成使用每次运行独立的 session lane • 目的是避免重复运行时被之前的陈旧任务堵住 • Cron 的“定时”本身不难 • 真正难点在于 调度 + 排队 + 执行 lane 隔离 • 如果你有大量 isolated 任务，队列和超时是重点风险点
2、 isolated 模式与 heartbeat 指令污染
代表问题
• Cron isolated sessions should not inject HEARTBEAT_OK system prompt instructions• 链接：https://github.com/openclaw/openclaw/issues/43274
核心问题：
• isolated cron session 继承了完整 system prompt • 里面包含 heartbeat 的 HEARTBEAT_OK指令• 某些模型可能误以为自己收到的是 heartbeat poll • 最终输出 HEARTBEAT_OK，导致 cron 真正结果被吞掉或丢弃
经验：
• isolated虽然是独立会话，但它和 heartbeat 的系统级行为仍可能发生意外交叉• 这说明：Cron(isolated) 和 Heartbeat 在实现层不是完全绝缘的
这也是为什么理解“调度机制”和“执行上下文”很重要。
3、 isolated 任务反过来修改自己的 cron 配置
代表问题
• [BUG] Isolated agentTurn cron session rewrites its own cron job• 链接：https://github.com/openclaw/openclaw/issues/44940
核心问题：
• 某些 isolated agentTurncron 运行后• 会把原本的 cron 配置改回 main+systemEvent• 相当于定时任务在运行过程中“改写了自己”
踩坑：
• 对于可自修改配置的 agent 系统，调度器和 agent 行为边界要非常清楚 • 这类问题说明：隔离执行 不等于 配置面完全隔离
4、delivery / webhook / 通知投递问题
代表问题 1
• fix(doctor): remove dead notify:true when cron.webhook is unset• 链接：https://github.com/openclaw/openclaw/pull/44506
这说明：
• 历史版本里有旧的 notify:true兼容路径• webhook 未配置时，旧字段可能残留，形成“死配置” • 需要 doctor 做迁移 / 清理
代表问题 2
• cron: honor delivery.threadId for Telegram announce delivery• 链接：https://github.com/openclaw/openclaw/pull/43808
这说明：
• 定时任务不只是“能不能跑” • 还涉及“跑完之后结果投到哪里、线程上下文是否正确”
归类结论：
• delivery 是 Cron 的重要组成部分 • 实际生产里，投递准确性 和 执行成功率 一样重要
5、生命周期 / 自终止能力
代表问题
• feat(cron): CRON_DONE signal and condition-based job self-deletion• 链接：https://github.com/openclaw/openclaw/issues/33167
核心问题：
• 某些 cron 是“监视直到条件达成” • 一旦目标完成，任务应该自动停止 • 但当前可能缺少任务自我终止的自然机制
典型场景：
• 每小时检查下载是否完成 • 一旦完成，就不该继续每小时提醒
踩坑：
• 做简单提醒器可以，但是如果想当“持续观察型自动化工具”使用，需要更强的生命周期管理能力。目前 bug 还很多。
六、把 issue 区和官方机制连起来看
此外，工程上最容易出问题的，不是“定不定时”，而是“怎么执行与怎么投递”：
• 队列 / lane / 超时 • prompt 污染 • 配置回写 • delivery 路由 • 重试与生命周期
选型建议
• 要精确时刻 → 先看 Cron • 不要求精确时刻，只是巡检 → 看 Heartbeat • 要独立执行 → 在 Cron 里选 isolated
场景 1：提醒类
例如：
• 每天 7 点提醒起床 • 20 分钟后提醒喝水
建议：
• 简单提醒 → Cron + main• 更复杂、需要生成文案 → Cron + isolated
场景 2：巡检类
例如：
• 每 30 分钟看邮箱 • 每小时看日历和通知
建议：
• Heartbeat
场景 3：复杂 AI 工作流
例如：
• 每天下午生成日报 • 每周自动分析项目状态 • 定时拉取资料并总结
建议：
• Cron + isolated
场景 4：长期有状态任务
例如：
• 每天在同一个项目上下文里追加记录
建议：
• Cron + session:custom-id
梳理了一遍，做个总结。我准备回去用我熟悉的脚本了，因为目前，用 OpenClaw 做这些定时任务，太麻烦。
附：官方文档
• https://docs.openclaw.ai/llms.txt • https://docs.openclaw.ai/automation/cron-jobs • https://docs.openclaw.ai/automation/cron-vs-heartbeat • https://docs.openclaw.ai/cli/cron • https://docs.openclaw.ai/automation/webhook
