OpenClaw Cron 完全指南：解锁 AI 智能体的定时自动化超能力

版本说明：本文基于 2026 年 3 月的 OpenClaw 官方文档校订与补充，命令、配置路径与运行机制均按当前文档表述整理。

前言

在 AI 智能体真正落地之前，很多自动化都停留在"发一条指令，执行一次动作"的阶段。这样的使用方式并不算错，但生产力释放得并不充分。在我看来，真正把 AI 从"聊天助手"变成"自动化执行者"的关键，不在于多问几句，而在于让它能够按时间主动运行、长期稳定运行、在无人值守时也能把流程闭环跑完。

OpenClaw Cron 的价值，恰好就在这里。

它不是一个花哨的小功能，也不是某个插件市场里的附加组件，而是 Gateway 层内置的调度能力。只要把时间规则、执行内容、运行会话和交付方式设计清楚，Cron 就能把提醒、简报、巡检、汇总、备份、通知这些原本需要手工驱动的流程，稳定地推到自动运行轨道上。
这篇文章会把 OpenClaw Cron 的核心概念、当前版本的真实运行机制、命令用法、实战模式、常见误区和排障思路一次讲透。重点不只是"怎么创建一个定时任务"，而是"怎么把定时任务真正用对"。

一、先讲结论：OpenClaw Cron 到底是什么

OpenClaw Cron 是 Gateway 内置的定时调度器。它负责保存任务、计算下一次触发时间、在合适的时间唤醒智能体执行任务，并在需要时把结果投递回聊天通道、主会话或 Webhook。

如果让我用一句话概括，它做的事情其实很简单：

把"什么时候执行"和"执行什么内容"拆开，再由 Gateway 在正确时间点自动把这件事跑起来。

这套设计和 Linux 里的 Crontab 很像，但又不是照搬传统 cron。它不只是"到点执行 shell 命令"，而是面向 AI 智能体的会话、上下文、模型、通道和结果投递做了专门适配。因此，OpenClaw Cron 更像是：

一个时间驱动的调度中枢；
一个面向 AI 执行链路的唤醒器；
一个能把执行结果继续送回会话、通道或外部系统的自动化入口。

二、最容易混淆的三个概念：Cron、Skills、Heartbeat

2.1 Cron 不是 Skill

这是最常见的误解，也是我认为原始博客里最需要强调的一点。

Cron 不是 Skill。Skill、插件、工具、外部集成，负责的是"智能体能做什么"；Cron 负责的是"这件事什么时候自动触发"。两者根本不是同一层。

维度	OpenClaw Cron	Skills/插件/工具能力
本质	Gateway 内置调度器	智能体可调用的能力扩展
核心职责	决定何时触发	决定能做什么
运行位置	Gateway 进程内	智能体运行时//工具层/集成层
依赖关系	可调用能力，但不隶属于能力	可被Cron调度，但不负责时间触发
管理方式	`openclaw cron` / Control UI / Gateway API	安装、启用、配置具体能力

换句话说，Cron 是调度中枢，能力扩展是执行部件。Cron 可以调度带有浏览器、消息、日历、邮件、文件处理等能力的任务，但 Cron 本身不是这些能力的一部分。

2.2 Cron 也不等于 Heartbeat

很多人第一次接触 OpenClaw 的自动化，会把 Cron 和 Heartbeat 混在一起。实际上，两者虽然都和"定时"有关，但定位并不一样。

Cron 适合明确的调度任务，例如"每天 7 点运行一次""20 分钟后提醒一次""每 5 分钟巡检一次"。
Heartbeat 更像主会话的定期心跳执行机制，强调在主上下文中按固定节奏跑检查、摘要、提醒、静默维护等动作。

一个非常重要的运行细节是：主会话型的 Cron 任务，本质上是先排入一个 system event，再通过 heartbeat 执行通道把任务跑起来。因此，Cron 与 Heartbeat 不是替代关系，而是有明确的协作关系。

2.3 当前版本里，Cron 还是一等工具接口

从产品架构上说，Cron 属于 Gateway 层内置调度器；从接口层说，Gateway 还把它暴露成了一等的 cron.\* 工具 / API，Control UI 和自动化面板也正是通过这些接口管理任务。因此，把它理解成"Gateway 原生调度能力 + 对外暴露的管理接口"最准确。

