CLI — openclaw cron

概述

openclaw cron 管理 Gateway 调度器的定时任务。CLI 命令是对 Gateway WebSocket RPC（cron.list、cron.get 等）的封装，详见 cron-ws-protocol。

openclaw cron list [--agent <id>] [--json]
openclaw cron get <job-id>
openclaw cron show <job-id> [--json]
openclaw cron add --name <name> --cron <expr> --session <type> --message <text> [options]
openclaw cron edit <job-id> [options]
openclaw cron run <job-id> [--due]
openclaw cron runs --id <job-id> [--limit N]

三种查看命令的区别：

命令	对应 WS 方法	输出
`cron list`	`cron.list`	表格（默认）或带计算 `status` 字段的 JSON
`cron get <id>`	`cron.get`	原始 job JSON（无额外计算）
`cron show <id>`	`cron.status`	人类可读视图 + 投递路由预览

cron list --json 和 cron show --json 在每个 job 上附加计算出的 status 字段（disabled / running / ok / error / skipped / idle），由 enabled、state.runningAtMs、state.lastRunStatus 推导。

Session 类型

--session 接受以下值：

值	说明
`main`	绑定到 agent 的主会话
`isolated`	每次运行创建全新 transcript 和 session id
`current`	绑定到创建时的活跃会话
`session:<id>`	固定到指定的持久 session key

isolated 运行会重置环境上下文（渠道路由、队列策略、elevation、ACP 绑定等）。

调度

一次性任务

openclaw cron add --name "提醒" --at "2026-05-15T09:00:00" --session isolated --message "检查部署"
openclaw cron add --name "提醒" --at "2026-05-15T09:00:00" --tz "Asia/Shanghai" --session isolated --message "检查部署"

--at <datetime> 无时区偏移时视为 UTC，加 --tz <iana> 按本地时区解释
成功后默认删除；--keep-after-run 保留

周期性任务

使用标准 cron 表达式（5 字段）。连续失败后指数退避重试：30s → 1m → 5m → 15m → 60m，下次成功后恢复正常。

跳过的运行单独追踪，不影响重试退避。

手动运行

openclaw cron run <job-id>        # 强制立即运行
openclaw cron run <job-id> --due  # 仅在到期时运行

返回 { ok: true, enqueued: true, runId }，用 openclaw cron runs --id <job-id> 跟踪结果。

投递

投递模式

模式	说明
`--announce`	runner 回退投递最终回复（isolated 任务默认）
`--no-deliver`	禁用 runner 回退投递（不移除 agent 的 `message` 工具）
`--webhook`	将完成 payload POST 到 URL

isolated 任务中 agent 可直接用 message 工具发送；announce 仅在 agent 未直接发送时作为回退。

失败投递解析顺序

任务的 delivery.failureDestination
全局 cron.failureDestination
任务的主 announce 目标

静默 token

isolated 运行返回 NO_REPLY/no_reply 时，抑制所有投递，不发送任何内容。

模型配置

openclaw cron add --model openai/gpt-5.4-mini ...
openclaw cron edit <job-id> --model anthropic/claude-haiku-4-5

isolated cron 模型解析优先级：

Gmail-hook 覆盖
任务 --model
存储的 cron-session 模型覆盖
Agent 或默认模型

模型不允许或无法解析时，运行失败（不回退到 agent 默认模型）。

常用管理命令

# 查看任务
openclaw cron list
openclaw cron list --agent ops
openclaw cron show <job-id>          # 含投递路由预览
openclaw cron get <job-id>           # 原始 JSON
 
# 编辑投递
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --no-deliver
openclaw cron edit <job-id> --best-effort-deliver
 
# 编辑 agent/session
openclaw cron edit <job-id> --agent ops
openclaw cron edit <job-id> --clear-agent
openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"
 
# 轻量 bootstrap（仅 isolated 任务）
openclaw cron edit <job-id> --light-context

创建轻量 isolated 任务示例：

openclaw cron add \
  --name "Lightweight morning brief" \
  --cron "0 7 * * *" \
  --session isolated \
  --message "Summarize overnight updates." \
  --light-context \
  --no-deliver

保留与维护

cron.sessionRetention（默认 24h）：清理已完成的 isolated 运行会话
cron.runLog.maxBytes / cron.runLog.keepLines：清理 ~/.openclaw/cron/runs/<jobId>.jsonl
旧格式迁移：openclaw doctor --fix

Wiki AI

目录