Openclaw源码深潜之三——调度器架构详解

** 作者：** AiToMoney 团队阅读时间：约 25 分钟

📋 学习目标

学完本教程后，你将理解：

1. OpenClaw Cron 调度器的整体架构
2. CronService → ops → timer → isolated-agent 调用链
3. at（一次性）/every（周期性）任务的调度机制
4. 孤立会话（isolated-agent）的执行原理
5. 如何设计一个自定义 Cron Job

🗺️ 架构总览

OpenClaw 的 Cron 调度器采用分层架构，从对外接口到底层执行分为 4 层：

┌─────────────────────────────────────────────┐ │ Gateway 层 │ │ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │ │ │ REST API │ │ System │ │ Heartbeat │ │ │ │ /cron │ │ Event │ │ Trigger │ │ │ └─────┬─────┘ └─────┬─────┘ └──────┬───────┘ │ └────────┼──────────────┼──────────────┼───────────────┘ │ │ │ ┌────────┴──────────────┴──────────────┴───────────────┐ │ CronService 层 │ │ service.ts（对外接口）→ ops.ts（核心逻辑） │ └──────────────────────┬───────────────────────────────┘ │ ┌──────────────────────┴───────────────────────────────┐ │ Timer 层 │ │ timer.ts → armTimer() → executeJobCoreWithTimeout() │ └──────────────────────┬───────────────────────────────┘ │ ┌──────────────────────┴───────────────────────────────┐ │ Isolated-Agent 层 │ │ isolated-agent/ → 创建独立 session → 执行任务 │ └───────────────────────────────────────────────────────┘

🔌 CronService 接口（service.ts）

CronService是对外接口，采用薄封装模式，所有实际逻辑委托给ops.*函数：

exportclassCronServiceimplementsCronServiceContract{privatereadonlystate;constructor(deps:CronServiceDeps){this.state=createCronServiceState(deps);}asyncstart(){awaitops.start(this.state);}asyncadd(input:CronJobCreate){returnawaitops.add