夜雨聆风
OpenClaw Heartbeat 功能说明与配置指南
本文档详细介绍 OpenClaw 的 Heartbeat（心跳）机制，包括功能原理、配置项说明、最佳实践示例。
【💻云产品推荐】
腾讯云coding plan
https://go.wangzhijie.com/txcoding
腾讯云低价云主机
https://go.wangzhijie.com/txecs
阿里云一键部署openclaw
https://go.wangzhijie.com/aliyunopenclaw
阿里云领7000万token
https://go.wangzhijie.com/aliyunai
阿里云轻量服务器68/年 99/年
https://go.wangzhijie.com/aliyun
阿里云百炼Coding Plan
https://go.wangzhijie.com/aliyuncoding一、Heartbeat 是什么
Heartbeat 是 OpenClaw Gateway 的定期轻量级检查机制，每隔一定时间自动触发一次，用于执行后台监控任务。与 cron 任务的区别在于：
| 触发方式 | ||
| 用途定位 | ||
| 模型配置 | ||
| 结果处理 | ||
| 适用场景 |
二、配置项详解
Heartbeat 在 openclaw.json 中的配置路径为 agents.defaults.heartbeat。
2.1 完整配置示例
{
"agents": {
"defaults": {
"heartbeat": {
"every": "30m", // 触发间隔
"model": "qwen3.5-flash", // 使用的模型（可单独指定）
"includeReasoning":true // 是否包含推理过程
}
}
}
}2.2 各配置项说明
every | "30m" | m（分钟）、h（小时）。 |
如 "15m"、"2h"、"1h30m" |
| model | string | 主模型 | 单独指定 Heartbeat 使用的模型，如 "qwen3.5-flash"、"gpt-4o" |
| includeReasoning | boolean | false | 是否在回复中包含模型的推理过程。设为 true 可看到思考链路 |
2.3 模型配置
模型需要在 models.providers 中提前配置好，例如：
{
"models": {
"providers": {
"alibailian": {
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"apiKey": "sk-xxxxxxxxxxxx",
"api": "openai-completions",
"models": [
{
"id": "qwen3.5-flash",
"name": "qwen3.5-flash",
"contextWindow": 200000,
"maxTokens": 8192
}
]
}
}
}
}配置模型有两种方式：
• 通过 openclaw configure向导配置（交互式）• 手动编辑 openclaw.json（如上所示）
三、HEARTBEAT.md 任务文件
Heartbeat 触发时，会读取工作区根目录下的 HEARTBEAT.md 文件作为任务指令。
3.1 文件位置
~/.openclaw/workspace/HEARTBEAT.md3.2 文件格式
# HEARTBEAT.md
## 任务1
具体要执行的检查或任务描述...
## 任务2
另一个任务描述...3.3 特殊规则
• 文件为空或只包含注释：Heartbeat 回复 HEARTBEAT_OK（静默确认）• 文件有实际内容：执行任务内容并返回结果 • 任务执行失败：返回错误信息。通知用户
四、最佳实践示例
4.1 基础示例：天气提醒
## 天气提醒
检查当前泉州天气，根据天气状况给出实用提醒（如：带伞、防晒、添衣等）。
如果天气恶劣（如暴雨、台风）则立即提醒。
用简短自然的话语表达。触发效果：每 30 分钟自动检查天气，有异常天气时主动提醒。
4.2 进阶示例：邮件 + 日历 + 天气综合检查
## 邮件检查
检查未读邮件数量，如果 > 3 封未读，简要列出前3封的标题和发件人。
## 日历检查
查看今天接下来的日程安排，如果 2 小时内有会议，提前提醒时间和主题。
## 天气提醒
检查当前天气，如需带伞/添衣/防晒等，给出一句话提醒。触发效果：
• 未读邮件多 → 列出前3封 • 2小时内有会 → 提前提醒 • 天气有变化 → 一句话提醒 • 无异常 → 回复 HEARTBEAT_OK 静默
4.3 轻量示例：仅天气提醒
## 天气
查一下当前天气，简短提醒即可。4.4 高级示例：多城市天气 + 预警
## 天气监控
检查以下城市的当前天气：
- 泉州（主）
- 上海（出差）
- 北京（家人）
如果任何城市出现以下情况，立即提醒：
- 暴雨/台风/大雪
- 气温 > 38°C 或 < 0°C
- 空气质量指数 > 150
其他情况只给一句话简报。五、Heartbeat 与定时任务的配合
5.1 分工原则
5.2 配合示例
┌─────────────────────────────────────────────┐
│ Heartbeat（每30分钟。说到这个，低成本监控） │
│ ├── 天气检查 → 有异常才提醒 │
│ ├── 邮件检查 → 未读>3封才提醒 │
│ └── 日历检查 → 2小时内有会才提醒 │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ Cron（每天定时，主动推送） │
│ ├── 08:00 → AI科技要闻简报 │
│ ├── 10:00 → OpenClaw资讯推送 │
│ └── 20:00 → 今日晚报 │
└─────────────────────────────────────────────┘六、常见问题
Q1: Heartbeat 和 Cron 哪个更省成本？
Heartbeat 更省。
Heartbeat 设计为轻量检查，模型调用频率高（每30分钟一次），适合用便宜或免费的模型（如 qwen3.5-flash）。Cron 任务频率低但单次任务重，适合用高质量模型。
Q2: 可以不用 HEARTBEAT.md 吗？
不行。HEARTBEAT.md 是 Heartbeat 的任务定义文件，每次触发都会读取。没有这个文件，Heartbeat 不知道要执行什么。
Q3: Heartbeat 支持哪些模型？
任何在 models.providers 中配置好的模型都可以使用，包括：
• OpenAI 系列（GPT-4o、GPT-3.5） • Anthropic 系列（Claude 3.5） • 阿里云百炼（qwen 系列） • 本地模型（Ollama） • 其他兼容 OpenAI API 格式的模型
Q4: Heartbeat 触发时间可以自定义吗？
不可以。Heartbeat 的触发间隔只能设置"每隔多久"，不能设置"每天几点"。但是吧，如果需要精确时间点的任务，请使用 Cron。
七、总结
Heartbeat 是 OpenClaw 的轻量级后台监控机制，核心价值在于：
1. 自动化：无需人工干预，定期检查 2. 智能化：有情况才通知。无情况静默 3. 低成本：可搭配轻量模型使用 4. 灵活组合：与 Cron 任务配合，实现 7×24 小时智能助理
掌握 Heartbeat，让你的 OpenClaw 成为真正主动关怀你的数字助手。
