计划任务

​

快速开始

openclaw cron create "2026-02-01T16:00:00Z" \
  --name "提醒" \
  --session main \
  --system-event "提醒：检查 cron 文档草稿" \
  --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 的工作方式

• Cron 在 Gateway 进程内部运行（不在模型内部）。
• 作业定义、运行时状态和运行历史会持久化到 OpenClaw 共享的 SQLite 状态数据库中，因此重启不会丢失计划任务。
• 升级时，运行 openclaw doctor --fix 可将旧的 ~/.openclaw/cron/jobs.json、jobs-state.json 和 runs/*.jsonl 文件导入 SQLite，并以 .migrated 后缀重命名。格式异常的作业行会被跳过运行时处理，并复制到 jobs-quarantine.json 供后续修复或审查。
• cron.store 仍然是逻辑 cron 存储键和 doctor 导入路径的名称。导入后，编辑该 JSON 文件将不再更改活动的 cron 作业；请改用 openclaw cron add|edit|remove 或 Gateway cron RPC 方法。
• 所有 cron 执行都会创建 后台任务 记录。
• 在 Gateway 启动时，逾期的独立 agent-turn 作业会被重新安排到 channel-connect 窗口之外，而不是立即回放，因此 Discord/Telegram 启动和原生命令设置在重启后仍能保持响应。
• 一次性作业（--at）默认在成功后自动删除。
• 独立 cron 在完成时会尽最大努力关闭其 cron:<jobId> 会话下追踪到的浏览器标签页/进程，因此分离式浏览器自动化不会留下孤儿进程。
• 收到狭义的 cron 自清理授权的独立 cron 运行，仍然可以读取调度器状态、当前作业的自过滤列表以及该作业的运行历史，因此状态/heartbeat 检查可以在不获得更广泛的 cron 修改权限的情况下检查自己的计划任务。
• 独立 cron 运行还会防止过时的确认回复。如果第一个结果只是中间状态更新（on it、pulling everything together 以及类似提示），并且没有任何后代子 agent 运行仍负责最终答案，OpenClaw 会在交付前重新提示一次以获取实际结果。
• 独立 cron 运行会使用来自嵌入式运行的结构化执行拒绝元数据，包括其嵌套错误消息以 SYSTEM_RUN_DENIED 或 INVALID_REQUEST 开头的 node-host UNAVAILABLE 包装，因此被阻止的命令不会被报告为成功运行，而普通的助手文本也不会被当作拒绝。
• 独立 cron 运行也会将运行级 agent 失败视为作业错误，即使没有产生回复载荷也是如此，因此模型/提供方失败会增加错误计数并触发失败通知，而不是将作业清空为成功状态。
• 当独立 agent-turn 作业达到 timeoutSeconds 时，cron 会中止底层 agent 运行并给它一个短暂的清理窗口。如果运行没有退出，Gateway 托管的清理会在 cron 记录超时之前强制清除该运行的会话所有权，因此排队中的聊天工作不会因一个陈旧的处理会话而被遗留。
• 如果独立 agent-turn 在 runner 启动前或首次模型调用前停滞，cron 会记录特定阶段的超时，例如 setup timed out before runner start 或 stalled before first model call (last phase: context-engine)。这些看门狗适用于嵌入式提供方和 CLI 后备提供方，在其外部 CLI 进程真正启动之前就会生效，并且与较长的 timeoutSeconds 值独立限额，因此冷启动/认证/上下文失败会更快暴露，而不是等待整个作业预算耗尽。
• 如果你使用系统 cron 或其他外部调度器来运行 openclaw agent，即使 CLI 会处理 SIGTERM/SIGINT，也应给它包上一层硬杀升级。Gateway 托管的运行会请求 Gateway 中止已接受的运行；本地和嵌入式回退运行会收到相同的中止信号。对于 GNU timeout，应优先使用 timeout -k 60 600 openclaw agent ...，而不是单纯的 timeout 600 ...；其中 -k 值是当进程无法正常退出时的监督层后备。对于 systemd 单元，也应保持相同的形态：使用 SIGTERM 停止信号加上一个宽限窗口，例如 TimeoutStopSec，然后再进行最终 kill。如果某次重试在原始 Gateway 运行仍处于活动状态时复用了 --run-id，重复请求会被报告为正在进行中，而不会启动第二次运行。

​

计划类型

​

月中的日期和星期采用 OR 逻辑

# 期望："15 日上午 9 点，且仅当那天是星期一"
# 实际：  "每个 15 日上午 9 点，以及每个星期一上午 9 点"
0 9 15 * 1

​

执行样式

​

Command payloads

openclaw cron create "*/15 * * * *" \
  --name "Queue depth probe" \
  --command "scripts/check-queue.sh" \
  --command-cwd "/srv/app" \
  --announce \
  --channel telegram \
  --to "-1001234567890"

