摘要：什么是 OpenClaw 的 Heartbeat 机制？

OpenClaw 的 Heartbeat（心跳）机制 是一种在主会话中定期运行代理任务的自动化方式，让 AI 助手能够主动检查并提醒你需要关注的事情，而不会频繁打扰你。它的核心目标是将多个周期性检查任务（如收件箱、日历、天气、通知等）批量处理，利用主会话的完整上下文做出智能决策，同时通过 HEARTBEAT_OK 机制在无需关注时保持静默。

一、 理解背景：为什么需要 Heartbeat？

在使用 AI 助手时，我们经常会遇到这样的场景：需要定期检查某些事情（比如收件箱有没有紧急邮件、日历有没有即将到来的会议、天气是否需要带伞），但又不想为此创建一堆独立的定时任务，也不想被频繁的通知打扰。

让我们看看几种常见的自动化方式以及它们的局限：

方式一：多个独立的 Cron Job

为每个检查项创建一个单独的定时任务：

  • 每 30 分钟检查一次收件箱
  • 每 30 分钟检查一次日历
  • 每 30 分钟检查一次天气
  • 每 30 分钟检查一次项目状态

问题在哪里？

  • 资源浪费：每个 Cron Job 都是一次独立的代理运行，需要加载完整上下文，消耗大量 token。
  • 缺乏协调：多个任务各自为政，无法根据整体情况智能判断优先级。
  • 通知泛滥：如果每个任务都可能发送通知，你会被频繁打扰。

方式二：完全手动检查

什么自动化都不做，完全靠自己记得去检查：

  • 想起来的时候看看收件箱
  • 想起来的时候看看日历
  • 想起来的时候看看天气

问题在哪里？

  • 容易遗漏：人类不是机器，总会忘记检查某些事情。
  • 效率低下：需要主动花费精力去记、去检查。
  • 错失时机：重要的事情可能因为没有及时检查而被错过。

Heartbeat 机制就是为了解决这些问题而生的。

二、 Heartbeat 的核心思想

Heartbeat 的核心思想可以概括为：在主会话中定期批量处理多个检查任务，利用完整上下文智能决策，无需关注时保持静默。

  • “Heartbeat”（心跳）：指定期触发的代理运行，就像心跳一样有规律。
  • “主会话”：Heartbeat 运行在你的主会话中，拥有完整的对话历史和上下文。
  • “批量处理”：一次 Heartbeat 可以处理多个检查项（收件箱、日历、天气等）。
  • “智能决策”：利用主会话的上下文，判断什么是紧急的、什么可以等待。
  • “静默机制”：如果没有需要关注的事情，回复 HEARTBEAT_OK，不会发送任何通知。

三、 Heartbeat 的工作原理

让我们详细了解 Heartbeat 是如何工作的：

1. 定期触发

Heartbeat 按照配置的间隔定期触发（默认是 30 分钟）。你可以通过配置调整这个间隔：

1
2
3
4
5
6
7
8
9
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 每 30 分钟运行一次
      },
    },
  },
}

2. 发送默认提示词

触发后，OpenClaw 会向代理发送默认的 Heartbeat 提示词：

1
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.

这个提示词的意思是：

  • 如果工作区中存在 HEARTBEAT.md 文件，读取它并严格遵循
  • 不要推断或重复之前对话中的旧任务
  • 如果没有需要关注的事情，回复 HEARTBEAT_OK

你也可以自定义这个提示词：

1
2
3
4
5
6
7
8
9
{
  agents: {
    defaults: {
      heartbeat: {
        prompt: "你的自定义提示词...",
      },
    },
  },
}

3. 代理处理并回复

代理收到提示词后，会：

  1. 读取 HEARTBEAT.md（如果存在）
  2. 根据提示词和 HEARTBEAT.md 的内容进行处理
  3. 做出决策：
    • 如果有需要关注的事情：回复提醒内容（不包含 HEARTBEAT_OK）
    • 如果没有需要关注的事情：回复 HEARTBEAT_OK

4. 静默机制（HEARTBEAT_OK）

这是 Heartbeat 最关键的特性之一：

  • 如果代理回复以 HEARTBEAT_OK 开头或结尾，且剩余内容 ≤ 300 字符（可配置），OpenClaw 会：
    • 剥离 HEARTBEAT_OK 标记
    • 丢弃整条回复
    • 不发送任何通知
  • 如果代理回复的是提醒内容（不包含 HEARTBEAT_OK），OpenClaw 会正常发送通知

这样，你只会在真正需要关注的时候收到通知，不会被频繁打扰。

四、 HEARTBEAT.md：你的心跳检查清单

