Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw cron
Quản lý các tác vụ Cron cho bộ lập lịch Gateway.
Phiên
--session chấp nhận main, isolated, current, hoặc session:<id>.
Session keys
Session keys
mainliên kết với phiên chính của agent.isolatedtạo một transcript mới và session id mới cho mỗi lần chạy.currentliên kết với phiên đang hoạt động tại thời điểm tạo.session:<id>ghim vào một khóa phiên bền vững rõ ràng.
Isolated session semantics
Isolated session semantics
Các lần chạy cô lập đặt lại ngữ cảnh hội thoại xung quanh. Định tuyến kênh và nhóm, chính sách gửi/xếp hàng, nâng quyền, nguồn gốc, và liên kết runtime ACP được đặt lại cho lần chạy mới. Các tùy chọn an toàn và model do người dùng chọn rõ ràng hoặc ghi đè xác thực có thể được giữ qua các lần chạy.
Phân phối
openclaw cron list và openclaw cron show <job-id> xem trước tuyến phân phối đã phân giải. Với channel: "last", bản xem trước hiển thị tuyến được phân giải từ phiên chính hay phiên hiện tại, hoặc sẽ thất bại đóng.
Các tác vụ
cron add cô lập mặc định dùng phân phối --announce. Dùng --no-deliver để giữ đầu ra nội bộ. --deliver vẫn là bí danh đã lỗi thời cho --announce.Quyền sở hữu phân phối
Phân phối chat Cron cô lập được chia sẻ giữa agent và runner:- Agent có thể gửi trực tiếp bằng công cụ
messagekhi có tuyến chat. announcephân phối dự phòng chỉ phản hồi cuối cùng khi agent không gửi trực tiếp đến đích đã phân giải.webhookđăng payload đã hoàn tất lên một URL.nonetắt phân phối dự phòng của runner.
--announce là phân phối dự phòng của runner cho phản hồi cuối cùng. --no-deliver tắt dự phòng đó nhưng không xóa công cụ message của agent khi có tuyến chat.
Nhắc nhở được tạo từ một chat đang hoạt động giữ nguyên đích phân phối chat trực tiếp cho phân phối thông báo dự phòng. Khóa phiên nội bộ có thể ở dạng chữ thường; đừng dùng chúng làm nguồn sự thật cho ID nhà cung cấp phân biệt hoa thường, chẳng hạn như ID phòng Matrix.
Phân phối lỗi
Thông báo lỗi được phân giải theo thứ tự này:delivery.failureDestinationtrên tác vụ.cron.failureDestinationtoàn cục.- Đích thông báo chính của tác vụ (khi không đặt đích lỗi rõ ràng).
Các tác vụ phiên chính chỉ có thể dùng
delivery.failureDestination khi chế độ phân phối chính là webhook. Các tác vụ cô lập chấp nhận nó trong mọi chế độ.Lập lịch
Tác vụ chạy một lần
--at <datetime> lập lịch một lần chạy một lần. Datetime không có offset được xem là UTC trừ khi bạn cũng truyền --tz <iana>, khi đó thời gian theo đồng hồ sẽ được diễn giải trong múi giờ đã cho.
Theo mặc định, tác vụ chạy một lần sẽ bị xóa sau khi thành công. Dùng
--keep-after-run để giữ lại chúng.Tác vụ lặp lại
Tác vụ lặp lại dùng backoff thử lại theo hàm mũ sau các lỗi liên tiếp: 30 giây, 1 phút, 5 phút, 15 phút, 60 phút. Lịch trở lại bình thường sau lần chạy thành công tiếp theo. Các lần chạy bị bỏ qua được theo dõi riêng với lỗi thực thi. Chúng không ảnh hưởng đến backoff thử lại, nhưngopenclaw cron edit <job-id> --failure-alert-include-skipped có thể chọn đưa thông báo lỗi vào các thông báo lặp lại về lần chạy bị bỏ qua.
Với các tác vụ cô lập nhắm đến một nhà cung cấp model cục bộ đã cấu hình, Cron chạy một bước kiểm tra trước nhẹ nhàng cho nhà cung cấp trước khi bắt đầu lượt agent. Các nhà cung cấp local loopback, mạng riêng, và .local api: "ollama" được thăm dò tại /api/tags; các nhà cung cấp tương thích OpenAI cục bộ như vLLM, SGLang, và LM Studio được thăm dò tại /models. Nếu endpoint không truy cập được, lần chạy được ghi nhận là skipped và được thử lại ở lịch sau; các endpoint chết khớp sẽ được cache trong 5 phút để tránh nhiều tác vụ dồn dập đánh vào cùng một máy chủ cục bộ.
Lưu ý: định nghĩa tác vụ Cron nằm trong jobs.json, trong khi trạng thái runtime đang chờ nằm trong jobs-state.json. Nếu jobs.json được chỉnh sửa từ bên ngoài, Gateway tải lại các lịch đã thay đổi và xóa các ô chờ đã cũ; các lần viết lại chỉ thay đổi định dạng không xóa ô chờ.
Chạy thủ công
openclaw cron run trả về ngay khi lần chạy thủ công được xếp hàng. Phản hồi thành công bao gồm { ok: true, enqueued: true, runId }. Dùng openclaw cron runs --id <job-id> để theo dõi kết quả cuối cùng.
openclaw cron run <job-id> mặc định chạy cưỡng bức. Dùng --due để giữ hành vi cũ “chỉ chạy nếu đã đến hạn”.Model
cron add|edit --model <ref> chọn một model được phép cho tác vụ.
Cron --model là model chính của tác vụ, không phải ghi đè /model của phiên chat. Điều đó có nghĩa là:
- Các fallback model đã cấu hình vẫn áp dụng khi model tác vụ đã chọn thất bại.
- Payload theo tác vụ
fallbacksthay thế danh sách fallback đã cấu hình khi có mặt. - Danh sách fallback theo tác vụ rỗng (
fallbacks: []trong payload/API của tác vụ) khiến lần chạy Cron trở nên nghiêm ngặt. - Khi một tác vụ có
--modelnhưng không cấu hình danh sách fallback, OpenClaw truyền một ghi đè fallback rỗng rõ ràng để model chính của agent không được thêm vào như một đích thử lại ẩn.
Thứ tự ưu tiên model Cron cô lập
Cron cô lập phân giải model đang hoạt động theo thứ tự này:- Ghi đè Gmail-hook.
--modeltheo tác vụ.- Ghi đè model phiên Cron đã lưu (khi người dùng đã chọn một model).
- Lựa chọn model của agent hoặc mặc định.
Chế độ nhanh
Chế độ nhanh Cron cô lập tuân theo lựa chọn model trực tiếp đã phân giải. Cấu hình modelparams.fastMode áp dụng theo mặc định, nhưng ghi đè fastMode của phiên đã lưu vẫn thắng cấu hình.
Thử lại chuyển đổi model trực tiếp
Nếu một lần chạy cô lập némLiveSessionModelSwitchError, Cron lưu nhà cung cấp và model đã chuyển đổi (và ghi đè hồ sơ xác thực đã chuyển đổi khi có) cho lần chạy đang hoạt động trước khi thử lại. Vòng lặp thử lại bên ngoài bị giới hạn ở hai lần thử lại chuyển đổi sau lần thử ban đầu, rồi hủy thay vì lặp vô hạn.
Đầu ra lần chạy và từ chối
Chặn xác nhận cũ
Các lượt Cron cô lập chặn các phản hồi chỉ xác nhận đã cũ. Nếu kết quả đầu tiên chỉ là một cập nhật trạng thái tạm thời và không có lần chạy subagent hậu duệ chịu trách nhiệm cho câu trả lời cuối cùng, Cron nhắc lại một lần để lấy kết quả thật trước khi phân phối.Chặn token im lặng
Nếu một lần chạy Cron cô lập chỉ trả về token im lặng (NO_REPLY hoặc no_reply), Cron chặn cả phân phối trực tiếp đi ra và đường dẫn tóm tắt xếp hàng dự phòng, nên không có gì được đăng lại vào chat.
Từ chối có cấu trúc
Các lần chạy Cron cô lập ưu tiên metadata 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ừ chối đã biết trong đầu ra cuối cùng, chẳng hạn nhưSYSTEM_RUN_DENIED, INVALID_REQUEST, và các cụm từ từ chối liên kết phê duyệt.
cron list và lịch sử chạy hiển thị lý do từ chối thay vì báo cáo một lệnh bị chặn là ok.
Lưu giữ
Lưu giữ và cắt tỉa được kiểm soát trong cấu hình:cron.sessionRetention(mặc định24h) cắt tỉa các phiên chạy cô lập đã hoàn tất.cron.runLog.maxBytesvàcron.runLog.keepLinescắt tỉa~/.openclaw/cron/runs/<jobId>.jsonl.
Di chuyển tác vụ cũ hơn
Nếu bạn có tác vụ Cron từ trước định dạng lưu trữ và phân phối hiện tại, hãy chạy
openclaw doctor --fix. Doctor chuẩn hóa các trường Cron cũ (jobId, schedule.cron, các trường phân phối cấp cao nhất bao gồm threadId cũ, các bí danh phân phối provider của payload) và di chuyển các tác vụ fallback webhook đơn giản notify: true sang phân phối webhook rõ ràng khi cron.webhook được cấu hình.Chỉnh sửa thường gặp
Cập nhật cài đặt phân phối mà không thay đổi thông điệp:--light-context chỉ áp dụng cho các tác vụ lượt agent cô lập. Với các lần chạy Cron, chế độ nhẹ giữ ngữ cảnh bootstrap trống thay vì tiêm toàn bộ tập bootstrap của workspace.
Lệnh quản trị thường gặp
Chạy thủ công và kiểm tra:cron runs bao gồm chẩn đoán phân phối với đích Cron dự kiến, đích đã phân giải, các lần gửi bằng công cụ message, việc dùng fallback, và trạng thái đã phân phối.
Đổi đích agent và phiên: