Cron vs Heartbeat：何时使用哪个

心跳和 Cron 任务都允许您按计划运行任务。本指南帮助您为您的用例选择正确的机制。

快速决策指南

用例	推荐	原因
每 30 分钟检查收件箱	Heartbeat	与其他检查批量处理，上下文感知
每天上午 9 点准时发送日报	Cron（isolated）	需要精确时间
监控日历中的即将发生事件	Heartbeat	适合定期感知
运行每周深度分析	Cron（isolated）	独立任务，可以使用不同模型
20 分钟后提醒我	Cron（main，`--at`）	一次性任务，精确计时
后台项目健康检查	Heartbeat	利用现有周期

Heartbeat：定期感知

心跳在主会话中以固定间隔运行（默认：30 分钟）。它们设计用于让代理检查事物并呈现任何重要内容。

何时使用心跳

多个定期检查：与其使用 5 个单独的 Cron 任务检查收件箱、日历、天气、通知和项目状态，不如使用单个心跳批量处理所有这些。
上下文感知决策：代理拥有完整的主会话上下文，因此可以智能决定哪些紧急，哪些可以等待。
对话连续性：心跳运行共享同一会话，因此代理记得最近的对话并可以自然跟进。
低开销监控：一个心跳可以替代许多小型轮询任务。

心跳优势

批量处理多个检查：一个代理轮次可以一起审查收件箱、日历和通知。
减少 API 调用：单个心跳比 5 个独立的 Cron 任务更便宜。
上下文感知：代理知道您一直在做什么，并可以相应优先处理。
智能抑制：如果不需要关注任何内容，代理回复 HEARTBEAT_OK 并且不发送消息。
自然计时：根据队列负载略有漂移，这对于大多数监控来说是可以接受的。

心跳示例：HEARTBEAT.md 检查清单

# Heartbeat checklist

- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in

代理在每次心跳时读取此内容，并在一个轮次中处理所有项目。

配置心跳

json5

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",        // 间隔
        target: "last",      // 警报发送位置
        activeHours: { start: "08:00", end: "22:00" }  // 可选
      }
    }
  }
}

完整配置请参阅 Heartbeat。

Cron：精确调度

Cron 任务在精确时间运行，可以在隔离会话中运行而不影响主上下文。

何时使用 Cron

需要精确计时："每周一上午 9:00 发送此内容"（不是"大约 9 点左右"）。
独立任务：不需要对话上下文的任务。
不同模型/思考级别：需要更强大模型的重度分析。
一次性提醒：使用 --at 的"20 分钟后提醒我"。
嘈杂/频繁任务：会混乱主会话历史记录的任务。
外部触发器：无论代理是否处于活动状态都应独立运行的任务。

Cron 优势

精确计时：支持时区的 5 字段 cron 表达式。
会话隔离：在 cron:<jobId> 中运行，不会污染主历史记录。
模型覆盖：每个任务可以使用更便宜或更强大的模型。
交付控制：可以直接交付到频道；默认情况下仍会向主会话发布摘要（可配置）。
不需要代理上下文：即使主会话空闲或压缩，也能运行。
一次性支持：--at 用于精确的未来时间戳。

Cron 示例：每日早间简报

bash

openclaw cron add \
  --name "Morning briefing" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
  --model opus \
  --deliver \
  --channel whatsapp \
  --to "+15551234567"

这将在纽约时间上午 7:00 准时运行，使用 Opus 模型保证质量，并直接发送到 WhatsApp。

Cron 示例：一次性提醒

bash

openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: standup meeting starts in 10 minutes." \
  --wake now \
  --delete-after-run

完整 CLI 参考请参阅 Cron jobs。

决策流程图

任务是否需要精确时间运行？
  是 -> 使用 cron
  否 -> 继续...

任务是否需要与主会话隔离？
  是 -> 使用 cron（isolated）
  否 -> 继续...

此任务是否可以与其他定期检查批量处理？
  是 -> 使用 heartbeat（添加到 HEARTBEAT.md）
  否 -> 使用 cron

这是否是一次性提醒？
  是 -> 使用 cron 配合 --at
  否 -> 继续...

是否需要不同的模型或思考级别？
  是 -> 使用 cron（isolated）配合 --model/--thinking
  否 -> 使用 heartbeat

结合使用两者

最高效的设置是同时使用两者：

Heartbeat 处理日常监控（收件箱、日历、通知），每 30 分钟批量处理一次。
Cron 处理精确调度（每日报告、每周回顾）和一次性提醒。

示例：高效自动化设置

HEARTBEAT.md（每 30 分钟检查）：

