Cron 调度模块总览

OpenClaw 的 cron 模块是一个生产级分布式任务调度系统，位于 src/cron/，共约 172 个 TypeScript 文件。

核心职责

• 管理定时任务的生命周期（创建/更新/删除/启用/禁用）
• 按调度计划触发 Agent 执行或系统事件
• 将执行结果交付到消息渠道或 Webhook
• 持久化任务配置与运行状态

目录结构

src/cron/
├── types.ts                    # 主类型定义
├── types-shared.ts             # 共享基础类型
├── service.ts                  # CronService 主类
├── service-contract.ts         # 服务接口契约
├── schedule.ts                 # 调度计算引擎
├── parse.ts                    # 时间解析
├── stagger.ts                  # 错开机制
├── normalize.ts                # 数据规范化
├── normalize-job-identity.ts   # 任务标识规范化
├── delivery.ts                 # 交付核心
├── delivery-plan.ts            # 交付计划解析
├── delivery-preview.ts         # 交付预览
├── delivery-field-schemas.ts   # 交付字段验证（Zod）
├── isolated-agent.ts           # 隔离 Agent 入口
├── session-target.ts           # 会话目标解析
├── session-reaper.ts           # 会话清理器
├── run-diagnostics.ts          # 诊断信息收集
├── run-id.ts                   # 执行 ID 生成
├── run-log.ts                  # 运行日志
├── active-jobs.ts              # 活跃任务追踪
├── heartbeat-policy.ts         # 心跳策略
├── webhook-url.ts              # Webhook URL 验证
├── validate-timestamp.ts       # 时间戳验证
├── service/                    # 服务层子模块
│   ├── state.ts                # 服务状态管理
│   ├── ops.ts                  # 核心操作
│   ├── jobs.ts                 # 任务管理逻辑
│   ├── timer.ts                # 定时器和执行引擎
│   ├── store.ts                # 持久化存储
│   ├── locked.ts               # 并发锁机制
│   ├── normalize.ts            # 数据规范化
│   ├── timeout-policy.ts       # 超时策略
│   └── list-page-types.ts      # 分页查询类型
└── isolated-agent/             # 隔离 Agent 子模块
    ├── run.ts                  # Agent 运行核心
    ├── run.types.ts            # 运行类型定义
    ├── run-executor.ts         # 执行器
    ├── run-session-state.ts    # 会话状态管理
    ├── session.ts              # 会话解析
    ├── session-key.ts          # 会话密钥
    ├── model-selection.ts      # 模型选择
    ├── model-preflight.ts      # 模型预检
    ├── channel-output-policy.ts # 通道输出策略
    ├── skills-snapshot.ts      # 技能快照
    ├── subagent-followup.ts    # 子 Agent 跟进
    ├── delivery-dispatch.ts    # 交付分发
    └── delivery-target.ts      # 交付目标解析

模块依赖关系

CronService (service.ts)
  ├─→ CronServiceState (service/state.ts)
  ├─→ ops.ts (核心操作)
  │   ├─→ jobs.ts (任务管理)
  │   ├─→ timer.ts (定时器)
  │   ├─→ store.ts (持久化)
  │   └─→ locked.ts (并发控制)
  ├─→ schedule.ts (调度计算)
  │   └─→ parse.ts (时间解析)
  ├─→ normalize.ts (数据规范化)
  ├─→ delivery.ts (交付)
  │   ├─→ delivery-plan.ts
  │   └─→ isolated-agent/delivery-dispatch.ts
  ├─→ isolated-agent/run.ts (Agent 执行)
  │   ├─→ isolated-agent/session.ts
  │   ├─→ isolated-agent/model-selection.ts
  │   └─→ isolated-agent/run-executor.ts
  └─→ session-reaper.ts (会话清理)

关键常量

常量	值	说明
DEFAULT_JOB_TIMEOUT_MS	5 分钟	任务默认超时
MAX_TIMER_DELAY_MS	60s	定时器最大延迟
MIN_REFIRE_GAP_MS	2s	防止自旋最小间隔
DEFAULT_TOP_OF_HOUR_STAGGER_MS	5 分钟	整点错开默认值
DEFAULT_MISSED_JOB_STAGGER_MS	5s	启动追赶错开间隔
DEFAULT_MAX_MISSED_JOBS_PER_RESTART	5	启动最多追赶任务数
DEFAULT_FAILURE_ALERT_AFTER	2	连续失败多少次告警
DEFAULT_FAILURE_ALERT_COOLDOWN_MS	1 小时	告警冷却时间
DEFAULT_RETENTION_MS	24 小时	会话保留期
CRON_EVAL_CACHE_MAX	512	Cron 表达式 LRU 缓存大小

相关页面

• cron-types — 核心数据结构
• cron-schedule — 调度引擎与错开机制
• cron-service — 服务层与持久化
• cron-isolated-agent — 隔离 Agent 执行
• cron-delivery — 交付系统
• cron-delivery — 实践笔记