三、当前版本真正的运行机制

这一部分是本文校订后的重点，因为很多旧写法已经和当前文档不一致了。

3.1 Cron 跑在 Gateway 里，不跑在模型里

Cron 的执行主体不是模型本身，而是 Gateway。只要 Gateway 持续在线，Cron 就会持续工作；Gateway 停掉，Cron 也会一起停掉。

这意味着：

没有常驻 Gateway，就没有稳定定时；
远程云端部署时，Gateway 的在线连续性直接决定了自动化可靠性；
本地测试时如果只是在前台临时跑一次 Gateway，关掉终端后 Cron 也会一起失效。

3.2 任务与运行历史的真实存储位置

当前版本里，Cron 相关数据默认保存在以下位置：

任务定义：\~/.openclaw/cron/jobs.json

运行历史：\~/.openclaw/cron/runs/<jobId>.jsonl

这两个路径非常重要。前者决定"有哪些任务"，后者决定"这些任务实际跑过什么结果"。

除此之外，隔离会话型任务还会产生独立的 cron 运行会话记录，默认由 cron.sessionRetention 控制保留时间。

3.3 配置文件不是 `config.yaml`，而是 `\~/.openclaw/openclaw.json`

这一点必须单独点出来。

当前 OpenClaw 官方文档里的配置文件主路径是：

json5 复制代码

