概念

Cron 是 OpenClaw 的「鬧鐘」— 讓 agent 在指定時間自動執行任務。

兩種執行模式：

Main session：喚醒主 session，注入 system event
Isolated：獨立 session，執行完畢後可以 announce

Cron Job 結構

{
  "id": "abc12345-1234-5678-9abc-def012345678",
  "name": "Morning Brief",
  "enabled": true,
  
  // 什麼時候跑
  "schedule": {
    "kind": "cron",
    "expr": "0 8 * * *",    // 每天早上 8 點
    "tz": "Asia/Taipei"
  },
  
  // 跑在哪裡
  "sessionTarget": "isolated",  // 或 "main"
  
  // 做什麼
  "payload": {
    "kind": "agentTurn",
    "message": "整理今天的行事曆和待辦事項",
    "timeoutSeconds": 300
  },
  
  // 結果發到哪
  "delivery": {
    "mode": "announce",
    "channel": "whatsapp",
    "to": "+1234567890"
  }
}

Schedule 類型

// 1. 一次性（at）
{
  "kind": "at",
  "at": "2026-02-20T14:00:00+08:00"  // ISO 8601
}

// 2. 固定間隔（every）
{
  "kind": "every",
  "everyMs": 3600000  // 每小時
}

// 3. Cron 表達式
{
  "kind": "cron",
  "expr": "0 8,12,16,20 * * *",  // 每天 8/12/16/20 點
  "tz": "Asia/Taipei"
}

Cron 表達式： 分時日月週

0 8 * * * = 每天 08:00
*/30 * * * * = 每 30 分鐘
0 9 * * 1-5 = 週一到週五 09:00

Main vs Isolated

Main Session Job

{
  "sessionTarget": "main",
  "payload": {
    "kind": "systemEvent",
    "text": "提醒：該檢查信箱了"
  },
  "wakeMode": "now"  // 立即喚醒 heartbeat
}

特點：

注入到主 session
保留對話歷史
適合「提醒」類任務

Isolated Session Job

{
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "執行每日報告腳本",
    "model": "anthropic/claude-sonnet-4-5",
    "timeoutSeconds": 600
  },
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "9876543210"
  }
}

特點：

獨立的乾淨 session
每次都是新的 context
結果可以發送到指定 channel

CLI 快速操作

# 列出所有 jobs
openclaw cron list

# 新增 job
openclaw cron add \
  --name "Daily Report" \
  --cron "0 20 * * *" \
  --tz "Asia/Taipei" \
  --session isolated \
  --message "產生今日摘要" \
  --announce \
  --channel whatsapp \
  --to "+1234567890"

# 手動執行
openclaw cron run <job-id>

# 查看執行歷史
openclaw cron runs --id <job-id>

# 編輯
openclaw cron edit <job-id> --message "新的 prompt"

# 停用
openclaw cron edit <job-id> --disable

核心代碼

// Cron scheduler 主迴圈
async function runCronScheduler() {
  while (true) {
    const now = Date.now();
    
    for (const job of jobs) {
      if (!job.enabled) continue;
      if (job.state.nextRunAtMs > now) continue;
      
      // 該執行了
      try {
        await executeJob(job);
        job.state.lastStatus = 'ok';
        job.state.consecutiveErrors = 0;
      } catch (e) {
        job.state.lastStatus = 'error';
        job.state.consecutiveErrors++;
        job.state.lastError = e.message;
      }
      
      // 計算下次執行時間
      job.state.nextRunAtMs = calculateNextRun(job.schedule);
      
      // 一次性 job 自動刪除
      if (job.schedule.kind === 'at' && job.deleteAfterRun) {
        deleteJob(job.id);
      }
    }
    
    await sleep(1000);  // 每秒檢查一次
  }
}

💡 關鍵洞察

Cron 跑在 Gateway 裡面
- 不是獨立 process
- Gateway 關掉 = Cron 停止
- 重啟後會恢復排程
Main vs Isolated 的選擇
- 需要對話 context → main
- 獨立任務 → isolated
- 頻繁執行 → isolated（避免 context 膨脹）
Delivery 控制輸出
- announce：發送到指定 channel
- none：不發送（內部記錄）
- 避免用 message tool，用 delivery
失敗會自動 retry（有 backoff）
- 30s → 1m → 5m → 15m → 60m
- 成功後 backoff 重置

🔗 核心檔案

Jobs 儲存：~/.openclaw/cron/jobs.json
執行歷史：~/.openclaw/cron/runs/<jobId>.jsonl
文檔：/opt/homebrew/lib/node_modules/openclaw/docs/automation/cron-jobs.md

明天： Memory 系統（compaction, memory-flush）

Day 6: Cron 系統（schedule, payload, delivery）