HEARTBEAT.md 是一个可选但强烈推荐的文件，放在你的代理工作区中。它就像是你的「心跳检查清单」，告诉代理每次 Heartbeat 时应该做什么。

为什么需要 HEARTBEAT.md？

  • 明确任务：清晰地告诉代理每次 Heartbeat 应该检查什么
  • 保持稳定：清单内容稳定，不会因为对话历史的变化而改变
  • 节省 Token：清单简短，避免提示词臃肿

HEARTBEAT.md 的例子

1
2
3
4
5
6
# Heartbeat checklist

- 快速扫描：收件箱里有没有紧急邮件？
- 检查日历：未来 2 小时内有没有即将到来的事件？
- 如果是白天，且没有其他待处理事项，做一个轻量级的问候
- 如果有任务被阻塞，记下缺少什么，下次问主人

HEARTBEAT.md 的最佳实践

  • 保持简短：只包含核心的检查项，避免提示词臃肿
  • 保持稳定：清单内容应该是相对稳定的，不需要频繁修改
  • 不要放机密信息：HEARTBEAT.md 会成为提示词的一部分，不要放 API 密钥、电话号码等私密信息

代理可以更新 HEARTBEAT.md 吗？

可以！如果你告诉代理，它可以更新 HEARTBEAT.md：

  • “更新 HEARTBEAT.md，添加每日日历检查”
  • “重写 HEARTBEAT.md，让它更简短，专注于收件箱跟进”

如果你想让这个过程自动化，也可以在 Heartbeat 提示词中明确加入：”如果清单变得过时，用更好的清单更新 HEARTBEAT.md”。

五、 Heartbeat 的配置选项

Heartbeat 提供了丰富的配置选项，让你可以根据自己的需求定制。

基本配置

1
2
3
4
5
6
7
8
9
10
11
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 间隔：30分钟
        target: "last", // 投递目标：最后使用的渠道（默认是 none）
        directPolicy: "allow", // 允许直接/私信投递（默认）
      },
    },
  },
}

高级配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        model: "anthropic/claude-opus-4-6", // 为 Heartbeat 指定不同的模型
        includeReasoning: false, // 是否包含推理过程（默认 false）
        lightContext: false, // 轻量级上下文：只保留 HEARTBEAT.md（默认 false）
        isolatedSession: false, // 隔离会话：每次运行在新会话中（默认 false）
        target: "last", // 投递目标：last | none | <渠道 id>
        to: "+15551234567", // 可选的渠道特定收件人
        accountId: "ops-bot", // 可选的多账户渠道 id
        prompt: "自定义提示词...", // 覆盖默认提示词
        ackMaxChars: 300, // HEARTBEAT_OK 后允许的最大字符数
        activeHours: { // 活跃时间窗口
          start: "08:00",
          end: "22:00",
          timezone: "Asia/Shanghai", // 可选时区
        },
      },
    },
  },
}

配置项详解

配置项 说明 默认值
every Heartbeat 间隔（时长字符串，默认单位是分钟） 30m
model 可选的模型覆盖 使用主会话模型
includeReasoning 是否包含推理过程 false
lightContext 轻量级上下文（只保留 HEARTBEAT.md） false
isolatedSession 隔离会话（每次在新会话中运行） false
target 投递目标：last|none|<渠道 id> none
directPolicy 直接/私信投递策略：allow|block allow
to 可选的渠道特定收件人 -
accountId 可选的多账户渠道 id -
prompt 覆盖默认提示词 -
ackMaxChars HEARTBEAT_OK 后允许的最大字符数 300
activeHours 活跃时间窗口（start、end、可选 timezone） -

六、 Heartbeat 的高级特性

1. 活跃时间窗口（Active Hours）

你可以限制 Heartbeat 只在特定时间窗口内运行，避免在深夜打扰你：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "08:00", // 开始时间（包含）
          end: "22:00",   // 结束时间（不包含）
          timezone: "Asia/Shanghai", // 可选时区
        },
      },
    },
  },
}

在这个时间窗口之外（比如 22:00 到第二天 08:00），Heartbeat 会被跳过，直到下一个在窗口内的时间点。

2. 24/7 运行

如果你想让 Heartbeat 全天运行，可以：

  • 完全省略 activeHours（没有时间窗口限制，这是默认行为）
  • 或者设置一个完整的全天窗口：activeHours: { start: "00:00", end: "24:00" }

注意：不要设置相同的 start 和 end 时间（比如 08:00 到 08:00），这会被视为零宽度窗口，Heartbeat 会始终被跳过。

3. 轻量级上下文（Light Context）

