Cron vs Heartbeat：何时使用哪个

适用场景

在以下情况使用本页面：

• 决定如何调度重复任务
• 设置后台监控或通知
• 优化定期检查的 Token 使用

心跳和 cron 定时任务都可以让您按计划运行任务。本指南帮助您为您的用例选择正确的机制。

快速决策指南

心跳：定期感知

心跳在主会话中以固定间隔运行（默认：30 分钟）。它们旨在让 Agent 检查事物并暴露任何重要内容。

何时使用心跳

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

心跳优势

• 批量处理多个检查：一个 Agent 轮次可以一起检查收件箱、日历和通知。
• 减少 API 调用：单个心跳比 5 个隔离的 cron 任务更便宜。
• 上下文感知：Agent 知道您一直在做什么，并可以相应地确定优先级。
• 智能抑制：如果不需要注意，Agent 会回复 HEARTBEAT_OK 并且不会投递消息。
• 自然计时：基于队列负载略微漂移，这对于大多数监控来说是可以的。

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

# 心跳检查清单

- 检查电子邮件中的紧急消息
- 查看未来 2 小时内的日历事件
- 如果后台任务完成，总结结果
- 如果空闲 8 小时以上，发送简短的检查

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

配置心跳

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

完整配置参见 Heartbeat。

Cron：精确调度

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

何时使用 cron

• 需要精确时间：“每周一上午 9:00 发送此消息”（而不是"9 点左右"）。
• 独立任务：不需要对话上下文的任务。
• 不同的模型/思考：值得使用更强大模型的繁重分析。
• 一次性提醒：使用 --at “在 20 分钟后提醒我”。
• 嘈杂/频繁任务：会弄乱主会话历史的任务。
• 外部触发器：无论 Agent 是否 otherwise 活动都应独立运行的任务。

Cron 优势

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

Cron 示例：每日早间简报

moltbot cron add \
  --name "早间简报" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "生成今天的简报：天气、日历、热门邮件、新闻摘要。" \
  --model opus \
  --deliver \
  --channel whatsapp \
  --to "+15551234567"

这在纽约时间上午 7:00 准确运行，使用 Opus 保证质量，并直接投递到 WhatsApp。

Cron 示例：一次性提醒

moltbot cron add \
  --name "会议提醒" \
  --at "20m" \
  --session main \
  --system-event "提醒：站立会议在 10 分钟后开始。" \
  --wake now \
  --delete-after-run

完整的 CLI 参考参见 Cron 定时任务。

决策流程图

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

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

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

这是一次性提醒吗？
  是 -> 使用带有 --at 的 cron
  否  -> 继续...

它需要不同的模型或思考级别吗？
  是 -> 使用带有 --model/--thinking 的 cron（隔离）
  否  -> 使用心跳

结合使用两者

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

1. 心跳处理例行监控（收件箱、日历、通知），每 30 分钟批量处理一轮。
2. Cron处理精确调度（每日报告、每周审查）和一次性提醒。

示例：高效的自动化设置

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

# 心跳检查清单
- 扫描收件箱中的紧急邮件
- 查看未来 2 小时内的日历事件
- 查看任何待处理的任务
- 如果 8 小时以上安静，则进行轻度检查

Cron 定时任务（精确时间）：

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

# 上午 9 点的每周项目审查
moltbot cron add --name "每周审查" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# 一次性提醒
moltbot cron add --name "回电" --at "2h" --session main --system-event "回电给客户" --wake now

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

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

Lobster 的适用场景

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

它如何与心跳和 cron 配对

• 心跳/cron 决定运行何时发生。
• Lobster 定义一旦运行开始发生什么步骤。

对于调度的工作流，使用 cron 或心跳触发调用 Lobster 的 Agent 轮次。 对于临时工作流，直接调用 Lobster。

操作说明（来自代码）

• Lobster 作为本地子进程（lobster CLI）在工具模式下运行，并返回 JSON 信封。
• 如果工具返回 needs_approval，您使用 resumeToken 和 approve 标志恢复。
• 该工具是可选插件；您必须在 tools.allow 中将 lobster 列入允许列表。
• 如果您传递 lobsterPath，它必须是绝对路径。

完整用法和示例参见 Lobster。

主会话 vs 隔离会话

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

何时使用主会话 cron

当您想要以下内容时，使用 --session main 和 --system-event：

• 提醒/事件出现在主会话上下文中
• Agent 在下一次心跳时使用完整上下文处理它
• 没有单独的隔离运行

moltbot cron add \
  --name "检查项目" \
  --every "4h" \
  --session main \
  --system-event "到了项目健康检查的时候" \
  --wake now

何时使用隔离 cron

当您想要以下内容时，使用 --session isolated：

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

moltbot cron add \
  --name "深度分析" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "每周代码库分析..." \
  --model opus \
  --thinking high \
  --deliver

成本考虑

提示：

• 保持 HEARTBEAT.md 小以最小化 Token 开销。
• 将类似的检查批量处理到心跳中，而不是多个 cron 任务。
• 如果您只想要内部处理，请在心跳上使用 target: "none"。
• 对例行任务使用带有更便宜模型的隔离 cron。

相关

• Heartbeat - 完整的心跳配置
• Cron 定时任务 - 完整的 cron CLI 和 API 参考
• System - 系统事件 + 心跳控制