​

Cron jobs (Bộ lập lịch Gateway)

Cron vs Heartbeat? Xem Cron vs Heartbeat để biết khi nào nên sử dụng từng loại.

​

Tóm tắt nhanh

• Cron chạy bên trong Gateway (không phải bên trong mô hình).
• Công việc được lưu trữ dưới ~/.openclaw/cron/ để không mất lịch trình khi khởi động lại.
• Hai kiểu thực thi:
  • Phiên chính: xếp hàng một sự kiện hệ thống, sau đó chạy vào heartbeat tiếp theo.
  • Cô lập: chạy một lượt agent riêng biệt trong cron:<jobId> hoặc một phiên tùy chỉnh, với thông báo (mặc định là thông báo hoặc không có).
  • Phiên hiện tại: gắn với phiên nơi cron được tạo (sessionTarget: "current").
  • Phiên tùy chỉnh: chạy trong một phiên được đặt tên cố định (sessionTarget: "session:custom-id").
• Wakeups là ưu tiên hàng đầu: một công việc có thể yêu cầu “wake now” hoặc “next heartbeat”.
• Đăng webhook theo từng công việc qua delivery.mode = "webhook" + delivery.to = "<url>".
• Cơ chế dự phòng cũ vẫn còn cho các công việc lưu trữ với notify: true khi cron.webhook được thiết lập, chuyển các công việc đó sang chế độ giao hàng webhook.
• Để nâng cấp, openclaw doctor --fix có thể chuẩn hóa các trường lưu trữ cron cũ trước khi bộ lập lịch xử lý chúng.

​

Bắt đầu nhanh (hành động)

openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run

openclaw cron list
openclaw cron run <job-id>
openclaw cron runs --id <job-id>

openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

​

Tương đương với lệnh công cụ (Công cụ cron Gateway)

​

Nơi lưu trữ cron jobs

​

Tổng quan thân thiện với người mới bắt đầu

1. Chọn lịch trình
   • Lời nhắc một lần → schedule.kind = "at" (CLI: --at)
   • Công việc lặp lại → schedule.kind = "every" hoặc schedule.kind = "cron"
   • Nếu dấu thời gian ISO của bạn không có múi giờ, nó được coi là UTC.
2. Chọn nơi nó chạy
   • sessionTarget: "main" → chạy trong heartbeat tiếp theo với ngữ cảnh chính.
   • sessionTarget: "isolated" → chạy một lượt agent riêng biệt trong cron:<jobId>.
   • sessionTarget: "current" → gắn với phiên hiện tại (được giải quyết tại thời điểm tạo thành session:<sessionKey>).
   • sessionTarget: "session:custom-id" → chạy trong một phiên được đặt tên cố định duy trì ngữ cảnh qua các lần chạy.
   Hành vi mặc định (không thay đổi):
   • Payload systemEvent mặc định là main
   • Payload agentTurn mặc định là isolated
   Để sử dụng gắn kết phiên hiện tại, hãy đặt rõ sessionTarget: "current".
3. Chọn payload
   • Phiên chính → payload.kind = "systemEvent"
   • Phiên cô lập → payload.kind = "agentTurn"

​

Khái niệm

​

Jobs

• một lịch trình (khi nào nó nên chạy),
• một payload (nó nên làm gì),
• chế độ giao hàng tùy chọn (announce, webhook, hoặc none).
• ràng buộc agent tùy chọn (agentId): chạy công việc dưới một agent cụ thể; nếu thiếu hoặc không xác định, gateway sẽ quay lại agent mặc định.

​

Lịch trình

• at: dấu thời gian một lần qua schedule.at (ISO 8601).
• every: khoảng thời gian cố định (ms).
• cron: biểu thức cron 5 trường (hoặc 6 trường với giây) với múi giờ IANA tùy chọn.

• --stagger 30s (hoặc 1m, 5m) để đặt một cửa sổ giãn cách rõ ràng.
• --exact để buộc staggerMs = 0.

​

Thực thi chính vs cô lập

​

Công việc phiên chính (sự kiện hệ thống)

• wakeMode: "now" (mặc định): sự kiện kích hoạt một lần chạy heartbeat ngay lập tức.
• wakeMode: "next-heartbeat": sự kiện chờ đợi heartbeat tiếp theo được lên lịch.

​

Công việc cô lập (phiên cron riêng biệt)

