08-OpenClaw自动化与定时任务

作者：安逸 i
OpenClaw 自动化与定时任务

免费专栏全套教程：OpenClaw从入门到精通
OpenClaw 提供了一套完整的自动化系统，包括 Heartbeat 心跳机制、Cron 定时任务、Hooks 事件钩子和 Webhook 外部触发。本章将详细介绍这些机制的概念、配置和实战应用。

---

目录

自动化工作流概念Heartbeat 心跳机制Cron 定时任务配置Hooks 事件钩子Webhook 外部触发实战案例故障排查

---

1. 自动化工作流概念

1.1 核心组件

OpenClaw 的自动化系统由四个核心组件构成：

组件	用途	触发方式	适用场景
Heartbeat	周期性检查	自动定时	批量检查、上下文感知监控
Cron	精确定时任务	时间驱动	固定时间执行、独立任务
Hooks	事件驱动响应	事件触发	命令响应、生命周期管理
Webhook	外部系统集成	HTTP 请求	第三方系统对接、推送接收

1.2 组件选择决策树

1. 任务是否需要精确时间点执行？
2. ├── 是 → 使用 Cron
3. └── 否 → 任务是否需要与其他检查批量处理？
4.           ├── 是 → 使用 Heartbeat（添加到 HEARTBEAT.md）
5.           └── 否 → 任务是否由外部事件触发？
6.                     ├── 是 → 使用 Webhook
7.                     └── 否 → 任务是否需要独立上下文？
8.                               ├── 是 → 使用 Cron（隔离模式）
9.                               └── 否 → 使用 Heartbeat

复制代码

1.3 协同工作模式

最佳实践是组合使用多种机制：

1. ┌─────────────────────────────────────────────────────────────┐
2. │                      OpenClaw 自动化架构                      │
3. ├─────────────────────────────────────────────────────────────┤
4. │                                                             │
5. │   Heartbeat (每30分钟)                                       │
6. │   ├── 检查邮件紧急消息                                        │
7. │   ├── 检查日历近期事件                                        │
8. │   └── 轻量级状态监控                                          │
9. │                                                             │
10. │   Cron (精确时间)                                            │
11. │   ├── 每日早间简报 (7:00 AM)                                 │
12. │   ├── 每周项目复盘 (周一 9:00 AM)                            │
13. │   └── 一次性提醒 (20分钟后)                                  │
14. │                                                             │
15. │   Hooks (事件响应)                                           │
16. │   ├── /new 命令时保存会话记忆                                │
17. │   ├── /reset 命令时记录审计日志                              │
18. │   └── Gateway 启动时执行引导脚本                             │
19. │                                                             │
20. │   Webhook (外部触发)                                         │
21. │   ├── Gmail 新邮件推送                                       │
22. │   ├── GitHub 事件通知                                        │
23. │   └── 自定义系统集成                                         │
24. │                                                             │
25. └─────────────────────────────────────────────────────────────┘

复制代码

---

2. Heartbeat 心跳机制

2.1 概念与工作原理

Heartbeat 是 OpenClaw 的周期性检查机制，运行在主会话中，能够访问完整的对话上下文。
核心特点：

运行在主会话中，共享对话历史默认间隔 30 分钟（可配置）智能抑制：无事可做时返回 HEARTBEAT_OK，不发送消息可与 Cron 任务事件合并处理

工作流程：

1. ┌──────────────┐    定时触发     ┌──────────────┐
2. │   Gateway    │ ──────────────→ │  Heartbeat   │
3. │   Scheduler  │                 │   Runner      │
4. └──────────────┘                 └──────┬───────┘
5.                                         │
6.                                         ▼
7.                                  ┌──────────────┐
8.                                  │ 读取 HEARTBEAT.md │
9.                                  │ 检查任务列表    │
10.                                  └──────┬───────┘
11.                                         │
12.                     ┌───────────────────┴───────────────────┐
13.                     ▼                                       ▼
14.            ┌──────────────┐                       ┌──────────────┐
15.            │ 有任务需要处理 │                       │ 无需处理      │
16.            └──────┬───────┘                       └──────┬───────┘
17.                   │                                      │
18.                   ▼                                      ▼
19.            ┌──────────────┐                       ┌──────────────┐
20.            │ 执行任务并报告 │                       │ HEARTBEAT_OK │
21.            └──────────────┘                       └──────────────┘

复制代码

2.2 配置 Heartbeat

基础配置：

1. {
2.   agents: {
3.     defaults: {
4.       heartbeat: {
5.         every: "30m",           // 心跳间隔
6.         target: "last",         // 告警投递目标
7.         activeHours: {          // 活跃时段（可选）
8.           start: "08:00",
9.           end: "22:00"
10.         }
11.       }
12.     }
13.   }
14. }

