OpenClaw 心跳与定时任务实战指南

原文来源：OpenClaw 官方文档发布时间：2026年3月7日

一、快速选择指南

使用场景	推荐方案	原因
每 30 分钟检查一次邮箱	Heartbeat	可以批量处理多个检查任务，上下文感知
每天早上 9 点准时发送日报	Cron (isolated)	需要精确的时间点
监控日历中的即将到来的事件	Heartbeat	自然适合周期性感知任务
每周进行一次深度分析	Cron (isolated)	独立任务，可以使用不同的模型
20 分钟后提醒我	Cron (main, `--at`)	一次性提醒，精确时间
后台项目健康检查	Heartbeat	复用现有的心跳周期

二、Heartbeat：周期性感知

2.1 什么是 Heartbeat

Heartbeat 是在主会话中以固定间隔运行的周期性任务（默认 30 分钟）。它被设计为让 AI 检查各项状态并汇报重要事项。

2.2 工作原理

Heartbeat 运行时，OpenClaw 会：

注入 HEARTBEAT.md：如果工作区存在 HEARTBEAT.md 文件，其内容会被包含在上下文中

发送系统提示：默认提示为：

Read HEARTBEAT.md if it exists (workspace context). Follow it strictly.
Do not infer or repeat old tasks from prior chats.
If nothing needs attention, reply HEARTBEAT_OK.

执行模型推理：模型根据提示生成响应
处理响应：
- 如果响应包含 HEARTBEAT_OK，消息会被抑制
- 如果有其他内容，会被发送到配置的目标通道

2.3 何时使用 Heartbeat

批量检查多个任务：不需要创建 5 个独立的 cron 任务，一次心跳可以检查邮箱、日历、通知和项目状态
需要上下文感知：模型拥有完整的主会话上下文，可以智能判断事情的优先级
对话连续性：心跳运行共享同一会话，AI 可以记住最近的对话并自然跟进
低开销监控：一次心跳可以替代多个小型的轮询任务

2.4 HEARTBEAT.md 示例

创建 ~/.openclaw/workspace/HEARTBEAT.md：

markdown

# 心跳检查清单

- 快速扫描：是否有紧急邮件？
- 如果是白天，在无事待处理时进行轻度问候
- 如果任务被阻塞，记录缺少什么，下次询问 Peter

2.5 配置示例

在 ~/.openclaw/openclaw.json 中配置：

json5

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",          // 间隔时间
        "target": "last",         // 发送到上次使用的通道
        "activeHours": {
          "start": "08:00",
          "end": "22:00"
        }
      }
    }
  }
}

完整配置选项：

字段	说明	默认值
`every`	心跳间隔（持续时间字符串）	`30m`
`model`	心跳运行的模型	主会话模型
`target`	消息发送目标：`last`/`none`/通道 ID	`none`
`lightContext`	轻量级上下文，只注入 HEARTBEAT.md	`false`
`activeHours`	活动时间窗口	无限制
`includeReasoning`	包含推理消息	`false`
`prompt`	自定义提示文本	默认提示

三、Cron：精确调度

3.1 什么是 Cron

Cron 是 OpenClaw 的内置调度器。它会持久化任务，在正确的时间唤醒 AI，并可以选择将输出发送回聊天。

3.2 工作原理

Cron 任务存储在 ~/.openclaw/cron/jobs.json，每次运行会记录到 ~/.openclaw/cron/runs/<jobId>.jsonl。

任务结构（基于实际配置）：

json

{
  "id": "413bafe8-e0cb-41e7-b252-ab36325e3ea6",
  "agentId": "main",
  "name": "汇报你的状态",
  "enabled": true,
  "schedule": {
    "kind": "every",
    "everyMs": 3600000,
    "anchorMs": 1772878537891
  },
  "sessionTarget": "isolated",
  "wakeMode": "now",
  "payload": {
    "kind": "agentTurn",
    "message": "汇报你的状态"
  },
  "delivery": {
    "mode": "announce",
    "channel": "feishu",
    "to": "ou_18ae12605e08e97517eb74c4bc5aa63f"
  },
  "state": {
    "nextRunAtMs": 1772896466710,
    "lastRunAtMs": 1772892866710,
    "lastRunStatus": "ok"
  }
}

3.3 两种执行模式

3.3.1 Main Session（主会话模式）

通过系统事件触发，在下次心跳时运行：

bash

openclaw cron add \
  --name "提醒" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "提醒：检查 cron 文档草稿" \
  --wake now \
  --delete-after-run

适用场景：

