Tác vụ theo lịch

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

Bắt đầu nhanh

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

openclaw cron listopenclaw cron get <job-id>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 phải bên trong mô hình. Gateway phải đang chạy thì lịch mới được kích hoạt.
• Định nghĩa công việc, trạng thái thời gian chạy và lịch sử chạy được lưu bền vững trong cơ sở dữ liệu trạng thái SQLite dùng chung của OpenClaw, vì vậy việc khởi động lại không làm mất lịch.
• Mỗi lần thực thi Cron tạo một bản ghi tác vụ nền.
• Theo mặc định, các công việc chạy một lần (--at) sẽ tự động bị xóa sau khi thành công; truyền --keep-after-run để giữ lại.
• Ngân sách thời gian thực tế cho mỗi lần chạy: --timeout-seconds khi được đặt. Nếu không, các công việc lượt tác tử cô lập/tách rời bị giới hạn bởi bộ giám sát 60 phút riêng của Cron trước khi thời gian chờ lượt tác tử bên dưới (agents.defaults.timeoutSeconds, mặc định 48 giờ) có thể được áp dụng; công việc lệnh mặc định là 10 phút và tải trọng tập lệnh mặc định là 5 phút.
• Khi Gateway khởi động, các công việc lượt tác tử cô lập đã quá hạn được lên lịch lại thay vì phát lại ngay lập tức, giúp công việc khởi tạo mô hình/công cụ không diễn ra trong khoảng thời gian kết nối kênh.
• Nếu bạn điều khiển openclaw agent bằng Cron hệ thống hoặc một trình lập lịch bên ngoài khác, hãy bọc nó bằng cơ chế leo thang buộc dừng ngay cả khi CLI đã xử lý SIGTERM/SIGINT. Các lần chạy dựa trên Gateway yêu cầu Gateway hủy những lần chạy đã được chấp nhận; các lần chạy dự phòng cục bộ và nhúng nhận cùng tín hiệu hủy. Với GNU timeout, nên dùng timeout -k 60 600 openclaw agent ... thay vì chỉ dùng timeout 600 ... — giá trị -k là biện pháp dự phòng nếu tiến trình không thể kết thúc kịp thời. Với các đơn vị systemd, hãy dùng tín hiệu dừng SIGTERM với khoảng thời gian gia hạn (TimeoutStopSec) trước khi buộc dừng cuối cùng. Việc sử dụng lại một --run-id khi lần chạy Gateway ban đầu vẫn đang hoạt động sẽ báo cáo bản trùng lặp là đang thực thi thay vì bắt đầu lần chạy thứ hai.

Các loại lịch

Các dấu thời gian không có múi giờ được xem là UTC. Thêm --tz America/New_York để diễn giải một giá trị ngày giờ --at không có độ lệch, hoặc để đánh giá một biểu thức Cron, trong múi giờ IANA đó. Các biểu thức Cron không có --tz sử dụng múi giờ của máy chủ Gateway. --tz không hợp lệ với --every hoặc --on-exit.

Các biểu thức lặp lại vào đầu giờ (phút 0 với trường giờ là ký tự đại diện) được tự động phân tán tối đa 5 phút để giảm đột biến tải. Dùng --exact để buộc thời gian chính xác hoặc --stagger 30s để đặt khoảng thời gian rõ ràng (chỉ dành cho lịch Cron).

Nhịp động (điều tiết)

Các công việc lặp lại có thể đặt pacing.min và/hoặc pacing.max thành chuỗi thời lượng như 15m hoặc 4h; cần ít nhất một giới hạn. Dùng --pacing-min và --pacing-max với cron add|edit (--clear-pacing xóa cả hai giới hạn).

Trong một lần chạy cô lập, công việc có điều tiết có thể gọi công cụ cron với action: "next_check" và in: "30m". Đề xuất chỉ áp dụng cho công việc hiện đang chạy đó và được tính từ khi lần chạy hoàn tất thành công. OpenClaw âm thầm giới hạn đề xuất trong các giới hạn đã cấu hình.

