OpenClaw 自动化与定时任务
OpenClaw 提供了一套完整的自动化系统，涵盖 Heartbeat 心跳机制、Cron 定时任务、Hooks 事件钩子和 Webhook 外部触发。本章将深入解析这些机制的原理、配置细节以及实战中的组合策略。
自动化工作流核心概念
组件选型与决策
OpenClaw 的自动化能力主要由四个核心组件支撑，理解它们的适用场景是构建高效工作流的关键：
| 组件 | 用途 | 触发方式 | 适用场景 |
|---|---|---|---|
| Heartbeat | 周期性检查 | 自动定时 | 批量检查、上下文感知监控 |
| Cron | 精确定时任务 | 时间驱动 | 固定时间执行、独立任务 |
| Hooks | 事件驱动响应 | 事件触发 | 命令响应、生命周期管理 |
| Webhook | 外部系统集成 | HTTP 请求 | 第三方系统对接、推送接收 |
在实际项目中，单一机制往往不够用。建议根据任务特性选择：
- 需要精确时间点？选 Cron。
- 需要结合对话历史或批量处理？选 Heartbeat。
- 由外部事件（如邮件到达）触发？选 Webhook。
- 需要对特定命令做出反应？选 Hooks。
最佳实践通常是组合使用。例如，Heartbeat 负责轻量级状态监控，Cron 负责每日简报，Hooks 处理用户指令，Webhook 对接外部服务。
协同架构示意
┌─────────────────────────────────────────────────────────────┐
│ OpenClaw 自动化架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Heartbeat (每 30 分钟) │
│ ├── 检查邮件紧急消息 │
│ ├── 检查日历近期事件 │
│ └── 轻量级状态监控 │
│ │
│ Cron (精确时间) │
│ ├── 每日早间简报 (7:00 AM) │
│ ├── 每周项目复盘 (周一 9:00 AM) │
│ └── 一次性提醒 (20 分钟后) │
│ │
│ Hooks (事件响应) │
│ ├── /new 命令时保存会话记忆 │
│ ├── /reset 命令时记录审计日志 │
│ └── Gateway 启动时执行引导脚本 │
│ │
│ Webhook (外部触发) │
│ ├── Gmail 新邮件推送 │
│ ├── GitHub 事件通知 │
│ └── 自定义系统集成 │
│ └─────────────────────────────────────────────────────────────┘
Heartbeat 心跳机制
原理与特点
Heartbeat 是运行在主会话中的周期性检查机制，能够访问完整的对话上下文。它的核心优势在于智能抑制——如果无事可做，它不会发送任何消息，避免打扰用户。
关键特性：
- 默认间隔 30 分钟（可配置）
- 共享主会话历史
- 支持活跃时段限制
配置与编写
在 config.json 中配置基础参数：
{
"agents": {
"defaults": {
"heartbeat": {
"every": "30m",
"target": "last",
"activeHours": {
"start": "08:00",
"end": "22:00"
}
}
}
}
}
任务清单需放置在根目录的 HEARTBEAT.md 文件中。这里建议保持清单简洁，明确条件触发规则，并包含抑制逻辑。
# Heartbeat Checklist
每次心跳时按顺序检查以下项目：
## 优先级检查
- [ ] 检查邮箱中的紧急邮件
- [ ] 查看未来 2 小时内的日历事件
- [ ] 检查是否有待处理的提醒事项
## 抑制规则
- 深夜时段（23:00-08:00）不发送消息，除非紧急
- 如果上次检查无新内容，跳过本次报告
CLI 控制
可以通过命令行直接干预心跳行为：
# 查看上次心跳状态
openclaw system heartbeat last
# 立即触发心跳
openclaw system heartbeat run
# 发送系统事件唤醒
openclaw system event --mode now --text "检查电池状态"
Cron 定时任务配置
核心机制
Cron 是 OpenClaw 的精确定时任务系统，独立于主会话运行。它支持持久化存储，重启后任务依然存在，并提供主会话和隔离两种执行模式。
模式对比：
- 主会话模式：共享上下文，适合需要上下文的提醒。
- 隔离模式：全新会话，适合独立报告或批量任务，可指定不同模型。
任务创建与管理
1. 创建任务
一次性任务（at）：
openclaw cron add \
--name "会议提醒" \
--at "2026-02-01T09:00:00Z" \
--session main \
--system-event "10 分钟后开始站会" \
--wake now
周期性任务（cron）：
openclaw cron add \
--name "每日早间简报" \
--cron "0 7 * * *" \
--tz "Asia/Shanghai" \
--session isolated \
--message "生成今日简报：天气、日历、邮件摘要" \
--model opus \
--announce \
--channel whatsapp \
--to "+8613800138000"
2. 常用表达式
| 表达式 | 说明 |
|---|---|
0 7 * * * | 每天早上 7:00 |
0 9 * * 1 | 每周一早上 9:00 |
*/15 * * * * | 每 15 分钟 |
0 0 1 * * | 每月 1 号零点 |
3. 任务管理
# 列出所有任务
openclaw cron list
# 查看执行历史
openclaw cron runs --id <jobId> --limit 50
# 手动执行
openclaw cron run <jobId>
# 删除任务
openclaw cron remove <jobId>
错误处理
周期性任务失败后会自动重试，间隔逐渐拉长（30 秒 → 1 分钟 → 5 分钟...）。一次性任务失败则会被禁用。查看日志时可过滤关键字：
openclaw logs --follow | grep cron
Hooks 事件钩子
事件驱动扩展
Hooks 允许在特定事件发生时执行自定义逻辑。OpenClaw 内置了 session-memory、command-logger 等钩子，也支持用户自定义。
常见事件类型：
command:new/command:reset：用户指令触发gateway:startup：网关启动时message:received：收到消息时
自定义 Hook 开发
创建一个 Hook 需要两个文件：HOOK.md（元数据）和 handler.ts（处理逻辑）。
handler.ts 示例：
const handler = async (event) => {
if (event.type !== "command" || event.action !== "new") return;
console.log(`[my-hook] /new 命令触发`);
try {
await doSomething(event.context);
event.messages.push("✨ 自定义钩子已执行！");
} catch (err) {
console.error("[my-hook] 执行失败:", err);
}
};
export default handler;
启用与管理
# 列出所有 Hooks
openclaw hooks list
# 启用/禁用
openclaw hooks enable session-memory
openclaw hooks disable command-logger
Webhook 外部触发
集成外部系统
Webhook 提供了 HTTP 接口，让外部系统能触发 Agent 执行任务。适用于邮件推送、GitHub 事件回调等场景。
端点调用
唤醒主会话：
curl -X POST http://127.0.0.1:18789/hooks/wake \
-H 'Authorization: Bearer your-secure-token' \
-H 'Content-Type: application/json' \
-d '{ "text": "收到新邮件，请检查收件箱", "mode": "now" }'
运行独立 Agent：
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H 'Authorization: Bearer your-secure-token' \
-H 'Content-Type: application/json' \
-d '{ "message": "总结收件箱中的重要邮件", "deliver": true, "channel": "whatsapp" }'
安全建议： 务必设置专用 Token，限制 allowedAgentIds，并将端点绑定在可信网络。
实战案例
1. 每日早间简报
每天早上 7:00 生成天气、日历、邮件摘要。使用 Cron 隔离模式，指定输出渠道。
2. 项目健康监控
每小时检查 Git 变更、构建状态。利用 Heartbeat + 条件触发，仅异常时报警。
3. 会话记忆持久化
启用 session-memory Hook，每次 /new 命令自动保存上下文摘要到本地。
故障排查
常见问题诊断
Cron 任务不执行：
- 确认
cron.enabled为true。 - 检查 Gateway 是否运行。
- 验证时区配置是否正确。
Heartbeat 未触发：
- 检查
activeHours是否在当前时间段内。 - 查看
HEARTBEAT.md是否有 actionable 内容。 - 确认主会话是否繁忙（
requests-in-flight）。
日志分析：
openclaw logs --follow | grep -E "(cron|heartbeat|error)"
通过合理组合上述机制，你可以构建出强大的自动化工作流，让 OpenClaw 真正成为得力的智能助手。
