项目目标：把“定时任务”做成可控的工程能力

在很多团队里，定时任务往往从一段 crontab + 脚本开始，最终演变成“谁也不敢动”的黑盒：

• 定时触发不可靠：机器重启、时钟漂移、网络抖动导致漏跑或重复跑。
• 失败后没有补偿：偶发失败不重试，长期失败没人知。
• 通知不闭环：报警要么太吵要么没声音，无法定位到具体任务与执行实例。

本篇作为《OpenClaw教程：从入门到实战的分层学习路线》中的实战项目，聚焦一个可落地的“定时任务项目”最小闭环：

1) 定时触发（按 Cron/固定间隔触发）
2) 重试补偿（指数退避、最大重试、补偿重跑）
3) 告警通知（失败阈值、静默、聚合、渠道推送）

你可以把它理解为：用 OpenClaw 搭一个“任务调度 + 执行编排 + 可靠性保障”的基础能力。

架构拆解：调度、执行、状态、通知四个模块

一个可运维的定时任务系统，建议按以下 4 块拆开：

1) 调度器（Scheduler）

• 负责根据 Cron/间隔生成“本次要执行的任务实例”。
• 要解决：不漏触发、不重复触发（至少做到幂等可控）。

2) 执行器（Worker）

• 负责真正执行任务逻辑（HTTP 调用/SQL/脚本/消息投递等）。
• 要解决：超时、并发控制、资源隔离。

3) 状态存储（State Store）

• 保存任务定义、执行实例、执行结果、重试次数、下一次重试时间。
• 强烈建议把关键状态落到可靠存储（如数据库/Redis），而不是仅内存。

4) 通知与告警（Notifier）

• 根据策略发送通知：失败、连续失败、长时间未执行、延迟过高等。
• 要解决：去重、聚合、静默、分级。

OpenClaw 在你的工程里扮演“编排与执行控制”的核心。调度、存储和通知可以是 OpenClaw 的组件或你的配套模块，但要按这个思路把责任边界划清。

任务模型设计：用“任务定义 + 执行实例”避免混乱

建议你在 OpenClaw 定时任务项目里落地两个核心概念：

任务定义（Job）字段建议

• job_id：唯一标识
• name：任务名称
• schedule_type：cron / fixed_rate / fixed_delay
• schedule_expr：Cron 表达式或间隔秒数
• timezone：时区（避免跨区服务器导致的“跑错时间”）
• payload：执行参数（URL、SQL、业务参数等）
• concurrency_policy：并发策略（forbid/allow/replace）
• misfire_policy：错过触发策略（skip/catch_up_once/catch_up_all）
• enabled：是否启用

执行实例（Run）字段建议

• run_id：执行实例 ID（建议可追踪，如 job_id + planned_time）
• job_id
• planned_time：理论触发时间
• trigger_time：实际入队时间
• start_time / end_time
• status：pending/running/success/failed/canceled
• attempt：当前重试次数（从 0 开始）
• max_attempts
• next_retry_time
• last_error
• idempotency_key：幂等键（对外部系统调用尤其重要）

这套模型能让你做到：

• 每一次触发都可观测、可追溯
• 重试不是“覆盖日志”，而是“同一 run 的多次 attempt”
• 告警能精确指向 run_id 与失败原因

定时触发：三种常见策略与落地步骤

策略一：Cron 触发（推荐用于“固定时间点”）

适用：每日 02:00 对账、每周一生成报表等。

落地步骤：

1. 调度器每隔 N 秒（如 10 秒）扫描“未来一小段窗口”

   • 例如扫描未来 60 秒内所有应触发的 planned_time
2. 对每个 planned_time 生成一个 run 记录
3. 将 run 投递给 OpenClaw 执行（或进入队列等待 worker 拉取）
4. 写入状态存储：确保调度器重启后仍可恢复

关键点：防重复触发

• 以 (job_id, planned_time) 做唯一约束（数据库唯一索引）
• 若插入冲突，说明已触发过，直接跳过

策略二：Fixed Rate（固定频率，按节拍）

适用：每 5 分钟拉一次数据，强调“节拍”，可能出现任务执行时间超过间隔。

建议：结合 concurrency_policy=forbid 或 replace，避免堆积。

策略三：Fixed Delay（上次完成后延迟）