启用 lightContext: true 后，Heartbeat 运行时只保留 HEARTBEAT.md 作为工作区引导文件，其他文件会被忽略，从而节省 token：

1
2
3
4
5
6
7
8
9
{
  agents: {
    defaults: {
      heartbeat: {
        lightContext: true,
      },
    },
  },
}

4. 隔离会话（Isolated Session）

启用 isolatedSession: true 后，每次 Heartbeat 都在一个新的会话中运行，没有之前的对话历史，大幅降低每次运行的 token 消耗：

1
2
3
4
5
6
7
8
9
{
  agents: {
    defaults: {
      heartbeat: {
        isolatedSession: true,
      },
    },
  },
}

结合 lightContext: true 可以实现最大程度的 token 节省。

5. 可见性控制

你可以按渠道或账户调整 Heartbeat 的可见性：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
channels:
  defaults:
    heartbeat:
      showOk: false      # 隐藏 HEARTBEAT_OK（默认）
      showAlerts: true    # 显示提醒消息（默认）
      useIndicator: true  # 发送指示器事件（默认）
  telegram:
    heartbeat:
      showOk: true        # 在 Telegram 上显示 OK 确认
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # 为这个账户禁止提醒投递

各标志的作用：

  • showOk：当模型返回仅包含 OK 的回复时，发送 HEARTBEAT_OK 确认
  • showAlerts：当模型返回非 OK 回复时，发送提醒内容
  • useIndicator：为 UI 状态表面发送指示器事件

如果所有三个都是 false，OpenClaw 会完全跳过 Heartbeat 运行（不调用模型）。

6. 手动唤醒（On-Demand）

你可以通过命令手动触发一次即时 Heartbeat：

1
openclaw system event --text "检查紧急跟进事项" --mode now

如果多个代理配置了 Heartbeat，手动唤醒会立即运行所有这些代理的 Heartbeat。

使用 --mode next-heartbeat 可以等待下一次计划的触发。

七、 Heartbeat vs Cron：如何选择？

OpenClaw 提供了两种主要的自动化方式：Heartbeat 和 Cron Jobs。让我们看看如何选择：

使用场景 推荐方式 原因
每 30 分钟检查收件箱 Heartbeat 可以和其他检查批量处理，上下文感知
每天早上 9 点整发送日报 Cron（隔离） 需要精确时间
监控日历即将到来的事件 Heartbeat 天然适合周期性感知
每周深度分析 Cron（隔离） 独立任务，可以使用不同模型
20 分钟后提醒我 Cron（主会话，--at） 一次性，精确时间
后台项目健康检查 Heartbeat 搭便车在现有周期上

快速决策流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
任务需要在精确时间运行吗？
  YES → 使用 Cron
  NO  → 继续...

任务需要与主会话隔离吗？
  YES → 使用 Cron（隔离）
  NO  → 继续...

这个任务可以和其他周期性检查批量处理吗？
  YES → 使用 Heartbeat（添加到 HEARTBEAT.md）
  NO  → 使用 Cron

这是一次性提醒吗？
  YES → 使用 Cron 配合 --at
  NO  → 继续...

需要不同的模型或思考等级吗？
  YES → 使用 Cron（隔离）配合 --model/--thinking
  NO  → 使用 Heartbeat

最佳实践：两者结合使用

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

  1. Heartbeat 处理日常监控（收件箱、日历、通知），每 30 分钟批量处理一次
  2. Cron 处理精确时间的任务（日报、周报）和一次性提醒

八、 成本意识：如何节省 Token？

Heartbeat 运行完整的代理回合，间隔越短消耗的 token 越多。以下是降低成本的方法：

  1. 使用 isolatedSession: true：避免发送完整对话历史（从约 10 万 token 降到每次约 2-5K）
  2. 使用 lightContext: true：将引导文件限制为仅 HEARTBEAT.md
  3. 设置更便宜的 model（比如 ollama/llama3.2:1b）
  4. 保持 HEARTBEAT.md 简短
  5. 如果只需要内部状态更新，使用 target: "none"

九、 总结

OpenClaw 的 Heartbeat 机制是一种强大而灵活的自动化方式：

  • 批量处理：一次运行处理多个检查任务
  • 上下文感知：利用主会话的完整上下文做出智能决策
  • 静默机制：无需关注时保持静默，不打扰你
  • 高度可配置：丰富的配置选项满足各种需求
  • 成本可控：多种方式降低 token 消耗

通过合理配置 Heartbeat，结合 HEARTBEAT.md 清单，你可以让 AI 助手成为一个主动、智能、不打扰你的好帮手。

参考

[1] OpenClaw Heartbeat 官方文档
[2] Cron vs Heartbeat