openclaw cron

Kelola tugas Cron untuk penjadwal Gateway.

Membuat tugas dengan cepat

openclaw cron create adalah alias untuk openclaw cron add. Untuk tugas baru, letakkan jadwal terlebih dahulu dan prompt setelahnya:

openclaw cron create "0 7 * * *" \  "Ringkas pembaruan semalam." \  --name "Ringkasan pagi" \  --agent ops

Gunakan --webhook <url> ketika tugas harus melakukan POST terhadap payload yang telah selesai, alih-alih mengirimkannya ke target obrolan:

openclaw cron create "0 18 * * 1-5" \  "Ringkas deployment hari ini sebagai JSON." \  --name "Ringkasan deployment" \  --webhook "https://example.invalid/openclaw/cron"

Gunakan --command untuk tugas deterministik bergaya shell yang berjalan di dalam Cron OpenClaw tanpa memulai eksekusi agen/model terisolasi:

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

--command <shell> menyimpan argv: ["sh", "-lc", <shell>]. Gunakan --command-argv '["node","scripts/report.mjs"]' untuk eksekusi argv yang persis. Tugas perintah menangkap stdout/stderr, mencatat riwayat Cron normal, dan merutekan keluaran melalui mode pengiriman announce, webhook, atau none yang sama dengan tugas terisolasi. Perintah yang hanya mencetak NO_REPLY akan disembunyikan.

Sesi

--session menerima main, isolated, current, atau session:<id>.

Pengiriman

openclaw cron list dan openclaw cron show <job-id> menampilkan pratinjau rute pengiriman yang telah diselesaikan. Untuk channel: "last", pratinjau menunjukkan apakah rute diselesaikan dari sesi utama atau sesi saat ini, atau akan gagal secara tertutup.

Target dengan awalan penyedia dapat memperjelas kanal pengumuman yang belum diselesaikan. Misalnya, to: "telegram:123" memilih Telegram ketika delivery.channel dihilangkan atau last. Hanya awalan yang diumumkan oleh Plugin yang dimuat yang merupakan pemilih penyedia. Jika delivery.channel ditentukan secara eksplisit, awalan harus cocok dengan kanal tersebut; channel: "whatsapp" dengan to: "telegram:123" akan ditolak. Awalan layanan seperti imessage: dan sms: tetap merupakan sintaks target yang dimiliki kanal.

Kepemilikan pengiriman

Pengiriman obrolan Cron terisolasi digunakan bersama oleh agen dan runner:

• Agen dapat mengirim secara langsung menggunakan alat message ketika rute obrolan tersedia.
• announce mengirimkan balasan akhir sebagai fallback hanya ketika agen tidak mengirim secara langsung ke target yang telah diselesaikan.
• webhook mengirimkan payload yang telah selesai ke URL.
• none menonaktifkan pengiriman fallback oleh runner.

Gunakan cron add|create --webhook <url> atau cron edit <job-id> --webhook <url> untuk mengatur pengiriman Webhook. Jangan gabungkan --webhook dengan flag pengiriman obrolan seperti --announce, --no-deliver, --channel, --to, --thread-id, atau --account.

cron edit <job-id> dapat membatalkan pengaturan masing-masing bidang perutean pengiriman dengan --clear-channel, --clear-to, --clear-thread-id, dan --clear-account (masing-masing ditolak ketika digabungkan dengan flag pengaturan yang sesuai). Tidak seperti --no-deliver, yang hanya menonaktifkan pengiriman fallback oleh runner, opsi ini menghapus bidang yang tersimpan sehingga tugas kembali menyelesaikan bagian rutenya tersebut dari nilai default.

--announce adalah pengiriman fallback oleh runner untuk balasan akhir. --no-deliver menonaktifkan fallback tersebut, tetapi tidak menghapus alat message milik agen ketika rute obrolan tersedia.

Pengingat yang dibuat dari obrolan aktif mempertahankan target pengiriman obrolan langsung untuk pengiriman pengumuman fallback. Kunci sesi internal dapat menggunakan huruf kecil; jangan menggunakannya sebagai sumber kebenaran untuk ID penyedia yang peka terhadap kapitalisasi, seperti ID ruang Matrix.

Pengiriman kegagalan

Notifikasi kegagalan diselesaikan dalam urutan berikut:

1. delivery.failureDestination pada tugas.
2. cron.failureDestination global.
3. Target pengumuman utama tugas (ketika tidak satu pun dari kedua opsi di atas diselesaikan menjadi tujuan konkret).

