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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

这意味着：

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

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

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

运行历史：~/.openclaw/cron/runs/ .jsonl

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

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

这一点必须单独点出来。

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

 
  
    
    
 
     
GPT plus 代充 只需 145// ~/.openclaw/openclaw.json 
 
     
{ cron: {
 
     
enabled: true, store: "~/.openclaw/cron/jobs.json", maxConcurrentRuns: 1, sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000, }, 
 
     
}, }
 
    

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

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

• main：主会话；
• isolated：隔离 cron 会话；
• current：绑定当前会话；
• session: ：绑定自定义持久会话。

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

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

这类任务的特点是：

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

示例：

 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron add \ 
 
    

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

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

它的优点在于：

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

示例：

GPT plus 代充 只需 145 
  
    
    
 
     
openclaw cron add \ 
 
    

GPT plus 代充 只需 145 

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

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

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

 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron add \ 
 
    

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

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

先检查 Gateway 状态：

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

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

GPT plus 代充 只需 145 
  
    
    
 
     
{ 
 
     
cron: {
 
     
GPT plus 代充 只需 145enabled: true, 
 
     
}, }
 
    

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

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

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

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

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

GPT plus 代充 只需 145 
  
    
    
 
     
openclaw cron add \ 
 
    

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

先看 Cron 总状态：

 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron status
 
    
 
再看任务列表：
 
  
    
    
 
     
openclaw cron list
 
    
 
等待任务触发后，查看运行历史：
 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron runs --id 
        
          --limit 20 
        
 
    
 
如果还要看更底层的日志，直接跟 Gateway 日志即可：
 
  
    
    
 
     
openclaw logs --follow
 
    
 
这套链路比旧写法里的 openclaw gateway logs | grep ... 更贴近当前官方排障文档，也更适合跨平台场景。
 

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

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

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

 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron add \ 
 
    

 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron edit 
        
          \ 
        
 
    

 
如果是秒级或整点高频任务，希望完全按时而不是使用调度器默认的错峰窗口，可以显式设为 exact：
 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron edit 
        
          --exact 
        
 
    
 
  
    
    
 
     
openclaw cron run 
        
 
    
 
这里还有一个非常容易误判的点：openclaw cron run 返回成功，并不等于任务已经全部执行完成。 当前版本里，这条命令表示"手动执行已经排队成功"，真正的最终结果还要去看 runs：
 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron runs --id 
        
          --limit 50 
        
 
    
 
  
    
    
 
     
openclaw cron runs --id 
        
          --limit 20 
        
 
    
 
这比只看任务列表更有价值，因为排障时真正要看的不是"任务在不在"，而是"最近一次到底有没有跑成、为什么没跑成、是跳过、报错还是投递失败"。
 

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

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

OpenClaw Cron 支持的 schedule 一共三种：

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

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

标准 5 字段表达式；

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

例如：

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

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

GPT plus 代充 只需 145 
  
    
    
 
     
openclaw cron add \ 
 
    

GPT plus 代充 只需 145 
或者给出明确错峰窗口：
 
  
    
    
 
     
openclaw cron add \ 
 
    

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

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

 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron add \ 
 
    

 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron add \ 
 
    

 
这一类任务往往执行频率高，适合内部运行，并把异常结果再交给后续流程处理。
 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron add \ 
 
    

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

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

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

建议按下面顺序排：

GPT plus 代充 只需 145 
  
    
    
 
     
openclaw status 
 
     
openclaw gateway status openclaw cron status openclaw cron list openclaw cron runs –id 
      
        –limit 20 openclaw logs –follow openclaw doctor 
        
      
 
    

GPT plus 代充 只需 145 

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

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

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

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

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

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

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

 
  
    
    
 
     
GPT plus 代充 只需 145openclaw cron run 
         
        
 
     
openclaw cron runs –id 
      
        –limit 20 
        
      
 
    

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

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

GPT plus 代充 只需 145 
  
    
    
 
     
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 才不只是一个会聊天的代理，而是一套开始具备自动执行力的系统。