定时任务：一个住在 Gateway 里的调度室

一句话结论

定时任务完全跑在 Gateway 进程内部，调度、执行、投递、落库是一条闭环，任何一环断了都只在进程里表现为「本次 run 的状态」。

分工是明确的：worker 线程负责「哪个槽位到期了」（调度、队列容量、持久化结果），主线程负责「启动已提交的请求」。代码注释写得很直白：“The worker decides which slots are due; the host only launches committed requests.”（src/cron/service/scheduler-actor.ts:178）

四层组件，一条调用链

从协议定义到实际投递，「定时任务」被拆成四层，每层各自有专职文件。

← 表格可横向滚动 →

调用链：从启动到一次触发

1. Gateway 启动 → server-cron.ts:464 new CronService(deps)
2. CronService.start() service.ts:41 → ops-lifecycle.start() ops-lifecycle.ts:9
3. ensureLoaded + recoverCronRuns() 重启恢复，见 §05
4. startCronScheduler() service/scheduler-actor.ts:76 → 新建 BroadcastChannel("openclaw.cron.<uuid>")
5. worker 执行 cron.schedulerStart → runCronSchedulerInWorker() scheduler-actor.worker.ts:401
6. boundedCatchup() 启动补偿 → requestAndDrainCronRunsInWorker() 提交请求 / 认领 receipt → armActor() setTimeout ≤60s
7. 定时器到点（worker） → postMessage scheduler-actor.worker.ts:179-206
8. 主线程 tickCronScheduler() service/scheduler-actor.ts:115-125, 179 → worker 选出到期任务、提交请求、重新 arm
9. launchCronRunQueueResult() → executeJobCoreWithTimeout() timer-job-runner.ts:497
10. executeJobCore() timer-execution.ts:39 按 payload 分派 → 系统事件 / heartbeat / command / script / agentTurn
11. deliverPrimaryWebhook() timer-job-runner.ts:61, 416（webhook 模式）
12. worker 记录结果 + 写历史 + 算 nextRunAtMs → 重新 arm 回到第 1 步

一个 job 长什么样

权威定义是 CronJobSchema（packages/gateway-protocol/src/schema/cron.ts:463-499），运行时类型 CronJob（src/cron/types.ts:362-382）。

只在存储层存在、不对外暴露的字段在 CronStoredJob（types.ts:409-430）：inferenceBinding、sourceConversation（创建时绑定的结果回落会话）、skillLibrarySelections、createdActor、toolsAllowProvenance、runtimeAuthority 等。

schedule 的 kind：一共 6 种

注意：没有叫 interval 的 kind，固定间隔叫 every。

只有 at / every / cron 是按时间调度的（jobs-scheduling.ts:350-356）；其余三种由 watcher 驱动，不参与定时器 arm。

payload 的 kind：5 种，客户端只能建 4 种

sessionTarget 的默认值

• systemEvent / heartbeat → main
• agentTurn → current；调用方没有会话上下文时降级为 isolated（session-target.ts:39-48）
• command / script → isolated

state：运行时状态

公开字段见 CronJobStateSchema（cron.ts:413-447），内部扩展在 types.ts:299-334。分四组：

• 调度：nextRunAtMs、scheduleActivatedAtMs（防止改 schedule 后凭空产生「错过」槽位）、startupCatchupAtMs、pacedNextRunAtMs
• 运行标记：queuedAtMs、runningAtMs、runningReceiptId
• 结果：lastRunAtMs、lastRunStatus（ok / error / skipped）、lastError、lastDurationMs、lastDiagnostics
• 计数：consecutiveErrors、consecutiveSkipped、scheduleErrorCount、autoDisabled{reason, atMs, consecutiveErrors}
• 投递：lastDelivered、lastDeliveryStatus（delivered / not-delivered / unknown / not-requested）、lastDeliveryError、deliverySuppressionReason

一次性 vs 周期

它怎么醒过来，又在哪里跑

