OpenClaw系列第18课:Cron 定时任务 – 让 AI 自动定时工作-夜雨聆风

OpenClaw系列第18课:Cron 定时任务 – 让 AI 自动定时工作

这是「OpenClaw 教程课程」第 18 课。前两课我们讲了多 Agent：第 16 课讲 sessions_spawn，第 17 课讲 subagents 管理。今天进入自动化里最常用的一块：Cron 定时任务。

图：Cron 让 OpenClaw 可以在指定时间或固定周期自动唤醒 Agent，执行提醒、摘要、检查、报告等任务。

很多人第一次理解 OpenClaw 的自动化，会自然想到一句话：

“能不能让它每天自动帮我做点事？”

比如：

每天早上 8 点发一份晨报
每晚总结今天的任务
每周一检查项目状态
20 分钟后提醒我看某个文档
每隔一段时间跑一次健康检查
定时打开网页、收集信息、发回结果

这些事情，不应该靠你每天手动发消息。

也不应该让 Agent 在对话里傻等一个 sleep 3600。

在 OpenClaw 里，这类“到点自动执行”的工作，应该交给 Cron。

这一课我们讲清楚：

OpenClaw 的 Cron 是什么，怎么用，适合什么，不适合什么，以及怎样避免自动任务变成打扰。

一、Cron 是什么？

Cron 是 OpenClaw Gateway 内置的调度器。

文档里一句话说得很清楚：

Cron is the Gateway’s built-in scheduler.

翻译成新手能理解的话：

Cron 是 Gateway 里的定时任务系统。

它负责：

保存任务定义
在指定时间触发任务
唤醒 Agent
记录运行历史
必要时把结果发回聊天渠道或 webhook

这里有一个重点：

Cron 运行在 Gateway 里，不运行在模型里。

这意味着，模型不会一直“记着时间”等到点。

真正负责看时间、触发任务的是 Gateway。

到点以后，Gateway 再把任务交给 Agent 执行。

二、为什么不能让 Agent 自己等？

新手容易有一个错误想法：

让 AI 等 20 分钟后提醒我。

听起来可以，但技术上不应该这样做。

因为如果让 Agent 自己等，会出现很多问题：

占着当前对话运行
浪费模型或工具资源
Gateway 重启后可能丢状态
无法稳定管理多个提醒
不好查看任务列表和历史
不能像真正调度器一样处理失败、重试和投递

所以正确做法是：

未来某个时间再做的事，交给 Cron。

这和第 12 课 exec 里讲过的原则一致：

不要用 sleep 循环模拟定时任务。

OpenClaw 已经有 Cron，就应该让 Gateway 调度。

图：sleep 只是让一个过程傻等；Cron 是 Gateway 持久化管理的调度系统，更适合提醒、周期任务和后台自动化。

三、Cron 适合做哪些事？

Cron 适合“明确时间触发”的任务。

1）一次性提醒

比如：

20 分钟后提醒我检查文章封面图。

或者：

明天上午 10 点提醒我发布第 18 课。

这类任务适合 one-shot job。

2）周期性摘要

比如：

每天早上发晨报
每晚总结今日任务
每周一发项目周报
每月 1 号整理账单提醒

这类任务适合 recurring job。

3）定时健康检查

比如：

每小时检查 Gateway 状态
每天检查磁盘空间
每周检查日志里有没有错误

这类任务可以结合 exec 做只读检查。

4）定时内容生产

比如：

每天生成一个教程选题
每周整理一篇阅读摘要
定时生成频道更新草稿

这类任务适合用 isolated session，避免污染主对话。

5）自动化报告

比如：

每天早上总结某个目录变化
每周检查文章是否缺 front matter
每天汇总昨天的任务结果

Cron 很适合“定时触发 + Agent 整理 + 发回结果”。

四、Cron 不适合做哪些事？

Cron 不是万能自动化。

下面这些情况不适合直接用 Cron。

1）需要实时连续监听的事情

比如：

一有新消息就马上处理。

这种更像 webhook、事件触发或 channel 消息处理。

Cron 是按时间触发，不是实时事件监听。

2）需要高频秒级循环的任务

比如每 5 秒检查一次状态。

这不适合 Cron，也不适合 Agent。

应该用专门监控系统，或者降低频率。

3）需要用户现场确认的敏感操作

比如：

到点自动删除文件
到点自动发公开消息
到点自动改生产配置

这些高风险动作不应该直接自动执行。

更好的做法是：

到点生成计划或提醒，由用户确认后再执行。

4）模糊目标

比如：

每天帮我做点有用的事。

这太模糊。

Cron 任务应该目标明确。

例如：

每天 9 点总结昨天 articles 目录新增或修改的 Markdown 文件，输出 5 条以内。

这样才可控。

五、Cron 的三种 schedule 类型

