08-OpenClaw自动化与定时任务

OpenClaw 自动化与定时任务

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

目录

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

1. 自动化工作流概念

1.1 核心组件

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

1.2 组件选择决策树

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

1.3 协同工作模式

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

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

2. Heartbeat 心跳机制

2.1 概念与工作原理

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

核心特点：

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

工作流程：

┌──────────────┐ 定时触发 ┌──────────────┐ │ Gateway │ ──────────────→ │ Heartbeat │ │ Scheduler │ │ Runner │ └──────────────┘ └──────┬───────┘ │ ▼ ┌──────────────┐ │ 读取 HEARTBEAT.md │ │ 检查任务列表 │ └──────┬───────┘ │ ┌───────────────────┴───────────────────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ 有任务需要处理 │ │ 无需处理 │ └──────┬───────┘ └──────┬───────┘ │ │ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ 执行任务并报告 │ │ HEARTBEAT_OK │ └──────────────┘ └──────────────┘ 

2.2 配置 Heartbeat

基础配置：

{ agents: { defaults: { heartbeat: { every: "30m", // 心跳间隔 target: "last", // 告警投递目标 activeHours: { // 活跃时段（可选） start: "08:00", end: "22:00" } } } } } 

配置项说明：

2.3 编写 HEARTBEAT.md

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

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

最佳实践：

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

2.4 心跳状态跟踪

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

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

这样可以避免重复检查同一内容。

2.5 CLI 控制

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

3. Cron 定时任务配置

3.1 概念与特点

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

核心特点：

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

3.2 任务存储

Cron 任务存储在：

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

3.3 执行模式对比

主会话模式：

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

隔离模式：

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

3.4 调度类型

一次性任务（at）

在指定时间执行一次：

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

间隔任务（every）

按固定间隔执行：

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

Cron 表达式（cron）

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

┌───────────── 分钟 (0-59) │ ┌───────────── 小时 (0-23) │ │ ┌───────────── 日期 (1-31) │ │ │ ┌───────────── 月份 (1-12) │ │ │ │ ┌───────────── 星期几 (0-6, 0=周日) │ │ │ │ │ * * * * * # 6字段版本（含秒） ┌───────────── 秒 (0-59) │ ┌───────────── 分钟 (0-59) │ │ ┌───────────── 小时 (0-23) │ │ │ ┌───────────── 日期 (1-31) │ │ │ │ ┌───────────── 月份 (1-12) │ │ │ │ │ ┌───────────── 星期几 (0-6) │ │ │ │ │ │ * * * * * * 

常用表达式示例：

时区设置：

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

3.5 消息投递配置

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

# 投递到 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 模型和思考级别覆盖

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

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

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

3.8 配置文件

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

3.9 错误处理与重试

重试机制：

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

查看失败原因：

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

4. Hooks 事件钩子

4.1 概念与用途

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

支持的事件类型：

4.2 内置 Hooks

OpenClaw 提供四个内置 Hooks：

4.3 启用和管理 Hooks

# 列出所有 Hooks openclaw hooks list # 查看详情 openclaw hooks info session-memory # 启用 Hook openclaw hooks enable session-memory # 禁用 Hook openclaw hooks disable command-logger # 检查资格 openclaw hooks check 

4.4 创建自定义 Hook

目录结构：

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

HOOK.md 示例：

--- name: my-hook description: "自定义钩子：执行特定操作" homepage: https://docs.example.com/hooks/my-hook metadata: openclaw: emoji: "🎯" events: ["command:new"] requires: bins: ["node"] env: ["MY_API_KEY"] --- # My Custom Hook 当用户发送 /new 命令时执行自定义操作。 ## 功能 - 记录会话信息 - 执行初始化逻辑 - 发送欢迎消息 

handler.ts 示例：

consthandler=async(event)=>{// 过滤事件类型if(event.type !=="command"|| event.action !=="new"){return;}console.log(`[my-hook] /new 命令触发`);console.log(` 会话: ${event.sessionKey}`);console.log(` 时间: ${event.timestamp.toISOString()}`);// 自定义逻辑try{awaitdoSomething(event.context); event.messages.push("✨ 自定义钩子已执行！");}catch(err){console.error("[my-hook] 执行失败:", err);}};exportdefault handler;

4.5 事件上下文

每个事件包含丰富的上下文信息：

// 命令事件{ type:"command", action:"new", sessionKey:"agent:main:main", timestamp:newDate(), messages:[], context:{ sessionId:"abc123", sessionFile:"/path/to/session.json", commandSource:"whatsapp", senderId:"+1234567890", workspaceDir:"/path/to/workspace"}}// 消息事件{ type:"message", action:"received", context:{ from:"+1234567890", content:"Hello!", channelId:"whatsapp", messageId:"msg-123"}}

4.6 配置 Hooks

{ hooks: { internal: { enabled: true, entries: { "session-memory": { enabled: true }, "command-logger": { enabled: false }, "my-hook": { enabled: true, env: { "MY_CUSTOM_VAR": "value" } } } } } } 

5. Webhook 外部触发

5.1 概念与用途

Webhook 提供 HTTP 接口，让外部系统能够触发 OpenClaw Agent 执行任务。

适用场景：

• 邮件推送通知（Gmail Pub/Sub）
• GitHub 事件集成
• 第三方系统回调
• 自动化工作流集成

5.2 启用 Webhook

{ hooks: { enabled: true, token: "your-secure-token", // 必须设置 path: "/hooks", // 默认路径 allowedAgentIds: ["hooks", "main"] } } 

5.3 端点说明

POST /hooks/wake

唤醒主会话并发送系统事件：

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" }'

参数：

POST /hooks/agent

运行独立的 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": "总结收件箱中的重要邮件", "name": "Email Summary", "agentId": "hooks", "wakeMode": "now", "deliver": true, "channel": "whatsapp", "to": "+8613800138000", "model": "openai/gpt-5.2-mini", "thinking": "low" }'

参数：

5.4 自定义 Webhook 映射

配置自定义 Webhook 端点：

{ hooks: { enabled: true, token: "${OPENCLAW_HOOKS_TOKEN}", mappings: { "github": { match: { "source": "github" }, action: "agent", message: "处理 GitHub 事件: {{json .}}", channel: "discord", to: "channel:123456789" } } } } 

5.5 安全建议

• 使用专用 Webhook Token，不要复用 Gateway 认证 Token
• 将 Webhook 端点限制在本地回环或可信网络
• 启用 allowedAgentIds 限制 Agent 选择
• 保持 allowRequestSessionKey=false（默认关闭）

6. 实战案例

6.1 每日早间简报

需求： 每天早上 7:00 生成并发送包含天气、日历、邮件摘要的简报。

解决方案： 使用 Cron 隔离模式任务。

# 创建早间简报任务 openclaw cronadd\--name"每日早间简报"\--cron"0 7 * * *"\--tz"Asia/Shanghai"\--session isolated \--message"生成今日早间简报，包括： 1. 今日天气和穿衣建议 2. 今日日历事件列表 3. 昨晚收到的未读邮件摘要 4. 待办事项提醒 使用简洁友好的语气，控制在 500 字以内。"\--model opus \--thinking medium \--announce\--channel whatsapp \--to"+8613800138000"

6.2 项目健康监控

需求： 每小时检查项目状态，有异常时通知。

解决方案： 使用 Heartbeat + 条件触发。

HEARTBEAT.md：

# 项目健康监控 每小时检查以下内容： ## 检查项 - 检查 Git 仓库是否有未提交的重要变更 - 检查是否有构建失败或测试错误 - 检查是否有未响应的重要 Issue ## 触发规则 - 只有发现异常时才发送消息 - 正常状态返回 HEARTBEAT_OK 

6.3 会议提醒系统

需求： 会议开始前 15 分钟发送提醒。

解决方案： 动态创建 Cron 任务。

# 创建一次性提醒（假设从日历获取会议时间） openclaw cronadd\--name"项目评审会议提醒"\--at"2026-02-26T09:45:00+08:00"\--session main \ --system-event "会议提醒：10:00 项目评审会议将在会议室A举行，请提前准备好演示材料。"\--wake now \ --delete-after-run 

6.4 周报自动生成

需求： 每周五下午 5:00 生成并发送周报。

openclaw cronadd\--name"每周工作总结"\--cron"0 17 * * 5"\--tz"Asia/Shanghai"\--session isolated \--message"生成本周工作总结报告： 1. 本周完成的主要任务 2. 本周遇到的问题和解决方案 3. 下周计划 4. 需要协调的事项 格式要求： - 使用 Markdown 格式 - 条理清晰，使用列表和标题 - 包含数据支撑（如有） - 控制在 1000 字以内"\--model opus \--thinking high \--announce\--channel telegram \--to"-1001234567890"

6.5 Gmail 新邮件推送

需求： 收到重要邮件时立即处理。

解决方案： Webhook + Gmail Pub/Sub。

1. 配置 Gmail Pub/Sub： 参考 /automation/gmail-pubsub 文档
2. 设置 Webhook：

# 配置 Gmail 推送映射 openclaw webhooks gmail setup # 验证配置 openclaw webhooks gmail verify 

3. 处理逻辑： 当 Gmail 推送新邮件通知时，Webhook 触发 Agent 处理邮件并决定是否通知用户。

6.6 会话记忆持久化

需求： 每次发送 /new 命令时自动保存会话摘要。

解决方案： 使用内置 session-memory Hook。

# 启用会话记忆 Hook openclaw hooks enable session-memory # 配置工作区# 确保 config.json 中设置了 workspace.dir

效果： 每次执行 /new 时，会在 ~/.openclaw/workspace/memory/ 下创建日期命名的记忆文件。

6.7 综合自动化配置

完整配置示例：

{ agents: { defaults: { heartbeat: { every: "30m", target: "last", activeHours: { start: "08:00", end: "22:00", timezone: "Asia/Shanghai" } }, userTimezone: "Asia/Shanghai" } }, cron: { enabled: true, maxConcurrentRuns: 2, sessionRetention: "48h", runLog: { maxBytes: "5mb", keepLines: 3000 } }, hooks: { enabled: true, token: "${OPENCLAW_HOOKS_TOKEN}", internal: { enabled: true, entries: { "session-memory": { enabled: true }, "command-logger": { enabled: true }, "boot-md": { enabled: true } } } } } 

7. 故障排查

7.1 诊断命令

# 检查系统状态 openclaw status openclaw gateway status openclaw doctor # 检查 Cron openclaw cron status openclaw cron list openclaw cron runs --id<jobId>--limit20# 检查 Heartbeat openclaw system heartbeat last # 查看日志 openclaw logs --follow

7.2 常见问题

Cron 任务不执行

诊断步骤：

# 1. 确认 Cron 已启用 openclaw config get cron.enabled # 2. 检查 Gateway 是否运行 openclaw gateway status # 3. 查看任务状态 openclaw cron list # 4. 检查执行历史 openclaw cron runs --id<jobId>--limit20

常见原因：

• cron.enabled: false 或环境变量 OPENCLAW_SKIP_CRON=1
• Gateway 未运行
• 时区配置错误
• 任务被禁用

Cron 执行但无消息

诊断步骤：

# 检查任务配置 openclaw cron list # 检查渠道连接 openclaw channels status --probe# 查看日志 openclaw logs --follow|grep-E"(cron|deliver)"

常见原因：

• 隔离任务的 delivery.mode 为 none
• 投递目标配置错误（channel/to）
• 渠道认证失败

Heartbeat 未触发

诊断步骤：

# 检查上次心跳 openclaw system heartbeat last # 检查配置 openclaw config get agents.defaults.heartbeat # 查看 HEARTBEAT.md 内容cat ~/.openclaw/workspace/HEARTBEAT.md 

常见原因：

• activeHours 限制
• requests-in-flight（主会话繁忙）
• HEARTBEAT.md 为空或无 actionable 内容

7.3 日志分析

# 实时查看日志 openclaw logs --follow# 过滤 Cron 相关 openclaw logs --follow|grepcron# 过滤 Heartbeat 相关 openclaw logs --follow|grep heartbeat # 过滤错误 openclaw logs --follow|grep-i error 

总结

OpenClaw 的自动化系统提供了灵活的定时和事件驱动能力：

1. Heartbeat 适合周期性、需要上下文的批量检查
2. Cron 适合精确时间点执行的任务
3. Hooks 适合命令和生命周期事件的响应
4. Webhook 适合外部系统集成

选择合适的机制组合使用，可以构建强大的自动化工作流，让 OpenClaw 成为你的智能助手。