• Lời nhắc được tiền tố với [cron:<jobId> <job name>] để dễ dàng theo dõi.
• Mỗi lần chạy bắt đầu một id phiên mới (không có cuộc trò chuyện trước đó), trừ khi sử dụng một phiên tùy chỉnh.
• Các phiên tùy chỉnh (session:xxx) duy trì ngữ cảnh qua các lần chạy, cho phép các quy trình làm việc như các cuộc họp hàng ngày xây dựng trên các bản tóm tắt trước đó.
• Hành vi mặc định: nếu delivery bị bỏ qua, công việc cô lập thông báo một bản tóm tắt (delivery.mode = "announce").
• delivery.mode chọn điều gì xảy ra:
  • announce: gửi một bản tóm tắt đến kênh mục tiêu và đăng một bản tóm tắt ngắn gọn lên phiên chính.
  • webhook: POST payload sự kiện đã hoàn thành đến delivery.to khi sự kiện đã hoàn thành bao gồm một bản tóm tắt.
  • none: chỉ nội bộ (không giao hàng, không có bản tóm tắt phiên chính).
• wakeMode kiểm soát khi nào bản tóm tắt phiên chính được đăng:
  • now: heartbeat ngay lập tức.
  • next-heartbeat: chờ đợi heartbeat tiếp theo được lên lịch.

​

Hình dạng payload (chạy cái gì)

• systemEvent: chỉ phiên chính, được định tuyến qua lời nhắc heartbeat.
• agentTurn: chỉ phiên cô lập, chạy một lượt agent riêng biệt.

• message: lời nhắc văn bản bắt buộc.
• model / thinking: ghi đè tùy chọn (xem bên dưới).
• timeoutSeconds: ghi đè thời gian chờ tùy chọn.
• lightContext: chế độ khởi động nhẹ tùy chọn cho các công việc không cần tiêm file khởi động workspace.

• delivery.mode: none | announce | webhook.
• delivery.channel: last hoặc một kênh cụ thể.
• delivery.to: mục tiêu cụ thể của kênh (announce) hoặc URL webhook (chế độ webhook).
• delivery.bestEffort: tránh thất bại công việc nếu giao hàng thông báo thất bại.

​

Luồng giao hàng thông báo

• Nội dung: giao hàng sử dụng payload outbound của lần chạy cô lập (văn bản/phương tiện) với phân đoạn và định dạng kênh bình thường.
• Phản hồi chỉ có heartbeat (HEARTBEAT_OK không có nội dung thực) không được giao.
• Nếu lần chạy cô lập đã gửi một tin nhắn đến cùng mục tiêu qua công cụ nhắn tin, giao hàng bị bỏ qua để tránh trùng lặp.
• Mục tiêu giao hàng thiếu hoặc không hợp lệ làm thất bại công việc trừ khi delivery.bestEffort = true.
• Một bản tóm tắt ngắn được đăng lên phiên chính chỉ khi delivery.mode = "announce".
• Bản tóm tắt phiên chính tôn trọng wakeMode: now kích hoạt một heartbeat ngay lập tức và next-heartbeat chờ đợi heartbeat tiếp theo được lên lịch.

​

Luồng giao hàng webhook

• Endpoint phải là một URL HTTP(S) hợp lệ.
• Không có giao hàng kênh nào được thử trong chế độ webhook.
• Không có bản tóm tắt phiên chính nào được đăng trong chế độ webhook.
• Nếu cron.webhookToken được thiết lập, header xác thực là Authorization: Bearer <cron.webhookToken>.
• Cơ chế dự phòng cũ: các công việc lưu trữ cũ với notify: true vẫn đăng lên cron.webhook (nếu được cấu hình), với một cảnh báo để bạn có thể chuyển sang delivery.mode = "webhook".

​

Ghi đè mô hình và suy nghĩ

• model: Chuỗi nhà cung cấp/mô hình (ví dụ: anthropic/claude-sonnet-4-20250514) hoặc bí danh (ví dụ: opus)
• thinking: Mức độ suy nghĩ (off, minimal, low, medium, high, xhigh; chỉ các mô hình GPT-5.2 + Codex)

1. Ghi đè payload công việc (cao nhất)
2. Mặc định cụ thể của hook (ví dụ: hooks.gmail.model)
3. Mặc định cấu hình agent

​

Ngữ cảnh khởi động nhẹ

• Sử dụng điều này cho các công việc định kỳ không cần tiêm file khởi động workspace.
• Trong thực tế, runtime nhúng chạy với bootstrapContextMode: "lightweight", giữ ngữ cảnh khởi động cron trống rỗng có chủ đích.
• Tương đương CLI: openclaw cron add --light-context ... và openclaw cron edit --light-context.