​

Payload options for isolated jobs

1. Gmail hook 模型覆盖（当运行来自 Gmail 且该覆盖被允许时）
2. 每个作业的载荷 model
3. 用户选择的已存储 cron 会话模型覆盖
4. Agent/default 模型选择

​

交付与输出

​

输出语言

openclaw cron edit <jobId> \
  --message "总结更新。请用中文回复；保留 URL、代码和产品名称不变。"

• cron.failureDestination 设置失败通知的全局默认值。
• job.delivery.failureDestination 可按作业覆盖该设置。
• 如果两者都未设置，且作业已经通过 announce 交付，那么失败通知现在会回退到该主 announce 目标。
• delivery.failureDestination 仅在 sessionTarget="isolated" 的作业上受支持，除非主要交付模式是 webhook。
• failureAlert.includeSkipped: true 可让作业或全局 cron 告警策略纳入重复的跳过运行告警。跳过运行会保留单独的连续跳过计数，因此不会影响执行错误退避。

​

CLI 示例

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "下一次 heartbeat：检查日历。"
  --wake now

openclaw cron create "0 7 * * *" \
  "总结昨夜更新。" \
  --name "Morning brief" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "每周对项目进展进行深度分析。" \
  --model "opus" \
  --thinking high \
  --announce

openclaw cron create "0 18 * * 1-5" \
  "将今天的部署总结为 JSON。" \
  --name "Deploy digest" \
  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \
  --name "Queue depth probe" \
  --command "scripts/check-queue.sh" \
  --command-cwd "/srv/app" \
  --announce \
  --channel telegram \
  --to "-1001234567890"

​

Webhook

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

​

认证

• Authorization: Bearer <token>（推荐）
• x-openclaw-token: <token>

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"收到新邮件","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"总结收件箱","name":"Email","model":"openai/gpt-5.4"}'

​

Gmail PubSub 集成

​

向导设置（推荐）

openclaw webhooks gmail setup --account [email protected]

​

Gateway 自动启动

​

手动一次性设置

gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:[email protected] \
  --role=roles/pubsub.publisher

gog gmail watch start \
  --account [email protected] \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

​

Gmail 模型覆盖

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

​

管理作业

# 列出所有作业
openclaw cron list

# 以 JSON 形式获取一个已存储的作业
openclaw cron get <jobId>

# 显示一个作业，包括解析后的传递路由
openclaw cron show <jobId>

# 编辑一个作业
openclaw cron edit <jobId> --message "已更新提示词" --model "opus"

# 立即强制运行一个作业
openclaw cron run <jobId>

# 现在强制运行一个作业并等待其终态
openclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s

# 仅在到期时运行
openclaw cron run <jobId> --due

# 查看运行历史
openclaw cron runs --id <jobId> --limit 50

# 查看一次精确运行
openclaw cron runs --id <jobId> --run-id <runId>

# 删除一个作业
openclaw cron remove <jobId>

# 代理选择（多代理设置）
openclaw cron create "0 6 * * *" "检查运维队列" --name "Ops sweep" --session isolated --agent ops
openclaw cron edit <jobId> --clear-agent

​

配置

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 8,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

​

故障排除

​

命令序列

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

​

相关内容

• 自动化 — 一览所有自动化机制
• 后台任务 — cron 执行的任务账本
• 心跳 — 周期性的主会话轮次
• 时区 — 时区配置