定时任务
概述
OpenClaw 的定时任务（Cron）系统让 AI 可以主动工作，而不是被动等待你的指令。你可以让它每天早上发送简报、每小时检查服务器状态、每周生成工作总结。任务在 Gateway 中持久化存储，即使重启也不会丢失。
OpenClaw Cron 不是传统的 Linux cron，而是一个让 AI 按时间表主动执行任务的系统，支持三种调度方式：
| 调度方式 | 说明 | 示例 |
|---|---|---|
| at | 一次性，在指定时间执行一次 | --at 20m（20 分钟后） |
| every | 固定间隔，每隔一段时间执行 | --every 10m（每 10 分钟） |
| cron | 表达式，精确控制时间 | --cron "0 8 * * *"（每天早上 8 点） |
心跳（Heartbeat）
心跳是 OpenClaw 最核心的定时任务功能。它像生物钟一样，每隔一段时间唤醒 AI，让 AI 读取当前状态和 HEARTBEAT.md 文件，自主判断「我现在该不该为你做点什么」。
推荐频率
| 使用强度 | 建议间隔 |
|---|---|
| 轻度使用 | 每 2-4 小时一次 |
| 中度使用 | 每 1-2 小时一次 |
| 重度使用 | 每 30 分钟一次 |
注意 Token 消耗
每次心跳都会消耗 Token。入门阶段建议保持禁用状态，等到重度使用且 Token 充足时再开启。
管理心跳
# 查看心跳状态
openclaw cron list
# 设置心跳间隔
openclaw cron set heartbeat "0 */2 * * *" # 每 2 小时
# 禁用心跳
openclaw cron disable heartbeatHeartbeat vs Cron 对比
两者不是二选一，最佳实践是组合使用：
| 维度 | Heartbeat | Cron |
|---|---|---|
| 触发方式 | 固定间隔（默认 30 分钟） | 精确时间表达式（如 0 8 * * * = 每天8点） |
| 精确度 | 粗粒度，半小时级 | 细粒度，分钟级 |
| 适合场景 | 定期巡检、状态检查、清理杂务 | 定时报告、每日任务生成、定时备份 |
| 成本特征 | 每次心跳都有 token 消耗，不管有没有事做 | 只在触发时消耗 |
Cron 管「几点该干什么」，Heartbeat 管「有没有待处理的事」。两者配合才是完整的调度系统。
组合调度配置示例
cron:
- schedule: "0 8 * * *" # 每天 8 点：生成今日任务清单
- schedule: "0 18 * * *" # 每天 6 点：生成今日工作总结
heartbeat:
interval: 30m # 每 30 分钟：检查待执行子任务创建定时任务
通过对话创建（最简单）
直接告诉 OpenClaw 你需要什么：
每天早上 8 点给我发送今日简报，包括天气、日程和重要邮件OpenClaw 会自动创建定时任务并保存，你只需要用自然语言描述。
通过命令行创建
# 添加定时任务（--name 必填，--channel 指定发送目标）
openclaw cron add --name "每日简报" --cron "30 7 * * *" \
--message "发送今日简报" --channel "telegram:chat:123456789"
# 添加间隔任务
openclaw cron add --name "健康检查" --every 10m \
--message "检查服务器状态" --channel "qqbot:c2c:your_openid"
# 添加一次性任务（20 分钟后执行）
openclaw cron add --name "提醒我" --at 20m \
--message "该休息了" --channel "telegram:chat:123456789"
# 为任务指定工具白名单（2026.4.1+）
openclaw cron add --name "日报生成" --cron "0 18 * * *" \
--message "整理今日工作并生成日报" --channel "feishu:chat:xxxx" \
--tools "read,write,exec"--tools 任务级白名单（2026.4.1+）
从 2026.4.1 起，openclaw cron --tools 可以为每个定时任务单独指定工具白名单。常见用法：
- 只读巡检 ——
--tools "read,memory_search"，禁止任何写入或执行 - 简报生成 ——
--tools "read,web_search,write"，允许写结果但不能执行命令 - 运维脚本 ——
--tools "read,exec"，允许 shell 但不开放浏览器工具
这样你可以把单个定时任务的权限收紧到最小集合，即使 Agent 被提示注入攻破，它能做的坏事也有限。
失败通知走主渠道（2026.4.5+）
未显式设置 failureDestination 时，定时任务执行失败的通知会走成功投递时使用的同一个主渠道和会话上下文，不会再把失败信息丢到一个陌生的默认通道里。
--channel 格式
定时任务是主动推送，必须用 --channel 指定发送目标：
- Telegram 私聊：
telegram:chat:<ChatID> - QQ 私聊：
qqbot:c2c:<openid> - QQ 群聊：
qqbot:group:<groupid> - 飞书：
feishu:chat:<chatId>
不指定 --channel 时，任务仍会执行，但结果只能在 Web 控制面板中查看。
管理任务
# 查看所有任务和状态
openclaw cron list
# 手动触发执行（测试用）
openclaw cron run <name>
# 暂停/恢复任务
openclaw cron disable <name>
openclaw cron enable <name>
# 查看执行历史
openclaw cron runs --id <jobId>
# 编辑任务
openclaw cron edit <jobId>
# 删除任务
openclaw cron rm <jobId>实战案例
每日简报
每天早上 7:30 给我发送今日简报到 Telegram：
1. 北京今天的天气和空气质量
2. 今天的日历事件列表
3. 未读的重要邮件（来自老板或客户的）
4. Hacker News 今日热门前 3 条服务器监控
每 10 分钟检查服务器状态，如果 CPU 超过 90% 或内存超过 85% 就发送告警到飞书周报生成
每周五下午 5 点生成本周工作总结：
- 统计 Git 提交次数和代码行数
- 列出完成的 Jira 任务
- 生成 Markdown 格式周报
- 发送到飞书工作群数据备份
每天凌晨 2 点备份数据库到 S3，完成后通知我定期清理
每周日凌晨 3 点清理 30 天前的日志文件，保留错误日志高级配置
全局设置
在 openclaw.json 中配置：
{
"cron": {
"enabled": true,
"maxConcurrentRuns": 2
}
}条件执行
在 prompt 中直接写条件逻辑，OpenClaw 会智能理解：
openclaw cron add --name "disk_alert" --cron "*/30 * * * *" \
--message "检查磁盘使用率，如果超过 80% 就发送告警，否则不做任何操作"任务依赖
任务之间可以设置依赖关系（在 ~/.openclaw/cron/jobs.json 中）：
{
"name": "upload_backup",
"schedule": "0 3 * * *",
"depends_on": "backup_db",
"prompt": "将备份文件上传到云存储"
}upload_backup 只有在 backup_db 成功执行后才会运行。
错误处理与重试
{
"name": "api_sync",
"schedule": "0 */1 * * *",
"prompt": "从 API 同步数据到本地数据库",
"retry": {
"max_attempts": 3,
"delay": 60
},
"on_failure": {
"notify": true,
"channel": "telegram"
}
}推荐通过对话或 CLI 创建任务
jobs.json 由 Gateway 管理，手动编辑需要先停止 Gateway。日常使用推荐通过对话或 openclaw cron add 命令创建任务。
超时保护
防止任务运行时间过长：
{
"name": "data_sync",
"schedule": "0 */1 * * *",
"prompt": "同步 API 数据到本地",
"timeout": 300
}timeout 单位为秒，超时后任务会被自动终止。
调度频率建议
| 任务类型 | 建议频率 | 说明 |
|---|---|---|
| 系统监控 | 5-10 分钟 | CPU、内存、磁盘告警 |
| 数据同步 | 15-30 分钟 | API 数据拉取 |
| 日报/简报 | 每天 1 次 | 固定时间推送 |
| 周报 | 每周 1 次 | 周五下午 |
| 备份 | 每天 1 次 | 凌晨低峰期 |
| 清理 | 每周 1 次 | 周末凌晨 |
减少不必要的通知
使用条件执行（在 prompt 中写明条件）来减少噪音。例如「只在 CPU 超过 90% 时才通知」，而不是每次都发送状态报告。