从OpenClaw源码分析小龙虾是如何工作的?——定时任务与心跳机制

“
近期将连续发布《从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 的区别

维度	Cron（定时任务）	Heartbeat（心跳）
目的	执行具体任务	检查是否有需要关注的事项
输出	任务执行结果	需要关注的警报或 HEARTBEAT_OK
触发方式	Cron 表达式	定时调度 / 手动触发
Session	可独立 Session	在主 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 从被动变主动