8. Cron Jobs

Mục tiêu: Thiết lập tác vụ tự động chạy theo lịch trong OpenClaw.

Cron Job là gì?

Cron Job là tác vụ được lập lịch chạy tự động tại thời điểm cụ thể. Trong OpenClaw:

Chạy trong Gateway process (không cần external scheduler)
Persist jobs (không mất khi restart)
Có thể gửi kết quả về chat channel
Chạy trong isolated session (không ảnh hưởng main session)

So sánh Cron vs Heartbeat:

	Cron Jobs	Heartbeat
Thời điểm	Chính xác ("8:00 AM")	Định kỳ ("mỗi 2 giờ")
Session	Isolated (không chia sẻ context)	Main session
Use case	Báo cáo theo lịch, reminder	Background sync, maintenance

Cấu trúc một Job

Mỗi job có:

Schedule: Khi nào chạy
Payload: Chạy cái gì
Delivery: Gửi kết quả đâu (tùy chọn)
Agent binding: Chạy trên agent nào

┌─────────────────────────────────────────┐
│           Cron Job                      │
├─────────────────────────────────────────┤
│  Schedule: "0 8 * * *"                  │
│  Payload: "Gửi báo cáo doanh thu"       │
│  Delivery: telegram → @channel          │
│  Agent: main (mặc định)                 │
└─────────────────────────────────────────┘

Schedule Types

1. At (One-shot)

Chạy một lần tại thời điểm cụ thể.

json5

{
  schedule: {
    at: "2024-12-25T08:00:00Z", // ISO 8601
  },
}

2. Every (Fixed Interval)

Chạy mỗi X ms.

json5

{
  schedule: {
    every: 3600000, // 1 giờ (milliseconds)
  },
}

3. Cron Expression

Dùng 5-field cron (hoặc 6-field với seconds).

  ┌───────────── minute (0-59)
  │ ┌───────────── hour (0-23)
  │ │ ┌───────────── day of month (1-31)
  │ │ │ ┌───────────── month (1-12)
  │ │ │ │ ┌───────────── day of week (0-7, 0=Sun)
  │ │ │ │ │
  * * * * *

Ví dụ:

json5

{
  schedule: {
    cron: "0 8 * * *", // 8:00 AM mỗi ngày
    cron: "0 */2 * * *", // Mỗi 2 giờ
    cron: "0 7 * * 1", // 7:00 AM mỗi thứ 2
    timezone: "Asia/Ho_Chi_Minh", // Múi giờ
  },
}

Stagger (tránh burst):

Các job chạy cùng giờ tự động spread trong 0-5 phút
Dùng --exact để tắt stagger
Dùng --stagger 30s để set cụ thể

Payload Types

1. System Event (Main Session)

Trigger event vào main session.

json5

{
  payload: {
    kind: "systemEvent",
    event: "morning-briefing",
  },
  // wakeMode: "now" (mặc định) - chạy ngay
  // wakeMode: "next-heartbeat" - đợi heartbeat tiếp theo
}

2. Agent Turn (Isolated Session)

Chạy dedicated agent turn trong session riêng.

json5

{
  payload: {
    kind: "agentTurn",
    message: "Gửi báo cáo doanh thu hôm nay",
    model: "anthropic/claude-3-5-sonnet", // Override model
    thinking: "medium", // Override thinking level
    timeoutSeconds: 60,
  },
}

Delivery Modes

1. Announce (Mặc định)

Gửi summary đến channel + post brief summary vào main session.

json5

{
  delivery: {
    mode: "announce",
    channel: "telegram",
    to: "@channel-id", // Channel/group ID
    bestEffort: false, // Fail job nếu delivery fail
  },
}

2. Webhook

POST kết quả đến HTTP endpoint.

json5

{
  delivery: {
    mode: "webhook",
    to: "https://my-api.com/webhook",
  },
}

Headers:

Authorization: Bearer <cron.webhookToken>
Content-Type: application/json

3. None

Không delivery - chỉ chạy internal.

json5

{
  delivery: {
    mode: "none",
  },
}

CLI Commands

Tạo Job

bash

# Cơ bản
openclaw cron add \
  --name "morning-report" \
  --schedule "0 8 * * *" \
  --message "Gửi báo cáo doanh thu"

# Với delivery
openclaw cron add \
  --name "daily-briefing" \
  --schedule "0 7 * * *" \
  --message "Daily briefing" \
  --channel telegram \
  --to "@mychannel"

# One-shot
openclaw cron add \
  --name "reminder" \
  --at "2024-12-25T09:00:00Z" \
  --message "Nhắc họp với khách hàng"

Quản lý Jobs

bash

# Liệt kê tất cả jobs
openclaw cron list

# Xem chi tiết job
openclaw cron show <job-id>

# Chạy job ngay lập tức (bypass schedule)
openclaw cron run <job-id>

# Cập nhật job
openclaw cron update <job-id> --schedule "0 9 * * *"

# Xóa job
openclaw cron remove <job-id>

# Pause job
openclaw cron pause <job-id>

# Resume job
openclaw cron resume <job-id>

Xem Run History

bash

# Lịch sử chạy
openclaw cron runs <job-id>

# Lịch sử lỗi
openclaw cron runs <job-id> --status error

Cấu hình Global