触发：worker 里的 setTimeout，单次最长 60s

• worker actor 每次处理完命令后调用 armActor()（scheduler-actor.worker.ts:208-251）：取所有 enabled、按时间调度、没有活动 run 的 job 中最小的 nextRunAtMs，然后 setTimeout。
• 单次 timer 最长 60s（timer-execution-timeout.ts:24）。更长的等待分段：醒来检查是否到 deadlineAtMs，没到继续睡。注释说明了原因：“Native timers alone cannot notice a clock step or suspend”（:247-248）。
• 到期后向所有订阅的 BroadcastChannel postMessage，并额外 arm 一个 60s 兜底 timer（:196-203）。
• 主线程 tickCronScheduler 串行执行（service/scheduler-actor.ts:115-125, 179-189），并先取 beginGatewayRootWorkAdmissionWhenOpen("cron:worker-tick")；Gateway 在 draining 时直接放弃本轮。
• 墙钟前跳检测：墙钟流逝与单调时钟流逝差超过 2s、或已过 wakeAtMs + 2s，标记 catchupNeeded 走补偿路径（:446-452, 471）。
• 防自旋：MIN_REFIRE_GAP_MS = 2_000。算出的 delay 为 0 时，wake 时间按 now + 2s 计（:245）。

到期之后的六步

1. 筛：isRunnableJob()（timer-runnable.ts:69-166）排除已在 queued / running 的、在错误退避窗口内的、以及已跑过的一次性任务。
2. 签发确定性 receipt：cron-slot-v1. + base64url([storeKey, jobId, slotMs])（run-request-id.ts:3-12）。同一个槽位重复提交会被拒，理由 already-requested。
3. 队列校验（run-queue.worker.ts:143-225）：job 存在、不在 queued/running、configRevision 未变、已启用（force 模式除外）、scheduledSlotMs 等于当前 nextRunAtMs、owner agent 可用、delivery mode 合法 —— 全部通过才认领 receipt。
4. 并发容量：同时运行的 run 上限 8（src/config/cron-limits.ts:3），超出的留在队列。resolveCronMaxConcurrentRuns() 直接返回常量，不可配置。
5. 分派：executeJobCoreWithTimeout → executeJobCore（timer-execution.ts:39-231）。顺序是：有 trigger 先跑条件脚本（fire:false 记 ok 但不执行 payload）→ script → heartbeat / heartbeat-task → sessionTarget=main → 其余走 detached（command 或 agentTurn）。
6. 落库与重排：worker 写结果、写历史、算 nextRunAtMs，重新 arm。

三种跑法：任务落在哪个会话

isolated run 结束后会尽力清理 cron:<jobId> 会话里的浏览器 tab 和 MCP runtime；已完成的 run 会话按 cron.sessionRetention 清理，默认 24h，false 或 0h 表示关闭（src/cron/session-reaper.ts:34, 81-102）。

另外，main + wakeMode="now" 会同步等 heartbeat 跑完；如果因为 busy 或 guard 被推迟，最多等 2 分钟就「交接」给 heartbeat 队列自己重试，此时本次 run 记为 ok（timer-execution.ts:279-316）。所以 ok 不代表 agent 已经回复。

结果往哪儿送

默认值：agentTurn / command / script 配 isolated / current / session:* 且没写 delivery 时，默认 {mode:"announce"}，channel 为 "last"（delivery-defaults.ts:9-25）。main + systemEvent 默认 none，输出走 heartbeat 自己的投递。

目标解析的五个判断

1. 有 sourceConversation 且没显式目标时，先确认创建它的会话这一代还存在；不存在直接失败，错误是 “Creating conversation unavailable”。
2. 用会话条目里记录的 last route 解析 channel 和 to；没有 last channel 时回落到已配置的渠道。
3. accountId 优先级：job 显式值 → 会话 lastAccountId → agent bindings 的第一个绑定账号。
4. implicit 模式下，目标不在渠道 allowFrom 里时改发给 allowFrom 的第一个对象。
5. 拒绝从共享 agent-main 会话继承 last 收件人：没有自己的会话 key、没有显式 to、又用了共享 main 兜底时直接报错（delivery-target.ts:323-343，见 #91613）。