Việc điều tiết không có đề xuất sẽ giữ nguyên lịch thông thường. Các lần chạy thất bại, hết thời gian chờ và bị bỏ qua sẽ loại bỏ đề xuất, vì vậy hành vi thử lại và tăng thời gian chờ khi có lỗi hiện tại được ưu tiên. Việc buộc chạy thủ công một công việc lặp lại nằm ngoài luồng và giữ nguyên khung giờ tự nhiên hoặc được điều tiết đang chờ. Với các công việc được kích hoạt theo điều kiện, khoảng thời gian tối thiểu tích hợp vẫn là giới hạn dưới ngay cả khi đề xuất yêu cầu kiểm tra sớm hơn.

Ngày trong tháng và ngày trong tuần sử dụng logic OR

Các biểu thức Cron được phân tích bởi 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.

# Mục đích: "9 giờ sáng ngày 15, chỉ khi đó là thứ Hai"# Thực tế:  "9 giờ sáng vào mọi ngày 15, VÀ 9 giờ sáng vào mọi thứ Hai"0 9 15 * 1

Lịch 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. Để 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 theo một trường và kiểm tra trường còn lại trong lời nhắc hoặc lệnh của công việc.

Trình kích hoạt sự kiện (trình theo dõi điều kiện)

Trình kích hoạt sự kiện thêm một tập lệnh điều kiện không giao diện vào lịch every hoặc cron. Cron đánh giá tập lệnh khi đến hạn công việc và chỉ chạy tải trọng thông thường khi tập lệnh trả về fire: true:

