夜雨聆风“近期将连续发布《从OpenClaw源码分析小龙虾是如何工作的？》，本系列一共十篇文章。 主题为：概览与调试环境搭建->Gateway中央控制器->Session管理分析->提示词上下文分析->ReAct原理与源码分析->定时任务与心跳机制->记忆系统分析->Skill 体系分析->Channel 系统分析->自我进化机制。
第6篇：定时任务与心跳机制
一、概述
OpenClaw 的定时任务与心跳机制是其主动运行能力的核心。与传统的"用户问→AI答"被动模式不同，OpenClaw 能够：
定时执行任务：按照 Cron 表达式自动触发任务。 心跳检查：周期性主动检查需要关注的事项并通知用户。
二、定时任务管理方式
OpenClaw 提供两种管理定时任务的方式：
2.1 Web 界面管理
访问 http://127.0.0.1:18789/，进入 "定时任务" 菜单：
查看所有任务列表 创建新任务（Cron 表达式 + 提示词） 编辑/删除任务 查看任务运行日志
2.2 CLI 命令管理
# 列出所有定时任务openclaw cron list# 创建定时任务openclaw cron create --name "每日日报" --schedule "0 9 * * *" --prompt "生成今日日报"# 删除定时任务openclaw cron delete --id <job-id># 立即触发任务openclaw cron trigger --id <job-id># 暂停/恢复任务openclaw cron pause --id <job-id>openclaw cron resume --id <job-id>
三、Croner 库
OpenClaw 使用 croner 库来解析标准 Cron 表达式。croner 是一个轻量级、纯 TypeScript 实现的 Cron 解析库，支持标准 Cron 表达式和时区设置。
3.1 Cron 表达式格式
┌───────────── 分钟 (0 - 59)│ ┌─────────── 小时 (0 - 23)│ │ ┌───────── 日期 (1 - 31)│ │ │ ┌─────── 月份 (1 - 12)│ │ │ │ ┌───── 星期 (0 - 6, 0 = 星期日)│ │ │ │ │* * * * *3.2 Croner 使用示例
3.3 支持的三种模式
支持三种模式：
一次性任务。 间隔重复。 标准cron表达式。
|
四、Gateway 的 Cron 架构
Gateway包含了Cron服务层，提供CronService服务，对应核心代码src/cron/service.ts，该服务提供cron操作。
到期的任务会在执行层，先构建提示词，然后交给pi agent实现ReAct模式交互调用。
所有任务的信息和运行状态都是持久化的。 ~/.openclaw/cron/jobs.json ←─ 任务定义~/.openclaw/cron/runs/.jsonl ←─ 运行日志~/.openclaw/sessions/.json ←─ 会话存储 (包含 cron 会话)
五、持久化存储详解
5.1 jobs.json —— 任务定义
文件路径：~/.openclaw/cron/jobs.json
存储所有定时任务的定义信息：
5.2 runs/*.jsonl —— 运行日志
文件路径：~/.openclaw/cron/runs/{job-id}.jsonl
记录每次任务执行的详细信息（追加写入）：
5.3 会话日志
六、CLI 端和 Web 端的处理流程
6.1 CLI 端调用流程
用户执行: openclaw cron create --name "日报" --schedule "0 9 * * *" --prompt "生成日报"
6.2 Web 端调用流程
用户在 Web 界面点击"创建定时任务"
七、Cron 提示词格式
当定时任务被触发时，OpenClaw 会构建一个特殊的提示词发送给 Agent：
Cron 提示词 = 系统提示词 + 历史对话 + cron 提示词7.1 Cron 提示词格式
[cron:{jobId} {jobName}] {userMessage}Current time: {formattedTime} ({timezone})7.2 示例
[cron:daily-report-002 生成日报] 分析今天的服务器日志，生成运维日报摘要，包含错误统计和性能指标。Current time: 2026-05-31 18:00:00 (Asia/Shanghai)Return your summary as plain text; it will be delivered automatically.If the task explicitly calls for messaging a specific external recipient,note who/where it should go instead of sending it yourself.
八、Heartbeat 心跳机制
Heartbeat 是 OpenClaw 的周期性后台主动检查机制，让 Agent 能够在没有用户输入的情况下主动检查需要关注的事项并通知用户。
8.1 Heartbeat 与 Cron 的区别
| 目的 | ||
| 输出 | ||
| 触发方式 | ||
| Session | ||
| 典型场景 |
8.2 Agent Heartbeat
OpenClaw 的主要心跳机制，周期性地在主 Session 中运行 Agent 检查。
触发源：
定时调度：最小单位是各 Agent 配置的 every（如every: "10m"）Cron 触发： sessionTarget: "main"的 Cron job 通过requestHeartbeatNow()触发手动触发：用户通过 openclaw system event --mode now手动触发
8.3 Heartbeat 提示词机制
当 Heartbeat 触发时，Agent 会收到特殊的提示词指令：
## 心跳机制心跳提示：读取 HEARTBEAT.md（如果存在，位于工作区上下文中）。严格遵守其中的内容。不要推断或重复之前对话中的旧任务。如果没有任何需要关注的事项，回复 HEARTBEAT_OK。如果你收到一个心跳轮询（即用户消息与上述心跳提示相匹配），并且没有任何需要关注的事项，则精确回复：HEARTBEAT_OKOpenClaw 会将开头/结尾带有 HEARTBEAT_OK 的消息视为心跳确认（并可能将其丢弃）。如果确实有需要关注的事项，不要包含 HEARTBEAT_OK；应改为回复相应的警报内容。8.4 HEARTBEAT.md 示例
# 心跳检查清单请定期检查以下事项：## 系统状态- 检查磁盘使用率是否超过 80%- 检查内存使用率是否超过 90%- 检查是否有未处理的错误日志## 待办事项- 检查是否有今日截止的任务未完成- 检查是否有用户消息超过 1 小时未回复## 外部事件- 检查 GitHub 是否有新的 Issue 被分配给我- 检查是否有新的 PR 需要 review如有任何异常，请立即通知我。九、总结
两种管理方式：Web 界面和 CLI 命令，满足不同使用习惯 Croner 库：轻量级 Cron 表达式解析，支持时区和多种模式 CronService：统一的任务管理器，负责 CRUD 和调度 持久化存储：jobs.json（任务定义）+ runs/*.jsonl（运行日志） Cron 提示词：特殊格式，明确标识任务 ID 和当前时间 Heartbeat 机制：主动检查能力，让 Agent 从被动变主动
