Tác vụ đã lên lịch

Cron là bộ lập lịch tích hợp sẵn của Gateway. Nó lưu trữ các job lâu bền, đánh thức tác nhân vào đúng thời điểm và có thể gửi đầu ra trở lại một kênh trò chuyện hoặc điểm cuối Webhook.

# Bắt đầu nhanh

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 show <job-id>

openclaw cron runs --id <job-id>

# Cách cron hoạt động

• Cron chạy bên trong tiến trình Gateway (không chạy bên trong mô hình).
• Định nghĩa job được lưu lâu bền tại ~/.openclaw/cron/jobs.json để các lần khởi động lại không làm mất lịch.
• Trạng thái thực thi runtime được lưu cạnh đó trong ~/.openclaw/cron/jobs-state.json. Nếu bạn theo dõi định nghĩa cron trong git, hãy theo dõi jobs.json và đưa jobs-state.json vào gitignore.
• Sau khi tách ra, các phiên bản OpenClaw cũ hơn có thể đọc jobs.json nhưng có thể coi job là mới vì các trường runtime hiện nằm trong jobs-state.json.
• Khi jobs.json được chỉnh sửa trong lúc Gateway đang chạy hoặc đã dừng, OpenClaw so sánh các trường lịch đã thay đổi với siêu dữ liệu slot runtime đang chờ và xóa các giá trị nextRunAtMs đã lỗi thời. Các lần viết lại chỉ thay đổi định dạng hoặc thứ tự khóa vẫn giữ nguyên slot đang chờ.
• Tất cả lần thực thi cron đều tạo bản ghi tác vụ nền.
• Khi Gateway khởi động, các job lượt tác nhân cô lập đã quá hạn được lập lịch lại ra ngoài khoảng kết nối kênh thay vì phát lại ngay lập tức, nhờ đó quá trình khởi động Discord/Telegram và thiết lập lệnh gốc vẫn phản hồi tốt sau khi khởi động lại.
• Job chạy một lần (--at) mặc định tự động xóa sau khi thành công.
• Các lần chạy cron cô lập cố gắng đóng các tab/quy trình trình duyệt được theo dõi cho phiên cron:<jobId> của chúng khi lần chạy hoàn tất, để tự động hóa trình duyệt tách rời không để lại quy trình mồ côi.
• Các lần chạy cron cô lập nhận được quyền tự dọn dẹp cron hẹp vẫn có thể đọc trạng thái bộ lập lịch và danh sách tự lọc của job hiện tại của chúng, để kiểm tra trạng thái/Heartbeat có thể xem lịch của chính chúng mà không có quyền thay đổi cron rộng hơn.
• Các lần chạy cron cô lập cũng bảo vệ khỏi phản hồi xác nhận lỗi thời. Nếu kết quả đầu tiên chỉ là một cập nhật trạng thái tạm thời (on it, pulling everything together và các gợi ý tương tự) và không có lần chạy tác nhân con nào vẫn chịu trách nhiệm cho câu trả lời cuối cùng, OpenClaw sẽ nhắc lại một lần để lấy kết quả thực tế trước khi gửi.
• Các lần chạy cron cô lập ưu tiên siêu dữ liệu từ chối thực thi có cấu trúc từ lần chạy nhúng, rồi quay về các dấu hiệu tóm tắt/đầu ra cuối đã biết như SYSTEM_RUN_DENIED và INVALID_REQUEST, để một lệnh bị chặn không bị báo cáo là lượt chạy thành công.
• Các lần chạy cron cô lập cũng coi lỗi tác nhân cấp lượt chạy là lỗi job ngay cả khi không tạo payload phản hồi, để lỗi mô hình/nhà cung cấp làm tăng bộ đếm lỗi và kích hoạt thông báo lỗi thay vì xóa job như thể đã thành công.
• Khi một job lượt tác nhân cô lập đạt timeoutSeconds, cron hủy lần chạy tác nhân bên dưới và cho nó một khoảng ngắn để dọn dẹp. Nếu lần chạy không thoát hết, quá trình dọn dẹp do Gateway sở hữu sẽ buộc xóa quyền sở hữu phiên của lần chạy đó trước khi cron ghi nhận timeout, để công việc trò chuyện trong hàng đợi không bị kẹt sau một phiên xử lý đã lỗi thời.

