OpenClaw 内置 Gateway 调度器（Cron），可持久化定时任务，在指定时间唤醒 Agent，并将输出投递到聊天频道。无论是「每天早上运行」还是「20 分钟后提醒我」，Cron 都是实现机制。
核心概念速览
- Cron 运行在 Gateway 内部（不在模型内部）
- 任务持久化在
~/.openclaw/cron/下，重启不丢失 - 两种执行模式：Main Session（主会话）和 Isolated（隔离会话）
- 支持 Webhook 投递（HTTP POST）
快速开始
创建一次性提醒：
bash
openclaw cron add \
--name "提醒" \
--at "2026-02-01T16:00:00Z" \
--session main \
--system-event "提醒：查看 Cron 文档" \
--wake now \
--delete-after-run
openclaw cron list
openclaw cron run <job-id>创建每日定时隔离任务：
bash
openclaw cron add \
--name "早间简报" \
--cron "0 7 * * *" \
--tz "Asia/Shanghai" \
--session isolated \
--message "总结昨晚的更新。" \
--announce \
--channel telegram \
--to "你的Chat ID"三种调度模式
| 调度类型 | 语法 | 说明 |
|---|---|---|
| 一次性 | --at "2026-02-01T16:00:00Z" 或 --at "20m" | 指定时间点执行一次 |
| 固定间隔 | schedule.kind = "every"，everyMs（毫秒） | 每隔固定时间执行 |
| Cron 表达式 | --cron "0 7 * * *" --tz "Asia/Shanghai" | 标准 5/6 字段 Cron 表达式 |
注意：顶部整点（如
0 * * * *）会自动随机偏移最多 5 分钟，避免大量 Gateway 同时触发。用--exact强制准时。
两种执行模式
Main Session（主会话）
- 将系统事件加入队列，在下次心跳时执行
wakeMode: "now"→ 立即触发心跳（默认）wakeMode: "next-heartbeat"→ 等待下次定时心跳- 适合需要主会话上下文的任务
json
{
"name": "待办提醒",
"schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
"sessionTarget": "main",
"wakeMode": "now",
"payload": { "kind": "systemEvent", "text": "提醒：提交费用报告" },
"deleteAfterRun": true
}Isolated（隔离会话）
- 在
cron:<jobId>专属 Session 中独立运行 - 每次运行启动全新 Session（无历史记录携带）
- 默认投递模式：
announce（发送到目标频道） - 适合「嘈杂」、高频或「后台杂务」类任务
json
{
"name": "每日简报",
"schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "Asia/Shanghai" },
"sessionTarget": "isolated",
"payload": {
"kind": "agentTurn",
"message": "总结今天的收件箱和日程。",
"lightContext": true
},
"delivery": {
"mode": "announce",
"channel": "telegram",
"to": "-1001234567890",
"bestEffort": true
}
}投递模式
| 模式 | 说明 |
|---|---|
announce | 发送到目标频道，并在主会话发送简短摘要 |
webhook | HTTP POST 到指定 URL |
none | 仅内部执行，不投递 |
Telegram 频道主题（Forum Thread）
bash
openclaw cron add \
--name "夜间摘要" \
--cron "0 22 * * *" \
--tz "Asia/Shanghai" \
--session isolated \
--message "总结今天；发到夜间主题。" \
--announce \
--channel telegram \
--to "-1001234567890:topic:123"高级功能
模型和思维级别覆盖
隔离任务可以使用与主会话不同的模型：
bash
openclaw cron add \
--name "深度分析" \
--cron "0 6 * * 1" \
--tz "Asia/Shanghai" \
--session isolated \
--message "每周深度分析项目进展。" \
--model "opus" \
--thinking high \
--announce \
--channel telegram \
--to "你的Chat ID"多 Agent 指定
bash
# 将任务绑定到特定 Agent
openclaw cron add --name "运维检查" --cron "0 6 * * *" --session isolated --message "检查运维队列" --agent ops
# 修改现有任务的 Agent
openclaw cron edit <jobId> --agent ops轻量上下文（lightContext）
不需要工作区启动文件的任务可设置 --light-context，减少 Token 消耗：
bash
openclaw cron add --name "状态检查" --cron "*/30 * * * *" --session isolated --message "执行状态检查" --light-context --announce重试策略
一次性任务：
- 临时错误（限速、网络、5xx）：最多重试 3 次，指数退避（30s → 1m → 5m）
- 永久错误（认证失败、配置错误）：立即禁用
周期性任务：
- 任何错误：指数退避（30s → 1m → 5m → 15m → 60m）
- 任务保持启用；下次成功后退避重置
配置文件
json
{
"cron": {
"enabled": true,
"store": "~/.openclaw/cron/jobs.json",
"maxConcurrentRuns": 1,
"retry": {
"maxAttempts": 3,
"backoffMs": [60000, 120000, 300000]
},
"webhookToken": "your-token-here",
"sessionRetention": "24h",
"runLog": {
"maxBytes": "2mb",
"keepLines": 2000
}
}
}常用 CLI 命令
bash
# 列出所有任务
openclaw cron list
# 立即运行某任务
openclaw cron run <jobId>
# 查看运行历史
openclaw cron runs --id <jobId> --limit 50
# 编辑任务
openclaw cron edit <jobId> --message "更新的提示词"
# 删除任务
openclaw cron remove <jobId>
# 发送即时系统事件（不创建任务）
openclaw system event --mode now --text "下次心跳：检查电量。"常见问题排查
任务不执行：检查 cron.enabled 和 OPENCLAW_SKIP_CRON 环境变量；确认 Gateway 持续运行。
时区问题：确认 --tz 参数与预期时区一致（推荐使用 Asia/Shanghai）。
Telegram 投递到错误位置：论坛主题使用 -100…:topic:<id> 格式，明确指定主题 ID。
原文：Cron Jobs - OpenClaw | 来源：OpenClaw 官方文档