​

Giao hàng (kênh + mục tiêu)

• delivery.mode: announce (giao hàng kênh), webhook (HTTP POST), hoặc none.
• delivery.channel: whatsapp / telegram / discord / slack / mattermost (plugin) / signal / imessage / last.
• delivery.to: mục tiêu người nhận cụ thể của kênh.

• Mục tiêu Slack/Discord/Mattermost (plugin) nên sử dụng tiền tố rõ ràng (ví dụ: channel:<id>, user:<id>) để tránh mơ hồ. Mattermost ID 26 ký tự không có tiền tố được giải quyết ưu tiên người dùng (DM nếu người dùng tồn tại, kênh nếu không) — sử dụng user:<id> hoặc channel:<id> để định tuyến xác định.
• Chủ đề Telegram nên sử dụng dạng :topic: (xem bên dưới).

​

Mục tiêu giao hàng Telegram (chủ đề / luồng diễn đàn)

• -1001234567890 (chỉ id chat)
• -1001234567890:topic:123 (ưu tiên: dấu chủ đề rõ ràng)
• -1001234567890:123 (viết tắt: hậu tố số)

• telegram:group:-1001234567890:topic:123

​

JSON schema cho các cuộc gọi công cụ

​

Tham số cron.add

{
  "name": "Reminder",
  "schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": { "kind": "systemEvent", "text": "Reminder text" },
  "deleteAfterRun": true
}

{
  "name": "Morning brief",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "agentTurn",
    "message": "Summarize overnight updates.",
    "lightContext": true
  },
  "delivery": {
    "mode": "announce",
    "channel": "slack",
    "to": "channel:C1234567890",
    "bestEffort": true
  }
}

{
  "name": "Daily standup",
  "schedule": { "kind": "cron", "expr": "0 9 * * *" },
  "sessionTarget": "current",
  "payload": {
    "kind": "agentTurn",
    "message": "Summarize yesterday's progress."
  }
}

{
  "name": "Project monitor",
  "schedule": { "kind": "every", "everyMs": 300000 },
  "sessionTarget": "session:project-alpha-monitor",
  "payload": {
    "kind": "agentTurn",
    "message": "Check project status and update the running log."
  }
}

• schedule.kind: at (at), every (everyMs), hoặc cron (expr, tz tùy chọn).
• schedule.at chấp nhận ISO 8601 (múi giờ tùy chọn; được coi là UTC khi bị bỏ qua).
• everyMs là mili giây.
• sessionTarget: "main", "isolated", "current", hoặc "session:<custom-id>".
• "current" được giải quyết thành "session:<sessionKey>" khi tạo.
• Các phiên tùy chỉnh (session:xxx) duy trì ngữ cảnh cố định qua các lần chạy.
• Các trường tùy chọn: agentId, description, enabled, deleteAfterRun (mặc định là true cho at), delivery.
• wakeMode mặc định là "now" khi bị bỏ qua.

​

Tham số cron.update

{
  "jobId": "job-123",
  "patch": {
    "enabled": false,
    "schedule": { "kind": "every", "everyMs": 3600000 }
  }
}

• jobId là chuẩn; id được chấp nhận để tương thích.
• Sử dụng agentId: null trong patch để xóa ràng buộc agent.

​

Tham số cron.run và cron.remove

{ "jobId": "job-123", "mode": "force" }

{ "jobId": "job-123" }

​

Lưu trữ & lịch sử

• Lưu trữ công việc: ~/.openclaw/cron/jobs.json (JSON do Gateway quản lý).
• Lịch sử chạy: ~/.openclaw/cron/runs/<jobId>.jsonl (JSONL, tự động cắt bớt theo kích thước và số dòng).
• Các phiên chạy cron cô lập trong sessions.json được cắt bớt bởi cron.sessionRetention (mặc định 24h; đặt false để vô hiệu hóa).
• Ghi đè đường dẫn lưu trữ: cron.store trong cấu hình.

​

Chính sách thử lại

​

Lỗi tạm thời (thử lại)

• Giới hạn tốc độ (429, quá nhiều yêu cầu, tài nguyên cạn kiệt)
• Quá tải nhà cung cấp (ví dụ: Anthropic 529 overloaded_error, tóm tắt dự phòng quá tải)
• Lỗi mạng (timeout, ECONNRESET, fetch failed, socket)
• Lỗi máy chủ (5xx)
• Lỗi liên quan đến Cloudflare