发送、重试与幂等

• 实际发送走持久化出站队列 sendDurableMessageBatchCore（src/cron/delivery.ts:51-208）。幂等键 buildDirectCronDeliveryIdempotencyKey({jobId, runStartedAt, delivery})：重试或恢复时发现已发送完成就不再重发。
• durability = bestEffort ? "best_effort" : "required"。
• 瞬时失败重试：5s / 10s / 20s，共 4 次尝试。只重试「可证明没送达」的错误；一旦可能已到达收件人就不再重试（shouldRetryError: () => !recipientReached）。
• webhook 模式由 deliverPrimaryWebhook 处理，鉴权用 cron.webhookToken（Bearer），SSRF 策略用 cron.webhookSsrfPolicy；结果分 delivered / not-delivered / unknown。

失败告警默认连续 2 次才发、冷却 1h、默认不含 skipped；路由按 全局 cron.failureAlert → delivery.failureDestination → job failureAlert 逐层覆盖，和主投递目标相同时不重复发。

超时、重试、补偿、去重

timeoutSeconds 到底管多长

这是调度器的墙钟预算，和模型单次尝试的超时（agents.defaults.timeoutSeconds）是两套东西，fallback 换模型不会重置这个预算。对 isolated agentTurn，墙钟超时推迟到 runner 启动后才开始计时；启动前另有阶段看门狗：setup 60s，pre-execution 取 min(60s, jobTimeout/2)、最少 1s。超时后 abort，等清理最多 20s，然后强制清掉会话占用。

失败退避与自动禁用

退避从「运行结束时间」开始算，不是从原定槽位（timer-runnable.ts:132-136；jobs-scheduling.ts:74-80, 130-156）。

• 瞬时错误快重试：rate_limit / overloaded / network / timeout / server_error 可重试，最多 3 次，退避取上面序列的前 3 档。retryOn 写死为 undefined（五类全重试），没有用户配置入口。
• 会话生命周期竞争类错误只在 executionStarted !== true 时重试 —— 执行开始后，工具可能已经产生了不可重放的副作用。
• 周期任务：重试时间早于下一个自然槽位时，安排一次额外重试；否则取 max(自然槽位, 结束时间 + 退避)。
• 自动禁用：运行失败连续 10 次（auto-disable.ts:11-15）；schedule 计算出错连续 3 次（jobs-scheduling.ts:412-450）。禁用后会通知 owner，用 openclaw automations enable <id> 恢复。
• 被取消（errorClassification.kind === "aborted"）的 run 不计入失败，也不告警。

错过的任务：重启后怎么补

boundedCatchup（scheduler-actor.worker.ts:262-399）只在 cron.schedulerStart 或检测到墙钟前跳时运行。

• 每个 job 最多补一次。判定看「最近一个应触发的槽位」是否晚于上次运行（hasMissedCronSlotSinceLastRun），不会把重启期间错过的多个槽位逐个重放。
• 槽位早于 scheduleActivatedAtMs（即修改 schedule 之前）的不算错过（#91944）。
• 按 nextRunAtMs 从早到晚排序：最多立即补 5 个，其余每个间隔 5s 错开，并且要等立即批次跑完后才开始。
• agent 类工作（agentTurn、heartbeat、heartbeat-task、main+systemEvent+wakeMode=now）启动时不立即执行，统一推迟 2 分钟；推迟点写进 startupCatchupAtMs，重启后仍然有效。
• cron.skipMissedJobs: true 时周期任务直接跳到下一个槽位，不补；一次性任务不受影响。
• 5 个 / 5s / 2min 这三个常量只能通过 CronServiceDeps 注入，Gateway 没有暴露成用户配置。

