OpenClaw �� Heartbeat心跳功能指南:让 AI 主动巡检、自动提醒.

你有没有想过——能不能让 AI 自己主动看看有没有什么要紧事，不用你每次去问？

比如每天早上自动查一下天气、看看今天有没有会议、检查一下邮箱有没有紧急邮件？

OpenClaw 的心跳（Heartbeat）功能就是干这个的。简单说：每隔一段时间，AI 会自动”醒来”看看有没有需要处理的事，然后把结果发给你。

心跳是啥？

说真的，HEARTBEAT就是OpenClaw的定时主动找你的功能。

官方文档是这么说的：

Heartbeat runs periodic agent turns in the main session so the model can surface anything that needs attention without spamming you.

人话版：HEARTBEAT会定期运行agent，看看有没有什么需要告诉你的，有就发消息，没有就安静待着。

这个设计挺聪明的。AI不会每天都来烦你，但它会定期看看有没有事，有事才找你。

心跳和定时任务（Cron）有点像，但不太一样：

心跳更适合那种”不定时检查一下有没有事”的场景，比如：

• • 检查邮箱有没有紧急邮件
• • 看看今天有没有约会/会议
• • 偶尔问候一下主人

系统初始化时加载的文件

OpenClaw 启动时，会自动加载工作区里的几个文件：

这些文件会在 Agent 启动时自动注入上下文，让 AI 知道自己是谁、该干什么。

HEARTBEAT.md 的作用

HEARTBEAT.md 是心跳功能的核心。它告诉 AI 每次心跳时该检查什么。

位置：~/.openclaw/workspace/HEARTBEAT.md

如果这个文件只有注释或为空，心跳就会跳过（啥也不干）。

标准的心跳文件格式

官方推荐的 HEARTBEAT.md 格式：

# HEARTBEAT.md# Keep this file empty (or with only comments) to skip heartbeat API calls.# Add tasks below when you want the agent to check something periodically.## 定期检查- 检查邮箱是否有紧急邮件- 查看今天是否有会议/约会- 检查是否有待办事项到期## 定时提醒- 每天早上 8 点提醒我喝水- 每周五下午提醒写周报

格式要点

1. 1. 文件开头可以是注释 – # 开头的内容会被忽略
2. 2. 用标题分组 – 比如”定期检查”、”定时提醒”
3. 3. 用列表写检查项 – - 开头的列表项
4. 4. 保持简洁 – 不要写太复杂的逻辑，心跳是轻量级的

心跳机制详解

默认间隔

• • 默认：30 分钟（Anthropic OAuth 认证时是 1 小时）
• • 可以配置：agents.defaults.heartbeat.every: "60m"

HEARTBEAT_OK 机制

这是心跳的核心机制：

• • 没情况：AI 回复 HEARTBEAT_OK（会被系统拦截，不发给你）
• • 有情况：AI 直接说内容（会发给你）

比如：

• • AI 检查完发现没啥事 → 回复 HEARTBEAT_OK → 你收不到消息
• • AI 发现今天有会议 → 回复”今天下午 3 点有会” → 你收到消息

ackMaxChars 限制

如果 AI 回复的内容太长（超过 ackMaxChars，默认 300 字符），就算带了 HEARTBEAT_OK 也会发给你。

activeHours 时间窗口

你可以限制心跳只在某些时间段运行：

{  agents: {    defaults: {      heartbeat: {        every: "30m",        activeHours: {          start: "08:00",          end: "22:00",          timezone: "Asia/Shanghai",        },      },    },  },}

这样半夜就不会被打扰了。

isolatedSession 省 token

默认心跳会带着完整的聊天记录跑，比较费 token。可以开启独立会话模式：

{  agents: {    defaults: {      heartbeat: {        every: "30m",        isolatedSession: true,  // 每次心跳用干净的新会话        lightContext: true,     // 只注入 HEARTBEAT.md      },    },  },}

这样每次心跳只读取 HEARTBEAT.md，大大节省 token。

实战配置示例

场景一：每小时检查，送达 QQ

{  agents: {    defaults: {      heartbeat: {        every: "1h",        target: "qqbot",        to: "你的QQID",      },    },  },}

场景二：每天工作时间检查，送达 Telegram

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "telegram",        to: "你的TG ID",        activeHours: {          start: "09:00",          end: "18:00",          timezone: "Asia/Shanghai",        },      },    },  },}

场景三：省 token 模式

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",           // 送达上次联系渠道        isolatedSession: true,    // 独立会话        lightContext: true,       // 只注入 HEARTBEAT.md      },    },  },}

常见问题

1. 为什么没收到消息？

• • 检查 AI 是不是只回复了 HEARTBEAT_OK（会被拦截）
• • 检查 target 和 to 配置对不对
• • 检查是不是在 activeHours 窗口外

2. 怎么关闭心跳？

{  agents: {    defaults: {      heartbeat: {        every: "0m",  // 0m 表示关闭      },    },  },}

3. 心跳和 Cron 该用哪个？

• • 检查事项、偶尔提醒 → 用心跳
• • 定时报天气、汇总报告 → 用 Cron