openclaw cron

Kelola tugas Cron untuk penjadwal Gateway.

Membuat tugas dengan cepat

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

openclaw cron create "0 7 * * *" \  "Summarize overnight updates." \  --name "Morning brief" \  --agent ops

Gunakan --webhook <url> jika tugas harus mengirim payload yang telah selesai melalui POST, alih-alih mengirimkannya ke target percakapan:

openclaw cron create "0 18 * * 1-5" \  "Summarize today's deploys as JSON." \  --name "Deploy digest" \  --webhook "https://example.invalid/openclaw/cron"

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

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --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 seperti 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 saat ini, atau akan gagal secara tertutup.

Target dengan prefiks penyedia dapat memperjelas kanal pengumuman yang belum diselesaikan. Contohnya, to: "telegram:123" memilih Telegram saat delivery.channel tidak dicantumkan atau bernilai last. Hanya prefiks yang diumumkan oleh Plugin yang dimuat yang menjadi pemilih penyedia. Jika delivery.channel ditentukan secara eksplisit, prefiks harus cocok dengan kanal tersebut; channel: "whatsapp" dengan to: "telegram:123" akan ditolak. Prefiks layanan seperti imessage: dan sms: tetap menjadi sintaks target yang dimiliki kanal.

Kepemilikan pengiriman

Pengiriman percakapan Cron terisolasi dibagi antara agen dan penjalan:

• Agen dapat mengirim secara langsung menggunakan alat message saat rute percakapan tersedia.
• announce mengirimkan balasan akhir sebagai cadangan hanya jika agen tidak mengirim langsung ke target yang telah diselesaikan.
• webhook mengirim payload yang telah selesai ke sebuah URL.
• none menonaktifkan pengiriman cadangan oleh penjalan.

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

cron edit <job-id> dapat menghapus masing-masing bidang perutean pengiriman dengan --clear-channel, --clear-to, --clear-thread-id, dan --clear-account (masing-masing ditolak jika digabungkan dengan flag pengaturan pasangannya). Berbeda dari --no-deliver, yang hanya menonaktifkan pengiriman cadangan oleh penjalan, opsi-opsi ini menghapus bidang yang tersimpan sehingga tugas kembali menyelesaikan bagian rutenya tersebut dari nilai default.

--announce adalah pengiriman cadangan oleh penjalan untuk balasan akhir. --no-deliver menonaktifkan cadangan tersebut, tetapi tidak menghapus alat message milik agen saat rute percakapan tersedia.

Pengingat yang dibuat dari percakapan aktif mempertahankan target pengiriman percakapan langsung untuk pengiriman pengumuman cadangan. Kunci sesi internal mungkin menggunakan huruf kecil; jangan menggunakannya sebagai sumber kebenaran untuk ID penyedia yang peka huruf besar-kecil, 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 (jika kedua opsi di atas tidak menghasilkan tujuan konkret).

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

Tugas Cron perintah 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 proses 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 macet yang menyebutkan fase awal 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 proses sekali jalan. Waktu tanggal tanpa offset diperlakukan sebagai UTC, kecuali jika Anda juga meneruskan --tz <iana>, yang menafsirkan waktu jam dinding dalam zona waktu yang diberikan.

Tugas berulang

Tugas berulang menggunakan penundaan percobaan ulang eksponensial setelah kesalahan berturut-turut: 30 dtk, 1 mnt, 5 mnt, 15 mnt, 60 mnt. Jadwal kembali normal setelah proses berikutnya berhasil.

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

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