需要提醒出现在主会话上下文中
希望在下一次心跳时由完整上下文处理
不需要单独的隔离运行

3.3.2 Isolated（隔离模式）

在独立的 cron:<jobId> 会话中运行，每次都是全新上下文：

bash

openclaw cron add \
  --name "早报" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "总结今天的收件箱和日历。" \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

适用场景：

需要干净的上下文，不受之前对话影响
使用不同的模型或思考级别
发布总结到通道，不污染主会话历史

3.4 Cron 调度类型

类型	命令	说明
一次性提醒	`--at "20m"` 或 `--at "2026-03-07T16:00:00Z"`	在指定时间运行一次
固定间隔	`--every "1h"`	每隔固定时间运行
Cron 表达式	`--cron "0 7 * * *"`	使用 5 字段 cron 表达式

Cron 表达式示例：

表达式	说明
`0 * * * *`	每小时整点
`0 9 * * 1`	每周一上午 9 点
`/30 * * *`	每 30 分钟
`0 0 * * 0`	每周日午夜
`0 7,12,18 * * *`	每天 7 点、12 点、18 点

3.5 配置选项

字段	说明	默认值
`name`	任务名称	必需
`schedule.kind`	`at`/`every`/`cron`	必需
`sessionTarget`	`main`/`isolated`	必需
`wakeMode`	`now`/`next-heartbeat`	`now`
`delivery.mode`	`none`/`announce`/`webhook`	`announce`（隔离模式）
`enabled`	是否启用	`true`
`deleteAfterRun`	运行成功后删除	`true`（一次性任务）

四、实战案例对比

4.1 案例 1：每小时状态汇报

使用 Cron（当前配置）：

bash

openclaw cron add \
  --name "状态汇报" \
  --every "1h" \
  --session isolated \
  --message "汇报你的状态" \
  --announce \
  --channel feishu \
  --to "ou_18ae12605e08e97517eb74c4bc5aa63f"

4.2 案例 2：每日晨报 + 周报 + 一次性提醒

使用 HEARTBEAT.md：

markdown

# HEARTBEAT.md

- 检查紧急邮件
- 审查未来 2 小时内的日历
- 查看待处理的任务
- 如果 8 小时以上安静，发送轻量问候

bash

# Cron 任务
openclaw cron add \
  --name "早报" \
  --cron "0 7 * * *" \
  --session isolated \
  --message "生成今天的早报" \
  --announce

openclaw cron add \
  --name "周报" \
  --cron "0 9 * * 1" \
  --session isolated \
  --message "生成本周总结" \
  --model opus \
  --announce

五、最佳实践

5.1 合理使用 Heartbeat 和 Cron

Heartbeat：批量定期检查、上下文感知任务
Cron：精确调度、独立任务、一次性提醒

5.2 避免夜间打扰

json5

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "activeHours": {
          "start": "08:00",
          "end": "23:00"
        }
      }
    }
  }
}

5.3 轻量上下文

对于简单的心跳任务，启用轻量模式：

json5

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "lightContext": true
      }
    }
  }
}

5.4 模型选择

使用更便宜的模型处理常规任务：

bash

openclaw cron add \
  --name "日报" \
  --session isolated \
  --model sonnet \
  --message "生成日报"

5.5 负载分散

OpenClaw 自动为整点 Cron 任务分散负载（0-5分钟），避免高峰：

bash

# 自动分散
openclaw cron add --cron "0 * * * *" ...

# 强制精确时间（不推荐）
openclaw cron add --cron "0 * * * *" --exact ...

六、常见问题

Q1: Heartbeat 和 Cron 可以同时使用吗？

A: 可以，而且推荐同时使用。Heartbeat 负责日常监控，Cron 负责精确时间的任务。

Q2: 如何禁用 Heartbeat？

A: 设置 agents.defaults.heartbeat.every: "0m"：

json5

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "0m"
      }
    }
  }
}

Q3: Cron 任务失败了怎么办？

A: OpenClaw 会自动重试：

瞬时错误：指数退避重试（30s → 1m → 5m → 15m → 60m）
永久错误：立即禁用任务

查看运行日志：

bash

openclaw cron runs --id <jobId>

Q4: 如何测试 Cron 任务？

A: 使用 --due 强制运行：

bash

# 立即运行
openclaw cron run <jobId>

# 只在到期时运行
openclaw cron run <jobId> --due

Q5: Isolated 会话的上下文从哪里来？

默认：完整的引导文件（BOOTSTRAP.md 等）
轻量模式（lightContext: true）：只有系统提示，没有引导文件

Q6: 如何删除 Cron 任务？

