OpenClaw 高阶玩法：定时任务配置完全指南

在上一阶段的学习中，我们已经掌握了技能组合和自动化工作流的基本用法。本篇文章将详细介绍 OpenClaw 的 Cron 定时任务系统，这是实现精确时间点自动化的核心工具。

什么是 Cron 定时任务？

Cron 是 OpenClaw 的精确定时任务系统，运行在 Gateway 中独立运行。与 Heartbeat 的周期性检查不同，Cron 支持在精确时间点执行任务，特别适合以下场景：

每日固定时间发送提醒
每周特定日期执行复盘
一次性提醒（如"20分钟后提醒我"）
定时批量处理任务

核心特点

精确时间执行：支持到分钟级别的精确调度
任务持久化：存储在 ~/.openclaw/cron/jobs.json，重启不丢失
两种执行模式：主会话模式（共享上下文）和隔离模式（全新会话）
自动重试机制：失败后按间隔重试

任务存储结构

Cron 任务存储在以下位置：

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

执行模式对比

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

主会话模式示例

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

隔离模式示例

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

三种调度类型

1. 一次性任务（at）

在指定时间执行一次：

# ISO 时间戳（UTC）
openclaw cron add \
  --name "会议提醒" \
  --at "2026-02-01T09:00:00Z" \
  --session main \
  --system-event "10分钟后开始站会" \
  --wake now \
  --delete-after-run

# 相对时间
openclaw cron add \
  --name "20分钟后提醒" \
  --at "20m" \
  --session main \
  --system-event "检查烤箱" \
  --wake now

2. 间隔任务（every）

按固定间隔执行：

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

3. Cron 表达式（cron）

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

┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日期 (1-31)
│ │ │ ┌───────────── 月份 (1-12)
│ │ │ │ ┌───────────── 星期几 (0-6, 0=周日)
* * * * *

常用表达式示例：

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

时区设置

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

消息投递配置

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

# 投递到 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

任务管理 CLI

# 列出所有任务
openclaw cron list

# 查看任务详情
openclaw cron status

# 查看执行历史
openclaw cron runs --id <jobId> --limit 50

# 手动执行任务
openclaw cron run <jobId>          # 强制执行
openclaw cron run <jobId> --due    # 仅在到期时执行

# 编辑任务
openclaw cron edit <jobId> --message "更新后的提示" --model opus

# 删除任务
openclaw cron remove <jobId>

# 启用/禁用任务
openclaw cron edit <jobId> --enabled false

错误处理与重试

重试机制

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

查看失败原因

openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow | grep cron

自动化组件选择决策树

面对不同的自动化需求，如何选择合适的组件？参考以下决策树：

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

实战案例：组合使用 Heartbeat 和 Cron

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

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

总结

Cron 定时任务是 OpenClaw 自动化体系中的重要组成部分，它与 Heartbeat、心跳机制、Hooks 事件钩子和 Webhook 外部触发共同构成了完整的自动化生态系统。

通过本篇文章的学习，你应该能够：

理解 Cron 与 Heartbeat 的区别
使用三种调度类型配置定时任务
掌握任务管理和消息投递配置
学会错误处理和故障排查