# Kiểu lịch

Dấu thời gian không có múi giờ được xử lý là UTC. Thêm --tz America/New_York để lập lịch theo giờ địa phương.

Các biểu thức lặp lại vào đầu giờ được tự động rải lệch tối đa 5 phút để giảm đỉnh tải. Dùng --exact để buộc thời điểm chính xác hoặc --stagger 30s cho một cửa sổ rõ ràng.

# Ngày trong tháng và ngày trong tuần dùng logic OR

Biểu thức cron được phân tích bằng croner. Khi cả trường ngày trong tháng và ngày trong tuần đều không phải ký tự đại diện, croner khớp khi một trong hai trường khớp — không phải cả hai. Đây là hành vi cron Vixie tiêu chuẩn.

# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1

Điều này kích hoạt khoảng 5–6 lần mỗi tháng thay vì 0–1 lần mỗi tháng. OpenClaw dùng hành vi OR mặc định của Croner ở đây. Để yêu cầu cả hai điều kiện, hãy dùng bộ sửa đổi ngày trong tuần + của Croner (0 9 15 * +1) hoặc lập lịch trên một trường và kiểm tra trường còn lại trong prompt hoặc lệnh của job.

# Kiểu thực thi

# Tùy chọn payload cho job cô lập

--model dùng mô hình được phép đã chọn làm mô hình chính của job đó. Nó không giống ghi đè /model của phiên trò chuyện: các chuỗi dự phòng đã cấu hình vẫn áp dụng khi mô hình chính của job thất bại. Nếu mô hình được yêu cầu không được phép hoặc không thể phân giải, cron làm lần chạy thất bại với lỗi xác thực rõ ràng thay vì âm thầm quay về lựa chọn mô hình tác nhân/mặc định của job.

Nếu các mục jobs.json cũ hơn hoặc được chỉnh tay lưu payload.model là "default", "null", chuỗi trống hoặc JSON null, hãy chạy openclaw doctor --fix. Doctor xóa các sentinel ghi đè đã lưu không hợp lệ đó; runtime không hỗ trợ chúng làm bí danh dự phòng. Bỏ qua trường mô hình để dùng lựa chọn mô hình tác nhân/mặc định thông thường.

Job Cron cũng có thể mang fallbacks cấp payload. Khi có mặt, danh sách đó thay thế chuỗi dự phòng đã cấu hình cho job. Dùng fallbacks: [] trong payload/API của job khi bạn muốn một lần chạy cron nghiêm ngặt chỉ thử mô hình đã chọn. Nếu một job có --model nhưng không có dự phòng payload hoặc dự phòng đã cấu hình, OpenClaw truyền một ghi đè dự phòng rỗng rõ ràng để mô hình chính của tác nhân không được thêm làm mục tiêu thử lại ẩn.

Thứ tự ưu tiên chọn mô hình cho job cô lập là:

1. Ghi đè mô hình hook Gmail (khi lần chạy đến từ Gmail và ghi đè đó được phép)
2. model trong payload của từng job
3. Ghi đè mô hình phiên cron đã lưu do người dùng chọn
4. Lựa chọn mô hình tác nhân/mặc định

Chế độ nhanh cũng đi theo lựa chọn trực tiếp đã phân giải. Nếu cấu hình mô hình đã chọn có params.fastMode, cron cô lập mặc định dùng cấu hình đó. Ghi đè fastMode của phiên đã lưu vẫn thắng cấu hình theo cả hai hướng.

Nếu một lần chạy cô lập gặp bàn giao chuyển đổi mô hình trực tiếp, cron thử lại với nhà cung cấp/mô hình đã chuyển đổi và lưu lâu bền lựa chọn trực tiếp đó cho lần chạy đang hoạt động trước khi thử lại. Khi chuyển đổi cũng mang theo một hồ sơ xác thực mới, cron cũng lưu lâu bền ghi đè hồ sơ xác thực đó cho lần chạy đang hoạt động. Số lần thử lại có giới hạn: sau lần thử ban đầu cộng với 2 lần thử lại chuyển đổi, cron hủy thay vì lặp mãi mãi.