// \~/.openclaw/openclaw.json
{
  cron: {
    enabled: true,
    store: "\~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

也就是说，当前版本的 Cron 配置不应再写成 \~/.openclaw/config.yaml 这一套表述。如果一篇博客还在把配置路径写成 yaml，很容易把读者带偏。

3.4 Cron 任务不只有"主会话"和"独立会话"两种粗略理解

更准确的理解应该是四种运行目标：

main：主会话；
isolated：隔离 cron 会话；
current：绑定当前会话；
session:<custom-id>：绑定自定义持久会话。

这意味着 Cron 并不是只能"要么发到主聊天窗口，要么静默后台跑"。当前版本对会话绑定的支持已经更灵活，可以把重复任务绑定到一个长期存在的自定义会话，让它持续累积上下文。

四、主会话任务与隔离任务：真正的差别在哪里

4.1 主会话任务：适合提醒、摘要、需要主上下文的任务

主会话任务使用 systemEvent 语义，通常配合 --session main 和 --system-event 创建。

这类任务的特点是：

先把系统事件排入主会话；
再通过 heartbeat 通道执行；
适合需要主上下文、主人格、主路线回传的任务；
适合提醒、待办整理、晨报、主聊天窗口同步结果这类场景。

示例：

bash 复制代码

openclaw cron add \\
  --name "daily-main-reminder" \\
  --cron "0 7 \* \* \*" \\
  --tz "Asia/Shanghai" \\
  --session main \\
  --system-event "生成今日晨间提醒：整理日程、待办与重点事项，控制在300字以内。" \\
  --wake now

这里的 --wake now 很关键，表示 Cron 触发后立即唤醒 heartbeat 去跑，而不是等下一次自然心跳。

4.2 隔离任务：适合后台执行、专用通道投递、独立自动化流程

隔离任务使用 agentTurn 语义，通常配合 --session isolated 和 --message 创建。

它的优点在于：

不直接污染主会话对话历史；
可以单独指定模型、思考等级、交付通道；
可以投递到 Telegram / Slack / WhatsApp 等外部通道；
更适合巡检、日报、监控、批处理、夜间任务等后台工作。

示例：

bash 复制代码

openclaw cron add \\
  --name "morning-status" \\
  --cron "0 7 \* \* \*" \\
  --tz "Asia/Shanghai" \\
  --session isolated \\
  --message "汇总今日待办、未读重点消息与关键日程，形成一段简洁的晨间状态摘要。" \\
  --announce

4.3 一个很容易踩坑的细节：隔离任务默认不是"静默后台"

很多旧理解会把"独立会话"直接等同于"后台静默运行"，这是不准确的。

在当前文档里，如果隔离任务没有显式写 delivery，默认会采用 announce 投递摘要。也就是说，隔离任务默认会把结果做摘要投递，而不是天然静默。

如果只想让它内部执行、不对外发送，可以显式关闭投递：

bash 复制代码

openclaw cron add \\
  --name "nightly-internal-maintenance" \\
  --cron "0 2 \* \* \*" \\
  --tz "Asia/Shanghai" \\
  --session isolated \\
  --message "执行夜间维护：检查缓存、清理临时数据、记录执行状态。" \\
  --no-deliver

这一条是当前版本里非常值得补充的实践结论：隔离任务 ≠ 默认静默；需要静默时，要显式写 --no-deliver。

五、Cron 真正生效，需要满足哪些条件

5.1 Gateway 必须持续运行

这是最基本、也最容易被忽视的一步。

先检查 Gateway 状态：

bash 复制代码

openclaw gateway status

如果要做长期自动化，最好使用受监督的运行方式，确保 Gateway 在系统重启、终端关闭或异常退出后仍能恢复。

5.2 Cron 必须处于启用状态

当前配置项应写在 \~/.openclaw/openclaw.json 中，而不是 yaml：

json5 复制代码

{
  cron: {
    enabled: true,
  },
}

另外还要注意一个环境变量开关：如果设置了 OPENCLAW\_SKIP\_CRON=1，调度器会被跳过，任务不会自动执行。

5.3 时区必须处理清楚

Cron 的时间问题，绝大多数都不是"调度器坏了"，而是时区没配对。

有三条规则必须牢记：
--cron 表达式如果不写 --tz，默认使用 Gateway 所在主机的本地时区；
--at 使用 ISO 时间戳时，如果时间字符串不带时区，会按 UTC 解释；

国内部署如果希望按北京时间执行，最稳妥的写法仍然是显式加上 --tz "Asia/Shanghai"。

六、最快速、最稳妥的自检方法

只看配置不够。在我的实际排障经验里，最稳妥的方式始终是跑一条一次性测试任务，把"创建 → 调度 → 执行 → 记录结果"整条链路走通。

6.1 推荐的跨平台自检命令

当前文档已经支持相对时间，因此没有必要再用不同平台的 date 拼接命令。直接写成 1 分钟后执行即可：

bash 复制代码

openclaw cron add \\
  --name "cron-availability-test" \\
  --at "1m" \\
  --session main \\
  --system-event "Cron 调度链路测试：记录当前时间并确认任务已被成功执行。" \\
  --wake now

这种写法比手工拼 ISO 时间更稳，也避免了 Linux / macOS / Windows 不同 shell 的时间格式差异。

6.2 验证步骤

先看 Cron 总状态：

bash 复制代码

openclaw cron status

再看任务列表：

bash 复制代码

openclaw cron list

等待任务触发后，查看运行历史：

bash 复制代码

openclaw cron runs --id <job-id> --limit 20

如果还要看更底层的日志，直接跟 Gateway 日志即可：

bash 复制代码

openclaw logs --follow

这套链路比旧写法里的 openclaw gateway logs | grep ... 更贴近当前官方排障文档，也更适合跨平台场景。

七、当前版本里最值得掌握的核心命令

原始博客里把命令体系写成了 add / list / show / pause / resume / delete 的传统套路，但按当前文档，最核心、最实用的一组命令其实是下面这些。

命令	作用
`openclaw cron add`	创建任务
`openclaw cron status`	查看调度器整体状态
`openclaw cron list`	查看任务列表
`openclaw cron edit`	修改既有任务
`openclaw cron run`	手动触发一次任务
`openclaw cron runs --id <job-id>`	查看运行历史与结果
`openclaw cron --help`	查看当前版本完整子命令与参数

7.1 创建一次性任务

bash 复制代码

openclaw cron add \\
  --name "expense-reminder" \\
  --at "2026-04-01T15:00:00+08:00" \\
  --session main \\
  --system-event "提醒报销：检查票据、整理报销单并确认提交流程。" \\
  --wake now

这里显式写了 +08:00，就不会再被当成 UTC。

7.2 创建循环任务

bash 复制代码

openclaw cron add \\
  --name "daily-brief" \\
  --cron "0 7 \* \* \*" \\
  --tz "Asia/Shanghai" \\
  --session isolated \\
  --message "生成今日晨报：汇总天气、日程、待办与未读重点消息，控制在400字以内。" \\
  --announce

7.3 修改任务

bash 复制代码

openclaw cron edit <job-id> \\
  --message "更新后的任务内容：补充未完成事项与风险提醒。" \\
  --thinking low

如果是秒级或整点高频任务，希望完全按时而不是使用调度器默认的错峰窗口，可以显式设为 exact：

bash 复制代码

openclaw cron edit <job-id> --exact

7.4 手动调试任务

bash 复制代码

openclaw cron run <job-id>

这里还有一个非常容易误判的点：openclaw cron run 返回成功，并不等于任务已经全部执行完成。当前版本里，这条命令表示"手动执行已经排队成功"，真正的最终结果还要去看 runs：

bash 复制代码

openclaw cron runs --id <job-id> --limit 50

7.5 查看运行历史

bash 复制代码

openclaw cron runs --id <job-id> --limit 20

这比只看任务列表更有价值，因为排障时真正要看的不是"任务在不在"，而是"最近一次到底有没有跑成、为什么没跑成、是跳过、报错还是投递失败"。

7.6 启停与移除任务的现实做法

当前官方文档公开示例更集中在 status / list / add / edit / run / runs 这一组命令上；而 Control UI 的 Cron 面板已经明确支持 list / add / edit / run / enable / disable / run history。因此在日常运维里，任务的启停与管理完全可以优先放到 Control UI 中完成。

这也是当前版本一个很实际的变化：CLI 适合批量创建、脚本化调度和调试，Control UI 更适合日常管理、启停和排障观察。

八、Cron 表达式、相对时间与错峰机制

8.1 当前版本支持三种调度类型

OpenClaw Cron 支持的 schedule 一共三种：

at：一次性时间点；
every：固定时间间隔；
cron：Cron 表达式调度。
对 CLI 使用者来说，最常接触的就是：
--at "20m" 这类相对时间；
--at "2026-04-01T15:00:00+08:00" 这类绝对时间；
--cron "0 7 \* \* \*" 这类日历式调度。

8.2 Cron 表达式支持 5 字段，也支持 6 字段秒级表达式

当前文档明确写明，cron 调度支持：

标准 5 字段表达式；

以及带秒的 6 字段表达式。

例如：

表达式	含义
`0 7 \* \* \* \*`	每天 7 点
`0 9 \* \* \* 1-5`	工作日每天 9 点
`0 \* \* \* \* \*`	每分钟整点触发一次（6 字段秒级）
`/10 \ \* \* \* \*`	每 10 秒执行一次

8.3 一个新版本里很值得写进博客的细节：整点高频任务会默认错峰

当前文档提到，为了减少大量 Gateway 在整点同时触发带来的尖峰负载，OpenClaw 会对某些"整点型周期任务"施加确定性的错峰窗口。例如 0 \* \* \* \*、0 \*/2 \* \* \* 这类表达式，可能不会全部严格卡在整点 00 秒执行，而会在允许的窗口内错开。

如果就是要严格按点触发，可以显式写：

bash 复制代码

openclaw cron add \\
  --name "exact-hourly-job" \\
  --cron "0 \* \* \* \*" \\
  --tz "Asia/Shanghai" \\
  --exact \\
  --session isolated \\
  --message "执行严格整点任务。" \\
  --no-deliver

或者给出明确错峰窗口：

bash 复制代码

openclaw cron add \\
  --name "staggered-minute-job" \\
  --cron "0 \* \* \* \* \*" \\
  --tz "Asia/Shanghai" \\
  --stagger 30s \\
  --session isolated \\
  --message "执行分钟级监控。" \\
  --announce

这一点非常适合补进任何"Cron 完全指南"里，因为它直接关系到"为什么表达式没写错，但实际执行时间和想象中略有偏差"。

九、真正高价值的实战用法

9.1 每日晨报：主会话模式最稳

如果目标是把结果同步到日常聊天主线里，主会话模式更自然：

bash 复制代码

openclaw cron add \\
  --name "daily-main-brief" \\
  --cron "0 7 \* \* \*" \\
  --tz "Asia/Shanghai" \\
  --session main \\
  --system-event "生成今日晨报：整理天气、日程、待办、未读重点消息，并压缩为清晰的条目式摘要。" \\
  --wake now

9.2 服务器巡检：隔离会话更干净

bash 复制代码

openclaw cron add \\
  --name "server-health-check" \\
  --cron "\*/5 \* \* \* \*" \\
  --tz "Asia/Shanghai" \\
  --session isolated \\
  --message "执行服务器健康巡检：检查 CPU、内存、磁盘、关键进程与异常日志，输出结构化结果。" \\
  --no-deliver

这一类任务往往执行频率高，适合内部运行，并把异常结果再交给后续流程处理。

9.3 外部通道日报：隔离会话 + announce

bash 复制代码

openclaw cron add \\
  --name "nightly-summary" \\
  --cron "0 22 \* \* \*" \\
  --tz "Asia/Shanghai" \\
  --session isolated \\
  --message "整理今日工作进展与待处理事项，生成一份夜间总结。" \\
  --announce \\
  --channel telegram \\
  --to "-1001234567890:topic:123"

9.4 长期累积上下文的自动化：自定义持久会话

对于"每天都在同一条工作流里续写状态"的任务，可以考虑把任务绑到持久 session，而不是每次都开全新 isolated 运行。这样更适合连续日报、项目跟踪、迭代日志这类场景。

9.5 轻量级后台杂务：可以开启 light context

对于"不需要完整工作区 bootstrap 上下文"的小任务，当前版本还支持轻量上下文模式。这样能减少不必要的上下文注入，适合简单的定时检查和维护任务。

十、这篇博客最值得补上的排障思路

很多 Cron 文章喜欢讲"怎么创建"，却很少讲"出了问题怎么排"。实际上，真正决定体验的是排障链路是否清晰。

10.1 标准排障顺序

建议按下面顺序排：

bash 复制代码

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <job-id> --limit 20
openclaw logs --follow
openclaw doctor

10.2 常见故障与真实原因

表现	常见原因	正确排查方向
任务完全不触发	Gateway 没有常驻运行	先看 `openclaw gateway status`
任务存在但自动不跑	`cron.enabled` 被关，或 `OPENCLAW_SKIP_CRON=1`	看 `openclaw cron status` 与配置
任务执行时间不对	时区没写、ISO 时间被当成 UTC	统一显式写 `--tz` 或带时区偏移
隔离任务执行了但没看到消息	设置了 `--no-deliver`，或通道投递有问题	看 `runs` 和通道连接状态
`cron run` 看似成功但没有结果	只是成功入队，并非已完成	继续看 `openclaw cron runs`
整点任务有轻微偏移	触发了默认错峰机制	使用 `--exact` 或自定义 `--stagger`
旧版本任务升级后异常	历史任务字段形态和新版本不一致	运行 `openclaw doctor --fix`

10.3 一个非常实用的经验

排 Cron 问题时，不要只盯着"任务列表里有没有这条任务"。列表只能证明任务被存下来了，不能证明它已经跑通。真正有价值的是：

cron status 看调度器是否活着；
runs 看任务最近一次到底发生了什么；
logs 看 Gateway 侧有没有调度、投递、通道或鉴权错误。

十一、生产环境里的最佳实践

11.1 任务命名要带场景与周期

推荐采用这种命名风格：
daily-main-brief
server-health-check-5min
nightly-backup-sync
weekly-project-summary

这样在 cron list 和 Control UI 里一眼就能知道任务用途。

11.2 所有时间都显式写清楚

最佳实践不是"依赖默认值"，而是：

Cron 表达式写清楚；
--tz 写清楚；
ISO 时间写清楚时区偏移；
高频任务明确写 --exact 或 --stagger。

11.3 主会话与隔离会话分工明确

需要主上下文、主对话可见性、提醒感知强的任务，放主会话；
高频巡检、批处理、外部投递、后台执行任务，放隔离会话；
需要连续上下文沉淀的任务，放自定义持久 session。

11.4 先跑一遍手动执行，再上长期调度

在正式上生产前，先手动跑一遍：

bash 复制代码

openclaw cron run <job-id>
openclaw cron runs --id <job-id> --limit 20

只要这条链路没打通，就不要急着把它交给长期自动调度。

11.5 旧任务升级后先做一次 doctor 修复

如果环境经历过版本升级、字段变更或历史迁移，最好主动执行一次：

bash 复制代码

openclaw doctor --fix

这比等到任务 silently fail 之后再查要省心得多。

十二、总结

在我看来，OpenClaw Cron 的真正价值，不是"可以定时发一句提醒"这么简单，而是它把 AI 智能体从被动响应模式，推进到了时间驱动的主动执行模式。

理解 Cron，不能只停留在"会写一个 openclaw cron add 命令"。真正重要的是把下面几件事理解透：

它运行在 Gateway 中，而不是模型中；
它不是 Skill，而是调度中枢；
主会话任务与隔离任务的执行语义完全不同；
当前版本的配置文件是 \~/.openclaw/openclaw.json，不是 yaml；
隔离任务默认会 announce，不是天然静默；
cron run 只是入队，最终结果要看 cron runs；
整点型周期任务可能存在默认错峰，需要时可用 --exact；
真正稳定的自动化，依赖 Gateway 常驻、时区明确、日志可追、运行历史可查。

当这些环节都理顺之后，Cron 就不再只是一个"定时器"，而会成为整套 OpenClaw 自动化体系里的时间驱动中枢。把它和能力扩展、通道投递、持久会话、自定义工作流结合起来，AI 智能体才真正具备"无人值守持续做事"的能力。

OpenClaw Cron 完全指南：解锁 AI 智能体的定时自动化超能力

前言

一、先讲结论：OpenClaw Cron 到底是什么

二、最容易混淆的三个概念：Cron、Skills、Heartbeat

2.1 Cron 不是 Skill

2.2 Cron 也不等于 Heartbeat

2.3 当前版本里，Cron 还是一等工具接口

三、当前版本真正的运行机制

3.1 Cron 跑在 Gateway 里，不跑在模型里

3.2 任务与运行历史的真实存储位置

3.3 配置文件不是 config.yaml，而是 \~/.openclaw/openclaw.json

3.4 Cron 任务不只有"主会话"和"独立会话"两种粗略理解

四、主会话任务与隔离任务：真正的差别在哪里

4.1 主会话任务：适合提醒、摘要、需要主上下文的任务

4.2 隔离任务：适合后台执行、专用通道投递、独立自动化流程

4.3 一个很容易踩坑的细节：隔离任务默认不是"静默后台"

五、Cron 真正生效，需要满足哪些条件

5.1 Gateway 必须持续运行

5.2 Cron 必须处于启用状态

5.3 时区必须处理清楚

六、最快速、最稳妥的自检方法

6.1 推荐的跨平台自检命令

6.2 验证步骤

七、当前版本里最值得掌握的核心命令

7.1 创建一次性任务

7.2 创建循环任务

7.3 修改任务

7.4 手动调试任务

7.5 查看运行历史

7.6 启停与移除任务的现实做法

八、Cron 表达式、相对时间与错峰机制

8.1 当前版本支持三种调度类型

8.2 Cron 表达式支持 5 字段，也支持 6 字段秒级表达式

8.3 一个新版本里很值得写进博客的细节：整点高频任务会默认错峰

九、真正高价值的实战用法

9.1 每日晨报：主会话模式最稳

9.2 服务器巡检：隔离会话更干净

9.3 外部通道日报：隔离会话 + announce

9.4 长期累积上下文的自动化：自定义持久会话

9.5 轻量级后台杂务：可以开启 light context

十、这篇博客最值得补上的排障思路

10.1 标准排障顺序

10.2 常见故障与真实原因

10.3 一个非常实用的经验

十一、生产环境里的最佳实践

11.1 任务命名要带场景与周期

11.2 所有时间都显式写清楚

11.3 主会话与隔离会话分工明确

11.4 先跑一遍手动执行，再上长期调度

11.5 旧任务升级后先做一次 doctor 修复

十二、总结

3.3 配置文件不是 `config.yaml`，而是 `\~/.openclaw/openclaw.json`