{  schedule: { kind: "every", everyMs: 30000 },  trigger: {    // Chỉ kích hoạt khi trạng thái quan sát được khác với lần đánh giá trước.    script: "const res = await tools.call('exec', { command: 'gh pr checks 123 --json state -q \\'.[].state\\' | sort -u' }); const status = String(res?.result?.details?.aggregated ?? '').trim(); json({ fire: status !== trigger.state?.status, message: `PR 123 CI: ${trigger.state?.status ?? 'unknown'} -> ${status}`, state: { status } });",    once: false,  },  payload: { kind: "agentTurn", message: "Investigate the CI status change." },}

Tập lệnh phải trả về { fire, message?, state? }. Trạng thái JSON trước đó có sẵn dưới dạng trigger.state được đóng băng sâu; trả về một giá trị state mới để lưu bền vững trạng thái đó. Trạng thái được giới hạn ở 16 KB. Khi kết quả kích hoạt bao gồm message, Cron nối nó vào văn bản sự kiện hệ thống hoặc thông điệp lượt tác tử trước khi thực thi. once: true vô hiệu hóa công việc sau tải trọng được kích hoạt thành công đầu tiên.

fire: false lưu bền vững trạng thái đánh giá và các bộ đếm, sau đó lên lịch lại mà không tạo lịch sử chạy. Nếu lần chạy tải trọng được kích hoạt thất bại, state được trả về sẽ không được lưu bền vững — lần đánh giá tiếp theo thấy trạng thái trước đó và có thể kích hoạt lại, vì vậy hãy viết tập lệnh dưới dạng phép kiểm tra chỉ đọc và giữ các hành động trong tải trọng. Lịch trình kích hoạt có khoảng thời gian tối thiểu có thể cấu hình (mặc định là 30 giây). Mỗi lần đánh giá có ngân sách thời gian thực tế là 30 giây và tối đa 5 lần gọi công cụ.

Hãy xây dựng trình theo dõi dựa trên trạng thái có thể hành động, không chỉ thành công: một trình theo dõi ngừng phản hồi khi phép kiểm tra thất bại hoặc hết thời gian chờ sẽ có vẻ vẫn hoạt động tốt dù đã hỏng. So sánh quan sát với trigger.state và trả về trạng thái mới để loại bỏ trùng lặp; không dựa vào bộ nhớ của mô hình hoặc tiến trình. Khi kích hoạt, hãy làm cho message tự chứa đầy đủ thông tin vì nó trở thành toàn bộ ngữ cảnh sự kiện của lần chạy được kích hoạt.

Tạo một trình theo dõi từ tệp tập lệnh cục bộ (- đọc tập lệnh từ đầu vào chuẩn):

openclaw cron add \  --name "PR CI watcher" \  --every 30s \  --trigger-script ./watch-pr-ci.js \  --message "Respond to the CI status change" \  --session isolated

Tải trọng

Mỗi công việc mang chính xác một loại tải trọng, được chọn bằng cờ:

Tùy chọn lượt tác tử

--model đặt mô hình chính của tác vụ; nó không thay thế ghi đè /model của phiên, vì vậy các chuỗi dự phòng đã cấu hình vẫn được áp dụng trên đó. Một mô hình không thể phân giải hoặc không được phép khiến lượt chạy thất bại với lỗi xác thực rõ ràng thay vì âm thầm chuyển về mô hình mặc định. Nếu tác vụ có --model nhưng không có danh sách dự phòng rõ ràng hoặc đã cấu hình, OpenClaw truyền một ghi đè dự phòng rỗng thay vì âm thầm nối thêm mô hình chính của tác tử làm mục tiêu thử lại ẩn.

Thứ tự ưu tiên chọn mô hình cho tác vụ cô lập, từ cao nhất:

1. Tải trọng theo từng tác vụ model (cấu hình rõ ràng; mô hình không được phép khiến lượt chạy thất bại)
2. Ghi đè mô hình của hook Gmail (chỉ khi lượt chạy đến từ Gmail và ghi đè đó được phép)
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 tử/mặc định

Chế độ nhanh tuân 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 sử dụng nó theo mặc định; ghi đè fastMode của phiên đã lưu (sau đó là fastModeDefault của tác tử) vẫn được ưu tiên hơn cấu hình mô hình theo cả hai hướng. Chế độ tự động sử dụng ngưỡng params.fastAutoOnSeconds của mô hình, mặc định là 60 giây.

Nếu một lượt chạy 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ựa chọn đó (cùng mọi hồ sơ xác thực mới) cho lượt 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 thêm 2 lần thử lại do chuyển đổi, Cron hủy bỏ thay vì lặp vô hạn.

Trước khi một lượt chạy cô lập bắt đầu, OpenClaw kiểm tra các điểm cuối cục bộ có thể truy cập của những nhà cung cấp api: "ollama" và api: "openai-completions" đã cấu hình mà baseUrl là loopback, mạng riêng hoặc .local. Bước kiểm tra trước này duyệt chuỗi dự phòng đã cấu hình của tác vụ và chỉ đánh dấu lượt chạy là skipped khi mọi ứng viên đều không thể truy cập; --fallbacks "" giữ việc duyệt nghiêm ngặt chỉ với mô hình chính. Một điểm cuối ngừng hoạt động ghi lượt chạy là skipped kèm lỗi rõ ràng thay vì bắt đầu gọi mô hình. Kết quả được lưu vào bộ nhớ đệm trong 5 phút cho mỗi điểm cuối (không phải mỗi tác vụ hoặc mô hình), vì vậy nhiều tác vụ đến hạn dùng chung một máy chủ Ollama/vLLM/SGLang/LM Studio cục bộ đã ngừng hoạt động chỉ tốn một lần thăm dò thay vì gây bão yêu cầu. Các lượt chạy bị bỏ qua trong bước kiểm tra trước không làm tăng thời gian chờ lũy tiến do lỗi thực thi; đặt failureAlert.includeSkipped để nhận cảnh báo bỏ qua lặp lại.

Tải trọng lệnh

Tải trọng lệnh chạy các tập lệnh xác định bên trong bộ lập lịch Gateway mà không bắt đầu lượt được mô hình hỗ trợ. Chúng thực thi trên máy chủ Gateway, thu thập stdout/stderr, ghi lượt chạy vào lịch sử Cron và sử dụng lại các chế độ gửi announce, webhook và none giống như tác vụ lượt tác tử.

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell> lưu argv: ["sh", "-lc", <shell>]. Sử dụng --command-argv '["node","scripts/report.mjs"]' để thực thi argv chính xác mà không phân tích cú pháp shell. Các tùy chọn --command-env KEY=VALUE (có thể lặp lại), --command-input, --timeout-seconds (mặc định 10 phút), --no-output-timeout-seconds và --output-max-bytes kiểm soát môi trường tiến trình, stdin và giới hạn đầu ra.

Văn bản được gửi bắt nguồn từ đầu ra tiến trình: stdout không rỗng được ưu tiên; nếu stdout rỗng và stderr không rỗng, stderr được gửi; nếu có cả hai, Cron gửi một khối stdout: / stderr: nhỏ. Mã thoát 0 ghi lượt chạy là ok; mã thoát khác không, tín hiệu, hết thời gian hoặc hết thời gian chờ không có đầu ra ghi error và có thể kích hoạt cảnh báo lỗi. Một lệnh chỉ in NO_REPLY sử dụng cơ chế chặn mã thông báo im lặng thông thường của Cron và không đăng gì trở lại cuộc trò chuyện.

Tải trọng tập lệnh

Tải trọng tập lệnh chạy không giao diện trong cùng trình thực thi chế độ mã như các tập lệnh kích hoạt, mà không bắt đầu một lượt tác tử hội thoại. Bật cron.triggers.enabled trước khi tạo hoặc chạy chúng; cổng tự động hóa nguy hiểm này áp dụng cho cả tập lệnh kích hoạt và tải trọng tập lệnh. Tác vụ tập lệnh chỉ hỗ trợ các đích phiên main và isolated.

openclaw cron create "0 * * * *" \  --name "Hourly queue check" \  --script ./automation/check-queue.js \  --script-timeout-seconds 300 \  --script-tool-budget 50 \  --session isolated \  --announce

Sử dụng --script <file|-> để đọc JavaScript từ tệp hoặc stdin. Thời gian chờ mặc định là 300 giây và tối đa là 900; ngân sách công cụ mặc định là 50 lượt gọi và tối đa là 200. Các ngân sách tải trọng này tách biệt với ngân sách đánh giá cổng kích hoạt nhỏ hơn.

Tập lệnh có thể trả về một đối tượng với các trường tùy chọn sau:

• notify: Văn bản được gửi qua chế độ gửi announce, webhook hoặc none của tác vụ. Nếu bỏ qua, không có gì được gửi. Với tác vụ main, văn bản trở thành một sự kiện hệ thống.
• wake: "now" yêu cầu Heartbeat ngay lập tức sau khi đưa notify (hoặc một sự kiện hoàn thành ngắn gọn) vào hàng đợi; "next-heartbeat" đưa sự kiện vào hàng đợi cho Heartbeat tiếp theo.
• state: Trạng thái JSON, giới hạn ở 16 KB và chỉ được lưu sau một lượt chạy thành công. Lượt chạy tiếp theo nhận một bản sao bất biến dưới dạng trigger.state, tương tự các tập lệnh kích hoạt. Vì không gian tên đó chỉ có một chủ sở hữu trạng thái lưu trữ, tải trọng tập lệnh không thể kết hợp với trình kích hoạt có điều kiện trên cùng một tác vụ.
• nextCheck: Một khoảng thời gian như "15m". Chỉ hợp lệ với các tác vụ đã bật điều tiết nhịp độ và sử dụng cùng giới hạn điều tiết như các đề xuất lượt tác tử.

Ngoại lệ, hết thời gian, cạn ngân sách công cụ, kết quả không hợp lệ và nextCheck khi không có điều tiết nhịp độ đều là lỗi lượt chạy Cron thông thường: chúng được đưa vào lịch sử lượt chạy, cơ chế chờ lũy tiến và xử lý cảnh báo lỗi mà không lưu trạng thái trả về.

Kiểu thực thi

Phân phối và đầu ra

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

Khi phân phối thông báo sử 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 duy nhất đã cấu hình. Chỉ các tiền tố do plugin đã tải công bố mới là bộ chọn nhà cung cấp. Nếu delivery.channel được chỉ định rõ ràng, tiền tố đích phải nêu cùng nhà cung cấp; channel: "whatsapp" với to: "telegram:123" sẽ bị từ chối thay vì để WhatsApp diễn giải ID Telegram thành số điện thoại. Các tiền tố loại đích và dịch vụ (channel:<id>, user:<id>, imessage:<handle>, 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.

Đối với các tác vụ cô lập, việc phân phối trò chuyện được dùng chung: nếu có tuyến trò chuyện, agent có thể sử dụng công cụ message ngay cả với --no-deliver. Nếu agent gửi đến đích đã cấu hình/hiện tại, OpenClaw bỏ qua thông báo 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 lời nhắc cô lập 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 giữ nguyên cho tuyến thông báo dự phòng. Khóa phiên nội bộ có thể viết 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 có ngữ cảnh trò chuyện hiện tại.

Phân phối thông báo ngầm định sử 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 lỗi thời. Các phê duyệt trong 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

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

• cron.failureDestination đặt giá trị mặc định toàn cục cho thông báo lỗi.
• job.delivery.failureDestination ghi đè giá trị đó 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 quay về đích thông báo 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 cho phép một tác vụ hoặc chính sách cảnh báo cron toàn cục nhận cảnh báo lặp lại về các lượt chạy bị bỏ qua. Các lượt chạy bị bỏ qua duy trì bộ đếm bỏ qua liên tiếp riêng, vì vậy chúng không ảnh hưởng đến cơ chế lùi thời gian do lỗi thực thi.
• openclaw cron edit cung cấp khả năng tinh chỉnh cảnh báo theo từng tác vụ: --failure-alert/--no-failure-alert, --failure-alert-after <n>, --failure-alert-channel, --failure-alert-to, --failure-alert-cooldown, --failure-alert-include-skipped/--failure-alert-exclude-skipped, --failure-alert-mode và --failure-alert-account-id.

Ngôn ngữ đầu ra

Các tác vụ Cron không suy luận ngôn ngữ phản hồi từ kênh, ngôn ngữ hoặc tin nhắn trước đó. Đặt quy tắc ngôn ngữ trong tin nhắn hoặc mẫu đã lên lịch:

openclaw cron edit <jobId> \  --message "Tóm tắt các bản cập nhật. Trả lời bằng tiếng Trung; giữ nguyên URL, mã và tên sản phẩm."

Đối với tệp mẫu, giữ chỉ dẫn ngôn ngữ trong lời nhắc đã kết xuất và xác minh rằng các phần giữ chỗ như {{language}} đã được điền trước khi tác vụ chạy. Nếu đầu ra trộn lẫn các ngôn ngữ, hãy nêu rõ quy tắc, ví dụ: "Sử dụng tiếng Trung cho văn bản tường thuật và giữ các thuật ngữ kỹ thuật bằng tiếng Anh."

Ví dụ CLI

openclaw cron add \  --name "Kiểm tra lịch" \  --at "20m" \  --session main \  --system-event "Heartbeat tiếp theo: kiểm tra lịch." \  --wake now

openclaw cron create "0 7 * * *" \  "Tóm tắt các bản cập nhật qua đêm." \  --name "Bản tin buổi sáng" \  --tz "America/Los_Angeles" \  --session isolated \  --announce \  --channel slack \  --to "channel:C1234567890"

openclaw cron add \  --name "Phân tích chuyên sâu" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "Phân tích chuyên sâu hằng tuần về tiến độ dự án." \  --model "opus" \  --thinking high \  --announce

openclaw cron create "0 18 * * 1-5" \  "Tóm tắt các lần triển khai hôm nay dưới dạng JSON." \  --name "Bản tổng hợp triển khai" \  --webhook "https://example.invalid/openclaw/cron"

openclaw cron create "*/15 * * * *" \  --name "Thăm dò độ sâu hàng đợi" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

Quản lý tác vụ

# Liệt kê tất cả tác vụopenclaw cron list # Lấy một tác vụ đã lưu dưới dạng JSONopenclaw cron get <jobId> # Hiển thị một tác vụ, bao gồm tuyến phân phối đã phân giảiopenclaw cron show <jobId> # Bật/tắt mà không xóaopenclaw cron enable <jobId>openclaw cron disable <jobId> # Chỉnh sửa một tác vụopenclaw cron edit <jobId> --message "Lời nhắc đã cập nhật" --model "opus" # Buộc chạy một tác vụ ngay bây giờopenclaw cron run <jobId> # Buộc chạy một tác vụ ngay bây giờ và chờ trạng thái kết thúcopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Chỉ chạy nếu đến hạnopenclaw cron run <jobId> --due # Xem lịch sử chạyopenclaw cron runs --id <jobId> --limit 50 # Xem chính xác một lượt chạyopenclaw cron runs --id <jobId> --run-id <runId> # Xóa một tác vụopenclaw cron remove <jobId> # Chọn agent (thiết lập nhiều agent)openclaw cron create "0 6 * * *" "Kiểm tra hàng đợi vận hành" --name "Rà soát vận hành" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

Việc lưu trữ một phiên (Control UI hoặc sessions.patch { archived: true } từ trình gọi operator-admin) sẽ tắt mọi tác vụ cron đang bật được liên kết với phiên đó: phiên cron:<jobId> cô lập của nó, một đích session:<key>, hoặc một làn phân phối/đánh thức sessionKey. Khôi phục phiên không bật lại các tác vụ đó; sử dụng openclaw cron enable <jobId>. Các phiên có tác vụ liên kết đang bật hiển thị huy hiệu đồng hồ trong thanh bên Control UI.

openclaw cron run <jobId> trả về sau khi đưa lượt chạy thủ công vào hàng đợi. Sử dụng --wait cho hook tắt hệ thống, tập lệnh bảo trì hoặc tác vụ tự động hóa khác phải chặn cho đến khi lượt chạy trong hàng đợi hoàn tất; lệnh này thăm dò runId được trả về (thời gian chờ mặc định 10m, khoảng thăm dò 2s) và thoát với mã 0 cho trạng thái ok, mã khác không cho error, skipped hoặc khi hết thời gian chờ.

Công cụ agent cron trả về bản tóm tắt tác vụ nhỏ gọn (id, name, enabled, nextRunAtMs, scheduleKind, lastRunStatus) từ cron(action: "list"); sử dụng cron(action: "get", jobId: "...") để lấy một định nghĩa tác vụ đầy đủ. Các trình gọi Gateway trực tiếp có thể truyền compact: true đến cron.list; việc bỏ qua giá trị này giữ nguyên phản hồi đầy đủ cùng bản xem trước phân phối.

openclaw cron create là bí danh của openclaw cron add. Tác vụ mới có thể sử dụng lịch biểu theo vị trí ("0 9 * * 1", "every 1h", "20m" hoặc dấu thời gian ISO), sau đó là lời nhắc agent theo vị trí. Sử dụng --webhook <url> trên cron add|create hoặc cron edit để POST payload của lượt chạy đã hoàn tất đến một điểm cuối HTTP; phân phối Webhook không thể kết hợp với các cờ phân phối trò chuyện (--announce, --channel, --to, --thread-id, --account). Trên cron edit, --clear-channel, --clear-to, --clear-thread-id và --clear-account, hãy hủy đặt riêng từng trường định tuyến đó (mỗi trường bị từ chối khi dùng cùng cờ đặt tương ứng) — khác với --no-deliver, chỉ tắt phân phối dự phòng của trình chạy.

Webhook

Gateway có thể cung cấp các điểm cuối Webhook HTTP 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 token hook qua header:

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

Token trong chuỗi truy vấn sẽ 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":"Đã nhận email mới","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"Tóm tắt hộp thư đến","name":"Email","model":"openai/gpt-5.6-sol"}'

Tích hợp Gmail PubSub

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

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

openclaw webhooks gmail setup --account openclaw@gmail.com

Lệnh này ghi cấu hình hooks.gmail, bật thiết lập sẵn Gmail và mặc định dùng Tailscale Funnel cho endpoint push (--tailscale funnel|serve|off).

Tự động khởi động Gateway

Khi hooks.enabled=true được bật và hooks.gmail.account được đặt, Gateway sẽ khởi động gog gmail watch serve khi khởi động hệ thống và tự động gia hạn việc theo dõi. Đặt OPENCLAW_SKIP_GMAIL_WATCHER=1 để tắt tính năng này.

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

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

gcloud pubsub topics create gog-gmail-watchgcloud pubsub topics add-iam-policy-binding gog-gmail-watch \  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \  --role=roles/pubsub.publisher

gog gmail watch start \  --account openclaw@gmail.com \  --label INBOX \  --topic projects/<project-id>/topics/gog-gmail-watch

Ghi đè mô hình Gmail

{  hooks: {    gmail: {      model: "openai/gpt-5.6-sol",      thinking: "high",    },  },}

Đối với hộp thư đến không đáng tin cậy, hãy sử dụng mô hình thế hệ mới nhất thuộc hạng tốt nhất hiện có từ nhà cung cấp. Giá trị trên chỉ là ví dụ; mô hình phải tồn tại trong danh mục và danh sách cho phép đã cấu hình.

Cấu hình

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    triggers: {      enabled: false,    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",  },}

webhookToken được gửi dưới dạng Authorization: Bearer <token> trong các yêu cầu POST Webhook cron.

cron.store là khóa kho lưu trữ logic và đường dẫn di chuyển của doctor, không phải tệp JSON trực tiếp để chỉnh sửa thủ công. Dữ liệu tác vụ nằm trong SQLite; hãy sử dụng CLI hoặc API Gateway để thay đổi.

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

Khắc phục sự cố

Chuỗi lệnh kiểm tra

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

Liên quan

• Tự động hóa — tổng quan nhanh về tất cả cơ chế tự động hóa
• Tác vụ nền — sổ theo dõ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ờ