自动化与定时任务：Heartbeat 与 Cron 🟡

OpenClaw 不只是一个被动的"问答机器人"，它还可以主动执行任务。本章讲解两种自动化机制：Heartbeat（心跳）和 Cron（定时任务）。

本章目标

读完本章你将能够：

• 理解 Heartbeat 的工作原理（HEARTBEAT.md 驱动的主动触发）
• 掌握 Cron 任务的三种调度方式（at / every / cron）
• 理解定时任务的 Payload 类型和 Delivery 策略
• 实现常见自动化场景（每日报告、定时提醒等）

一、Heartbeat：主动触发的 AI

Heartbeat 是什么？

Heartbeat 是一种让 AI 定期自主检查任务并采取行动的机制，默认每 30 分钟触发一次。

每次心跳，AI 会：

1. 读取 HEARTBEAT.md 文件（如果存在）
2. 按文件中的指令执行操作
3. 如果没有需要处理的事项，回复 HEARTBEAT_OK 并静默（不推送给用户）

HEARTBEAT.md 示例

<!-- HEARTBEAT.md -->

# AI 助手任务清单

## 持续监控
- [ ] 检查 /logs/app.log 是否有新的 ERROR 级别日志
  - 如有：汇总并推送给用户
- [ ] 检查 ~/Downloads 目录是否有新文件
  - 如有：整理分类到对应目录

## 早上任务（每天 9:00 后首次心跳）
- [ ] 拉取 git 仓库最新状态
- [ ] 生成昨日工作摘要

## 待处理
- [ ] 审核 PR #42 的代码

Heartbeat 触发流程

flowchart TB
    TIMER["计时器到期\n（默认 30 分钟）"]
    READ["读取 HEARTBEAT.md"]
    CHECK{"内容是否\n有效为空？"}
    SKIP["跳过（不调用 LLM）"]
    CALL["调用 LLM\n（带 HEARTBEAT_PROMPT）"]
    REPLY{"AI 回复是否\n包含 HEARTBEAT_OK？"}
    SILENT["静默（不推送给用户）"]
    PUSH["推送给用户"]

    TIMER --> READ
    READ --> CHECK
    CHECK -->|"是（空文件）"| SKIP
    CHECK -->|"否"| CALL
    CALL --> REPLY
    REPLY -->|"是"| SILENT
    REPLY -->|"否"| PUSH

Heartbeat 配置

# config.yaml
agents:
  list:
    - id: main
      heartbeat:
        enabled: true
        every: "30m"        # 触发间隔
        prompt: |           # 自定义提示（覆盖默认 HEARTBEAT_PROMPT）
          Check HEARTBEAT.md and complete pending tasks.
          Be concise when reporting.

HEARTBEAT_PROMPT（默认值）：

Read HEARTBEAT.md if it exists (workspace context). Follow it strictly.
Do not infer or repeat old tasks from prior chats.
If nothing needs attention, reply HEARTBEAT_OK.

二、Cron：精确的定时任务系统

Cron 是比 Heartbeat 更精确的定时任务系统，支持在特定时间或特定间隔触发 AI 任务。

三种调度方式

// cron-tool.ts 中定义的调度类型
type CronScheduleKind = 'at' | 'every' | 'cron';

// 'at'：在特定时间点执行（一次性）
{ kind: 'at', at: '2024-03-15T09:00:00Z' }

// 'every'：按固定间隔循环执行
{ kind: 'every', everyMs: 60 * 60 * 1000 }  // 每小时

// 'cron'：使用 cron 表达式（最灵活）
{ kind: 'cron', expr: '0 9 * * 1-5' }  // 工作日每天 9:00

Cron 任务的 Payload 类型

每个定时任务触发时执行什么，由 payload 字段决定：

// agentTurn 示例：让 AI 每天早上生成日报
{
  kind: 'agentTurn',
  message: '请生成昨日工作摘要，包含完成的任务和待处理事项。',
  model: 'claude-opus-4-5',        // 可以覆盖默认模型
  timeoutSeconds: 120,              // 超时时间
  lightContext: true,               // 使用轻量上下文（不加载会话历史）
}

Cron 任务的 Delivery 策略

执行结果如何传递给用户，由 delivery 字段控制：

# 配置示例：每天早 9 点生成日报并推送到 Telegram
cron:
  jobs:
    - name: daily-report
      schedule:
        kind: cron
        expr: "0 9 * * *"    # 每天 9:00
      payload:
        kind: agentTurn
        message: "生成今日工作计划摘要"
      delivery:
        mode: announce        # 推送到关联会话

三、通过 AI 工具管理 Cron 任务

Agent 可以通过内置的 cron 工具在对话中直接管理定时任务：

用户："帮我每小时检查一下系统内存使用情况，如果超过 80% 就提醒我"

Agent 调用 cron 工具：
cron({
  action: 'add',
  name: 'memory-check',
  schedule: { kind: 'every', everyMs: 3600000 },
  payload: {
    kind: 'agentTurn',
    message: '检查系统内存使用率，如超过80%向用户发出警告'
  },
  delivery: { mode: 'announce' }
})

Cron 工具支持的操作（CRON_ACTIONS）：

四、任务注册表（Task Registry）

src/tasks/ 目录实现了完整的任务状态机，追踪每个定时任务的执行历史。

stateDiagram-v2
    [*] --> pending: 任务创建
    pending --> running: 开始执行
    running --> completed: 执行成功
    running --> failed: 执行失败
    running --> timeout: 超时
    completed --> [*]
    failed --> pending: 重试
    timeout --> failed

每次执行都有 TaskRecord：

type TaskRecord = {
  taskId: string;          // 任务唯一 ID
  runId: string;           // 本次运行 ID（同一任务多次运行有不同 runId）
  status: TaskStatus;      // 'pending' | 'running' | 'completed' | 'failed' | 'timeout'
  createdAt: Date;
  startedAt?: Date;
  completedAt?: Date;
  deliveryStatus: TaskDeliveryStatus; // 结果是否已投递给用户
  runtime: 'acp' | 'subagent';       // 执行运行时类型
};

五、使用场景举例

场景 1：每日晨报

# 每天工作日 8:30 生成晨报
cron:
  jobs:
    - name: morning-briefing
      schedule:
        kind: cron
        expr: "30 8 * * 1-5"  # 工作日早 8:30
      payload:
        kind: agentTurn
        message: |
          生成今日晨报：
          1. 今日天气
          2. 昨天的未完成任务
          3. 今天的重要日程（从 HEARTBEAT.md 读取）
      delivery:
        mode: announce

场景 2：长期文件监控

在 HEARTBEAT.md 中：

## 监控任务
- [ ] 检查 ~/project/logs/error.log，如有新错误行，汇总后通知我
- [ ] 如果 ~/Downloads 下有超过 7 天的文件，提示我清理

Heart beat 每 30 分钟检查一次，有新情况才推送通知。

关键源码索引

小结

1. Heartbeat 是"主动检查"：AI 定期读取 HEARTBEAT.md，有任务则执行，否则静默。
2. HEARTBEAT_OK 机制：AI 无事可做时回复特定 token，框架自动过滤，不打扰用户。
3. Cron 支持三种调度：at（指定时刻）、every（固定间隔）、cron（cron 表达式）。
4. 两种 Payload：agentTurn（AI 推理任务）和 systemEvent（系统触发）。
5. Agent 可以管理 Cron：用户通过对话就能创建/修改/删除定时任务，无需修改配置文件。

← Agent 作用域与上下文 | → 编写渠道插件