OpenClaw 文档里列了三种 schedule 类型：

类型	CLI 参数	说明
`at`	`--at`	一次性时间点
`every`	`--every`	固定间隔
`cron`	`--cron`	cron 表达式

1）at：一次性任务

适合提醒。

比如：

openclaw cron add \  --name "Calendar check" \  --at "20m" \  --session main \  --system-event "Next heartbeat: check calendar." \  --wake now

这里 20m 就是 20 分钟后。

也可以用 ISO 时间，比如：

2026-02-01T16:00:00Z

2）every：固定间隔

适合每隔一段时间做一次。

比如每小时、每 6 小时。

这种任务要谨慎，不要频率太高。

3）cron：标准 cron 表达式

适合复杂周期。

比如每天 7 点：

0 7 * * *

每周一 9 点：

0 9 * * 1

Cron 表达式很强，但也容易写错。

新手刚开始可以优先用 --at 和简单 --cron。

图：OpenClaw Cron 支持一次性 at、固定间隔 every、标准 cron 表达式三类调度方式。

六、时区：一定要说清楚

时间任务最容易踩坑的是时区。

文档里提到：

没有 timezone 的 timestamp 会按 UTC 处理。

所以如果你想按本地时间执行，最好明确传 --tz。

比如北京时间：

--tz "Asia/Shanghai"

例如每天早上 8 点按北京时间跑：

openclaw cron add \  --name "Morning brief" \  --cron "0 8 * * *" \  --tz "Asia/Shanghai" \  --session isolated \  --message "整理今日晨报，输出 5 条以内。" \  --announce

不要只写“明早 8 点”，却不说时区。

尤其是服务器在 UTC、用户在中国时，非常容易差 8 小时。

七、执行位置：main / isolated / current / session:id

Cron 触发后，需要决定任务跑在哪个 session 里。

OpenClaw 文档里列了几种 --session：

session	含义	适合场景
`main`	主会话	提醒、系统事件
`isolated`	每次新建独立运行	报告、后台整理、自动化任务
`current`	创建时绑定当前会话	和当前上下文相关的提醒
`session:<id>`	指定持久会话	需要长期积累上下文的工作流

这部分非常关键。

因为不同 session 会影响：

是否继承上下文
是否污染主对话
是否适合长期积累
结果怎么投递

八、main session：适合提醒和系统事件

main 适合轻量提醒。

比如：

openclaw cron add \  --name "Reminder" \  --at "20m" \  --session main \  --system-event "Reminder: check the cron docs draft" \  --wake now \  --delete-after-run

它更像：

到点往主会话塞一个系统事件，然后唤醒 Agent。

适合：

提醒你做某事
让主会话知道某个时间到了
简单唤醒

但不适合复杂后台分析。

复杂任务更推荐 isolated。

九、isolated session：适合后台报告

isolated 是自动化里非常常用的模式。

它的意思是：

每次 cron run 都在一个独立的新 session 里运行。

这有几个好处：

不污染主对话
每次运行上下文清爽
适合生成报告
适合跑后台检查
出问题也更容易隔离

例如每天早上生成晨报：

openclaw cron add \  --name "Morning brief" \  --cron "0 8 * * *" \  --tz "Asia/Shanghai" \  --session isolated \  --message "请整理今日晨报，控制在 5 条以内。" \  --announce \  --channel telegram \  --to "telegram:7995226813"

这里的重点是：

--session isolated：独立运行
--message：给 Agent 的任务
--announce：完成后投递结果
--channel / --to：指定投递渠道和目标

新手可以先把 isolated 理解成：

让 cron 自己开一个干净的小房间做任务，做完把结果发回来。

图：main 适合提醒，isolated 适合后台报告，current 适合绑定当前上下文，session:id 适合长期持久工作流。

十、current session：绑定创建时的当前会话

current 的意思是：

创建 cron 任务时，把它绑定到当前会话。

适合这些场景：

当前对话里已经有上下文
你希望后续提醒和这个上下文有关
不是全局主会话，而是某个具体频道、群、线程或 direct chat

例如你正在某个项目对话里讨论 bug。

你可以说：

明天上午提醒我继续看这个 bug。

这类任务就可能适合 current。

但如果任务不需要当前上下文，isolated 更干净。

十一、session:：适合长期积累上下文

session:<id> 是更进阶的用法。

它适合让某个定时任务长期在同一个命名 session 里积累上下文。

比如：

daily-brief
weekly-report
health-check-history

这样每次运行都不是完全陌生的。

它可以基于前几次结果继续积累。

但也要注意：

长期 session 可能积累噪音，也可能让上下文越来越重。

所以对新手来说，默认还是 isolated 更稳。

十二、Delivery：结果怎么发回来？

Cron 任务执行完，结果要不要发回来、发到哪里，是 delivery 问题。

文档里提到三种模式：

