Cron vs Heartbeat：何时使用哪个

Heartbeat 和 Cron 任务都能让你按计划运行任务。本指南帮你根据使用场景选择合适的机制。

快速决策指南

Heartbeat：周期性感知

Heartbeat 在主 Session 中按固定间隔运行（默认：30 分钟）。它的设计目的是让 Agent 定期检查事项并浮现重要信息。

何时使用 Heartbeat

• 多个周期性检查：不需要 5 个独立的 Cron 任务分别检查收件箱、日历、天气、通知和项目状态，一个 Heartbeat 就能批量处理所有这些。
• 上下文感知决策：Agent 拥有完整的主 Session 上下文，因此能智能判断什么紧急、什么可以等待。
• 对话连续性：Heartbeat 运行共享同一个 Session，所以 Agent 记得最近的对话，能自然地跟进。
• 低开销监控：一个 Heartbeat 替代许多小型轮询任务。

Heartbeat 的优势

• 批量处理多个检查：一次 Agent 回合可以一起审查收件箱、日历和通知。
• 减少 API 调用：单个 Heartbeat 比 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 时读取这个清单，并在一个回合中处理所有项目。

配置 Heartbeat

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

完整配置请参阅 Heartbeat。

Cron：精确调度

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

何时使用 Cron

• 需要精确时间：“每周一早上 9:00 发送”（不是”9 点左右”）。
• 独立任务：不需要对话上下文的任务。
• 不同模型/思考：需要更强大模型的重度分析。
• 单次提醒：“20 分钟后提醒我”，使用 --at。
• 嘈杂/频繁的任务：会让主 Session 历史变得混乱的任务。
• 外部触发：应该独立于 Agent 是否活跃而运行的任务。

Cron 的优势

• 精确时间：5 字段 Cron 表达式，支持时区。
• Session 隔离：在 cron:<jobId> 中运行，不污染主历史记录。
• 模型覆盖：每个任务可使用更便宜或更强大的模型。
• 发送控制：可以直接发送到 Channel；默认仍会向主 Session 发送摘要（可配置）。
• 不需要 Agent 上下文：即使主 Session 空闲或已压缩也能运行。
• 单次支持：--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 \
  --deliver \
  --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
  否 -> 继续...

任务需要与主 Session 隔离吗？
  是 -> 使用 Cron (isolated)
  否 -> 继续...

这个任务可以与其他周期性检查批量处理吗？
  是 -> 使用 Heartbeat（添加到 HEARTBEAT.md）
  否 -> 使用 Cron

这是单次提醒吗？
  是 -> 使用 Cron 配合 --at
  否 -> 继续...

需要不同的模型或思考级别吗？
  是 -> 使用 Cron (isolated) 配合 --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 "..." --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 是用于多步骤工具管道的工作流运行时，需要确定性执行和显式审批。 当任务不止一个 Agent 回合，并且你想要一个可恢复的工作流和人工检查点时，使用它。

何时适合 Lobster

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

它如何与 Heartbeat 和 Cron 配合

• Heartbeat/Cron 决定_何时_运行。
• Lobster 定义运行开始后_发生什么步骤_。

对于计划的工作流，使用 Cron 或 Heartbeat 触发调用 Lobster 的 Agent 回合。 对于临时工作流，直接调用 Lobster。

操作说明（来自代码）

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

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

主 Session vs 隔离 Session

Heartbeat 和 Cron 都可以与主 Session 交互，但方式不同：

何时使用主 Session Cron

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

• 提醒/事件出现在主 Session 上下文中
• Agent 在下一次 Heartbeat 期间用完整上下文处理它
• 没有单独的隔离运行

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

何时使用隔离 Cron

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

• 没有先前上下文的干净状态
• 不同的模型或思考设置
• 输出直接发送到 Channel（摘要默认仍会发送到主 Session）
• 不让主 Session 历史变得混乱

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

成本考虑

提示：

• 保持 HEARTBEAT.md 小巧以最小化 Token 开销。
• 将类似的检查批量放入 Heartbeat，而不是多个 Cron 任务。
• 如果只想要内部处理，在 Heartbeat 上使用 target: "none"。
• 对常规任务使用隔离 Cron 配合更便宜的模型。

相关内容

• Heartbeat - 完整 Heartbeat 配置
• Cron 任务 - 完整 Cron CLI 和 API 参考
• System - 系统事件 + Heartbeat 控制