bash

# 列出所有任务
openclaw cron list

# 删除指定任务
openclaw cron remove <jobId>

Q7: Heartbeat 的 `activeHours` 如何工作？

A: 在指定时间窗口外，心跳会被跳过：

json5

{
  "activeHours": {
    "start": "09:00",  // 包含
    "end": "22:00",    // 不包含
    "timezone": "Asia/Shanghai"
  }
}

在 22:00-09:00 期间，心跳不会运行。

Q8: Cron 的 `--exact` 和 `--stagger` 有什么区别？

--stagger 30s：在精确时间的基础上增加 0-30 秒的随机延迟（默认行为，用于分散负载）
--exact：取消随机延迟，精确在指定时间运行

bash

# 使用 30 秒的随机延迟（默认）
openclaw cron add --name "任务" --cron "0 * * * *" --stagger 30s

# 精确在整点运行
openclaw cron add --name "任务" --cron "0 * * * *" --exact

七、总结

Heartbeat 和 Cron 是 OpenClaw 自动化的两大支柱：

特性	Heartbeat	Cron
精度	时间可漂移	精确调度
上下文	主会话完整上下文	隔离或主会话
用途	批量监控、感知任务	精确时间、独立任务
成本	每次心跳调用模型	每个任务调用模型
配置位置	`HEARTBEAT.md` + `openclaw.json`	`~/.openclaw/cron/jobs.json`

核心原则：

用 Heartbeat 批量处理常规监控
用 Cron 处理精确时间的任务
合理组合使用，最大化效率

八、参考资源

相关文章：

OpenClaw Mem0 插件

OpenClaw 心跳与定时任务实战指南 ​

一、快速选择指南 ​

二、Heartbeat：周期性感知 ​

2.1 什么是 Heartbeat ​

2.2 工作原理 ​

2.3 何时使用 Heartbeat ​

2.4 HEARTBEAT.md 示例 ​

2.5 配置示例 ​

三、Cron：精确调度 ​

3.1 什么是 Cron ​

3.2 工作原理 ​

3.3 两种执行模式 ​

3.3.1 Main Session（主会话模式） ​

3.3.2 Isolated（隔离模式） ​

3.4 Cron 调度类型 ​

3.5 配置选项 ​

四、实战案例对比 ​

4.1 案例 1：每小时状态汇报 ​

4.2 案例 2：每日晨报 + 周报 + 一次性提醒 ​

五、最佳实践 ​

5.1 合理使用 Heartbeat 和 Cron ​

5.2 避免夜间打扰 ​

5.3 轻量上下文 ​

5.4 模型选择 ​

5.5 负载分散 ​

六、常见问题 ​

Q1: Heartbeat 和 Cron 可以同时使用吗？ ​

Q2: 如何禁用 Heartbeat？ ​

Q3: Cron 任务失败了怎么办？ ​

Q4: 如何测试 Cron 任务？ ​

Q5: Isolated 会话的上下文从哪里来？ ​

Q6: 如何删除 Cron 任务？ ​

Q7: Heartbeat 的 activeHours 如何工作？ ​

Q8: Cron 的 --exact 和 --stagger 有什么区别？ ​

七、总结 ​

八、参考资源 ​

OpenClaw 心跳与定时任务实战指南

一、快速选择指南

二、Heartbeat：周期性感知

2.1 什么是 Heartbeat

2.2 工作原理

2.3 何时使用 Heartbeat

2.4 HEARTBEAT.md 示例

2.5 配置示例

三、Cron：精确调度

3.1 什么是 Cron

3.2 工作原理

3.3 两种执行模式

3.3.1 Main Session（主会话模式）

3.3.2 Isolated（隔离模式）

3.4 Cron 调度类型

3.5 配置选项

四、实战案例对比

4.1 案例 1：每小时状态汇报

4.2 案例 2：每日晨报 + 周报 + 一次性提醒

五、最佳实践

5.1 合理使用 Heartbeat 和 Cron

5.2 避免夜间打扰

5.3 轻量上下文

5.4 模型选择

5.5 负载分散

六、常见问题

Q1: Heartbeat 和 Cron 可以同时使用吗？

Q2: 如何禁用 Heartbeat？

Q3: Cron 任务失败了怎么办？

Q4: 如何测试 Cron 任务？

Q5: Isolated 会话的上下文从哪里来？

Q6: 如何删除 Cron 任务？

Q7: Heartbeat 的 `activeHours` 如何工作？

Q8: Cron 的 `--exact` 和 `--stagger` 有什么区别？

七、总结

八、参考资源