Eksekusi Cron terisolasi memperlakukan kegagalan agen pada tingkat eksekusi sebagai kesalahan tugas meskipun tidak ada payload balasan yang dihasilkan, sehingga kegagalan model/penyedia tetap meningkatkan penghitung kesalahan dan memicu notifikasi kegagalan.

Tugas perintah Cron tidak memulai giliran agen terisolasi. Kode keluar nol mencatat ok; kode keluar bukan nol, sinyal, batas waktu, atau batas waktu tanpa keluaran mencatat error dan dapat memicu jalur notifikasi kegagalan yang sama.

Jika eksekusi terisolasi mencapai batas waktu sebelum permintaan model pertama, openclaw cron show dan openclaw cron runs menyertakan kesalahan khusus fase seperti setup timed out before runner start atau pesan kemacetan yang menyebutkan fase mulai terakhir yang diketahui (misalnya context-engine). Untuk penyedia berbasis CLI, pengawas pra-model tetap aktif hingga giliran CLI eksternal dimulai, sehingga kemacetan pencarian sesi, hook, autentikasi, prompt, dan penyiapan CLI dilaporkan sebagai kegagalan Cron pra-model.

Penjadwalan

Tugas sekali jalan

--at <datetime> menjadwalkan eksekusi sekali jalan. Nilai tanggal dan waktu tanpa offset dianggap sebagai UTC kecuali jika Anda juga meneruskan --tz <iana>, yang menafsirkan waktu jam dinding dalam zona waktu yang diberikan.

Tugas berulang

Tugas berulang menggunakan backoff percobaan ulang eksponensial setelah kesalahan berturut-turut: 30s, 1m, 5m, 15m, 60m. Jadwal kembali normal setelah eksekusi berikutnya berhasil.

Eksekusi yang dilewati dilacak secara terpisah dari kesalahan eksekusi. Eksekusi tersebut tidak memengaruhi backoff percobaan ulang, tetapi openclaw cron edit <job-id> --failure-alert-include-skipped dapat mengaktifkan notifikasi eksekusi yang dilewati berulang kali dalam peringatan kegagalan.

Untuk tugas terisolasi yang menargetkan penyedia model lokal terkonfigurasi (URL dasar pada loopback, jaringan privat, atau .local), Cron menjalankan pemeriksaan awal penyedia ringan sebelum memulai giliran agen: penyedia api: "ollama" diperiksa di /api/tags; penyedia lokal lain yang kompatibel dengan OpenAI (api: "openai-completions", misalnya vLLM, SGLang, LM Studio) diperiksa di /models. Jika titik akhir tidak dapat dijangkau, eksekusi dicatat sebagai skipped dan dicoba kembali pada jadwal berikutnya; hasil keterjangkauan disimpan dalam cache per titik akhir selama 5 menit agar banyak tugas yang menggunakan server lokal yang sama tidak membebaninya dengan pemeriksaan berulang.