跑到一半崩溃：不重放

recoverCronRuns（service/run-recovery.ts:10-34）处理三种死状态：

• 有 runningAtMs 且能找到本次 run 已落库的终态 → 直接恢复这个结果，不重新执行 payload，也不重投。
• 找不到终态 → 记为 interrupted，投递状态 Unknown，历史里显示失败。中断的一次性任务保持 disabled，需要人工检查后手动重跑；周期任务继续按后续槽位调度。
• 只有 queuedAtMs（还没开跑）时，带槽位 ID 的定时请求可以恢复；manual 或 event 请求丢了瞬时上下文的，记 skipped，错误是 queued request lost its launch context。

这是有意的取舍：宁可在崩溃窗口里丢一次执行，也不重放「命令 / 工具 / 投递」这类不确定是否已生效的副作用。

并发、去重与存储

• 同一个 job 同时最多一个 run：状态层有 queuedAtMs 或 runningAtMs 时不再入队；数据库层 cron_run_receipts 上有唯一部分索引 (store_key, job_id) WHERE status='running'。
• 同一个槽位不会重复：receipt ID 由 (storeKey, jobId, slotMs) 确定性生成，已存在的会被拒绝并修复已消费的 nextRunAtMs。
• 全局并发 8；投递去重靠出站队列的 intent id。
• 存储：任务定义、运行状态、历史全在共享 SQLite ~/.openclaw/state/openclaw.sqlite。表：cron_jobs、cron_run_receipts、cron_job_runtime_authorities、cron_job_scratch、cron_run_trigger_state_retirements；run 历史在 task_runs 里 runtime='cron' 的行。写入发生在 worker 线程的同步事务里。

它和 heartbeat 是什么关系

当前版本里，heartbeat 本身就是一个 cron job，由同一个调度器定时。

resolveHeartbeatMonitorPlan 为每个启用 heartbeat 的 agent 声明式 upsert 一个系统自有 job（heartbeat-monitor.ts:73-121）：declarationKey="<HEARTBEAT_PREFIX><agentId>"、schedule={kind:"every", everyMs, anchorMs:按种子算的相位}、payload={kind:"heartbeat"}、sessionTarget:"main"、wakeMode:"next-heartbeat"，默认间隔 30 分钟。旧版 heartbeat 的 tasks 会被 doctor 迁移成 systemEvent + main 的 cron job。

两者的交叉点：sessionTarget="main" 的 systemEvent 任务依赖 heartbeat runner 来消费事件。heartbeat 被禁用或延后，main 任务就会记 skipped；一次性 main + now 任务遇到「heartbeat disabled」时有专门的退避重试，最多 3 次。

十七个容易踩的地方

全部来自代码与注释，不是经验之谈。每条都附了可以自己去核的行号。

1. cron 表达式默认用宿主机时区

   容器里 TZ 往往是 UTC，0 9 * * * 会在 UTC 9 点触发。建议总是写 tz。

   schedule.ts:16-22
2. 整点任务会被自动错开最多 5 分钟

   0 * * * *、0 9 * * * 这类表达式创建时会被写入 staggerMs=300000，偏移由 jobId 的 sha256 决定。要准点必须显式写 staggerMs: 0。

   stagger.ts:10-11 normalize.ts:469-478
3. 重启补偿只补一次，agent 任务还要再推迟 2 分钟

   容器停了一整天，每个 job 也只补跑一次；agentTurn 和 heartbeat 类在启动后约 2 分钟才跑；一次最多立即跑 5 个，其余每 5s 一个。开 cron.skipMissedJobs 后周期任务完全不补。

   scheduler-actor.worker.ts:253-260, 347-374
4. 崩溃时正在跑的任务不会重放

   会记 interrupted，投递状态 Unknown。中断的一次性任务保持 disabled，需要手动处理。

   run-recovery.kernel.ts:202-223
