# Quy Trình 05 — Quản Lý Cron Job

> **Dành cho Architect Agent**
> Cập nhật: 2026-05-16 | Phiên bản: 1.0 (merged)

---

## Tổng Quan

Cron job trong OpenClaw dùng để:
- Tự động hóa pipeline nhiều batch liên tiếp
- Lên lịch hiệu đính vào giờ cụ thể
- Retry batch fail sau thời gian chờ

### Khi nào dùng cron vs sessions_spawn?

| Tình huống | Dùng |
|-----------|------|
| Chạy ngay 1 batch | `sessions_spawn` |
| Chạy nhiều batch liên tiếp, cách nhau N phút | `cron add` |
| Lên lịch giờ cụ thể (9:00 sáng mai) | `cron add` (schedule: at) |
| Retry sau fail | `cron add` |

---

## I. Cấu Trúc Cron Job Chuẩn

### Mẫu cho agentTurn (isolated session)
```json
{
  "name": "Tên job",
  "schedule": {
    "kind": "at",
    "at": "2026-05-16T14:00:00+07"
  },
  "payload": {
    "kind": "agentTurn",
    "message": "Nội dung prompt cho agent...",
    "timeoutSeconds": 600,
    "model": "modelstudio/qwen3.6-plus"
  },
  "sessionTarget": "isolated",
  "agentId": "translator",
  "deleteAfterRun": true,
  "delivery": {
    "mode": "announce",
    "channel": "webchat"
  }
}
```

### Mẫu cho systemEvent (main session)
```json
{
  "name": "Healthcheck",
  "schedule": {
    "kind": "every",
    "everyMs": 1800000
  },
  "payload": {
    "kind": "systemEvent",
    "text": "Kiểm tra tiến độ dự án..."
  },
  "sessionTarget": "main"
}
```

---

## II. Loại Schedule

### One-shot (at)
```json
{"kind": "at", "at": "2026-05-16T14:00:00+07"}
```

### Định kỳ (every)
```json
{"kind": "every", "everyMs": 300000}  // 5 phút
```

### Cron expression
```json
{"kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Bangkok"}  // 9:00 mỗi ngày
```

---

## III. Ràng Buộc Quan Trọng

- `sessionTarget="main"` → **PHẢI** dùng `payload.kind="systemEvent"`
- `sessionTarget="isolated"` → **PHẢI** dùng `payload.kind="agentTurn"`
- `sessionTarget="current"` → **PHẢI** dùng `payload.kind="agentTurn"`
- **KHÔNG** dùng `agentTurn` với `sessionTarget="main"` — sẽ bị reject

---

## IV. Chạy Nhiều Batch Liên Tiếp

### Pattern
```
Batch 1 (now) → Batch 2 (+5ph) → Batch 3 (+10ph) → ...
```

### Script mẫu
```bash
for i in $(seq 1 10); do
  MINUTES=$((i * 5))
  AT=$(date -d "+$MINUTES minutes" --iso-8601=seconds)
  # Tạo cron job cho batch $i
done
```

---

## V. Healthcheck Cron

Dùng cron định kỳ để kiểm tra tiến độ pipeline:

```json
{
  "name": "healthcheck",
  "schedule": {"kind": "every", "everyMs": 1800000},
  "payload": {
    "kind": "systemEvent",
    "text": "🔍 HEALTHCHECK: Đọc progress.json → báo cáo batch done/pending/stuck"
  },
  "sessionTarget": "main"
}
```

---

## VI. Xử Lý Sự Cố

| Vấn đề | Giải pháp |
|--------|----------|
| Job treo >30ph | Kill + spawn lại |
| Job fail liên tiếp | Đổi model, thử `modelstudio/qwen3.6-plus` |
| Job không chạy đúng giờ | Kiểm tra timezone, `staggerMs` |
| Delivery không nhận được | Kiểm tra `delivery.channel`, `delivery.mode` |

---

## VII. Best Practices

- ✅ Mỗi batch = 1 session riêng (tránh dồn token)
- ✅ Cách nhau ≥ 5 phút (đủ thời gian xử lý)
- ✅ `deleteAfterRun: true` — tránh rác cron job
- ✅ `timeoutSeconds` ≤ 600 (10 phút)
- ✅ Delivery `announce` để có thông báo khi hoàn thành
- ❌ Không chạy song song nhiều batch cùng lúc
- ❌ Không để cron tự động retry vô hạn (max 3 lần)

---

## File liên quan
- [[01-Dieu-Phoi-Agent]] — Điều phối agent
- [[02-Dich-Song-Ngu]] — Dịch song ngữ qua cron
- [[03-Hieu-Dinh]] — Hiệu đính (có phần cron automation)
- [[prompt-template-v4]] — Prompt template cho cron job hiệu đính