​

Lỗi vĩnh viễn (không thử lại)

• Lỗi xác thực (API key không hợp lệ, không được phép)
• Lỗi cấu hình hoặc xác thực
• Các lỗi không tạm thời khác

​

Hành vi mặc định (không cấu hình)

• Khi gặp lỗi tạm thời: thử lại tối đa 3 lần với backoff lũy tiến (30s → 1m → 5m).
• Khi gặp lỗi vĩnh viễn: vô hiệu hóa ngay lập tức.
• Khi thành công hoặc bỏ qua: vô hiệu hóa (hoặc xóa nếu deleteAfterRun: true).

• Khi gặp bất kỳ lỗi nào: áp dụng backoff lũy tiến (30s → 1m → 5m → 15m → 60m) trước lần chạy tiếp theo được lên lịch.
• Công việc vẫn được kích hoạt; backoff được đặt lại sau lần chạy thành công tiếp theo.

​

Cấu hình

{
  cron: {
    enabled: true, // mặc định true
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1, // mặc định 1
    // Tùy chọn: ghi đè chính sách thử lại cho công việc một lần
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhook: "https://example.invalid/legacy", // cơ chế dự phòng cũ cho các công việc lưu trữ notify:true
    webhookToken: "replace-with-dedicated-webhook-token", // token bearer tùy chọn cho chế độ webhook
    sessionRetention: "24h", // chuỗi thời lượng hoặc false
    runLog: {
      maxBytes: "2mb", // mặc định 2_000_000 bytes
      keepLines: 2000, // mặc định 2000
    },
  },
}

• cron.runLog.maxBytes: kích thước file nhật ký chạy tối đa trước khi cắt bớt.
• cron.runLog.keepLines: khi cắt bớt, chỉ giữ lại N dòng mới nhất.
• Cả hai áp dụng cho các file cron/runs/<jobId>.jsonl.

• Ưu tiên: đặt delivery.mode: "webhook" với delivery.to: "https://..." cho từng công việc.
• URL webhook phải là URL http:// hoặc https:// hợp lệ.
• Khi được đăng, payload là JSON sự kiện đã hoàn thành cron.
• Nếu cron.webhookToken được thiết lập, header xác thực là Authorization: Bearer <cron.webhookToken>.
• Nếu cron.webhookToken không được thiết lập, không có header Authorization nào được gửi.
• Cơ chế dự phòng cũ: các công việc lưu trữ cũ với notify: true vẫn sử dụng cron.webhook khi có.

• cron.enabled: false (cấu hình)
• OPENCLAW_SKIP_CRON=1 (biến môi trường)

​

Bảo trì

​

Mặc định

• cron.sessionRetention: 24h (đặt false để vô hiệu hóa cắt bớt phiên chạy)
• cron.runLog.maxBytes: 2_000_000 bytes
• cron.runLog.keepLines: 2000

​

Cách hoạt động

• Các lần chạy cô lập tạo các mục phiên (...:cron:<jobId>:run:<uuid>) và các file bản ghi.
• Bộ dọn dẹp loại bỏ các mục phiên chạy đã hết hạn cũ hơn cron.sessionRetention.
• Đối với các phiên chạy đã bị xóa không còn được tham chiếu bởi lưu trữ phiên, OpenClaw lưu trữ các file bản ghi và xóa các bản lưu trữ cũ đã bị xóa trên cùng cửa sổ giữ lại.
• Sau mỗi lần chạy thêm, cron/runs/<jobId>.jsonl được kiểm tra kích thước:
  • nếu kích thước file vượt quá runLog.maxBytes, nó được cắt bớt để giữ lại các dòng runLog.keepLines mới nhất.

​

Cảnh báo hiệu suất cho các bộ lập lịch có tần suất cao

• cửa sổ cron.sessionRetention dài với nhiều lần chạy cô lập
• cron.runLog.keepLines cao kết hợp với runLog.maxBytes lớn
• nhiều công việc định kỳ ồn ào ghi vào cùng một file cron/runs/<jobId>.jsonl

• giữ cron.sessionRetention ngắn nhất có thể theo nhu cầu gỡ lỗi/kiểm toán của bạn
• giữ nhật ký chạy trong giới hạn với runLog.maxBytes và runLog.keepLines vừa phải
• chuyển các công việc nền ồn ào sang chế độ cô lập với các quy tắc giao hàng tránh tiếng ồn không cần thiết
• xem xét tăng trưởng định kỳ với openclaw cron runs và điều chỉnh giữ lại trước khi nhật ký trở nên lớn