适用：每次完成后等 10 分钟再跑一次，强调“不要重叠”。

建议：用 Run 完成时间计算下一次 planned_time；若失败进入重试流程。

错过触发（Misfire）处理：别让“补跑”变成事故

服务器停机、发布重启、网络故障，都可能导致错过触发。

推荐的三种 misfire_policy

1) skip（跳过错过的）

• 适合：实时性不高、补跑意义不大
• 风险：数据缺口要接受

2) catch_up_once（补跑一次）

• 适合：日报/汇总类任务
• 行为：只补最近一次错过的 planned_time，避免狂补

3) catch_up_all（全部补跑）

• 适合：严格不丢的流水处理
• 风险：停机一晚可能补出成百上千个 run，容易压垮下游

工程建议：

• 给 catch-up 设置上限：如最多补 20 次
• 超过上限直接进入“人工处理告警”，而不是自动狂奔

重试补偿：从“重试”到“可控的失败恢复”

重试不是越多越好，核心是：可控、可观测、不放大故障。

失败分类：先决定“该不该重试”

建议把失败分为三类（可通过错误码/异常类型/返回体判断）：

1) 瞬时失败（可重试）

• 网络超时、503、连接重置、限流
  2) 确定性失败（不重试）
• 参数错误、鉴权失败、业务校验不通过
  3) 未知失败（有限重试 + 告警）
• 代码异常、第三方返回异常格式

落地做法：给任务定义一个 retry_policy：

• retry_on：可重试错误集合（HTTP 5xx、timeout、指定异常）
• max_attempts：如 5
• backoff：指数退避
• jitter：抖动，避免“同一时间集体重试”

指数退避（带抖动）的推荐参数

以 attempt 从 1 开始：

• base_delay = 10s
• delay = min( base_delay * 2^(attempt-1), 10min )
• delay = delay * random(0.7, 1.3)

这样做的好处：

• 短故障快速恢复
• 长故障逐步降压

补偿策略：失败后不只是重试

当达到 max_attempts 后，建议进入“补偿队列”或“人工介入队列”。常见补偿方式：

1) 延迟补偿：例如 2 小时后再补跑一次（不同于短期重试）
2) 降级执行：例如只做核心步骤，非核心跳过
3) 人工审批后重跑：防止重复扣费、重复发货等高风险任务

幂等：重试系统的生命线

重试会导致重复请求，必须确保：

• 对外部 API：传 idempotency_key（如 run_id）
• 对数据库写入：用唯一键约束或 upsert
• 对消息投递：使用去重表或幂等消费

示例：对账任务幂等键

• idempotency_key = job_id + planned_date
• 若同一天已生成对账单，则重试时只更新状态，不重复生成

告警通知：做到“少而准”，并能定位

告警不是发消息，而是让人能快速判断：

• 影响范围（哪个 job、影响多少 run）
• 是否需要立刻处理（严重度）
• 如何处理（链接、日志、参数、重跑入口）

告警触发规则（建议至少实现 4 类）

1) 单次失败告警（可选）

• 适合关键任务
• 可能噪音大，建议结合静默

2) 连续失败阈值（强烈推荐）

• 规则：同一 job 连续失败 >= 3 次触发
• 好处：过滤偶发抖动

3) 最终失败告警（必须）

• 规则：run 达到 max_attempts 后仍失败
• 包含：错误摘要、最后一次错误堆栈、run_id、重跑按钮/命令

4) 延迟/未执行告警（非常实用）

• 规则：超过 planned_time + grace_period 仍未开始/未完成
• 常见原因：队列堵塞、worker 掉线、并发策略阻塞

告警降噪：去重、聚合、静默

去重：同一个 job_id + error_signature 在 10 分钟内只发一次。

• error_signature 可取：错误类型 + 关键错误码 + 下游服务名

聚合：把 10 分钟内同一 job 的失败 run 汇总成一条：

• “10分钟内失败 12 次，成功 3 次，当前连续失败 5 次”

静默：允许运维设置维护窗口或临时静默时长。

通知内容模板（建议字段）

• 标题：[OpenClaw][Job失败][P1] job=xxx
• 关键信息：job_id、run_id、planned_time、attempt/max_attempts
• 错误摘要：错误类型、HTTP code/SQLState、异常栈首行
• 链接：执行详情页、日志查询、重跑入口、任务配置页
• 建议动作：如“下游 503，建议检查服务 A；可点击重试/补偿”