Trước khi một lần chạy cron cô lập đi vào trình chạy tác nhân, OpenClaw kiểm tra các điểm cuối nhà cung cấp cục bộ có thể truy cập cho các nhà cung cấp api: "ollama" và api: "openai-completions" đã cấu hình mà baseUrl là local loopback, mạng riêng hoặc .local. Nếu điểm cuối đó ngừng hoạt động, lần chạy được ghi là skipped với lỗi nhà cung cấp/mô hình rõ ràng thay vì bắt đầu một lệnh gọi mô hình. Kết quả điểm cuối được lưu đệm trong 5 phút, nên nhiều job đến hạn dùng cùng một máy chủ Ollama, vLLM, SGLang hoặc LM Studio cục bộ đã chết sẽ dùng chung một phép thăm dò nhỏ thay vì tạo bão yêu cầu. Các lần chạy bị bỏ qua do kiểm tra trước nhà cung cấp không làm tăng backoff lỗi thực thi; bật failureAlert.includeSkipped khi bạn muốn thông báo bỏ qua lặp lại.

# Gửi và đầu ra

Dùng --announce --channel telegram --to "-1001234567890" để phân phối qua kênh. Với các chủ đề diễn đàn Telegram, dùng -1001234567890:topic:123; các trình gọi RPC/cấu hình trực tiếp cũng có thể truyền delivery.threadId dưới dạng chuỗi hoặc số. Các đích Slack/Discord/Mattermost nên dùng tiền tố tường minh (channel:<id>, user:<id>). ID phòng Matrix phân biệt chữ hoa chữ thường; dùng ID phòng chính xác hoặc dạng room:!room:server từ Matrix.

Khi phân phối announce dùng channel: "last" hoặc bỏ qua channel, một đích có tiền tố nhà cung cấp như telegram:123 có thể chọn kênh trước khi cron quay về lịch sử phiên hoặc một kênh đã cấu hình duy nhất. Chỉ các tiền tố được Plugin đã tải quảng bá mới là bộ chọn nhà cung cấp. Nếu delivery.channel là tường minh, tiền tố đích phải đặt tên cùng nhà cung cấp; ví dụ, channel: "whatsapp" với to: "telegram:123" sẽ bị từ chối thay vì để WhatsApp diễn giải ID Telegram như một số điện thoại. Các tiền tố loại đích và dịch vụ như channel:<id>, user:<id>, imessage:<handle>, và sms:<number> vẫn là cú pháp đích do kênh sở hữu, không phải bộ chọn nhà cung cấp.

Với các tác vụ tách biệt, phân phối trò chuyện được chia sẻ. Nếu có tuyến trò chuyện, agent có thể dùng công cụ message ngay cả khi tác vụ dùng --no-deliver. Nếu agent gửi đến đích đã cấu hình/hiện tại, OpenClaw bỏ qua announce dự phòng. Nếu không, announce, webhook, và none chỉ kiểm soát cách trình chạy xử lý phản hồi cuối cùng sau lượt agent.

Khi agent tạo một lời nhắc tách biệt từ một cuộc trò chuyện đang hoạt động, OpenClaw lưu đích phân phối trực tiếp được bảo toàn cho tuyến announce dự phòng. Khóa phiên nội bộ có thể là chữ thường; đích phân phối của nhà cung cấp không được tái tạo từ các khóa đó khi ngữ cảnh trò chuyện hiện tại có sẵn.

Phân phối announce ngầm định dùng danh sách cho phép của kênh đã cấu hình để xác thực và định tuyến lại các đích cũ. Các phê duyệt từ kho ghép cặp DM không phải là người nhận tự động hóa dự phòng; đặt delivery.to hoặc cấu hình mục allowFrom của kênh khi một tác vụ đã lên lịch cần chủ động gửi đến DM.

Thông báo lỗi đi theo một đường dẫn đích riêng:

