概述
OpenClaw 内置的 cron 工具允许 AI 代理创建、管理和执行定时任务。无论是定期数据抓取、周期性报告生成，还是定时消息提醒，cron 工具都能胜任。作为七阶段工具流水线中的内置工具之一，它与 OpenClaw 的会话系统和消息通道深度集成。
Cron 工具架构
cron 工具在 Pi SDK 嵌入层中运行，利用系统级的定时调度器管理任务。每个定时任务本质上是一个预定义的代理动作，在触发时会创建一个新的代理会话来执行。
与传统 Cron 的区别
传统 cron 执行的是固定的 shell 命令，而 OpenClaw 的 cron 执行的是 AI 代理动作。这意味着定时任务可以包含智能决策——例如，"每天早上 9 点检查天气，如果有降雨预报就提醒我带伞"，AI 代理会根据实际天气情况决定是否发送提醒。
基本配置
启用 Cron 工具
tools:
cron:
enabled: true
maxTasks: 50
minInterval: 60
storage: /data/openclaw/cron
timezone: "Asia/Shanghai"
参数说明
- maxTasks：系统允许的最大定时任务数量
- minInterval：最小执行间隔（秒），防止过于频繁的任务
- storage：任务定义的持久化存储路径
- timezone：默认时区设置
创建定时任务
通过对话创建
用户可以直接通过自然语言对话让 AI 代理创建定时任务。例如：
- "每天早上 8 点给我发送新闻摘要"
- "每周一下午 2 点提醒我开周会"
- "每隔 6 小时检查一次某个网站的价格变化"
AI 代理会解析用户意图，将其转换为 cron 表达式和执行动作。
Cron 表达式
OpenClaw 支持标准的五字段 cron 表达式：
分钟 小时 日 月 星期
同时支持扩展语法：
@hourly— 每小时执行@daily— 每天执行（午夜）@weekly— 每周执行@monthly— 每月执行*/N— 每 N 个单位执行一次
任务定义结构
每个定时任务包含以下信息：
{
"id": "task-uuid",
"name": "每日新闻摘要",
"schedule": "0 8 * * *",
"channelId": "discord-channel-123",
"userId": "user-456",
"action": "搜索今日热门新闻并生成摘要，发送到频道",
"enabled": true,
"createdAt": "2026-03-14T10:00:00Z",
"lastRun": null,
"nextRun": "2026-03-15T08:00:00Z"
}
任务执行流程
当定时任务触发时，系统执行以下步骤：
- 会话创建：为任务创建一个新的代理会话
- 上下文恢复：加载任务关联的频道信息和用户偏好
- 系统提示词构建：调用
buildAgentSystemPrompt()生成适合的系统提示词 - 工具准备：通过七阶段流水线准备可用工具集
- 动作执行：AI 代理执行预定义的动作
- 结果分发：将执行结果发送到指定频道
- 状态更新：更新任务的
lastRun和nextRun记录
任务管理
查看任务列表
用户可以通过对话查询当前的定时任务："显示我所有的定时任务"。AI 代理会列出所有与该用户关联的任务及其状态。
修改和删除
任务支持随时修改执行时间、动作内容或目标频道。也可以临时禁用某个任务而不删除它，方便后续重新启用。
执行历史
每次任务执行的结果会被记录，包括执行时间、是否成功、输出内容和资源消耗。用户可以查看历史记录来评估任务效果。
与其他工具协作
cron 工具的强大之处在于它可以触发使用其他任何可用工具的操作：
- cron + browser：定时截取网页快照，监控页面变化
- cron + web：定时调用 API 获取数据更新
- cron + messaging：定时向多个频道发送通知
- cron + sessions：定时清理过期会话数据
错误处理与重试
重试策略
tools:
cron:
retry:
maxAttempts: 3
backoff: exponential
initialDelay: 60
maxDelay: 3600
当任务执行失败时，系统会根据配置的重试策略自动重试。指数退避策略确保不会因为频繁重试而加重系统负担。
失败通知
连续失败的任务会触发告警通知。管理员可以配置通知方式（频道消息、邮件等）和触发阈值。
资源控制
为防止定时任务过度消耗资源，OpenClaw 提供了多维度的限制：
- 并发限制：同一时刻最多执行的任务数量
- 执行时长限制：单个任务的最大执行时间
- 频率限制：同一任务的最小执行间隔
- 配额管理：每个用户可创建的任务数量上限
持久化
Cron 任务定义使用 JSONL 格式持久化存储。系统会定期对任务数据执行压缩（compaction），合并历史记录以控制存储空间。这与 OpenClaw 的会话持久化机制保持一致。
总结
OpenClaw 的 cron 工具将传统的定时任务与 AI 代理的智能决策能力相结合，使得定时任务不再局限于机械性的重复执行，而是能够根据实时情况做出灵活响应。合理利用这一工具，可以大幅提升自动化运维和信息获取的效率。