⏰ OpenClaw 定时任务进阶
Cron 表达式 · Wake 唤醒 · 隔离任务 · 失败告警
让 AI Agent 按时自动干活
📅 2026-06-09⏱️ 阅读 14 分钟🏷️ Cron · Scheduler · Automation
1. 调度系统概览
OpenClaw 的 cron 系统不只是简单的定时器。它支持三种调度方式、两种 Payload 类型、隔离执行、失败告警等高级功能。
| 功能 | 说明 |
|---|
| 三种调度 | at（一次性）、every（间隔）、cron（表达式） |
| 两种 Payload | systemEvent（系统事件）、agentTurn（Agent 对话） |
| 隔离执行 | isolated 模式，不影响主会话 |
| Wake 唤醒 | 立即或下次心跳唤醒 Agent |
| 失败告警 | 连续失败 N 次后发送告警 |
| 投递模式 | none、announce、webhook |
2. 三种调度类型
🕐 at — 一次性定时任务
// 30 分钟后执行一次
cron({
action: "add",
job: {
name: "30分钟后提醒喝水",
schedule: { kind: "at", at: "2026-06-09T01:30:00+08:00" },
payload: { kind: "systemEvent", text: "⏰ 提醒：该喝水了！" },
sessionTarget: "main"
}
})
🔁 every — 固定间隔任务
// 每 2 小时执行一次
cron({
action: "add",
job: {
name: "RSS 聚合",
schedule: { kind: "every", everyMs: 7200000 },
payload: {
kind: "agentTurn",
message: "执行 RSS 聚合，更新 /var/www/miaoquai/rss/ 页面"
},
sessionTarget: "isolated"
}
})
📅 cron — Cron 表达式
// 每天早上 8 点（上海时区）
cron({
action: "add",
job: {
name: "AI 新闻日报",
schedule: {
kind: "cron",
expr: "0 8 * * *",
tz: "Asia/Shanghai"
},
payload: {
kind: "agentTurn",
message: "生成今日 AI 新闻日报，保存到 /var/www/miaoquai/news/"
},
sessionTarget: "isolated"
}
})
💡 时区说明：cron 表达式使用 tz 参数指定时区。如果不指定，默认使用 Gateway 主机的本地时区。建议始终明确指定时区，避免歧义。
3. 两种 Payload 类型
| 类型 | 说明 | sessionTarget | 示例 |
|---|
| systemEvent | 注入文本到主会话 | 必须 main | 提醒、通知 |
| agentTurn | 触发一次 Agent 对话 | isolated/current/session | 自动化任务 |
systemEvent 示例
// 注入一条系统事件到主会话
payload: {
kind: "systemEvent",
text: "⏰ 提醒：下午 3 点有团队会议"
}
agentTurn 示例
// 触发一次完整的 Agent 对话
payload: {
kind: "agentTurn",
message: "搜索今天的 AI 热点新闻，生成日报",
model: "gpt-4o", // 可选：指定模型
thinking: "off", // 可选：推理模式
timeoutSeconds: 300 // 可选：超时时间
}
4. 隔离任务 vs 主会话任务
// 隔离任务（推荐用于自动化）
sessionTarget: "isolated"
// 优点：不影响主会话，资源独立
// 缺点：无法访问主会话上下文
// 主会话任务
sessionTarget: "main"
// 优点：可以触发主会话的 Agent
// 缺点：必须用 systemEvent，不能用 agentTurn
// 当前会话绑定
sessionTarget: "current"
// 优点：可以访问当前会话上下文
// 缺点：绑定到创建时的会话
// 指定会话
sessionTarget: "session:my-session-id"
// 优点：精确控制
// 缺点：需要知道会话 ID
💡 选择建议：
- 自动化任务（日报、RSS、SEO）→
isolated
- 提醒/通知 →
main + systemEvent
- 需要上下文的定期任务 →
current
5. Wake 唤醒机制
Wake 用于立即或延迟唤醒 Agent，常用于事件驱动的场景。
// 立即唤醒
cron({ action: "wake", text: "有紧急事项需要处理", mode: "now" })
// 下次心跳唤醒（默认）
cron({ action: "wake", text: "检查新消息", mode: "next-heartbeat" })
🔔 使用场景
- Webhook 回调：收到外部 webhook 时唤醒 Agent 处理
- 事件驱动：文件变化、监控告警等触发唤醒
- 手动触发：用户通过飞书/Telegram 发送特定指令
6. 失败告警
cron({
action: "add",
job: {
name: "SEO 数据采集",
schedule: { kind: "cron", expr: "0 */6 * * *", tz: "Asia/Shanghai" },
payload: { kind: "agentTurn", message: "采集 SEO 数据" },
sessionTarget: "isolated",
failureAlert: {
after: 3, // 连续失败 3 次后告警
mode: "announce", // 告警方式
channel: "feishu", // 告警频道
cooldownMs: 3600000 // 告警冷却 1 小时
}
}
})
7. 实战调度模式
📊 每日营销报告
cron({
action: "add",
job: {
name: "每日营销报告",
schedule: { kind: "cron", expr: "0 22 * * *", tz: "Asia/Shanghai" },
payload: {
kind: "agentTurn",
message: "生成今日营销报告：1) 网站流量 2) SEO 排名 3) 社区数据 4) 内容产出。保存到 /var/www/miaoquai/marketing-report.html 并发送飞书通知。"
},
sessionTarget: "isolated",
delivery: { mode: "announce", channel: "feishu" }
}
})
🔄 每 2 小时 RSS 聚合
cron({
action: "add",
job: {
name: "RSS 聚合",
schedule: { kind: "every", everyMs: 7200000 },
payload: {
kind: "agentTurn",
message: "执行 RSS 聚合任务，抓取 OpenClaw Blog 等源，更新 /var/www/miaoquai/rss/"
},
sessionTarget: "isolated"
}
})
⏰ 30 分钟提醒
cron({
action: "add",
job: {
name: "喝水提醒",
schedule: { kind: "every", everyMs: 1800000 },
payload: { kind: "systemEvent", text: "⏰ 该喝水了！" },
sessionTarget: "main",
deleteAfterRun: false
}
})
8. 常用 Cron 表达式
| 表达式 | 含义 | 示例场景 |
|---|
0 8 * * * | 每天 8:00 | 日报生成 |
0 */2 * * * | 每 2 小时 | RSS 聚合 |
0 9 * * 1-5 | 工作日 9:00 | 工作提醒 |
0 22 * * * | 每天 22:00 | 日报汇总 |
0 0 1 * * | 每月 1 号 0:00 | 月度报告 |
*/5 * * * * | 每 5 分钟 | 监控检查 |
0 8,12,18 * * * | 每天 8/12/18 点 | 热点追踪 |
30 1 * * * | 每天 01:30 | SEO 大规模生成 |
9. 最佳实践
- ✅ 始终指定时区，避免歧义
- ✅ 自动化任务用 isolated，不影响主会话
- ✅ 设置 failureAlert，及时发现问题
- ✅ 给任务起有意义的名字，便于管理
- ✅ 设置 timeoutSeconds，防止任务卡住
- ✅ 用 delivery: announce 让结果自动通知
- ❌ 不要用 sleep 循环模拟定时，用 cron
- ❌ 不要在 systemEvent 中放复杂指令，用 agentTurn