# Heartbeat checklist
- Scan inbox for urgent emails
- Check calendar for events in next 2h
- Review any pending tasks
- Light check-in if quiet for 8+ hours

Cron 任务（精确计时）：

bash

# 每日上午 7 点早间简报
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --deliver

# 每周一上午 9 点项目回顾
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# 一次性提醒
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now

Lobster：具有审批功能的确定性工作流

Lobster 是用于多步骤工具管道的工作流运行时，需要确定性执行和显式审批。当任务不仅仅是单个代理轮次，并且您想要具有人工检查点的可恢复工作流时，请使用它。

何时适合使用 Lobster

多步骤自动化：您需要固定的工具调用管道，而不是一次性提示。
审批关卡：副作用应暂停直到您批准，然后继续。
可恢复运行：继续暂停的工作流而无需重新运行早期步骤。

如何与心跳和 Cron 配合使用

Heartbeat/cron 决定何时运行。
Lobster 定义运行开始后执行哪些步骤。

对于计划工作流，使用 cron 或 heartbeat 触发调用 Lobster 的代理轮次。对于临时工作流，直接调用 Lobster。

操作说明（来自代码）

Lobster 作为本地子进程（lobster CLI）在工具模式下运行，并返回JSON 信封。
如果工具返回 needs_approval，您可以使用 resumeToken 和 approve 标志恢复。
该工具是可选插件；通过 tools.alsoAllow: ["lobster"] 启用（推荐）。
如果传递 lobsterPath，它必须是绝对路径。

完整用法和示例请参阅 Lobster。

主会话 vs 隔离会话

心跳和 Cron 都可以与主会话交互，但方式不同：

	Heartbeat	Cron（main）	Cron（isolated）
会话	主会话	主会话（通过系统事件）	`cron:<jobId>`
历史记录	共享	共享	每次运行都是新的
上下文	完整	完整	无（从头开始）
模型	主会话模型	主会话模型	可以覆盖
输出	如果不是 `HEARTBEAT_OK` 则发送	心跳提示 + 事件	摘要发布到主会话

何时使用主会话 Cron

当您希望以下情况时，使用 --session main 配合 --system-event：

提醒/事件出现在主会话上下文中
代理在下一个心跳时处理它，具有完整上下文
没有单独的隔离运行

bash

openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

何时使用隔离 Cron

当您希望以下情况时，使用 --session isolated：

没有先前上下文的干净状态
不同的模型或思考设置
输出直接发送到频道（默认情况下摘要仍会发布到主会话）
不会混乱主会话历史记录的历史记录

bash

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --deliver

成本考虑

机制	成本概况
Heartbeat	每 N 分钟一个轮次；随 HEARTBEAT.md 大小扩展
Cron（main）	将事件添加到下一个心跳（无隔离轮次）
Cron（isolated）	每个任务完整的代理轮次；可以使用更便宜的模型

提示：

保持 HEARTBEAT.md 较小以最小化令牌开销。
将类似检查批量处理到心跳中，而不是多个 Cron 任务。
如果只需要内部处理，在心跳上使用 target: "none"。
对于日常任务，使用更便宜模型的隔离 Cron。

Cron vs Heartbeat：何时使用哪个 ​

快速决策指南 ​

Heartbeat：定期感知 ​

何时使用心跳 ​

心跳优势 ​

心跳示例：HEARTBEAT.md 检查清单 ​

配置心跳 ​

Cron：精确调度 ​

何时使用 Cron ​

Cron 优势 ​

Cron 示例：每日早间简报 ​

Cron 示例：一次性提醒 ​

决策流程图 ​

结合使用两者 ​

示例：高效自动化设置 ​

Lobster：具有审批功能的确定性工作流 ​

何时适合使用 Lobster ​

如何与心跳和 Cron 配合使用 ​

操作说明（来自代码） ​

主会话 vs 隔离会话 ​

何时使用主会话 Cron ​

何时使用隔离 Cron ​

成本考虑 ​

相关链接 ​

Cron vs Heartbeat：何时使用哪个

快速决策指南

Heartbeat：定期感知

何时使用心跳

心跳优势

心跳示例：HEARTBEAT.md 检查清单

配置心跳

Cron：精确调度

何时使用 Cron

Cron 优势

Cron 示例：每日早间简报

Cron 示例：一次性提醒

决策流程图

结合使用两者

示例：高效自动化设置

Lobster：具有审批功能的确定性工作流

何时适合使用 Lobster

如何与心跳和 Cron 配合使用

操作说明（来自代码）

主会话 vs 隔离会话

何时使用主会话 Cron

何时使用隔离 Cron

成本考虑

相关链接