OpenClaw Cron Setup

核心功能

OpenClaw Cron 是 Gateway 原生的持久化任务调度系统，专为 AI Agent 设计，解决"何时执行"与"如何投递"的自动化编排问题。

执行模式

• 主会话（main）：以 systemEvent 形式融入正常心跳，适合上下文相关的提醒
• 独立会话（isolated）：后台静默执行，不污染主会话历史，适合高频/嘈杂任务

调度能力

| 类型 | 示例 | 适用场景 |

|------|------|---------|

| 一次性 | `20m` / ISO8601 | 临时提醒、延迟触发 |

| 固定间隔 | `everyMs: 3600000` | 等频轮询 |

| Cron 表达式 | `0 7 * * *` | 精确日历时间 |

投递渠道

• announce：推送至 Telegram/WhatsApp 等频道，主会话同步摘要
• webhook：HTTP POST 到自定义端点
• none：纯内部执行

显著优点

1. 持久化存储：任务保存在 ~/.openclaw/cron/jobs.json，Gateway 重启不丢失
2. 智能退避：连续失败触发指数退避（30s→60m），避免雪崩
3. 时区感知：支持 --tz 参数，跨时区场景友好
4. 模型覆盖：独立任务可临时切换模型（如周报用 opus + thinking: high）

局限性与风险

• Gateway 强依赖：Cron 在 Gateway 进程内执行，Gateway 停止则调度暂停
• 无分布式锁：多实例部署时可能出现重复执行
• 调试成本：失败任务需手动查看 ~/.openclaw/cron/runs/<jobId>.jsonl

适用人群

• 需要精准时间触发（如晨间简报、周报生成）的自动化用户
• 希望后台任务与主会话隔离、避免上下文污染的重度用户
• 需要结果外投到 IM 频道或内部系统的集成场景

常规风险

• 时区配置错误导致任务非预期时间执行
• deleteAfterRun 与手动调试冲突，建议开发阶段关闭
• Webhook 投递无内置重试（bestEffort: true 仅标记尽力而为）

核心用法

OpenClaw Cron Jobs 是 OpenClaw Gateway 内置的定时任务调度系统，通过纯文档配置即可实现 Agent 的自动化唤醒与执行。该技能提供两种执行模式：

• 主会话模式（main）：任务融入正常心跳流程，通过 systemEvent 触发，适合需要延续上下文的轻量提醒
• 独立会话模式（isolated）：后台隔离执行，不污染主会话历史，通过 agentTurn 触发，适合复杂自动化任务

支持三种调度类型：一次性定时（at）、固定间隔（every）、标准 Cron 表达式（cron），并可配置结果投递至 Telegram/WhatsApp 等聊天频道或 Webhook 端点。

典型应用场景

• 个人：每日晨间简报、周报自动生成、健康数据汇总
• 团队：定时数据同步、周期性报告推送、值班提醒
• 开发：定时备份、日志轮转、健康检查

显著优点

1. 零代码安全架构：纯 Markdown 文档型 Skill，无可执行代码，从根本上消除代码注入、供应链攻击等传统风险
2. 灵活的任务编排：支持精确时间、相对时间（如"20m后"）、复杂 Cron 表达式，适配从简单提醒到企业级调度的全场景
3. 会话隔离设计：独立会话模式避免后台任务污染主对话上下文，保持用户交互体验的纯净性
4. 多通道投递能力：原生支持 Telegram、WhatsApp 等主流 IM 渠道，也可通过 Webhook 集成企业内网系统
5. 智能失败处理：内置指数退避机制（30s→1m→5m→15m→60m），自动重试并防止雪崩效应

潜在缺点与局限性

1. 平台依赖性：完全绑定 OpenClaw Gateway 生态，无法脱离该运行时环境独立使用
2. 状态持久化限制：任务存储于本地 JSON 文件（~/.openclaw/cron/jobs.json），无分布式高可用保障，单点故障风险存在
3. 执行精度约束：实际执行时间受 Gateway 心跳周期影响，不适合毫秒级精确调度场景
4. 模型成本不可控：独立任务可覆盖模型配置（如 --model opus --thinking high），长期使用可能产生预期外的 Token 消耗
5. 调试相对复杂：后台任务失败时需手动查看 ~/.openclaw/cron/runs/ 日志，缺乏实时监控仪表盘

适合的目标群体

• OpenClaw 深度用户：已部署 Gateway 并期望构建个人/团队自动化工作流
• 效率工具爱好者：追求"设定即遗忘"的智能化日常管理
• 轻量级运维场景：小型团队需要定时报告、数据同步等基础自动化
• 隐私敏感用户：偏好本地优先、无需第三方 SaaS 的调度方案

不适合：需要分布式调度、毫秒级精度、复杂任务依赖编排的企业级场景。

使用风险与注意事项

1. Gateway 持续运行依赖：Cron 在 Gateway 进程内执行，若 Gateway 未持续运行，任务将积压或丢失
2. 时区配置陷阱：跨时区用户需显式设置 --tz 参数，否则可能因服务器时区差异导致执行时间偏差
3. 数据外泄风险：配置 --announce 投递至外部 IM 频道时，需确保任务输出不包含敏感信息
4. 资源占用：高频独立任务（如每小时执行）可能累积大量会话历史，需关注 sessionRetention 配置
5. 版本兼容性：OpenClaw Gateway 迭代更新可能导致配置格式变化，建议锁定版本或关注官方迁移指南