通知渠道按团队习惯接：企业微信/钉钉/Slack/邮件/短信。实现上建议抽象 Notifier 接口，便于替换。

实操落地：一个从 0 到 1 的实现清单

下面给出一个你可以直接照着做的迭代顺序（每一步都能上线、可验证）。

第 1 步：实现任务定义与执行实例表

• 建表/集合：Job、Run
• Run 表加唯一约束：(job_id, planned_time)
• Run 状态机：pending -> running -> success/failed

第 2 步：实现调度器的“窗口扫描 + 幂等插入”

• 每 10 秒扫描未来 60 秒内的 planned_time
• 对每个 planned_time 尝试插入 Run（冲突则跳过）
• 插入成功后把 run_id 投递给 OpenClaw 执行器

第 3 步：实现 Worker 执行与超时控制

• 统一封装执行函数：

  • 设置超时（如 60 秒）
  • 捕获异常并写入 last_error
  • 成功写 success + 输出摘要
• 并发控制：同一 job 根据 concurrency_policy 处理

第 4 步：实现重试策略（指数退避 + 最大次数）

• 当执行失败：

  • 判断是否可重试（错误分类）
  • attempt += 1
  • 计算 next_retry_time
  • 状态回到 pending（或单独状态 retry_wait）
• 调度器或一个重试扫描器负责把到期的 retry run 再次投递

第 5 步：实现告警

• 最小可用：最终失败告警 + 连续失败告警
• 增强：延迟告警 + 去重聚合
• 通知落地：至少一个渠道（如企业微信机器人）

第 6 步：补偿与运维入口

• 提供“手动重跑”能力：

  • 指定 job_id + planned_time 重新创建 run（或重置 run）

• 提供“补跑某段时间”的能力：

  • 输入起止时间，批量生成 run，但受上限控制

示例：一个“每日 02:10 拉取账单并入库”的任务如何配置

假设你的任务要做：每天 02:10 拉取第三方账单，写入数据库。

Job 配置建议

• schedule_type：cron
• schedule_expr：10 2 * * *
• timezone：Asia/Shanghai
• concurrency_policy：forbid（避免重叠入库）
• misfire_policy：catch_up_once（停机后补最近一次）

• retry_policy：

  • max_attempts=5
  • retry_on：timeout、HTTP 5xx
  • backoff：10s 指数退避，最大 10min
• idempotency_key：bill_date（或 run_id）

Run 执行逻辑要点

1) 先按账单日期检查是否已入库（幂等）
2) 调用第三方 API（带超时、带重试）
3) 入库使用 upsert/唯一键
4) 输出执行摘要：拉取条数、入库条数、耗时

告警策略

• 最终失败：P1（需要人工介入，避免账单缺口）
• 连续失败>=3：P2（可能第三方故障或凭证过期）
• 延迟>30分钟未完成：P2（队列/worker 堵塞）

常见坑与规避建议

1) 只靠内存计时

• 坑：重启就丢触发与重试
• 解法：Run 入库 + 扫描推进

2) 重试导致“雪崩式重放”

• 坑：所有任务同一时间失败又同一时间重试
• 解法：指数退避 + jitter + 限制全局重试并发

3) 告警过多导致“无人看”

• 坑：每次失败都发
• 解法：连续失败阈值 + 去重聚合 + 分级

4) 没有幂等

• 坑：重试导致重复扣费/重复入库
• 解法：idempotency_key + 唯一键 + 幂等消费

本篇小结：验收标准（你可以用它自测）

当你完成这个 OpenClaw 定时任务项目后，建议用以下标准验收：

• 定时触发：同一 job 不会因为调度器重启而漏跑；不会重复创建相同 planned_time 的 run。
• 重试补偿：失败后按策略重试，达到上限会进入最终失败，并可人工补跑。
• 告警通知：最终失败一定会通知到人；连续失败与延迟能提前暴露系统性问题；告警具备去重/聚合。
• 可追踪：任意一条告警都能定位到 run_id、日志与执行参数。

下一篇你可以在此基础上继续扩展：任务依赖编排（DAG）、分片任务、分布式锁与多活调度等，让 OpenClaw教程 的“定时任务能力”真正成为团队基础设施。