Cygnus Tech Blog
Cygnus Tech Blog

第26章 Cron 自动化 —— 定时任务自动化

Cygnus Yang 收录于 01-AI 工具与智能体/01-OpenClaw
 约 900 字 预计阅读 5 分钟 

OpenClaw 的 cron 是一个Gateway 内置调度器，专门用于处理定时任务。与传统的 crontab 或需要外部依赖的方案不同，OpenClaw 的 cron 直接运行在 Gateway 内部，支持多种执行模式，并且任务会自动持久化。

推荐操作入口是 openclaw cron ... 命令，任务持久化在状态目录里，不需要手工维护复杂的配置文件。

Cron 是如何工作的

图表 代码
flowchart TD
    A[创建 Cron 任务
openclaw cron add] --> B[任务持久化
~/.openclaw/cron/jobs.json]
    B --> C{等待触发时间}
    C -->|到时| D{执行模式}
    D -->|main| E[发送事件到主会话
systemEvent]
    D -->|isolated| F[启动独立会话
agentTurn]
    E --> G[任务执行]
    F --> G
    G --> H{投递方式}
    H -->|announce| I[发送到聊天渠道]
    H -->|webhook| J[发送到外部 URL]
    H -->|none| K[静默结束]
    I --> L{是否删除}
    J --> L
    K --> L
    L -->|deleteAfterRun=true| M[删除任务]
    L -->|false| N[保留任务继续调度]
flowchart TD
    A[创建 Cron 任务
openclaw cron add] --> B[任务持久化
~/.openclaw/cron/jobs.json]
    B --> C{等待触发时间}
    C -->|到时| D{执行模式}
    D -->|main| E[发送事件到主会话
systemEvent]
    D -->|isolated| F[启动独立会话
agentTurn]
    E --> G[任务执行]
    F --> G
    G --> H{投递方式}
    H -->|announce| I[发送到聊天渠道]
    H -->|webhook| J[发送到外部 URL]
    H -->|none| K[静默结束]
    I --> L{是否删除}
    J --> L
    K --> L
    L -->|deleteAfterRun=true| M[删除任务]
    L -->|false| N[保留任务继续调度]
flowchart TD
    A[创建 Cron 任务
openclaw cron add] --> B[任务持久化
~/.openclaw/cron/jobs.json]
    B --> C{等待触发时间}
    C -->|到时| D{执行模式}
    D -->|main| E[发送事件到主会话
systemEvent]
    D -->|isolated| F[启动独立会话
agentTurn]
    E --> G[任务执行]
    F --> G
    G --> H{投递方式}
    H -->|announce| I[发送到聊天渠道]
    H -->|webhook| J[发送到外部 URL]
    H -->|none| K[静默结束]
    I --> L{是否删除}
    J --> L
    K --> L
    L -->|deleteAfterRun=true| M[删除任务]
    L -->|false| N[保留任务继续调度]
flowchart TD
    A[创建 Cron 任务<br/>openclaw cron add] --> B[任务持久化<br/>~/.openclaw/cron/jobs.json]
    B --> C{等待触发时间}
    C -->|到时| D{执行模式}
    D -->|main| E[发送事件到主会话<br/>systemEvent]
    D -->|isolated| F[启动独立会话<br/>agentTurn]
    E --> G[任务执行]
    F --> G
    G --> H{投递方式}
    H -->|announce| I[发送到聊天渠道]
    H -->|webhook| J[发送到外部 URL]
    H -->|none| K[静默结束]
    I --> L{是否删除}
    J --> L
    K --> L
    L -->|deleteAfterRun=true| M[删除任务]
    L -->|false| N[保留任务继续调度]

官方文档的定义很明确：

  • Cron 运行在 Gateway 内部
  • 任务会持久化
  • 可以唤醒主会话，也可以跑隔离会话
  • 运行结束后可以 announce、webhook 或静默

默认存储位置：

~/.openclaw/cron/jobs.json

推荐做法是通过 CLI 或工具调用创建和编辑任务，而不是手工维护一个长长的配置数组。

两种执行模式

Main Session

主会话模式会把事件塞给 heartbeat 系统：

  • sessionTarget: "main"
  • payload.kind: "systemEvent"

这种模式适合：

  • 晨报提醒
  • 心跳内的常规巡检
  • 希望复用主会话上下文的定时任务

使用场景对比：

场景推荐模式原因
每日晨报推送到常用群组main上下文复用，用户在同一会话
紧急告警通知main需要立即被主会话感知
代码仓库健康检查isolated不需要打扰主会话，独立执行

Isolated Session

隔离模式会在 cron:<jobId> 里跑独立 agent turn：

  • sessionTarget: "isolated"
  • payload.kind: "agentTurn"

这种模式适合：

  • 噪音较大的后台任务
  • 周期性抓取/总结
  • 不想污染主会话历史的自动化

调度时间类型

OpenClaw 支持三种调度类型：

类型说明示例
at一次性提醒--at "2026-02-01T16:00:00Z"
every固定间隔--every "1h"
cron标准 cron 表达式--cron "0 7 * * *"

at — 一次性任务

指定一个 ISO 8601 格式的绝对时间戳：

openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --message "Check the docs draft" \
  --delete-after-run

配合 --delete-after-run 使用，适合一次性提醒。

every — 固定间隔任务

使用人类可读的间隔格式：

# 每 5 分钟
--every "5m"

# 每 1 小时
--every "1h"

# 每 2 天
--every "2d"
openclaw cron add \
  --name "Health check" \
  --every "30m" \
  --session isolated \
  --message "Check service health"