​

Ví dụ tùy chỉnh

{
  cron: {
    sessionRetention: "7d",
    runLog: {
      maxBytes: "10mb",
      keepLines: 5000,
    },
  },
}

{
  cron: {
    sessionRetention: false,
    runLog: {
      maxBytes: "5mb",
      keepLines: 3000,
    },
  },
}

{
  cron: {
    sessionRetention: "12h",
    runLog: {
      maxBytes: "3mb",
      keepLines: 1500,
    },
  },
}

​

CLI bắt đầu nhanh

openclaw cron add \
  --name "Send reminder" \
  --at "2026-01-12T18:00:00Z" \
  --session main \
  --system-event "Reminder: submit expense report." \
  --wake now \
  --delete-after-run

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

openclaw cron add \
  --name "Morning status" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize inbox + calendar for today." \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

openclaw cron add \
  --name "Minute watcher" \
  --cron "0 * * * * *" \
  --tz "UTC" \
  --stagger 30s \
  --session isolated \
  --message "Run minute watcher checks." \
  --announce

openclaw cron add \
  --name "Nightly summary (topic)" \
  --cron "0 22 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize today; send to the nightly topic." \
  --announce \
  --channel telegram \
  --to "-1001234567890:topic:123"

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

# Gắn một công việc vào agent "ops" (quay lại mặc định nếu agent đó thiếu)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops

# Chuyển đổi hoặc xóa agent trên một công việc hiện có
openclaw cron edit <jobId> --agent ops
openclaw cron edit <jobId> --clear-agent

openclaw cron run <jobId>
openclaw cron run <jobId> --due

openclaw cron edit <jobId> \
  --message "Updated prompt" \
  --model "opus" \
  --thinking low

openclaw cron edit <jobId> --exact

openclaw cron runs --id <jobId> --limit 50

openclaw system event --mode now --text "Next heartbeat: check battery."

​

Bề mặt API Gateway

• cron.list, cron.status, cron.add, cron.update, cron.remove
• cron.run (force hoặc due), cron.runs Đối với các sự kiện hệ thống ngay lập tức mà không có công việc, sử dụng openclaw system event.

​

Khắc phục sự cố

​

”Không có gì chạy”

• Kiểm tra cron đã được kích hoạt: cron.enabled và OPENCLAW_SKIP_CRON.
• Kiểm tra Gateway đang chạy liên tục (cron chạy bên trong quá trình Gateway).
• Đối với lịch trình cron: xác nhận múi giờ (--tz) so với múi giờ máy chủ.

​

Một công việc định kỳ liên tục trì hoãn sau khi thất bại

• OpenClaw áp dụng backoff thử lại lũy tiến cho các công việc định kỳ sau các lỗi liên tiếp: 30s, 1m, 5m, 15m, sau đó 60m giữa các lần thử lại.
• Backoff tự động đặt lại sau lần chạy thành công tiếp theo.
• Các công việc một lần (at) thử lại lỗi tạm thời (giới hạn tốc độ, quá tải, mạng, lỗi máy chủ) tối đa 3 lần với backoff; lỗi vĩnh viễn vô hiệu hóa ngay lập tức. Xem Chính sách thử lại.

​

Telegram giao hàng đến sai nơi

• Đối với các chủ đề diễn đàn, sử dụng -100…:topic:<id> để nó rõ ràng và không mơ hồ.
• Nếu bạn thấy các tiền tố telegram:... trong nhật ký hoặc các mục tiêu “last route” đã lưu trữ, điều đó là bình thường; giao hàng cron chấp nhận chúng và vẫn phân tích cú pháp ID chủ đề chính xác.

​

Thông báo giao hàng subagent thử lại

• Khi một lượt chạy subagent hoàn thành, gateway thông báo kết quả cho phiên yêu cầu.
• Nếu luồng thông báo trả về false (ví dụ: phiên yêu cầu đang bận), gateway thử lại tối đa 3 lần với theo dõi qua announceRetryCount.
• Các thông báo cũ hơn 5 phút sau endedAt bị hết hạn cưỡng bức để ngăn các mục cũ lặp lại vô thời hạn.
• Nếu bạn thấy các thông báo giao hàng lặp lại trong nhật ký, kiểm tra đăng ký subagent để tìm các mục có giá trị announceRetryCount cao.