OpenClaw 定时任务 (Cron Jobs) 操作指南 版本V2026.3.11

OpenClaw 定时任务 (Cron Jobs) 操作指南

一、什么是定时任务

定时任务让你可以设置"在某个时间自动执行某个任务"，比如：

• ⏰ 每天早上 8 点发送日报
• ⏰ 每 30 分钟检查一次邮箱
• ⏰ 20 分钟后提醒我开会

二、文件存储位置

~/.openclaw/cron/jobs.json          # 所有定时任务都存这里
~/.openclaw/cron/runs/<job-id>.jsonl # 每个任务的运行历史记录

三、完整操作流程

场景 1：创建一次性提醒（20 分钟后）

# 第 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 点发日报）

# 第 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：创建每小时检查任务

# 第 1 步：添加任务
openclaw cron add \
  --name "每小时检查" \
  --every "1h" \
  --session isolated \
  --message "检查是否有紧急邮件或消息" \
  --announce \
  --channel telegram \
  --to "xxxxxxxxxx". #telegram id

四、常用命令速查

# 查看所有任务
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 群聊

--announce --channel telegram --to "xxxxxxxx" #telegram id

发送到 Telegram 主题/帖子

--announce --channel telegram --to "xxxxxxxx:topic:123" #telegram id

发送到 WhatsApp

--announce --channel whatsapp --to "+8613800138000"

不发送（仅后台运行）

# 不加 --announce 参数即可

七、主会话 vs 隔离式

类型	参数	适用场景
主会话	--session main	需要主会话上下文，任务较少
隔离式	--session isolated	频繁任务、后台杂务，不污染主聊天

建议 ：周期性任务优先用 isolated，避免主会话记录太乱。

八、配置文件

全局配置（可选）

编辑 ~/.openclaw/config.json：

{
  cron: {
    enabled: true,              // 是否启用定时任务
    store: "~/.openclaw/cron/jobs.json",  // 任务存储位置
    maxConcurrentRuns: 1,       // 最多同时运行几个任务
  }
}

任务存储文件

~/.openclaw/cron/jobs.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
    }
  ]
}

九、故障排查

任务不运行

# 1. 检查定时任务是否启用
cat ~/.openclaw/config.json | grep cron

# 2. 检查 Gateway 是否在运行
openclaw gateway status

# 3. 查看任务状态
openclaw cron status --id <job-id>

时区不对

确保添加 --tz 参数：

--tz "Asia/Shanghai"  # 中国时区
--tz "America/Los_Angeles"  # 美国西部时区

Telegram 发送到错误位置

论坛主题使用明确格式：

--to "xxxxxxxxx:topic:123"  # 推荐格式 telegram id

十、完整示例：从零创建日报任务

# 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