Tugas Cron, status runtime tertunda, dan riwayat eksekusi berada di basis data status SQLite bersama. File lama jobs.json, <name>-state.json, dan runs/*.jsonl diimpor satu kali dan diganti namanya dengan akhiran .migrated. Setelah impor, edit jadwal dengan openclaw cron add|edit|remove, bukan dengan mengedit file JSON.

Eksekusi manual

openclaw cron run <job-id> secara default menjalankan secara paksa dan segera kembali setelah eksekusi manual dimasukkan ke antrean. Respons yang berhasil menyertakan { ok: true, enqueued: true, runId }. Gunakan runId yang dikembalikan untuk memeriksa hasilnya nanti:

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

Tambahkan --wait ketika skrip harus diblokir hingga eksekusi dalam antrean tersebut mencatat status terminal:

openclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s

Dengan --wait, CLI tetap memanggil cron.run terlebih dahulu, lalu melakukan polling cron.runs untuk runId yang dikembalikan. Perintah keluar dengan 0 hanya ketika eksekusi selesai dengan status ok. Perintah keluar dengan nilai bukan nol ketika eksekusi selesai dengan error atau skipped, ketika respons Gateway tidak menyertakan runId, atau ketika --wait-timeout berakhir (default 10m, dengan polling setiap 2s secara default). --poll-interval harus lebih besar dari nol.

Model

cron add|edit --model <ref> memilih model yang diizinkan untuk tugas. cron add|edit --fallbacks <list> mengatur model fallback per tugas, misalnya --fallbacks openrouter/gpt-4.1-mini,openai/gpt-5; teruskan --fallbacks "" untuk eksekusi ketat tanpa fallback. cron edit <job-id> --clear-fallbacks menghapus penggantian fallback per tugas. cron edit <job-id> --clear-model menghapus penggantian model per tugas sehingga tugas mengikuti prioritas pemilihan model Cron normal (penggantian sesi Cron tersimpan jika ada, atau model agen/default); opsi ini tidak dapat digabungkan dengan --model. cron add|edit --thinking <level> mengatur penggantian proses berpikir per tugas; cron edit <job-id> --clear-thinking menghapusnya sehingga tugas mengikuti prioritas proses berpikir Cron normal, dan tidak dapat digabungkan dengan --thinking.

--model Cron adalah model utama tugas, bukan penggantian /model sesi obrolan. Artinya:

• Fallback model yang dikonfigurasi tetap berlaku ketika model tugas yang dipilih gagal.
• fallbacks payload per tugas menggantikan daftar fallback terkonfigurasi ketika tersedia.
• Daftar fallback per tugas yang kosong (--fallbacks "" atau fallbacks: [] dalam payload/API tugas) membuat eksekusi Cron menjadi ketat.
• Ketika tugas memiliki --model tetapi tidak ada daftar fallback yang dikonfigurasi, OpenClaw meneruskan penggantian fallback kosong secara eksplisit agar model utama agen tidak ditambahkan sebagai target percobaan ulang tersembunyi.
• Pemeriksaan awal penyedia lokal menelusuri fallback terkonfigurasi sebelum menandai eksekusi Cron sebagai skipped.

openclaw doctor melaporkan tugas yang telah memiliki payload.model, termasuk jumlah namespace penyedia dan ketidakcocokan terhadap agents.defaults.model. Gunakan pemeriksaan tersebut ketika perilaku autentikasi, penyedia, atau penagihan tampak berbeda antara obrolan langsung dan tugas terjadwal.

Prioritas model Cron terisolasi

Cron terisolasi menyelesaikan model aktif dalam urutan berikut:

1. Penggantian hook Gmail.
2. --model per tugas.
3. Penggantian model sesi Cron tersimpan (ketika pengguna memilihnya).
4. Pemilihan model agen atau model default.

Mode cepat

Mode cepat cron terisolasi mengikuti pemilihan model live yang telah di-resolve. Konfigurasi model params.fastMode berlaku secara default, tetapi override sesi tersimpan fastMode tetap mengalahkan konfigurasi. Ketika mode yang di-resolve adalah auto, batas waktu menggunakan nilai params.fastAutoOnSeconds dari model yang dipilih, dengan default 60 detik.

Percobaan ulang peralihan model live

Jika proses terisolasi menghasilkan LiveSessionModelSwitchError, cron menyimpan penyedia dan model yang telah dialihkan (serta override profil autentikasi yang dialihkan jika ada) untuk proses aktif sebelum mencoba ulang. Perulangan percobaan ulang terluar dibatasi hingga dua percobaan ulang peralihan setelah upaya awal, lalu dibatalkan agar tidak berulang selamanya.

Output proses dan penolakan

Penekanan konfirmasi usang

Giliran cron terisolasi menekan balasan usang yang hanya berisi konfirmasi. Jika hasil pertama hanya berupa pembaruan status sementara dan tidak ada proses subagen turunan yang bertanggung jawab atas jawaban akhir, cron meminta ulang satu kali untuk mendapatkan hasil sebenarnya sebelum pengiriman.

Penekanan token senyap

Jika proses cron terisolasi hanya mengembalikan token senyap (NO_REPLY atau no_reply), cron menekan pengiriman keluar langsung dan jalur ringkasan antrean fallback, sehingga tidak ada yang dikirim kembali ke percakapan.

Penolakan terstruktur

Proses cron terisolasi menggunakan metadata penolakan eksekusi terstruktur dari proses tersemat (kesalahan fatal alat eksekusi dengan kode SYSTEM_RUN_DENIED atau INVALID_REQUEST) sebagai sinyal penolakan yang otoritatif. Proses tersebut juga mengenali wrapper UNAVAILABLE host Node yang membungkus kesalahan terstruktur bertingkat dengan salah satu kode tersebut.

Cron tidak mengklasifikasikan prosa output akhir atau frasa penolakan yang tampak seperti permintaan persetujuan sebagai penolakan, kecuali proses tersemat juga memberikan metadata penolakan terstruktur, sehingga teks asisten biasa tidak dianggap sebagai perintah yang diblokir.

cron list dan riwayat proses menampilkan alasan penolakan alih-alih melaporkan perintah yang diblokir sebagai ok.

Retensi

Perilaku retensi:

• cron.sessionRetention (default 24h, atau false untuk menonaktifkan) memangkas sesi proses terisolasi yang telah selesai.
• Riwayat proses menyimpan 2000 baris terminal terbaru per tugas cron. Baris yang hilang tetap menggunakan jangka waktu pembersihan tugas hilang standar selama 24 jam.

Memigrasikan tugas lama

Pengeditan umum

Perbarui pengaturan pengiriman tanpa mengubah pesan:

openclaw cron edit <job-id> --announce --channel telegram --to "123456789"

Nonaktifkan pengiriman untuk tugas terisolasi:

openclaw cron edit <job-id> --no-deliver

Aktifkan konteks bootstrap ringan untuk tugas terisolasi:

openclaw cron edit <job-id> --light-context

Umumkan ke saluran tertentu:

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"

Umumkan ke topik forum Telegram:

openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42

Buat tugas terisolasi dengan konteks bootstrap ringan:

openclaw cron create "0 7 * * *" \  "Ringkas pembaruan semalam." \  --name "Ringkasan pagi ringan" \  --session isolated \  --light-context \  --no-deliver

--light-context hanya berlaku untuk tugas giliran agen terisolasi. Untuk proses cron, mode ringan mempertahankan konteks bootstrap tetap kosong alih-alih memasukkan kumpulan bootstrap ruang kerja lengkap.

Buat tugas perintah dengan argv, cwd, env, stdin, dan batas output yang tepat:

openclaw cron create "*/30 * * * *" \  --name "Ekspor posisi" \  --command-argv '["node","scripts/export-position.mjs"]' \  --command-cwd "/srv/app" \  --command-env "NODE_ENV=production" \  --command-input '{"mode":"summary"}' \  --timeout-seconds 120 \  --no-output-timeout-seconds 30 \  --output-max-bytes 65536 \  --webhook "https://example.invalid/openclaw/cron"

