> ## Documentation Index
> Fetch the complete documentation index at: https://clawdbot.openclaw-doc-zh.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cron 与 Heartbeat

# Cron 与 Heartbeat：何时使用

心跳（heartbeat）与 cron 都可以按计划运行任务。本指南帮助你在具体场景中做选择。

## 快速决策指南

| 场景           | 推荐               | 原因               |
| ------------ | ---------------- | ---------------- |
| 每 30 分钟检查收件箱 | Heartbeat        | 可与其他检查批处理，且具备上下文 |
| 早上 9 点准时发送日报 | Cron（隔离）         | 需要精确时间           |
| 监控日历即将到来的事件  | Heartbeat        | 适合周期性意识维护        |
| 每周深度分析       | Cron（隔离）         | 独立任务，可用不同模型      |
| 20 分钟后提醒我    | Cron（主会话，`--at`） | 一次性且时间精确         |
| 后台项目健康检查     | Heartbeat        | 可与现有周期合并         |

## Heartbeat：周期性意识

心跳会在 **主会话** 中按固定间隔运行（默认 30 分钟）。它用于让代理主动检查并提示重要事项。

### 何时用心跳

* **多个周期检查**：与其设 5 个 cron 分别检查收件箱、日历、天气、通知、项目状态，不如用一次心跳批处理。
* **上下文驱动**：代理具备完整主会话上下文，能判断紧急程度。
* **对话连续性**：心跳共享同一会话，能自然跟进最近对话。
* **低开销监控**：一个心跳替代多个小轮询任务。

### 心跳优势

* **批处理多个检查**：一次代理回合可同时查看收件箱、日历和通知。
* **减少 API 调用**：一次心跳比 5 个隔离 cron 便宜。
* **上下文感知**：代理了解你在做什么并能优先级排序。
* **智能抑制**：若无关注事项，代理返回 `HEARTBEAT_OK`，不会投递消息。
* **自然时间**：会随着队列负载略有漂移，但对大多数监控无影响。

### 心跳示例：HEARTBEAT.md 清单

```md theme={null}
# 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 theme={null}
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // interval
        target: "last", // where to deliver alerts
        activeHours: { start: "08:00", end: "22:00" }, // optional
      },
    },
  },
}
```

完整配置见 [Heartbeat](/docs/gateway/heartbeat)。

## Cron：精确调度

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

### 何时用 cron

* **需要精确时间**：比如“每周一 9:00 发送”。
* **独立任务**：不需要对话上下文。
* **不同模型/思考**：重分析可用更强模型。
* **一次性提醒**：用 `--at`。
* **噪声高/频繁任务**：避免污染主会话历史。
* **外部触发**：任务需要独立于代理活跃状态运行。

### Cron 优势

* **精确时间**：5 字段 cron 表达式 + 时区支持。
* **会话隔离**：在 `cron:<jobId>` 中运行，不污染主历史。
* **模型覆盖**：每个任务可选更便宜或更强模型。
* **投递控制**：可直接投递到渠道；默认仍会向主会话发摘要（可配置）。
* **无需主会话上下文**：即使主会话闲置或已压缩也能运行。
* **一次性支持**：`--at` 指定精确未来时间戳。

### Cron 示例：每日早报

```bash theme={null}
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 theme={null}
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](/docs/automation/cron-jobs)。

## 决策流程图

```
Does the task need to run at an EXACT time?
  YES -> Use cron
  NO  -> Continue...

Does the task need isolation from main session?
  YES -> Use cron (isolated)
  NO  -> Continue...

Can this task be batched with other periodic checks?
  YES -> Use heartbeat (add to HEARTBEAT.md)
  NO  -> Use cron

Is this a one-shot reminder?
  YES -> Use cron with --at
  NO  -> Continue...

Does it need a different model or thinking level?
  YES -> Use cron (isolated) with --model/--thinking
  NO  -> Use heartbeat
```

## 组合使用

最高效的配置往往是 **两者搭配**：

1. **Heartbeat** 处理常规监控（收件箱、日历、通知），每 30 分钟一次合并处理。
2. **Cron** 处理精确调度（日报、周报）与一次性提醒。

### 示例：高效自动化配置

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

```md theme={null}
# 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 theme={null}
# Daily morning briefing at 7am
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --deliver

# Weekly project review on Mondays at 9am
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# One-shot reminder
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 envelope**。
* 工具返回 `needs_approval` 时，用 `resumeToken` + `approve` 继续。
* 该工具为 **可选插件**；建议通过 `tools.alsoAllow: ["lobster"]` 启用。
* 如果传入 `lobsterPath`，必须是 **绝对路径**。

详见 [Lobster](/docs/tools/lobster)。

## 主会话 vs 隔离会话

心跳与 cron 都会与主会话产生交互，但方式不同：

|     | Heartbeat            | Cron（主会话）  | Cron（隔离）       |
| --- | -------------------- | ---------- | -------------- |
| 会话  | 主会话                  | 主会话（系统事件）  | `cron:<jobId>` |
| 历史  | 共享                   | 共享         | 每次新建           |
| 上下文 | 完整                   | 完整         | 无（全新）          |
| 模型  | 主会话模型                | 主会话模型      | 可覆盖            |
| 输出  | 非 `HEARTBEAT_OK` 时投递 | 心跳提示词 + 事件 | 向主会话发摘要        |

### 何时使用主会话 cron

在你希望以下行为时，使用 `--session main` + `--system-event`：

* 提醒/事件出现在主会话上下文中
* 代理在下一次心跳里用完整上下文处理
* 不产生独立隔离运行

```bash theme={null}
openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now
```

### 何时使用隔离 cron

当你需要：

* 无历史上下文的干净环境
* 不同的模型或思考设置
* 输出直接投递到渠道（默认仍会向主会话发摘要）
* 不污染主会话历史的运行记录

```bash theme={null}
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（主会话） | 向下一次心跳添加事件（无隔离回合）                |
| Cron（隔离）  | 每个任务完整代理回合；可用更便宜模型               |

**建议**：

* 保持 `HEARTBEAT.md` 简洁，降低 token 开销。
* 把类似检查合并进心跳，而非多个 cron 任务。
* 若只需内部处理，心跳可用 `target: "none"`。
* 日常任务可用更便宜模型的隔离 cron。

## 相关内容

* [Heartbeat](/docs/gateway/heartbeat) - 完整心跳配置
* [Cron jobs](/docs/automation/cron-jobs) - 完整 cron CLI 与 API 参考
* [System](/docs/cli/system) - 系统事件与心跳控制