模式	含义
`announce`	如果 Agent 没直接发送，则 runner fallback 投递最终文本
`webhook`	把完成事件 POST 到 URL
`none`	runner 不做 fallback 投递

新手先理解 announce 就够了。

announce

announce 表示任务完成后，把结果发回指定渠道。

例如：

--announce --channel telegram --to "telegram:7995226813"

如果你不想它主动发消息，可以用：

--no-deliver

这会关闭 runner fallback delivery。

但注意，isolated cron chat delivery 是 shared 的。

如果有可用聊天路由，Agent 自己仍可能使用 message 工具发送，具体要看任务和工具策略。

十三、Cron 会记录运行历史

Cron 不只是“到点跑一下”。

它还会记录任务和运行历史。

常用命令：

openclaw cron listopenclaw cron show <job-id>openclaw cron runs --id <job-id>

分别用于：

list：查看所有 cron jobs
show：查看某个 job 详情
runs：查看某个 job 的运行历史

这对排错很重要。

比如你发现晨报没发出来，不要先猜。

先看：

openclaw cron listopenclaw cron show <job-id>openclaw cron runs --id <job-id>

确认它是没触发、触发失败、模型失败，还是投递失败。

十四、Cron 和 Background Tasks 的关系

第 16、17 课讲子 Agent 时，我们提到 background tasks。

Cron 也会创建 task 记录。

OpenClaw 文档里说：

All cron executions create background task records.

也就是说，每次 cron 执行，都会进入后台任务账本。

Background tasks 不是调度器。

它是记录：

什么任务跑过
是否 queued / running / succeeded / failed / timed_out / cancelled / lost
运行是否完成
是否投递成功

你可以理解成：

Cron 决定什么时候跑，Tasks 记录跑得怎么样。

图：Cron 是调度器，负责按时间触发；Background Tasks 是账本，负责记录后台执行状态和结果。

十五、失败、跳过和重试

Cron 任务不一定每次都成功。

可能出现：

模型不可用
本地 provider 没启动
工具被拒绝
任务超时
投递失败
网络问题

OpenClaw 对这些情况有一些保护。

文档里提到：

recurring jobs 遇到连续错误会用指数退避
skipped runs 和 execution errors 分开记录
isolated cron 对本地 provider 会做轻量 preflight
blocked command 不会被当成绿色成功
timeout 会中止底层 agent run

新手不需要一次记住全部细节。

你先记住：

Cron 不只是定时触发，它还会记录成功、失败、跳过和超时。

排错时，先看 run history，而不是凭感觉猜。

十六、一个最小例子：20 分钟后提醒

假设你想 20 分钟后提醒自己检查文章。

可以这样：

openclaw cron add \  --name "Check article" \  --at "20m" \  --session main \  --system-event "Reminder: check lesson 18 draft." \  --wake now \  --delete-after-run

解释一下：

--name：任务名
--at "20m"：20 分钟后
--session main：发到主会话
--system-event：到点注入的系统事件
--wake now：唤醒处理
--delete-after-run：成功后删除一次性任务

这是最适合理解 Cron 的例子。

它不是让 Agent 睡 20 分钟。

而是 Gateway 保存一个定时任务，到点再唤醒。

十七、一个实用例子：每天晨报

假设你想每天早上 8 点收到一个晨报。

可以用 isolated job：

openclaw cron add \  --name "Morning brief" \  --cron "0 8 * * *" \  --tz "Asia/Shanghai" \  --session isolated \  --message "请生成今日晨报，控制在 5 条以内。优先总结重要事项、风险和下一步行动。不要输出长篇背景。" \  --announce \  --channel telegram \  --to "telegram:7995226813"

这个例子里，最重要的是 --message 写得清楚。

定时任务不能太模糊。

不要写：

每天跟我说点东西。

要写：

控制在 5 条以内，优先总结重要事项、风险和下一步行动。

自动化任务越清楚，越不容易变成噪音。

十八、一个检查例子：每周检查文章格式

假设你维护一个文章目录。

可以每周检查一次：

openclaw cron add \  --name "Weekly article check" \  --cron "0 9 * * 1" \  --tz "Asia/Shanghai" \  --session isolated \  --message "请检查 articles 目录下最近一周修改的 Markdown 文件，确认是否包含 title、description、cover 和配图建议。只读检查，不要修改文件。输出异常列表和建议。" \  --tools read,exec \  --announce \  --channel telegram \  --to "telegram:7995226813"

这里有两个好习惯：

1）明确只读

只读检查，不要修改文件。

2）限制工具

--tools read,exec

这能减少不必要风险。

当然，具体工具是否可用还取决于你的工具策略配置。

十九、Cron 和 Heartbeat 有什么区别？

第 20 课会专门讲 Heartbeat。

这里先做一个最小区分。