json5

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // Số job chạy song song
    sessionRetention: "24h", // Giữ session sau khi chạy
    webhookToken: "secret-token", // Auth cho webhook
    runLog: {
      maxBytes: "2mb", // Giới hạn log mỗi job
      keepLines: 2000, // Giữ dòng log
    },
  },
}

Ví dụ thực tế

1. Báo cáo hàng ngày

bash

openclaw cron add \
  --name "daily-sales-report" \
  --schedule "0 8 * * *" \
  --timezone "Asia/Ho_Chi_Minh" \
  --message "Phân tích doanh thu hôm qua và đưa ra insights" \
  --channel telegram \
  --to "@sales-channel"

2. Reminder cuộc họp

bash

openclaw cron add \
  --name "standup-reminder" \
  --schedule "0 9 * * 1-5" \
  --message "@channel Standup meeting bắt đầu!" \
  --channel telegram \
  --to "@team-group"

3. Backup hàng tuần

bash

openclaw cron add \
  --name "weekly-backup" \
  --schedule "0 2 * * 0" \
  --message "Chạy backup dữ liệu và báo cáo kết quả" \
  --delivery webhook \
  --to "https://backup.mycompany.com/webhook"

4. Health check định kỳ

bash

openclaw cron add \
  --name "health-check" \
  --schedule "0 */4 * * *" \
  --message "Kiểm tra tình trạng hệ thống: disk, memory, services" \
  --model "anthropic/claude-3-5-sonnet"

Storage

Jobs được lưu tại:

~/.openclaw/cron/
├── jobs/
│   ├── daily-sales-report.json
│   ├── weekly-backup.json
│   └── ...
└── runs/
    └── <job-id>.jsonl    # Lịch sử chạy

Troubleshooting

"Nothing runs"

bash

# Kiểm tra cron enabled
openclaw config show cron.enabled

# Kiểm tra logs
openclaw logs --tail 100 | grep cron

# Kiểm tra job status
openclaw cron list

Job chạy chậm/delay

Kiểm tra maxConcurrentRuns (có đang đạt giới hạn?)
Kiểm tra stagger (có đang spread không?)
Kiểm tra timezone (đã đúng chưa?)

Delivery fail

Kiểm tra delivery.to đúng format
Kiểm tra bot có quyền post không
Dùng delivery.bestEffort: true để không fail job

Best Practices

1. Đặt tên job rõ ràng

✅ "daily-sales-report"
✅ "weekly-backup-db"
❌ "job1"
❌ "test"

2. Dùng timezone rõ ràng

json5

{
  schedule: {
    cron: "0 8 * * *",
    timezone: "Asia/Ho_Chi_Minh", // Không dùng default
  },
}

3. Giới hạn concurrent runs

json5

{
  cron: {
    maxConcurrentRuns: 2, // Tránh quá tải
  },
}

4. Monitor lịch sử chạy

bash

# Kiểm tra định kỳ
openclaw cron runs <job-id> --last 10

5. Test trước khi deploy

bash

# Chạy thử job
openclaw cron run <job-id>

# Kiểm tra output trước khi để chạy định kỳ

Tiếp theo?

Bài 9: Multi-Instance - Chạy nhiều Gateway độc lập
Bài 10: Troubleshooting - Xử lý sự cố

8. Cron Jobs ​

Cron Job là gì? ​

Cấu trúc một Job ​

Schedule Types ​

1. At (One-shot) ​

2. Every (Fixed Interval) ​

3. Cron Expression ​

Payload Types ​

1. System Event (Main Session) ​

2. Agent Turn (Isolated Session) ​

Delivery Modes ​

1. Announce (Mặc định) ​

2. Webhook ​

3. None ​

CLI Commands ​

Tạo Job ​

Quản lý Jobs ​

Xem Run History ​

Cấu hình Global ​

Ví dụ thực tế ​

1. Báo cáo hàng ngày ​

2. Reminder cuộc họp ​

3. Backup hàng tuần ​

4. Health check định kỳ ​

Storage ​

Troubleshooting ​

"Nothing runs" ​

Job chạy chậm/delay ​

Delivery fail ​

Best Practices ​

1. Đặt tên job rõ ràng ​

2. Dùng timezone rõ ràng ​

3. Giới hạn concurrent runs ​

4. Monitor lịch sử chạy ​

5. Test trước khi deploy ​

Tiếp theo? ​

8. Cron Jobs

Cron Job là gì?

Cấu trúc một Job

Schedule Types

1. At (One-shot)

2. Every (Fixed Interval)

3. Cron Expression

Payload Types

1. System Event (Main Session)

2. Agent Turn (Isolated Session)

Delivery Modes

1. Announce (Mặc định)

2. Webhook

3. None

CLI Commands

Tạo Job

Quản lý Jobs

Xem Run History

Cấu hình Global

Ví dụ thực tế

1. Báo cáo hàng ngày

2. Reminder cuộc họp

3. Backup hàng tuần

4. Health check định kỳ

Storage

Troubleshooting

"Nothing runs"

Job chạy chậm/delay

Delivery fail

Best Practices

1. Đặt tên job rõ ràng

2. Dùng timezone rõ ràng

3. Giới hạn concurrent runs

4. Monitor lịch sử chạy

5. Test trước khi deploy

Tiếp theo?