Cron 与 Heartbeat：怎么选

心跳和定时任务都能按计划执行工作。这份指南帮你根据场景选对机制。

快速决策表

场景推荐方式原因
每 30 分钟检查收件箱Heartbeat可以和其他检查合批，有上下文感知
每天早上 9 点准时发报告Cron（隔离模式）需要精确时间
监控日历里即将到来的事件Heartbeat天然适合周期性感知
每周做一次深度分析Cron（隔离模式）独立任务，可以用不同的模型
20 分钟后提醒我Cron（主会话，--at）一次性精确定时
后台项目健康检查Heartbeat搭现有周期的顺风车

Heartbeat：周期性感知

心跳在主会话中以固定间隔运行（默认 30 分钟）。它的设计目的是让 agent 定期检查各类事项，有重要的就浮出来。

什么时候用 heartbeat

  • 多项周期检查：与其搞 5 个独立的 cron 任务分别查收件箱、日历、天气、通知和项目状态，不如一次心跳全搞定。
  • 需要上下文判断：agent 有完整的主会话上下文，能聪明地判断什么紧急什么可以缓。
  • 对话连续性：心跳运行共享同一个会话，agent 记得最近的对话，跟进起来很自然。
  • 轻量监控：一次心跳替代一堆小轮询任务。

Heartbeat 的优势

  • 合批多项检查：一次 agent 轮次就能查收件箱、日历和通知。
  • 省 API 调用：一次心跳比 5 个隔离 cron 任务便宜。
  • 有上下文：agent 知道你在忙什么，据此设优先级。
  • 智能静默：如果没什么需要关注的，agent 回复 HEARTBEAT_OK，不发消息打扰你。
  • 自然时序：会因队列负载略有漂移，但大多数监控场景完全够用。

Heartbeat 示例：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

agent 每次心跳时读这个清单，一个轮次把所有项目处理完。

配置 heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 间隔
        target: "last", // 显式告警投递目标（默认 "none"）
        activeHours: { start: "08:00", end: "22:00" }, // 可选
      },
    },
  },
}

完整配置见 Heartbeat。

Cron：精确调度

Cron 任务在精确时间点执行，可以在隔离会话中运行而不影响主上下文。循环的整点调度会自动在 0-5 分钟窗口内施加确定性偏移。

什么时候用 cron

  • 需要精确时间：“每周一早上 9:00 发”（不是”大约 9 点左右”）。
  • 独立任务：不需要对话上下文的工作。
  • 不同的模型/思考级别：需要更强模型的重度分析。
  • 一次性提醒：“20 分钟后提醒我”，用 --at。
  • 嘈杂/高频任务：会把主会话历史搞乱的那种。
  • 外部触发：不管 agent 是否活跃都要独立运行的任务。

Cron 的优势

  • 精确时序：5 字段或 6 字段（含秒）cron 表达式，支持时区。
  • 内置负载均衡：循环的整点调度默认偏移最多 5 分钟。
  • 逐任务控制：用 --stagger <duration> 覆盖偏移，或用 --exact 强制精确执行。
  • 会话隔离：在 cron:<jobId> 中运行，不污染主历史。
  • 模型覆盖：每个任务可以用更便宜或更强的模型。
  • 投递控制：隔离任务默认 announce（摘要）；按需选 none。
  • 即时投递：announce 模式直接发送，不用等心跳。
  • 不依赖 agent 上下文：主会话空闲或压缩了也能跑。
  • 一次性支持：--at 指定精确的未来时间戳。

Cron 示例：每日早间简报

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 \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

这个任务在纽约时间早上 7:00 精确执行，用 Opus 保证质量，把摘要直接播报到 WhatsApp。

Cron 示例：一次性提醒

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
  否 -> 继续...

任务需要和主会话隔离吗？
  是 -> 用 cron（隔离模式）
  否 -> 继续...

这个任务能和其他周期检查合批吗？
  能 -> 用 heartbeat（加到 HEARTBEAT.md 里）
  不能 -> 用 cron

这是一次性提醒吗？
  是 -> 用 cron 加 --at
  否 -> 继续...

需要用不同的模型或思考级别吗？
  是 -> 用 cron（隔离模式）加 --model/--thinking
  否 -> 用 heartbeat

两者搭配使用

最高效的方案是两个都用：

  1. Heartbeat 处理日常监控（收件箱、日历、通知），每 30 分钟一次合批轮次。
  2. 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 任务（精确时序）：

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

# 每周一早上 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 是多步骤工具管线的工作流运行时，适合需要确定性执行和显式审批的场景。当任务不止一个 agent 轮次，且你想要一个可恢复的、有人工检查点的工作流时，就该用 Lobster。

适用场景

  • 多步骤自动化：你需要一个固定的工具调用管线，不是一次性提示。
  • 审批卡口：副作用操作应该暂停等你确认，然后再继续。
  • 可恢复运行：能从暂停的地方继续，不用重跑前面的步骤。

和 heartbeat、cron 的配合

  • Heartbeat/cron 决定 什么时候 触发运行。
  • Lobster 定义运行开始后 执行哪些步骤。

对定时工作流，用 cron 或 heartbeat 触发一个 agent 轮次来调用 Lobster。临时工作流直接调 Lobster 就行。

运行机制说明

  • Lobster 作为本地子进程（lobster CLI）以工具模式运行，返回 JSON 信封。
  • 如果工具返回 needs_approval，你用 resumeToken 和 approve 标志来恢复。
  • 这个工具是可选插件；通过 tools.alsoAllow: ["lobster"] 增量启用（推荐方式）。
  • Lobster 需要 lobster CLI 在 PATH 中可用。

完整用法和示例见 Lobster。

主会话 vs 隔离会话

heartbeat 和 cron 都能与主会话交互，但方式不同：

HeartbeatCron（主会话）Cron（隔离模式）
会话主会话主会话（通过系统事件）cron:<jobId>
历史共享共享每次运行全新
上下文完整完整无（干净启动）
模型主会话模型主会话模型可覆盖
输出非 HEARTBEAT_OK 时投递心跳提示词 + 事件播报摘要（默认）

何时用主会话 cron

当你需要以下效果时，用 --session main 配合 --system-event：

  • 提醒/事件出现在主会话上下文中
  • agent 在下次心跳时带着完整上下文处理
  • 不要单独的隔离运行
openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

何时用隔离 cron

当你需要以下效果时，用 --session isolated：

  • 干净的环境，没有之前的上下文
  • 不同的模型或思考设置
  • 摘要直接播报到频道
  • 历史不要污染主会话
openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --announce

成本考量

机制成本特征
Heartbeat每 N 分钟一个轮次；开销随 HEARTBEAT.md 大小增长
Cron（主会话）在下次心跳中加一个事件（不产生隔离轮次）
Cron（隔离模式）每个任务一个完整 agent 轮次；可以用更便宜的模型

省钱建议：

  • HEARTBEAT.md 保持精简，减少 token 开销。
  • 相似的检查合批到 heartbeat 里，别搞多个 cron 任务。
  • heartbeat 如果只需要内部处理，用 target: "none"。
  • 隔离 cron 搭配便宜模型处理常规任务。

相关文档

arrow_back
上一页
Cron Jobs
下一页
Troubleshooting
arrow_forward