心跳和 cron 任务都允许你按计划运行任务。本指南将帮助你根据用例选择合适的机制。

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

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

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

# 心跳清单

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

Agent 在每次心跳时读取此清单，并在一个回合内处理所有项。

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

请参阅 心跳 (Heartbeat) 以获取完整配置。

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

• 需要精确的时间：“每周一早上 9:00 发送这个”（而不是“9 点左右”）。
• 独立任务：不需要对话上下文的任务。
• 不同的模型/思考等级：需要更强大模型进行繁重分析的任务。
• 一次性提醒：使用 --at 实现“20 分钟后提醒我”。
• 嘈杂/频繁的任务：会干扰主会话历史的任务。
• 外部触发：应独立于 Agent 是否处于活跃状态而运行的任务。

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

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

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

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

请参阅 Cron 任务 以获取完整的 CLI 参考。

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

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

此任务是否可以与其他周期性检查合并？
  是 -> 使用心跳 (添加到 HEARTBEAT.md)
  否 -> 使用 cron

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

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

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

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

HEARTBEAT.md (每 30 分钟检查一次):

# 心跳清单

- 扫描收件箱是否有紧急邮件
- 检查日历中未来 2 小时内的事件
- 查看任何待办任务
- 如果空闲超过 8 小时，发送简短的问候

Cron 任务 (精确的时间):

# 每天早上 7 点的晨间简报
openclaw cron add --name "晨报" --cron "0 7 * * *" --session isolated --message "..." --deliver

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

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

Lobster 是用于需要确定性执行和显式审批的多步工具流水线的工作流运行时。 当任务不仅仅是单个 Agent 回合，且你想要一个带有关键人工检查点的可恢复工作流时，请使用它。

• 多步自动化：你需要固定的工具调用流水线，而不是一次性的提示。
• 审批门禁：副作用应暂停直到你批准，然后恢复。
• 可恢复的运行：继续已暂停的工作流，而无需重新运行前面的步骤。

• 心跳/cron 决定运行产生的时间。
• Lobster 定义运行开始后的执行步骤。

对于调度的任务流，使用 cron 或心跳触发一个调用 Lobster 的 Agent 回合。 对于临时任务流，直接调用 Lobster。

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

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

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

当你希望满足以下条件时，使用带有 --system-event 的 --session main：

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

openclaw cron add \
  --name "检查项目" \
  --every "4h" \
  --session main \
  --system-event "是时候进行项目健康检查了" \
  --wake now

当你希望满足以下条件时，使用 --session isolated：

• 一个没有任何先前上下文的空白状态
• 不同的模型或思考等级设置
• 输出直接投递到频道（默认情况下摘要仍会发布到主会话）
• 不干扰主会话历史的历史记录

openclaw 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) - 系统事件 + 心跳控制