复制代码

配置项说明：

配置项	类型	默认值	说明
every	string	"30m"	心跳间隔，如 "15m"、"1h"
target	string	"none"	消息投递目标："none"、"last" 或具体渠道
activeHours.start	string	-	活跃开始时间（本地时间）
activeHours.end	string	-	活跃结束时间（本地时间）

2.3 编写 HEARTBEAT.md

HEARTBEAT.md 是心跳检查的任务清单，放置在工作区根目录：

1. # Heartbeat Checklist
3. 每次心跳时按顺序检查以下项目：
5. ## 优先级检查
7. - [ ] 检查邮箱中的紧急邮件（标记为重要或来自关键联系人）
8. - [ ] 查看未来2小时内的日历事件
9. - [ ] 检查是否有待处理的提醒事项
11. ## 条件触发
13. - 如果超过8小时没有与用户互动，发送简短问候
14. - 如果有后台任务完成，汇报结果摘要
15. - 如果检测到重要事件，立即通知
17. ## 抑制规则
19. - 深夜时段（23:00-08:00）不发送消息，除非紧急
20. - 如果上次检查无新内容，跳过本次报告

复制代码

最佳实践：

保持清单简洁，避免过多检查项使用明确的条件和触发规则包含抑制规则，避免打扰用户定期回顾和更新清单内容

2.4 心跳状态跟踪

使用 JSON 文件跟踪上次检查状态：

1. // memory/heartbeat-state.json{"lastChecks":{"email":1703275200,"calendar":1703260800,"weather":null}}

复制代码

这样可以避免重复检查同一内容。
2.5 CLI 控制

1. # 查看上次心跳状态
2. openclaw system heartbeat last
4. # 立即触发心跳
5. openclaw system heartbeat run
7. # 发送系统事件（立即唤醒）
8. openclaw system event --mode now --text"检查电池状态"

复制代码

---

3. Cron 定时任务配置

3.1 概念与特点

Cron 是 OpenClaw 的精确定时任务系统，在 Gateway 中独立运行。
核心特点：

支持精确时间点执行任务持久化存储，重启不丢失两种执行模式：主会话模式 和 隔离模式支持一次性任务和周期性任务自动重试机制

3.2 任务存储

Cron 任务存储在：

1. ~/.openclaw/cron/
2. ├── jobs.json          # 任务定义
3. └── runs/              # 执行历史
4.     └── <jobId>.jsonl  # 按任务的运行日志

复制代码

3.3 执行模式对比

特性	主会话模式	隔离模式
会话上下文	共享主会话历史	全新会话
任务类型	系统事件	独立 Agent 执行
消息投递	通过心跳提示	直接投递或摘要
模型选择	使用主会话模型	可单独指定
适用场景	需要上下文的提醒	独立报告、批量任务

主会话模式：

1. openclaw cronadd\--name"项目检查提醒"\--every"4h"\--session main \
2.   --system-event "时间检查项目健康状况"\--wake now

复制代码

隔离模式：

1. openclaw cronadd\--name"每日早间简报"\--cron"0 7 * * *"\--tz"Asia/Shanghai"\--session isolated \--message"生成今日简报：天气、日历、邮件摘要"\--model opus \--announce\--channel whatsapp \--to"+8613800138000"

复制代码

3.4 调度类型

一次性任务（at）

在指定时间执行一次：

1. # ISO 时间戳（UTC）
2. openclaw cronadd\--name"会议提醒"\--at"2026-02-01T09:00:00Z"\--session main \
3.   --system-event "10分钟后开始站会"\--wake now \
4.   --delete-after-run
6. # 相对时间
7. openclaw cronadd\--name"20分钟后提醒"\--at"20m"\--session main \
8.   --system-event "检查烤箱"\--wake now

复制代码

间隔任务（every）

按固定间隔执行：

1. openclaw cronadd\--name"健康检查"\--every"1h"\--session isolated \--message"检查系统状态"\--announce

复制代码

Cron 表达式（cron）

使用标准 5 字段或 6 字段 cron 表达式：

1. ┌───────────── 分钟 (0-59)
2. │ ┌───────────── 小时 (0-23)
3. │ │ ┌───────────── 日期 (1-31)
4. │ │ │ ┌───────────── 月份 (1-12)
5. │ │ │ │ ┌───────────── 星期几 (0-6, 0=周日)
6. │ │ │ │ │
7. * * * * *
9. # 6字段版本（含秒）
10. ┌───────────── 秒 (0-59)
11. │ ┌───────────── 分钟 (0-59)
12. │ │ ┌───────────── 小时 (0-23)
13. │ │ │ ┌───────────── 日期 (1-31)
14. │ │ │ │ ┌───────────── 月份 (1-12)
15. │ │ │ │ │ ┌───────────── 星期几 (0-6)
16. │ │ │ │ │ │
17. * * * * * *