• cron.failureDestination đặt mặc định toàn cục cho thông báo lỗi.
• job.delivery.failureDestination ghi đè thiết lập đó cho từng tác vụ.
• Nếu cả hai đều chưa được đặt và tác vụ đã phân phối qua announce, thông báo lỗi hiện quay về đích announce chính đó.
• delivery.failureDestination chỉ được hỗ trợ trên các tác vụ sessionTarget="isolated" trừ khi chế độ phân phối chính là webhook.
• failureAlert.includeSkipped: true đưa chính sách cảnh báo cron toàn cục hoặc của tác vụ vào các cảnh báo lần chạy bị bỏ qua lặp lại. Các lần chạy bị bỏ qua giữ một bộ đếm bỏ qua liên tiếp riêng, nên chúng không ảnh hưởng đến backoff lỗi thực thi.

# Ví dụ CLI

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

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"

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

# Webhook

Gateway có thể cung cấp các điểm cuối HTTP Webhook cho trình kích hoạt bên ngoài. Bật trong cấu hình:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

# Xác thực

Mọi yêu cầu phải bao gồm mã thông báo hook qua header:

• Authorization: Bearer <token> (khuyến nghị)
• x-openclaw-token: <token>

Mã thông báo trong chuỗi truy vấn bị từ chối.

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'

# Tích hợp Gmail PubSub

Nối trình kích hoạt hộp thư đến Gmail với OpenClaw qua Google PubSub.

# Thiết lập bằng trình hướng dẫn (khuyến nghị)

openclaw webhooks gmail setup --account [email protected]

Lệnh này ghi cấu hình hooks.gmail, bật preset Gmail, và dùng Tailscale Funnel cho điểm cuối push.

# Tự khởi động Gateway

Khi hooks.enabled=true và hooks.gmail.account được đặt, Gateway khởi động gog gmail watch serve khi boot và tự động gia hạn watch. Đặt OPENCLAW_SKIP_GMAIL_WATCHER=1 để chọn không dùng.

# Thiết lập thủ công một lần

gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:[email protected] \
  --role=roles/pubsub.publisher

gog gmail watch start \
  --account [email protected] \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

# Ghi đè mô hình Gmail

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

# Quản lý tác vụ

# List all jobs
openclaw cron list

# Show one job, including resolved delivery route
openclaw cron show <jobId>

# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# Force run a job now
openclaw cron run <jobId>

# Run only if due
openclaw cron run <jobId> --due

# View run history
openclaw cron runs --id <jobId> --limit 50

# Delete a job
openclaw cron remove <jobId>

# Agent selection (multi-agent setups)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent

# Cấu hình

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

maxConcurrentRuns giới hạn cả việc điều phối cron theo lịch và thực thi lượt agent tách biệt. Các lượt agent cron tách biệt dùng nội bộ làn thực thi cron-nested chuyên dụng của hàng đợi, nên việc tăng giá trị này cho phép các lần chạy LLM cron độc lập tiến triển song song thay vì chỉ khởi động các wrapper cron bên ngoài của chúng. Làn nested không thuộc cron dùng chung không được mở rộng bởi thiết lập này.

Sidecar trạng thái runtime được dẫn xuất từ cron.store: một kho .json như ~/clawd/cron/jobs.json dùng ~/clawd/cron/jobs-state.json, trong khi đường dẫn kho không có hậu tố .json sẽ nối thêm -state.json.

Nếu bạn chỉnh sửa thủ công jobs.json, hãy để jobs-state.json ngoài kiểm soát mã nguồn. OpenClaw dùng sidecar đó cho slot đang chờ, marker đang hoạt động, siêu dữ liệu lần chạy gần nhất, và định danh lịch cho bộ lập lịch biết khi nào một tác vụ được chỉnh sửa bên ngoài cần nextRunAtMs mới.

Tắt cron: cron.enabled: false hoặc OPENCLAW_SKIP_CRON=1.

# Khắc phục sự cố

# Thang lệnh

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

# Liên quan

• Tự động hóa & Tác vụ — tất cả cơ chế tự động hóa trong một cái nhìn tổng quan
• Tác vụ nền — sổ cái tác vụ cho các lần thực thi cron
• Heartbeat — các lượt phiên chính định kỳ
• Múi giờ — cấu hình múi giờ