Tugas Cron, status runtime tertunda, dan riwayat proses berada dalam basis data status SQLite bersama. Berkas lama jobs.json, <name>-state.json, dan runs/*.jsonl diimpor satu kali lalu diganti namanya dengan sufiks .migrated. Setelah impor, ubah jadwal dengan openclaw cron add|edit|remove, bukan dengan mengedit berkas JSON.

Proses manual

openclaw cron run <job-id> secara default menjalankan secara paksa dan segera kembali setelah proses 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 jika skrip harus terblokir hingga proses persis yang diantrekan 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 terhadap cron.runs untuk runId yang dikembalikan. Perintah keluar dengan kode 0 hanya jika proses selesai dengan status ok. Perintah keluar dengan kode bukan nol jika proses selesai dengan error atau skipped, jika respons Gateway tidak menyertakan runId, atau jika --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> menetapkan model cadangan per tugas, misalnya --fallbacks openrouter/gpt-4.1-mini,openai/gpt-5; teruskan --fallbacks "" untuk proses ketat tanpa cadangan. cron edit <job-id> --clear-fallbacks menghapus penggantian cadangan per tugas. cron edit <job-id> --clear-model menghapus penggantian model per tugas sehingga tugas mengikuti urutan 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> menetapkan penggantian tingkat pemikiran per tugas; cron edit <job-id> --clear-thinking menghapusnya sehingga tugas mengikuti urutan prioritas pemikiran Cron normal, dan opsi ini tidak dapat digabungkan dengan --thinking.

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

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

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

Urutan 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 (jika pengguna memilihnya).
4. Pemilihan model agen atau model default.

Mode cepat

Mode cepat Cron terisolasi mengikuti pemilihan model langsung yang telah diselesaikan. Konfigurasi model params.fastMode berlaku secara default, tetapi penggantian fastMode sesi tersimpan tetap mengungguli konfigurasi. Jika mode yang diselesaikan adalah auto, ambang batas menggunakan nilai params.fastAutoOnSeconds dari model yang dipilih, dengan nilai default 60 detik.

Percobaan ulang peralihan model langsung

Jika proses terisolasi melempar LiveSessionModelSwitchError, Cron menyimpan penyedia dan model yang dialihkan (serta penggantian profil autentikasi yang dialihkan jika ada) untuk proses aktif sebelum mencoba kembali. Perulangan percobaan ulang luar dibatasi hingga dua percobaan ulang peralihan setelah percobaan awal, lalu dibatalkan agar tidak berulang selamanya.

Keluaran proses dan penolakan

Penyembunyian konfirmasi usang

Giliran Cron terisolasi menyembunyikan 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 kembali satu kali untuk mendapatkan hasil sebenarnya sebelum pengiriman.

Penekanan token senyap

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

Penolakan terstruktur

Eksekusi cron terisolasi menggunakan metadata penolakan eksekusi terstruktur dari eksekusi tertanam (kesalahan fatal alat eksekusi dengan kode SYSTEM_RUN_DENIED atau INVALID_REQUEST) sebagai sinyal penolakan yang berwenang. Eksekusi tersebut juga mengenali pembungkus UNAVAILABLE dari host Node di sekitar kesalahan terstruktur bertingkat yang memuat salah satu kode tersebut.

Cron tidak menggolongkan prosa keluaran akhir atau frasa penolakan yang tampak meminta persetujuan sebagai penolakan, kecuali eksekusi tertanam juga menyediakan metadata penolakan terstruktur, sehingga teks asisten biasa tidak diperlakukan sebagai perintah yang diblokir.

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

Retensi

Retensi dan pemangkasan dikendalikan dalam konfigurasi:

• cron.sessionRetention (nilai bawaan 24h, atau false untuk menonaktifkan) memangkas sesi eksekusi terisolasi yang telah selesai.
• cron.runLog.keepLines (nilai bawaan 2000) memangkas baris riwayat eksekusi SQLite yang dipertahankan per tugas. cron.runLog.maxBytes (nilai bawaan 2000000) tetap diterima untuk kompatibilitas dengan log eksekusi lama berbasis berkas; pemangkasan SQLite didasarkan pada jumlah baris.

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 * * *" \  "Summarize overnight updates." \  --name "Lightweight morning brief" \  --session isolated \  --light-context \  --no-deliver

--light-context hanya berlaku untuk tugas giliran agen terisolasi. Untuk eksekusi cron, mode ringan membiarkan konteks bootstrap kosong, alih-alih menyisipkan kumpulan bootstrap ruang kerja lengkap.

Buat tugas perintah dengan argv, cwd, env, stdin, dan batas keluaran yang presisi:

openclaw cron create "*/30 * * * *" \  --name "Position export" \  --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 administrasi umum

Eksekusi dan pemeriksaan manual:

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 secara bawaan menampilkan semua tugas yang cocok. Berikan --agent <id> untuk hanya menampilkan tugas dengan ID agen ternormalisasi efektif yang cocok; tugas tanpa ID agen tersimpan dianggap menggunakan agen bawaan 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 status tingkat teratas pada setiap tugas, yang dihitung dari enabled, state.runningAtMs, dan state.lastRunStatus. Nilainya: disabled, running, ok, error, skipped, atau idle. Status JSON tetap kanonis dan tanpa hiasan agar perkakas eksternal dapat membaca keadaan tugas tanpa menghitungnya kembali; keluaran untuk manusia dapat menghias status error yang berulang dengan jumlah kegagalan.

Entri cron runs menyertakan diagnostik pengiriman dengan target cron yang dimaksud, target yang diselesaikan, pengiriman alat pesan, penggunaan cadangan, dan keadaan 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 memperingatkan jika --agent dihilangkan pada tugas giliran agen dan menggunakan agen bawaan (main) sebagai cadangan. Berikan --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