Cron：到点做明确任务

比如：

每天 8 点发晨报
20 分钟后提醒
每周一检查文章

Cron 的特点是：

有明确时间或周期。

Heartbeat：保持 Agent 活跃和处理后台事件

Heartbeat 更像系统周期性检查和唤醒机制。

它适合保持 Agent 活跃，处理某些后台状态。

不是所有定时任务都应该塞进 Heartbeat。

新手先记住：

明确时间表用 Cron；保持活跃和后台节奏用 Heartbeat。

第 20 课我们会细讲。

二十、适合新手的 Cron 提问模板

下面这些句式可以直接复制。

1）一次性提醒

请帮我创建一个 20 分钟后的一次性提醒：提醒我检查第 18 课草稿。成功后自动删除任务。

2）每天晨报

请帮我创建一个每天北京时间早上 8 点的 isolated cron job，生成 5 条以内晨报，并发送到当前 Telegram 对话。

3）只读检查

请创建一个每周一北京时间 9 点的 isolated cron job，只读检查 articles 目录最近一周修改的 Markdown 文件，不要修改文件，只输出异常和建议。

4）不主动发消息

请创建 cron job，但不要主动投递结果，只保留运行记录供我之后查看。

5）排查 Cron

请帮我检查现有 cron job 列表、某个 job 的详情和最近运行历史，判断为什么没有发送结果。

6）避免打扰

这个 cron job 的输出请控制在 5 条以内；没有异常时只发送一句简短结果，不要长篇解释。

7）带时区

请按 Asia/Shanghai 时区创建任务，不要用 UTC 默认时间。

这些模板背后的重点是：

时间、会话、输出、投递、边界都要说清楚。

图：创建 Cron 任务时，要明确时间、时区、session、任务边界、输出长度和投递方式，避免自动任务变成噪音。

二十一、常见坑

坑 1：忘记时区

服务器常用 UTC。

用户想的是北京时间。

如果不写 --tz Asia/Shanghai，很容易错 8 小时。

坑 2：用 sleep 模拟定时任务

不要让 Agent 或 exec 等着未来时间。

未来任务用 Cron。

坑 3：任务描述太模糊

比如：

每天帮我总结一下。

总结什么？从哪里总结？发多长？发到哪里？

都不清楚。

坑 4：自动任务输出太长

定时任务如果每天发长篇，很快会变成噪音。

建议：

默认短输出，有异常再展开。

坑 5：让 Cron 自动做高风险写操作

比如自动删除、自动发布、自动改配置。

更安全的方式是：

Cron 到点生成计划或提醒，由人确认后执行。

坑 6：不知道跑在哪个 session

main、isolated、current、session:<id> 差别很大。

不确定时，后台报告优先 isolated。

坑 7：没看运行历史就猜问题

Cron 没按预期工作时，先看：

openclaw cron listopenclaw cron show <job-id>openclaw cron runs --id <job-id>

不要凭感觉改配置。

二十二、Cron 的安全原则

我建议记住这 6 条。

未来任务用 Cron，不用 sleep。
时间一定写清楚，尤其是时区。
后台报告优先 isolated。
自动输出要短，异常再展开。
高风险动作只提醒，不自动执行。
排错先看 job 和 run history。

这 6 条能避免大多数 Cron 使用问题。

二十三、这一课最值得记住的一句话

如果今天只记一句话，我建议你记这句：

Cron 不是让 AI 等时间，而是让 Gateway 到点唤醒 AI。

再补一句使用原则：

明确时间、明确任务、明确投递，自动化才不会变成打扰。

二十四、总结

今天这节课，我们讲清楚了 OpenClaw 的 Cron 定时任务：

Cron 是 Gateway 内置的调度器。
Cron 运行在 Gateway，不运行在模型里。
未来某个时间再做的事，应该交给 Cron，而不是 sleep。
Cron 支持 at、every、cron 三类 schedule。
没有 timezone 的时间默认按 UTC，建议明确 --tz。
main 适合提醒，isolated 适合后台报告，current 适合绑定当前上下文。
announce 用于把结果投递回聊天渠道。
Cron 每次执行都会创建 background task 记录。
排错时先看 cron list / show / runs。
定时任务要短、清楚、低打扰，高风险动作先让用户确认。

学会 Cron 后，OpenClaw 就不只是“你问它答”的助手了。

它开始能按时间主动做事：提醒、总结、检查、报告。

这就是自动化真正开始发生的地方。

下一课预告

下一课我们会讲：

第 19 课：Webhook / Hooks——外部事件触发 AI

也就是：

Webhook 和 Cron 有什么区别
外部系统怎么触发 OpenClaw
hooks/wake 和 hooks/agent 怎么理解
token 和安全边界怎么设置
哪些场景适合事件触发而不是定时任务

🦞 本文由八条撰写，持续更新中。