5. 一次性任务失败不会自动删除

   deleteAfterRun 只在 completion=succeeded 时生效；投递失败（必需投递 not-delivered）也会让一次性任务以 disabled 状态留在存储里。

   timer-outcomes.ts:215-220, 355-362
6. 投递失败不计入 consecutiveErrors

   run 仍是 ok，只记 lastDeliveryError，所以投递一直失败也不会触发自动禁用。只有配了独立失败告警路由才会收到 “delivery failed”。排查看 lastDeliveryStatus。

   failure-alerts.ts:575-614
7. channel:"last" 的隐式投递可能被拒绝

   用共享 agent-main 会话的 last 收件人兜底时会直接报错，防止发到别的群（#91613）。稳妥做法是显式写 delivery.channel + delivery.to，多账号再加 accountId。

   delivery-target.ts:323-343
8. sessionTarget:"main" 只会进 agent 的主会话

   代码没有把 job.sessionKey 传给 enqueueSystemEvent，它只用来取 deliveryContext。想在指定会话里跑，用 session:<id>，但它对应的 payload 应该是 agentTurn。

   timer-execution.ts:262-269
9. wakeMode 默认是 now

   next-heartbeat 下 run 立即记 ok，但真正执行要等下一次 heartbeat，最长约一个间隔（默认 30 分钟）。now 下 heartbeat busy 时最多等 2 分钟，然后「交接」并记为 ok。所以 ok 不代表 agent 已经回复。

   timer-execution.ts:289-316
10. timeoutSeconds: 0 表示不限时

    不是「立刻超时」。不设时 agentTurn 有 60 分钟兜底。

    timeout-policy.ts:30
11. isolated 的 systemEvent 会被跳过

    isolated / current 目标只接受 agentTurn 或 command；配了 systemEvent 会记 skipped，错误信息是 isolated job requires payload.kind="agentTurn" or "command"。

    timer-execution.ts:400-410
12. jobs.json 只是分区键

    状态全在 SQLite。resolveCronJobsStorePath 仍返回 <configDir>/cron/jobs.json，但它只作为 SQLite 的 store_key；磁盘上不一定有这个文件，找它或手改它没有意义。

    store/paths.ts:7-13 store/key.ts:4-7
13. 并发上限 8 和瞬时重试策略都写死了

    resolveCronMaxConcurrentRuns() 直接返回常量；retryOn 也是写死的。没有配置入口。

    cron-limits.ts:3-9 timer-trigger.ts:32, 170
14. 改 schedule 不会产生错过的槽位

    scheduleActivatedAtMs 会屏蔽修改前的槽位（#91944）。这是有意设计，不是 bug。

    timer-runnable.ts:59-66
15. 默认创建为 enabled 是有意的安全选择

    文档的解释：disabled 的任务不受任何监督，会「静默不执行」，比运行后报错更糟。

    docs/automation/cron-jobs/how-it-works.md
16. 整个调度依赖 Gateway 进程在运行

    OPENCLAW_SKIP_CRON=1 或 cron.enabled:false 会关掉调度。外部用系统 cron 调 openclaw agent 时，文档建议加硬杀兜底，例如 timeout -k 60 600 …。

    server-cron.ts:158-159
17. 架构还在演进

    docs/refactor/cron-worker-owned.md 是「worker 持有调度」的分阶段重构提案，行号基于旧基线 7517981b。当前代码已有 scheduler-actor.worker.ts 这条路径，但提案逐项落地到什么程度：未逐项确认。

    docs/refactor/cron-worker-owned.md
18. 「现在到底跑没跑」要四处对齐看

    lastRunStatus 说执行，lastDeliveryStatus 说送达，consecutiveErrors 说健康度，autoDisabled 说是否已被停用 —— 四者可以互相矛盾（例如 ok + not-delivered）。只看一个字段就会误判。

    types.ts:299-334 completion-status.ts:18-62

附：关键常量速查