复制代码

常用表达式示例：

表达式	说明
0 7 * * *	每天早上 7:00
0 9 * * 1	每周一早上 9:00
0 18 * * 1-5	工作日晚上 6:00
*/15 * * * *	每 15 分钟
0 */2 * * *	每 2 小时
0 0 1 * *	每月 1 号零点

时区设置：

1. openclaw cronadd\--name"北京时间早报"\--cron"0 7 * * *"\--tz"Asia/Shanghai"\--session isolated \--message"早安简报"\--announce

复制代码

3.5 消息投递配置

隔离模式任务支持灵活的消息投递：

1. # 投递到 WhatsApp--announce--channel whatsapp --to"+8613800138000"# 投递到 Telegram 群组主题--announce--channel telegram --to"-1001234567890:topic:123"# 投递到 Discord 频道--announce--channel discord --to"channel:123456789"# 投递到 Slack 频道--announce--channel slack --to"channel:C1234567890"# 投递到上次对话位置--announce--channel last

复制代码

3.6 模型和思考级别覆盖

隔离任务可以指定不同的模型：

1. openclaw cronadd\--name"每周深度分析"\--cron"0 6 * * 1"\--tz"Asia/Shanghai"\--session isolated \--message"分析本周项目进展"\--model"anthropic/claude-sonnet-4-20250514"\--thinking high \--announce

复制代码

3.7 任务管理 CLI

1. # 列出所有任务
2. openclaw cron list
4. # 查看任务详情
5. openclaw cron status
7. # 查看执行历史
8. openclaw cron runs --id<jobId>--limit50# 手动执行任务
9. openclaw cron run <jobId># 强制执行
10. openclaw cron run <jobId>--due# 仅在到期时执行# 编辑任务
11. openclaw cron edit <jobId>--message"更新后的提示"--model opus
13. # 删除任务
14. openclaw cron remove <jobId># 启用/禁用任务
15. openclaw cron edit <jobId>--enabledfalse

复制代码

3.8 配置文件

1. {
2.   cron: {
3.     enabled: true,                    // 启用 Cron
4.     store: "~/.openclaw/cron/jobs.json",
5.     maxConcurrentRuns: 1,             // 最大并发执行数
6.     webhookToken: "your-webhook-token",
7.     sessionRetention: "24h",          // 隔离会话保留时间
8.     runLog: {
9.       maxBytes: "2mb",                // 日志文件最大大小
10.       keepLines: 2000                  // 保留行数
11.     }
12.   }
13. }

复制代码

3.9 错误处理与重试

重试机制：

周期性任务失败后自动重试重试间隔：30秒 → 1分钟 → 5分钟 → 15分钟 → 60分钟成功后重置重试计数器一次性任务失败后禁用，不重试

查看失败原因：

1. openclaw cron runs --id<jobId>--limit20# 查看日志中的错误详情
2. openclaw logs --follow|grepcron

复制代码

---

4. Hooks 事件钩子

4.1 概念与用途

Hooks 是 OpenClaw 的事件驱动扩展系统，允许在特定事件发生时执行自定义逻辑。
支持的事件类型：

事件	触发时机
command:new	用户发送 /new 命令
command:reset	用户发送 /reset 命令
command:stop	用户发送 /stop 命令
agent:bootstrap	Agent 初始化引导时
gateway:startup	Gateway 启动时
message:received	收到消息时
message:sent	发送消息时

4.2 内置 Hooks

OpenClaw 提供四个内置 Hooks：

Hook	功能	事件
session-memory	保存会话记忆	command:new
bootstrap-extra-files	注入额外引导文件	agent:bootstrap
command-logger	记录命令审计日志	command:*
boot-md	启动时执行 BOOT.md	gateway:startup

4.3 启用和管理 Hooks

1. # 列出所有 Hooks
2. openclaw hooks list
4. # 查看详情
5. openclaw hooks info session-memory
7. # 启用 Hook
8. openclaw hooks enable session-memory
10. # 禁用 Hook
11. openclaw hooks disable command-logger
13. # 检查资格
14. openclaw hooks check

复制代码

4.4 创建自定义 Hook

目录结构：

1. ~/.openclaw/hooks/my-hook/
2. ├── HOOK.md          # 元数据和文档
3. └── handler.ts       # 处理函数

复制代码

HOOK.md 示例：
[code]---
name: my-hook
description: "自定义钩子：执行特定操作"
homepage: https://docs.example.com/hooks/my-hook
metadata:
  openclaw:
    emoji: "