OpenClaw 定时任务与自动化：Cron 详解

- 摘要
- 一、引言：为什么需要定时任务？
- - [1.1 自动化运维的基石](#1.1 自动化运维的基石)
  - [1.2 AI 智能体的定时需求](#1.2 AI 智能体的定时需求)
  - [1.3 OpenClaw 的解决方案](#1.3 OpenClaw 的解决方案)
- [二、Cron 基础概念：表达式语法详解](#二、Cron 基础概念：表达式语法详解)
- - [2.1 Cron 表达式简介](#2.1 Cron 表达式简介)
  - [2.2 五字段语法结构](#2.2 五字段语法结构)
  - [2.3 特殊字符详解](#2.3 特殊字符详解)
  - [2.4 常用 Cron 表达式示例](#2.4 常用 Cron 表达式示例)
  - [2.5 时区的重要性](#2.5 时区的重要性)
- [三、OpenClaw Cron 配置详解](#三、OpenClaw Cron 配置详解)
- - [3.1 配置文件位置](#3.1 配置文件位置)
  - [3.2 主配置结构](#3.2 主配置结构)
  - [3.3 任务配置详解](#3.3 任务配置详解)
  - [3.4 调度类型详解](#3.4 调度类型详解)
  - [3.5 会话目标详解](#3.5 会话目标详解)
  - [3.6 完整配置示例](#3.6 完整配置示例)
- [四、Cron 实战案例](#四、Cron 实战案例)
- - [4.1 案例一：定时提醒](#4.1 案例一：定时提醒)
  - [4.2 案例二：定时备份](#4.2 案例二：定时备份)
  - [4.3 案例三：定时健康检查](#4.3 案例三：定时健康检查)
  - [4.4 案例四：每周深度分析](#4.4 案例四：每周深度分析)
- [五、Cron vs Heartbeat：两种定时机制对比](#五、Cron vs Heartbeat：两种定时机制对比)
- - [5.1 核心差异](#5.1 核心差异)
  - [5.2 详细对比表](#5.2 详细对比表)
  - [5.3 Heartbeat 详解](#5.3 Heartbeat 详解)
  - [5.4 最佳实践：组合使用](#5.4 最佳实践：组合使用)
- 六、常见问题与排查
- - [6.1 任务不执行](#6.1 任务不执行)
  - [6.2 时区问题](#6.2 时区问题)
  - [6.3 投递失败](#6.3 投递失败)
  - [6.4 Telegram 投递到错误位置](#6.4 Telegram 投递到错误位置)
  - [6.5 日志查看](#6.5 日志查看)
- 七、总结
- 参考资料

摘要

在现代智能体系统中，定时任务是自动化运维的核心能力之一。OpenClaw 作为新一代 AI 智能体框架，提供了强大而灵活的定时任务调度机制，支持精确的 Cron 表达式、多种执行模式以及与心跳机制的协同工作。本文将深入剖析 OpenClaw 的 Cron 定时任务系统，从基础的 Cron 表达式语法讲起，逐步深入到 openclaw.yaml 配置、实战案例以及与 Heartbeat 机制的对比分析。通过本文的学习，读者将掌握如何利用 OpenClaw 构建高效、可靠的自动化任务调度系统，实现定时提醒、定时备份、定时检查等常见场景的自动化运维。🎯

一、引言：为什么需要定时任务？

1.1 自动化运维的基石

在软件开发和系统运维领域，定时任务是最基础也是最重要的自动化手段之一。无论是数据库的定时备份、日志的定期清理，还是报告的自动生成，都离不开定时任务的支持。传统上，我们使用 Linux 的 crontab 或 Windows 的任务计划程序来实现这些功能。但随着系统架构的演进，特别是 AI 智能体的兴起，定时任务的需求变得更加多样化和复杂化。🤖

1.2 AI 智能体的定时需求

AI 智能体作为新一代的自动化工具，其定时任务需求与传统系统有着显著不同：

上下文感知：智能体需要根据对话历史和当前状态做出智能决策
多渠道投递：任务结果可能需要发送到 Slack、Telegram、WhatsApp 等多种渠道
模型选择：不同任务可能需要不同能力的模型（如深度分析需要更强的模型）
会话隔离：某些任务需要独立运行，不污染主会话历史

1.3 OpenClaw 的解决方案

OpenClaw 提供了两种互补的定时机制来解决这些问题：

Cron 定时任务：精确时间调度，支持隔离执行和模型覆盖
Heartbeat 心跳：周期性感知，支持批量检查和上下文决策

这两种机制各有优势，可以根据具体场景灵活选择，甚至组合使用。接下来，让我们从 Cron 表达式的基础知识开始，逐步深入了解 OpenClaw 的定时任务系统。

二、Cron 基础概念：表达式语法详解

2.1 Cron 表达式简介

Cron 表达式是一种用于定义定时任务执行时间的字符串格式。它最初源自 Unix 系统的 cron 守护进程，如今已成为跨平台定时任务的标准表示方法。标准的 Cron 表达式包含 5 个字段，分别表示分钟、小时、日期、月份和星期。🕐

2.2 五字段语法结构

Cron 表达式
分钟 0-59
小时 0-23
日期 1-31
月份 1-12
星期 0-7
* 表示任意值
/ 表示间隔
, 表示枚举

表示范围

Cron 表达式的五个字段从左到右依次为：

字段	允许值	允许的特殊字符
分钟	0-59	`*` `,` `-` `/`
小时	0-23	`*` `,` `-` `/`
日期	1-31	`*` `,` `-` `/` `?` `L` `W`
月份	1-12 或 JAN-DEC	`*` `,` `-` `/`
星期	0-7 或 SUN-SAT	`*` `,` `-` `/` `?` `L` `#`

2.3 特殊字符详解

星号（*） ：表示匹配该字段的所有可能值。例如，* * * * * 表示每分钟执行一次。

斜杠（/） ：表示间隔。例如，*/15 * * * * 表示每 15 分钟执行一次。

逗号（,） ：表示枚举多个值。例如，0 9,12,18 * * * 表示每天 9:00、12:00 和 18:00 执行。

连字符（-） ：表示范围。例如，0 9-17 * * 1-5 表示周一到周五的 9:00 到 17:00，每小时执行一次。

问号（?） ：用于日期或星期字段，表示"不指定值"。当指定了日期时，星期需要用 ?，反之亦然。

字母 L：表示"最后"。在日期字段中表示当月最后一天，在星期字段中表示周六。

字母 W ：表示工作日。例如，15W 表示当月 15 日最近的工作日。

井号（#） ：用于星期字段，表示第几个星期几。例如，2#3 表示第三个周二。

2.4 常用 Cron 表达式示例

表达式	含义
`0 * * * *`	每小时整点执行
`/10 * * *`	每 10 分钟执行一次
`0 9 * * *`	每天早上 9:00 执行
`0 9 * * 1`	每周一早上 9:00 执行
`0 9 1 * *`	每月 1 日早上 9:00 执行
`0 0 * * *`	每天午夜执行
`0 9-17 * * 1-5`	周一到周五，9:00-17:00 每小时执行
`0 0 1 1 *`	每年 1 月 1 日午夜执行

2.5 时区的重要性

在分布式系统和跨地域部署中，时区设置至关重要。OpenClaw 支持 IANA 时区标识符，如 Asia/Shanghai、America/New_York 等。如果省略时区设置，系统将使用 Gateway 网关主机的本地时区。
已设置
未设置
定时任务触发
检查时区设置
使用指定时区
使用主机时区
计算下次执行时间
调度执行

三、OpenClaw Cron 配置详解

3.1 配置文件位置

OpenClaw 的定时任务配置主要存储在以下位置：

任务存储 ：~/.openclaw/cron/jobs.json（Gateway 网关管理的 JSON 文件）
运行历史 ：~/.openclaw/cron/runs/<jobId>.jsonl（JSONL 格式，自动清理）
主配置文件 ：openclaw.yaml 或 openclaw.json5

3.2 主配置结构

在 openclaw.yaml 中，Cron 相关的配置如下：

yaml 复制代码

cron:
  enabled: true                    # 是否启用定时任务，默认 true
  store: "~/.openclaw/cron/jobs.json"  # 任务存储路径
  maxConcurrentRuns: 1             # 最大并发运行数，默认 1

3.3 任务配置详解

每个定时任务包含以下核心组件：
定时任务结构
任务 Job
调度计划 Schedule
负载 Payload
投递 Delivery
会话目标 SessionTarget
at - 一次性
every - 固定间隔
cron - Cron表达式
systemEvent - 系统事件
agentTurn - 智能体轮次
announce - 投递摘要
none - 仅内部运行
main - 主会话
isolated - 隔离会话

3.4 调度类型详解

OpenClaw 支持三种调度类型：

1. at（一次性时间戳）

用于在特定时间执行一次的任务。支持 ISO 8601 格式的时间字符串，如果省略时区则视为 UTC。

json 复制代码

{
  "schedule": {
    "kind": "at",
    "at": "2026-02-01T16:00:00Z"
  }
}

2. every（固定间隔）

用于按固定时间间隔重复执行的任务。间隔时间以毫秒为单位。

json 复制代码

{
  "schedule": {
    "kind": "every",
    "everyMs": 3600000
  }
}

3. cron（Cron 表达式）

用于按 Cron 表达式执行的任务，支持时区设置。

json 复制代码

{
  "schedule": {
    "kind": "cron",
    "expr": "0 7 * * *",
    "tz": "Asia/Shanghai"
  }
}

3.5 会话目标详解

OpenClaw 提供两种会话执行模式：

主会话模式（main）

在主会话上下文中运行
共享对话历史
通过系统事件触发
适合需要上下文感知的任务

隔离会话模式（isolated）

在独立的 cron:<jobId> 会话中运行
每次运行都是全新会话
可覆盖模型和思维级别
适合独立的后台任务

3.6 完整配置示例

以下是一个完整的定时任务配置示例：

json 复制代码

{
  "name": "Morning briefing",
  "description": "每日早间简报生成",
  "schedule": {
    "kind": "cron",
    "expr": "0 7 * * *",
    "tz": "Asia/Shanghai"
  },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "agentTurn",
    "message": "Generate today's briefing: weather, calendar, top emails, news summary.",
    "model": "opus",
    "thinking": "high"
  },
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "-1001234567890:topic:123",
    "bestEffort": true
  },
  "enabled": true,
  "deleteAfterRun": false
}

代码解释：

上述配置定义了一个名为"Morning briefing"的定时任务，每天北京时间早上 7:00 执行。任务使用隔离会话模式，这意味着每次运行都是独立的，不会污染主会话历史。负载类型为 agentTurn，指定使用 Opus 模型并启用高级思维模式。任务执行后，结果会通过 Telegram 投递到指定的主题。bestEffort 设置为 true 表示即使投递失败也不会导致任务失败。这个配置展示了 OpenClaw 定时任务的完整能力，包括精确调度、模型选择、会话隔离和多渠道投递。

四、Cron 实战案例

4.1 案例一：定时提醒

定时提醒是最常见的定时任务应用场景之一。以下是一个 20 分钟后提醒的配置：

bash 复制代码

# 创建一次性提醒任务
openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: standup meeting starts in 10 minutes." \
  --wake now \
  --delete-after-run

代码解释：

这个命令创建了一个名为"Meeting reminder"的一次性提醒任务。--at "20m" 表示任务将在 20 分钟后执行。--session main 指定使用主会话模式，这意味着提醒会在主会话上下文中触发。--system-event 参数定义了提醒的内容，当任务执行时，这个系统事件会被注入到会话中。--wake now 表示立即唤醒智能体处理这个事件，而不是等待下一次心跳。--delete-after-run 确保任务执行成功后自动删除，避免重复提醒。这种一次性提醒非常适合会议提醒、任务截止日期提醒等场景。

4.2 案例二：定时备份

定时备份是系统运维的核心任务。以下是一个每日数据库备份检查的配置：

bash 复制代码

# 每日备份检查任务
openclaw cron add \
  --name "Daily backup check" \
  --cron "0 2 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "Check backup status: 1) Verify last backup completed 2) Check backup file size 3) Test backup integrity 4) Report any issues" \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

代码解释：

这个命令创建了一个每日备份检查任务，在每天凌晨 2:00（北京时间）执行。使用隔离会话模式确保备份检查不会干扰主会话。--message 参数定义了备份检查的具体步骤：验证上次备份是否完成、检查备份文件大小、测试备份完整性、报告任何问题。--announce 表示任务执行结果会以摘要形式投递。投递目标设置为 Slack 频道，这样运维团队可以及时收到备份状态报告。这种定时备份检查机制可以有效防止备份失败导致的数据丢失风险。

4.3 案例三：定时健康检查

系统健康检查需要定期执行，以确保服务正常运行：

bash 复制代码

# 每 15 分钟健康检查
openclaw cron add \
  --name "System health check" \
  --cron "*/15 * * * *" \
  --session isolated \
  --message "Perform health check: CPU usage, memory usage, disk space, service status. Alert if any metric exceeds threshold." \
  --model "sonnet" \
  --announce \
  --channel telegram \
  --to "+15551234567"

代码解释：

这个命令创建了一个每 15 分钟执行一次的系统健康检查任务。Cron 表达式 */15 * * * * 表示每小时的第 0、15、30、45 分钟执行。任务使用 Sonnet 模型（比 Opus 更轻量）来执行健康检查，包括 CPU 使用率、内存使用率、磁盘空间和服务状态。如果任何指标超过阈值，智能体会发出警报。结果通过 Telegram 发送到指定手机号。这种高频健康检查可以及时发现系统异常，防止服务中断。

4.4 案例四：每周深度分析

对于需要深度思考的分析任务，可以使用更强大的模型：

bash 复制代码

# 每周项目进度分析
openclaw cron add \
  --name "Weekly project analysis" \
  --cron "0 9 * * 1" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "Analyze weekly project progress: review commits, identify blockers, suggest improvements, predict risks." \
  --model "opus" \
  --thinking "high" \
  --announce \
  --channel slack \
  --to "channel:C8765432101"

代码解释：

这个命令创建了一个每周一早上 9:00 执行的项目进度分析任务。Cron 表达式 0 9 * * 1 中的 1 表示周一。任务使用 Opus 模型并启用高级思维模式（--thinking high），这对于复杂的分析任务非常重要。智能体会审查代码提交、识别阻碍因素、提出改进建议并预测风险。这种每周深度分析可以帮助团队及时了解项目状态，做出更好的决策。

五、Cron vs Heartbeat：两种定时机制对比

5.1 核心差异

OpenClaw 提供了两种定时机制：Cron 定时任务和 Heartbeat 心跳。它们各有优势，适用于不同的场景。
定时任务选择决策
是
否
是
否
是
否
是
否
是
否
需要定时执行任务
需要精确时间?
使用 Cron
需要会话隔离?
可与其他检查批量处理?
使用 Heartbeat
是一次性提醒?
需要不同模型?

5.2 详细对比表

特性	Cron 定时任务	Heartbeat 心跳
执行时机	精确时间点	固定间隔（约 30 分钟）
会话类型	主会话或隔离会话	仅主会话
上下文	隔离会话无上下文	完整主会话上下文
模型选择	可覆盖	使用主会话模型
投递控制	支持 announce/none	非 HEARTBEAT_OK 时投递
任务持久化	持久化存储	配置文件定义
一次性任务	支持	不支持
批量处理	每个任务独立运行	一次心跳处理多项检查

5.3 Heartbeat 详解

Heartbeat 心跳是一种周期性感知机制，默认每 30 分钟运行一次。它的设计目的是让智能体在主会话上下文中检查各种事项并呈现重要信息。

Heartbeat 配置示例：

yaml 复制代码

agents:
  defaults:
    heartbeat:
      every: "30m"              # 心跳间隔
      target: "last"            # 告警投递目标
      activeHours:              # 活跃时间
        start: "08:00"
        end: "22:00"

HEARTBEAT.md 检查清单：

markdown 复制代码

# Heartbeat checklist

- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in

5.4 最佳实践：组合使用

最高效的配置是两者结合使用：
组合策略
Heartbeat
收件箱检查
日历检查
通知检查
轻量监控
Cron 定时任务
每日早间简报
每周项目分析
一次性提醒
深度分析任务

组合使用示例：

Heartbeat 处理常规监控（每 30 分钟）：

扫描收件箱紧急邮件
检查日历即将到来的事件
审查待处理任务
长时间静默后发送轻量提醒

Cron 处理精确定时任务：

每天早上 7:00 的早间简报
每周一上午 9:00 的项目回顾
一次性提醒（如"20 分钟后提醒我"）

六、常见问题与排查

6.1 任务不执行

症状：定时任务配置正确，但到时间没有执行。

排查步骤：

bash 复制代码

# 1. 检查定时任务是否启用
openclaw cron list

# 2. 检查 Gateway 是否运行
openclaw gateway status

# 3. 检查配置
cat ~/.openclaw/config.yaml | grep -A5 cron

# 4. 检查环境变量
echo $OPENCLAW_SKIP_CRON

可能原因：

cron.enabled 设置为 false
环境变量 OPENCLAW_SKIP_CRON=1
Gateway 网关未运行
时区设置不正确

6.2 时区问题

症状：任务执行时间与预期不符。

解决方案：

bash 复制代码

# 明确指定时区
openclaw cron add \
  --name "Test job" \
  --cron "0 9 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "Test message"

6.3 投递失败

症状：任务执行成功，但结果未投递到目标渠道。

排查步骤：

bash 复制代码

# 检查运行历史
openclaw cron runs --id <jobId> --limit 10

# 检查投递配置
openclaw cron list

可能原因：

渠道配置不正确
目标 ID 格式错误
网络连接问题

6.4 Telegram 投递到错误位置

解决方案：

对于 Telegram 论坛主题，使用明确的格式：

bash 复制代码

# 推荐格式
--to "-1001234567890:topic:123"

# 简写格式
--to "-1001234567890:123"

# 带前缀格式
--to "telegram:group:-1001234567890:topic:123"

6.5 日志查看

bash 复制代码

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

# 手动触发任务（调试用）
openclaw cron run <jobId> --force

# 查看任务详情
openclaw cron list

七、总结

OpenClaw 的定时任务系统为 AI 智能体提供了强大而灵活的自动化能力。通过本文的学习，我们掌握了以下核心知识点：

Cron 表达式基础：五字段语法结构（分时日月周）以及特殊字符的使用，是配置定时任务的基础。理解时区设置的重要性，可以避免跨地域部署时的时间偏差问题。

OpenClaw Cron 配置：三种调度类型（at、every、cron）满足不同场景需求；两种会话模式（main、isolated）提供灵活的执行环境；模型和思维覆盖功能让任务可以按需选择最合适的智能体能力。

实战应用场景：定时提醒、定时备份、定时健康检查、每周深度分析等案例展示了 OpenClaw 定时任务的实际应用价值。通过合理的配置，可以实现从简单提醒到复杂分析的各类自动化需求。

Cron 与 Heartbeat 的选择：精确时间需求选择 Cron，批量检查需求选择 Heartbeat，最佳实践是两者组合使用。Heartbeat 适合需要上下文感知的周期性检查，Cron 适合独立运行的后台任务。

问题排查能力：掌握日志查看、手动触发、配置检查等调试技巧，可以快速定位和解决定时任务执行中的问题。

在实际应用中，建议根据具体场景选择合适的定时机制，合理配置会话模式和投递目标，并定期检查任务执行状态。通过 OpenClaw 的定时任务系统，可以构建高效、可靠的智能体自动化运维体系，显著提升工作效率。🚀

OpenClaw 定时任务与自动化：Cron 详解

目录

摘要

一、引言：为什么需要定时任务？

1.1 自动化运维的基石

1.2 AI 智能体的定时需求

1.3 OpenClaw 的解决方案

二、Cron 基础概念：表达式语法详解

2.1 Cron 表达式简介

2.2 五字段语法结构

2.3 特殊字符详解

2.4 常用 Cron 表达式示例

2.5 时区的重要性

三、OpenClaw Cron 配置详解

3.1 配置文件位置

3.2 主配置结构

3.3 任务配置详解

3.4 调度类型详解

3.5 会话目标详解

3.6 完整配置示例

四、Cron 实战案例

4.1 案例一：定时提醒

4.2 案例二：定时备份

4.3 案例三：定时健康检查

4.4 案例四：每周深度分析

五、Cron vs Heartbeat：两种定时机制对比

5.1 核心差异

5.2 详细对比表

5.3 Heartbeat 详解

5.4 最佳实践：组合使用

六、常见问题与排查

6.1 任务不执行

6.2 时区问题

6.3 投递失败

6.4 Telegram 投递到错误位置

6.5 日志查看

七、总结

参考资料