Scheduled Tasks (Cron)

Gateway 内置调度器，持久化任务定义，精确时间触发 Agent 运行。

快速开始

# 添加一次性提醒
openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run
 
# 查看任务列表
openclaw cron list
openclaw cron get <job-id>
openclaw cron show <job-id>
 
# 查看运行历史
openclaw cron runs --id <job-id>

工作原理

Cron 运行在 Gateway 进程内（不在模型内）
任务定义持久化：~/.openclaw/cron/jobs.json
运行时状态：~/.openclaw/cron/jobs-state.json（不需要 git 追踪）
所有 Cron 执行都创建后台任务记录
一次性任务（--at）成功后默认自动删除

调度类型

类型	CLI 标志	说明
`at`	`--at`	一次性时间戳（ISO 8601 或相对时间如 `20m`）
`every`	`--every`	固定间隔
`cron`	`--cron`	5/6 字段 cron 表达式，可加 `--tz`

无时区的时间戳视为 UTC。整点 cron 表达式自动错开最多 5 分钟（用 --exact 强制精确）。

注意：day-of-month 和 day-of-week 使用 OR 逻辑（标准 Vixie cron 行为）。

执行风格

风格	`--session` 值	运行位置	适合
主会话	`main`	下次心跳轮次	提醒、系统事件
隔离	`isolated`	专用 `cron:<jobId>`	报告、后台任务
当前会话	`current`	创建时绑定的会话	上下文感知的周期工作
自定义会话	`session:custom-id`	持久命名会话	构建历史的工作流

投递与输出

# 投递到 Slack channel
openclaw cron add \
  --name "Daily report" \
  --cron "0 9 * * 1-5" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate daily report" \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

Webhook 触发

外部系统可通过 HTTP POST 触发 Cron 任务：

# 注册 webhook 触发器
openclaw cron add \
  --name "GitHub webhook" \
  --webhook \
  --session isolated \
  --message "Process GitHub event: {{payload}}"

Gmail PubSub 触发

通过 Gmail PubSub 订阅触发 Agent 处理新邮件。

Wiki AI

目录