Perintah admin umum

Proses manual dan pemeriksaan:

openclaw cron listopenclaw cron list --agent opsopenclaw cron get <job-id>openclaw cron show <job-id>openclaw cron run <job-id>openclaw cron run <job-id> --dueopenclaw cron run <job-id> --wait --wait-timeout 10mopenclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2sopenclaw cron runs --id <job-id> --limit 50openclaw cron runs --id <job-id> --run-id <run-id>

openclaw cron list menampilkan tugas yang diaktifkan secara default. Teruskan --all untuk menyertakan tugas yang dinonaktifkan, atau --agent <id> untuk hanya menampilkan tugas yang ID agen ternormalisasi efektifnya cocok; tugas tanpa ID agen tersimpan dianggap menggunakan agen default yang dikonfigurasi.

openclaw cron get <job-id> mengembalikan JSON tugas tersimpan secara langsung. Gunakan cron show <job-id> jika Anda menginginkan tampilan yang mudah dibaca manusia dengan pratinjau rute pengiriman.

cron list --json dan cron show <job-id> --json menyertakan bidang tingkat atas status pada setiap tugas, yang dihitung dari enabled, state.runningAtMs, dan state.lastRunStatus. Nilai: disabled, running, ok, error, skipped, atau idle. Status JSON tetap kanonis dan tanpa dekorasi agar alat eksternal dapat membaca status tugas tanpa menghitungnya kembali; output manusia dapat menghias status error yang berulang dengan jumlah kegagalan.

Entri cron runs menyertakan diagnostik pengiriman dengan target cron yang dimaksud, target yang di-resolve, pengiriman alat pesan, penggunaan fallback, dan status terkirim.

Penargetan ulang agen dan sesi:

openclaw cron edit <job-id> --agent opsopenclaw cron edit <job-id> --clear-agentopenclaw cron edit <job-id> --session currentopenclaw cron edit <job-id> --session "session:daily-brief"

openclaw cron add memberikan peringatan ketika --agent tidak dicantumkan pada tugas giliran agen dan menggunakan agen default (main) sebagai fallback. Teruskan --agent <id> saat pembuatan untuk menetapkan agen tertentu.

Penyesuaian pengiriman:

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"openclaw cron edit <job-id> --webhook "https://example.invalid/openclaw/cron"openclaw cron edit <job-id> --best-effort-deliveropenclaw cron edit <job-id> --no-best-effort-deliveropenclaw cron edit <job-id> --no-deliver

Terkait

• Referensi CLI
• Tugas terjadwal