cron — 标准周期任务

使用标准的 cron 表达式（5 个字段：分 时 日 月 周）：

# 每天早上 7 点
"0 7 * * *"

# 每周一上午 9 点
"0 9 * * 1"

# 每 5 分钟
"*/5 * * * *"

# 每月 1 号凌晨 2 点
"0 2 1 * *"

# 工作日每天上午 9 点
"0 9 * * 1-5"

配合 --tz 指定时区：

openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "Summarize overnight updates" \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

任务投递方式

任务执行结束后，OpenClaw 支持三种投递方式：

模式说明适用场景
announce发送到聊天渠道推送报告、通知用户
webhook发送到外部 URL集成外部系统、数据分析
none静默结束纯后台处理、不需要通知

announce — 推送到聊天渠道 

openclaw cron add \
  --name "Daily report" \
  --cron "0 18 * * *" \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

webhook — 外部系统集成

如果你想让外部系统接收结果，而不是发回聊天渠道：

openclaw cron add \
  --name "Data export" \
  --cron "0 0 * * *" \
  --webhook https://api.example.com/cron-callback

关键字段：

  • delivery.mode — 投递模式：announce / webhook / none
  • delivery.channel — 聊天渠道：slack / discord / telegram 等
  • delivery.to — 目标：频道 ID 或用户 ID
  • delivery.bestEffort — 最佳投递（失败不重试）：true / false

CLI 命令详解

创建任务

一次性提醒任务：

openclaw cron add \
  --name “Reminder” \
  --at “2026-02-01T16:00:00Z” \
  --session main \
  --system-event “Reminder: check the docs draft” \
  --wake now \
  --delete-after-run

定时晨报任务：

openclaw cron add \
  --name “Morning brief” \
  --cron “0 7 * * *” \
  --tz “America/Los_Angeles” \
  --session isolated \
  --message “Summarize overnight updates.” \
  --announce \
  --channel slack \
  --to “channel:C1234567890”

管理任务 

# 列出所有任务
openclaw cron list

# 编辑任务
openclaw cron edit <job-id>

# 手动触发任务（不等待调度时间）
openclaw cron run <job-id>

# 查看任务执行历史
openclaw cron runs --id <job-id>

# 删除任务
openclaw cron rm <job-id>

JSON 结构详解

当前概念层面的关键字段：

字段说明示例值
schedule.kind调度类型"at" / "every" / "cron"
sessionTarget执行模式"main" / "isolated"
payload.kind载荷类型"systemEvent" / "agentTurn"
delivery.mode投递方式"announce" / "webhook" / "none"
wakeMode唤醒模式"now" / "next-heartbeat"
deleteAfterRun运行后删除true / false

完整的任务结构示例：

唤醒模式

wakeMode 决定了定时事件如何推动执行：

模式行为使用场景
"now"立即触发 heartbeat需要立即执行的紧急任务
"next-heartbeat"等待下一个 heartbeat 周期常规定时任务，资源友好
# 立即执行（紧急提醒）
--wake now

# 等待下次 heartbeat（常规任务，默认）
--wake next-heartbeat

故障排查

查看任务执行历史 

openclaw cron runs --id <job-id>

输出示例：

Runs for job "Morning brief" (job-xxx):

  #123  2026-02-01T07:00:00Z  success  2.3s
  #122  2026-01-31T07:00:00Z  success  2.1s
  #121  2026-01-30T07:00:00Z  failed   API timeout

常见问题

问题原因解决方法
任务没有触发时区配置错误检查 --tz 参数是否正确
webhook 调用失败URL 不可达或认证问题检查目标服务日志和认证配置
任务一直重试delivery.bestEffort = false设置为 true 或修复失败原因
主会话污染使用 main 模式执行高频任务改用 isolated 模式

最佳实践

选择执行模式

  • 日常报告、通知 → 使用 main，方便在同一个会话中查看
  • 数据抓取、健康检查 → 使用 isolated，避免污染主会话历史

选择调度类型

  • 一次性提醒 → at + --delete-after-run
  • 高频监控 → every（如每 5 分钟）
  • 周期性任务 → cron（如每天早上 7 点）

选择投递方式

  • 需要用户感知 → announce 推送到常用群组
  • 集成外部系统 → webhook
  • 纯后台处理 → none 静默结束

资源优化

  • 高频任务使用 isolated 模式 + wake next-heartbeat
  • 避免 wake now 用于大批量任务，防止资源耗尽

版本迁移说明

如果你正在从旧版迁移，注意以下变化：

旧方式新方式
手工维护配置数组openclaw cron add/edit/list
旧式 skill 执行事件systemEvent / agentTurn 载荷
event.type = "command"通过 CLI 创建任务
旧式通知字段delivery 对象

本章小结

  • 当前 cron 是 Gateway 内建调度器，任务保存在 ~/.openclaw/cron/jobs.json
  • 主要执行模式：main（主会话）和 isolated（独立会话）
  • 主要 schedule 类型：at（一次性）、every（间隔）、cron（周期）
  • 主要 delivery 模式：announce（聊天）、webhook（外部）、none（静默）
  • 正确操作入口是 openclaw cron add/edit/list/run/rm 命令

相关内容

收录于 合集・01-AI 工具与智能体/01-OpenClaw 34
更新于 2026-05-23 
CC BY-NC-SA 4.0
返回 | 主页
如果这篇文章对你有帮助，欢迎请我喝杯咖啡 ☕
Cygnus Yang 支付宝支付宝
Cygnus Yang 微信微信

目录