OpenClaw 定时任务 (Cron Jobs) 操作指南
一、什么是定时任务
定时任务让你可以设置"在某个时间自动执行某个任务"，比如：
- ⏰ 每天早上 8 点发送日报
- ⏰ 每 30 分钟检查一次邮箱
- ⏰ 20 分钟后提醒我开会
二、文件存储位置
~/.openclaw/cron/jobs.json # 所有定时任务都存这里
~/.openclaw/cron/runs/<job-id>.jsonl # 每个任务的运行历史记录三、完整操作流程
场景 1：创建一次性提醒（20 分钟后）
bash
# 第 1 步：添加任务
openclaw cron add \
--name "开会提醒" \
--at "20m" \
--session main \
--system-event "提醒：20 分钟后有会议，记得准备材料" \
--wake now
# 第 2 步：查看任务列表（确认已添加）
openclaw cron list
# 第 3 步：查看任务运行历史（运行后查看）
openclaw cron runs --id <job-id> --limit 5场景 2：创建周期性任务（每天早上 7 点发日报）
bash
# 第 1 步：添加任务
openclaw cron add \
--name "每日日报" \
--cron "0 7 * * *" \
--tz "Asia/Shanghai" \
--session isolated \
--message "总结昨天的工作进展，列出今天的计划" \
--announce \
--channel telegram \
--to "-1003844379529"
# 第 2 步：查看任务列表
openclaw cron list
# 第 3 步：手动测试运行（不等到第二天）
openclaw cron run <job-id> --force场景 3：创建每小时检查任务
bash
# 第 1 步：添加任务
openclaw cron add \
--name "每小时检查" \
--every "1h" \
--session isolated \
--message "检查是否有紧急邮件或消息" \
--announce \
--channel telegram \
--to "xxxxxxxxxx". #telegram id四、常用命令速查
bash
# 查看所有任务
openclaw cron list
# 查看任务详情
openclaw cron status --id <job-id>
# 手动运行任务（调试用）
openclaw cron run <job-id> --force
# 编辑任务（修改提示词/模型等）
openclaw cron edit <job-id> --message "新的提示词"
# 删除任务
openclaw cron remove <job-id>
# 查看运行历史
openclaw cron runs --id <job-id> --limit 10五、调度类型详解
| 类型 | 参数 | 示例 | 说明 |
|---|---|---|---|
| 一次性 | --at |
--at "20m" |
20 分钟后执行一次 |
| 一次性 | --at |
--at "2026-03-13T10:00:00" |
指定时间执行 |
| 固定间隔 | --every |
--every "1h" |
每 1 小时执行一次 |
| Cron 表达式 | --cron |
--cron "0 7 * * *" |
每天早上 7 点 |
Cron 表达式快速参考
* * * * *
│ │ │ │ │
│ │ │ │ └─ 星期几 (0-7, 0 和 7 都是周日)
│ │ │ └─── 月份 (1-12)
│ │ └───── 日期 (1-31)
│ └─────── 小时 (0-23)
└───────── 分钟 (0-59)
常用示例:
"0 7 * * *" → 每天早上 7:00
"*/30 * * * *" → 每 30 分钟
"0 9 * * 1-5" → 工作日早上 9:00
"0 0 1 * *" → 每月 1 号零点六、投递配置（任务结果发到哪里）
发送到 Telegram 群聊
bash
--announce --channel telegram --to "xxxxxxxx" #telegram id发送到 Telegram 主题/帖子
bash
--announce --channel telegram --to "xxxxxxxx:topic:123" #telegram id发送到 WhatsApp
bash
--announce --channel whatsapp --to "+8613800138000"不发送（仅后台运行）
bash
# 不加 --announce 参数即可七、主会话 vs 隔离式
| 类型 | 参数 | 适用场景 |
|---|---|---|
| 主会话 | --session main |
需要主会话上下文，任务较少 |
| 隔离式 | --session isolated |
频繁任务、后台杂务，不污染主聊天 |
建议 ：周期性任务优先用 isolated，避免主会话记录太乱。
八、配置文件
全局配置（可选）
编辑 ~/.openclaw/config.json：
json5
{
cron: {
enabled: true, // 是否启用定时任务
store: "~/.openclaw/cron/jobs.json", // 任务存储位置
maxConcurrentRuns: 1, // 最多同时运行几个任务
}
}任务存储文件
~/.openclaw/cron/jobs.json 内容示例：
json
{
"jobs": [
{
"jobId": "abc123",
"name": "每日日报",
"schedule": {
"kind": "cron",
"expr": "0 7 * * *",
"tz": "Asia/Shanghai"
},
"sessionTarget": "isolated",
"payload": {
"kind": "agentTurn",
"message": "总结昨天的工作进展"
},
"delivery": {
"mode": "announce",
"channel": "telegram",
"to": "xxxxxxxx" #telegram id
},
"enabled": true
}
]
}九、故障排查
任务不运行
bash
# 1. 检查定时任务是否启用
cat ~/.openclaw/config.json | grep cron
# 2. 检查 Gateway 是否在运行
openclaw gateway status
# 3. 查看任务状态
openclaw cron status --id <job-id>时区不对
确保添加 --tz 参数：
bash
--tz "Asia/Shanghai" # 中国时区
--tz "America/Los_Angeles" # 美国西部时区Telegram 发送到错误位置
论坛主题使用明确格式：
bash
--to "xxxxxxxxx:topic:123" # 推荐格式 telegram id十、完整示例：从零创建日报任务
bash
# 1. 创建任务
openclaw cron add \
--name "工作日报" \
--cron "0 20 * * *" \
--tz "Asia/Shanghai" \
--session isolated \
--message "总结今天完成的工作，列出明天计划，用简洁的格式" \
--announce \
--channel telegram \
--to "xxxxxxxxxx" #telegram id
# 2. 确认任务已创建
openclaw cron list
# 3. 复制 job-id（从列表输出中）
# 假设 job-id 是 "daily-report-001"
# 4. 手动测试运行
openclaw cron run daily-report-001 --force
# 5. 查看运行结果
openclaw cron runs --id daily-report-001 --limit 3