Skip to main content
Cron adalah penjadwal bawaan Gateway. Cron menyimpan pekerjaan secara persisten, membangunkan agen pada waktu yang tepat, dan dapat mengirimkan keluaran ke saluran obrolan, Webhook, atau tidak ke mana pun.

Mulai cepat

1

Tambahkan pengingat sekali jalan

2

Periksa pekerjaan Anda

3

Lihat riwayat eksekusi

Cara kerja Cron

  • Cron berjalan di dalam proses Gateway, bukan di dalam model. Gateway harus berjalan agar jadwal dapat dipicu.
  • Definisi pekerjaan, status waktu proses, dan riwayat eksekusi disimpan secara persisten dalam basis data status SQLite bersama milik OpenClaw, sehingga jadwal tidak hilang saat dimulai ulang.
  • Setiap eksekusi Cron membuat catatan tugas latar belakang.
  • Pekerjaan sekali jalan (--at) otomatis dihapus setelah berhasil secara default; berikan --keep-after-run untuk mempertahankannya.
  • Batas waktu nyata per eksekusi: --timeout-seconds jika ditetapkan. Jika tidak, pekerjaan giliran agen yang terisolasi/terlepas dibatasi oleh pengawas 60 menit milik Cron sebelum batas waktu giliran agen yang mendasarinya (agents.defaults.timeoutSeconds, default 48 jam) sempat berlaku; pekerjaan perintah memiliki default 10 menit, dan muatan skrip memiliki default 5 menit.
  • Saat Gateway dimulai, pekerjaan giliran agen terisolasi yang terlambat dijadwalkan ulang alih-alih langsung diputar ulang, sehingga pekerjaan bootstrap model/alat tidak memasuki jendela koneksi saluran.
  • Jika Anda menjalankan openclaw agent dari Cron sistem atau penjadwal eksternal lain, bungkus dengan eskalasi penghentian paksa meskipun CLI sudah menangani SIGTERM/SIGINT. Eksekusi yang didukung Gateway meminta Gateway membatalkan eksekusi yang telah diterima; eksekusi fallback lokal dan tertanam menerima sinyal pembatalan yang sama. Untuk GNU timeout, utamakan timeout -k 60 600 openclaw agent ... daripada timeout 600 ... biasa — nilai -k menjadi perlindungan terakhir jika proses tidak dapat selesai tepat waktu. Untuk unit systemd, gunakan sinyal penghentian SIGTERM dengan jendela tenggang (TimeoutStopSec) sebelum penghentian terakhir. Menggunakan kembali --run-id saat eksekusi Gateway asli masih aktif akan melaporkan duplikat sebagai sedang berjalan alih-alih memulai eksekusi kedua.
  • Eksekusi terisolasi berupaya sebaik mungkin untuk menutup tab/proses peramban yang dilacak bagi sesi cron:<jobId> setelah selesai, serta membuang setiap instans waktu proses MCP bawaan yang dibuat untuk pekerjaan melalui jalur pembongkaran bersama yang sama dengan yang digunakan oleh eksekusi sesi utama dan sesi khusus. Kegagalan pembersihan diabaikan agar hasil Cron tetap diutamakan.
  • Eksekusi terisolasi dengan izin terbatas untuk pembersihan mandiri Cron dapat membaca status penjadwal, daftar yang difilter mandiri dan hanya berisi pekerjaannya sendiri, serta riwayat eksekusi pekerjaan tersebut, dan hanya boleh menghapus pekerjaannya sendiri.
  • Eksekusi terisolasi melindungi dari balasan pengakuan yang kedaluwarsa: jika hasil pertama hanya berupa pembaruan status sementara (on it, pulling everything together, dan petunjuk serupa) dan tidak ada subagen turunan yang masih bertanggung jawab atas jawaban akhir, OpenClaw meminta ulang satu kali untuk memperoleh hasil sebenarnya sebelum pengiriman.
  • Metadata penolakan eksekusi terstruktur (termasuk pembungkus UNAVAILABLE host Node yang kesalahan bersarangnya dimulai dengan SYSTEM_RUN_DENIED atau INVALID_REQUEST) dikenali agar perintah yang diblokir tidak dilaporkan sebagai eksekusi berhasil, sementara prosa asisten biasa tidak keliru dianggap sebagai penolakan.
  • Kegagalan agen pada tingkat eksekusi dihitung sebagai kesalahan pekerjaan meskipun tidak ada muatan balasan, sehingga kegagalan model/penyedia menambah penghitung kesalahan dan memicu pemberitahuan kegagalan alih-alih menandai pekerjaan sebagai berhasil.
  • Saat pekerjaan mencapai timeoutSeconds, Cron membatalkan eksekusi dan memberinya jendela pembersihan singkat. Jika eksekusi tidak selesai, pembersihan milik Gateway secara paksa menghapus kepemilikan sesi eksekusi tersebut sebelum Cron mencatat batas waktu, sehingga pekerjaan obrolan dalam antrean tidak tertahan di belakang sesi pemrosesan yang kedaluwarsa.
  • Kemacetan penyiapan/mulai memiliki batas waktu khusus fase (misalnya cron: isolated agent setup timed out before runner start atau cron: isolated agent run stalled before execution start (last phase: context-engine)). Pengawas ini mencakup penyedia tertanam dan yang didukung CLI bahkan sebelum proses CLI eksternalnya dimulai, serta dibatasi secara terpisah dari nilai timeoutSeconds yang panjang agar kegagalan mulai dingin/autentikasi/konteks segera terlihat.
Rekonsiliasi tugas Cron pertama-tama dimiliki oleh waktu proses, kemudian didukung oleh riwayat persisten: tugas Cron aktif tetap berjalan selama waktu proses Cron masih melacak pekerjaan tersebut sebagai sedang berjalan, meskipun baris sesi anak lama masih ada. Setelah waktu proses berhenti memiliki pekerjaan tersebut dan jendela tenggang 5 menit berakhir, pemeriksaan pemeliharaan memeriksa log eksekusi persisten dan status pekerjaan untuk eksekusi cron:<jobId>:<startedAt> yang cocok. Hasil terminal di sana menyelesaikan buku besar tugas; jika tidak, pemeliharaan milik Gateway dapat menandai tugas sebagai lost. Audit CLI luring dapat memulihkan dari riwayat persisten, tetapi kumpulan pekerjaan aktif dalam proses miliknya yang kosong bukanlah bukti bahwa eksekusi milik Gateway telah berakhir.

Jenis jadwal

Stempel waktu tanpa zona waktu diperlakukan sebagai UTC. Tambahkan --tz America/New_York untuk menafsirkan waktu tanggal --at tanpa offset, atau mengevaluasi ekspresi Cron, dalam zona waktu IANA tersebut. Ekspresi Cron tanpa --tz menggunakan zona waktu host Gateway. --tz tidak valid bersama --every atau --on-exit. Ekspresi berulang pada awal jam (menit 0 dengan bidang jam wildcard) otomatis disebar hingga 5 menit untuk mengurangi lonjakan beban. Gunakan --exact untuk memaksakan waktu yang presisi, atau --stagger 30s untuk jendela eksplisit (khusus jadwal Cron).

Irama dinamis (pengaturan tempo)

Pekerjaan berulang dapat menetapkan pacing.min dan/atau pacing.max ke string durasi seperti 15m atau 4h; setidaknya satu batas diperlukan. Gunakan --pacing-min dan --pacing-max bersama cron add|edit (--clear-pacing menghapus kedua batas). Selama eksekusi terisolasi, pekerjaan dengan pengaturan tempo dapat memanggil alat cron dengan action: "next_check" dan in: "30m". Usulan tersebut hanya berlaku pada pekerjaan yang sedang berjalan itu dan diukur sejak eksekusi berhasil selesai. OpenClaw secara diam-diam membatasinya ke batas yang dikonfigurasi. Pengaturan tempo tanpa usulan tidak mengubah jadwal normal. Eksekusi yang gagal, mencapai batas waktu, dan dilewati akan membuang usulan, sehingga perilaku percobaan ulang dan penundaan kesalahan yang ada tetap diutamakan. Pemaksaan pekerjaan berulang secara manual berada di luar alur dan mempertahankan slot alami atau slot dengan tempo yang tertunda. Untuk pekerjaan yang dipicu kondisi, interval minimum bawaan tetap menjadi batas bawah meskipun usulan meminta pemeriksaan lebih awal.

Hari dalam bulan dan hari dalam minggu menggunakan logika OR

Ekspresi Cron diurai oleh croner. Saat bidang hari dalam bulan dan hari dalam minggu sama-sama bukan wildcard, croner mencocokkan ketika salah satu bidang cocok, bukan keduanya. Ini adalah perilaku standar Cron Vixie.
Ini dipicu sekitar 5-6 kali sebulan, bukan 0-1 kali sebulan. Untuk mewajibkan kedua kondisi, gunakan pengubah hari dalam minggu + milik croner (0 9 15 * +1), atau jadwalkan berdasarkan satu bidang dan periksa bidang lainnya dalam perintah atau prompt pekerjaan Anda.

Pemicu peristiwa (pemantau kondisi)

Pemicu peristiwa menambahkan skrip kondisi tanpa antarmuka ke jadwal every atau cron. Cron mengevaluasi skrip saat pekerjaan jatuh tempo dan menjalankan muatan normal hanya ketika skrip mengembalikan fire: true:
Skrip harus mengembalikan { fire, message?, state? }. Status JSON sebelumnya tersedia sebagai trigger.state yang dibekukan secara mendalam; kembalikan nilai state baru untuk menyimpannya secara persisten. Status dibatasi hingga 16 KB. Saat hasil pemicu menyertakan message, Cron menambahkannya ke teks peristiwa sistem atau pesan giliran agen sebelum eksekusi. once: true menonaktifkan pekerjaan setelah muatan terpicu pertamanya berhasil. fire: false menyimpan status dan penghitung evaluasi secara persisten, lalu menjadwalkan ulang tanpa membuat riwayat eksekusi. Jika eksekusi muatan yang terpicu gagal, state yang dikembalikan tidak disimpan secara persisten — evaluasi berikutnya melihat status sebelumnya dan dapat dipicu lagi, jadi tulis skrip sebagai pemeriksaan hanya-baca dan tempatkan tindakan dalam muatan. Jadwal pemicu memiliki interval minimum yang dapat dikonfigurasi (default 30 detik). Setiap evaluasi memiliki batas waktu nyata 30 detik dan hingga 5 panggilan alat. Rancang pemantau berdasarkan status yang dapat ditindaklanjuti, bukan hanya keberhasilan: pemantau yang berhenti memberikan sinyal saat pemeriksaannya gagal atau mencapai batas waktu tampak sehat padahal rusak. Bandingkan pengamatan dengan trigger.state dan kembalikan status baru untuk menghapus duplikasi; jangan mengandalkan memori model atau proses. Saat dipicu, buat message mandiri karena nilai tersebut menjadi konteks peristiwa lengkap untuk eksekusi yang terpicu.
Mengaktifkan cron.triggers.enabled mengizinkan skrip pemicu kondisi dan muatan script berjalan tanpa antarmuka dengan kebijakan alat lengkap agen pemilik, termasuk exec. Perlakukan ini sebagai eksekusi kode tanpa pengawasan dengan izin agen tersebut; biarkan dinonaktifkan kecuali setiap agen yang diizinkan membuat pekerjaan Cron dipercaya secara sesuai.
Buat pemantau dari berkas skrip lokal (- membaca skrip dari stdin):

Muatan

Setiap pekerjaan memiliki tepat satu jenis muatan, yang dipilih berdasarkan flag:

Opsi giliran agen

string
wajib
Teks prompt (wajib untuk tugas sesi terisolasi/saat ini/kustom).
string
Penggantian model; harus merujuk ke model yang diizinkan atau eksekusi gagal dengan kesalahan validasi.
string
Daftar model cadangan per tugas, misalnya --fallbacks openai/gpt-5.6-sol,openrouter/meta-llama/llama-3.3-70b-instruct:free. Teruskan --fallbacks "" untuk eksekusi ketat tanpa cadangan.
boolean
Pada cron edit, menghapus penggantian cadangan per tugas agar tugas mengikuti prioritas cadangan yang dikonfigurasi. Tidak dapat digabungkan dengan --fallbacks.
boolean
Pada cron edit, menghapus penggantian model per tugas agar tugas mengikuti prioritas model cron normal (penggantian sesi cron tersimpan, atau model agen/default). Tidak dapat digabungkan dengan --model.
string
Penggantian tingkat penalaran (off|minimal|low|medium|high|xhigh|adaptive|max|ultra). Tingkat yang tersedia tetap bergantung pada model dan runtime agen yang dipilih.
boolean
Pada cron edit, menghapus penggantian penalaran per tugas. Tidak dapat digabungkan dengan --thinking.
boolean
Lewati injeksi berkas bootstrap ruang kerja.
string
Batasi alat yang dapat digunakan tugas, misalnya --tools exec,read.
--model menetapkan model utama tugas; ini tidak menggantikan penggantian /model sesi, sehingga rantai cadangan yang dikonfigurasi tetap berlaku di atasnya. Model yang tidak dapat diidentifikasi atau tidak diizinkan membuat eksekusi gagal dengan kesalahan validasi eksplisit, alih-alih diam-diam beralih ke default. Jika tugas memiliki --model tetapi tidak memiliki daftar cadangan eksplisit atau terkonfigurasi, OpenClaw meneruskan penggantian cadangan kosong, alih-alih diam-diam menambahkan model utama agen sebagai target percobaan ulang tersembunyi. Prioritas pemilihan model untuk tugas terisolasi, dari tertinggi:
  1. Payload per tugas model (konfigurasi eksplisit; model yang tidak diizinkan membuat eksekusi gagal)
  2. Penggantian model hook Gmail (hanya ketika eksekusi berasal dari Gmail dan penggantian tersebut diizinkan)
  3. Penggantian model sesi cron tersimpan yang dipilih pengguna
  4. Pemilihan model agen/default
Mode cepat mengikuti pilihan aktif yang telah ditentukan. Jika konfigurasi model yang dipilih memiliki params.fastMode, cron terisolasi menggunakannya secara default; penggantian fastMode sesi tersimpan (kemudian fastModeDefault agen) tetap mengungguli konfigurasi model dalam kedua arah. Mode otomatis menggunakan batas params.fastAutoOnSeconds model, dengan default 60 detik. Jika eksekusi mengalami serah terima pergantian model aktif, cron mencoba kembali dengan penyedia/model yang telah diganti dan mempertahankan pilihan tersebut (serta profil autentikasi baru apa pun) untuk eksekusi aktif. Percobaan ulang dibatasi: setelah percobaan awal ditambah 2 percobaan ulang pergantian, cron membatalkan alih-alih terus berulang. Sebelum eksekusi terisolasi dimulai, OpenClaw memeriksa endpoint lokal yang dapat dijangkau untuk penyedia api: "ollama" dan api: "openai-completions" terkonfigurasi yang baseUrl-nya berupa loopback, jaringan privat, atau .local. Pemeriksaan awal ini menelusuri rantai cadangan yang dikonfigurasi untuk tugas dan hanya menandai eksekusi sebagai skipped setelah setiap kandidat tidak dapat dijangkau; --fallbacks "" membuat penelusuran tersebut ketat hanya pada model utama. Endpoint yang tidak aktif mencatat eksekusi sebagai skipped dengan kesalahan yang jelas, alih-alih memulai panggilan model. Hasilnya disimpan dalam cache selama 5 menit per endpoint (bukan per tugas atau model), sehingga banyak tugas jatuh tempo yang menggunakan server lokal Ollama/vLLM/SGLang/LM Studio yang tidak aktif hanya memerlukan satu pemeriksaan, bukan lonjakan permintaan. Eksekusi pemeriksaan awal yang dilewati tidak menambah backoff kesalahan eksekusi; tetapkan failureAlert.includeSkipped untuk mengaktifkan peringatan pengabaian berulang.

Payload perintah

Payload perintah menjalankan skrip deterministik di dalam penjadwal Gateway tanpa memulai giliran yang didukung model. Payload tersebut dijalankan pada host Gateway, menangkap stdout/stderr, mencatat eksekusi dalam riwayat cron, dan menggunakan kembali mode pengiriman announce, webhook, dan none yang sama seperti tugas giliran agen.
Cron perintah adalah permukaan otomatisasi Gateway untuk operator-admin, bukan panggilan tools.exec agen. Membuat, memperbarui, menghapus, atau menjalankan tugas cron secara manual memerlukan operator.admin; eksekusi perintah terjadwal kemudian dijalankan di dalam proses Gateway sebagai otomatisasi yang dibuat oleh admin tersebut. Kebijakan eksekusi agen (tools.exec.mode, prompt persetujuan, daftar izin alat per agen) mengatur alat eksekusi yang terlihat oleh model, bukan payload cron perintah.
--command <shell> menyimpan argv: ["sh", "-lc", <shell>]. Gunakan --command-argv '["node","scripts/report.mjs"]' untuk eksekusi argv persis tanpa penguraian shell. --command-env KEY=VALUE opsional (dapat diulang), --command-input, --timeout-seconds (default 10 menit), --no-output-timeout-seconds, dan --output-max-bytes mengendalikan lingkungan proses, stdin, dan batas keluaran. Teks yang dikirim berasal dari keluaran proses: stdout yang tidak kosong diprioritaskan; jika stdout kosong dan stderr tidak kosong, stderr dikirim; jika keduanya ada, cron mengirim blok kecil stdout: / stderr:. Kode keluar 0 mencatat eksekusi sebagai ok; kode keluar bukan nol, sinyal, batas waktu, atau batas waktu tanpa keluaran mencatat error dan dapat memicu peringatan kegagalan. Perintah yang hanya mencetak NO_REPLY menggunakan penekanan token senyap cron normal dan tidak mengirim apa pun kembali ke obrolan.

Payload skrip

Payload skrip berjalan tanpa antarmuka dalam pengeksekusi mode kode yang sama seperti skrip pemicu, tanpa memulai giliran agen percakapan. Aktifkan cron.triggers.enabled sebelum membuat atau menjalankannya; gerbang otomatisasi berbahaya ini mencakup skrip pemicu dan payload skrip. Tugas skrip hanya mendukung target sesi main dan isolated.
Gunakan --script <file|-> untuk membaca JavaScript dari berkas atau stdin. Batas waktu default adalah 300 detik dan dibatasi hingga 900; anggaran alat default adalah 50 panggilan dan dibatasi hingga 200. Anggaran payload ini terpisah dari anggaran evaluasi gerbang pemicu yang lebih kecil. Skrip dapat mengembalikan objek dengan bidang opsional berikut:
  • notify: Teks yang dikirim melalui mode pengiriman announce, webhook, atau none milik tugas. Jika dihilangkan, tidak ada yang dikirim. Untuk tugas main, teks menjadi peristiwa sistem.
  • wake: "now" meminta Heartbeat segera setelah mengantrekan notify (atau peristiwa penyelesaian ringkas); "next-heartbeat" mengantrekan peristiwa untuk Heartbeat berikutnya.
  • state: Status JSON, dibatasi hingga 16 KB dan hanya dipertahankan setelah eksekusi berhasil. Eksekusi berikutnya menerima salinan beku sebagai trigger.state, sesuai dengan skrip pemicu. Karena namespace tersebut memiliki satu pemilik persisten, payload skrip tidak dapat digabungkan dengan pemicu kondisi pada tugas yang sama.
  • nextCheck: Durasi seperti "15m". Ini hanya valid untuk tugas dengan pengaturan tempo yang diaktifkan dan menggunakan batas tempo yang sama seperti usulan giliran agen.
Pelemparan kesalahan, batas waktu, anggaran alat yang habis, hasil tidak valid, dan nextCheck tanpa pengaturan tempo merupakan kesalahan eksekusi cron normal: semuanya masuk ke riwayat eksekusi, backoff, dan penanganan peringatan kegagalan tanpa mempertahankan status yang dikembalikan.

Gaya eksekusi

Tugas sesi utama mengantrekan peristiwa sistem ke jalur eksekusi milik cron dan secara opsional membangunkan Heartbeat (--wake now atau --wake next-heartbeat). Tugas tersebut dapat menggunakan konteks pengiriman terakhir sesi utama target untuk balasan, tetapi tidak menambahkan giliran cron rutin ke jalur obrolan manusia dan tidak memperpanjang kebaruan reset harian/diam untuk sesi target. Tugas terisolasi menjalankan giliran agen khusus dengan sesi baru. Sesi kustom (session:xxx) mempertahankan konteks di seluruh eksekusi, sehingga memungkinkan alur kerja seperti rapat harian yang dibangun berdasarkan ringkasan sebelumnya.Peristiwa cron sesi utama adalah pengingat peristiwa sistem yang mandiri. Peristiwa tersebut tidak secara otomatis menyertakan instruksi “Read HEARTBEAT.md” dari prompt Heartbeat default; nyatakan hal tersebut secara eksplisit dalam teks peristiwa cron jika pengingat harus membaca HEARTBEAT.md.
ID transkrip/sesi baru per eksekusi. OpenClaw membawa preferensi yang aman (pengaturan penalaran/cepat/verbose, label, penggantian model/autentikasi eksplisit yang dipilih pengguna), tetapi tidak mewarisi konteks percakapan sekitar dari baris cron lama: perutean saluran/grup, kebijakan pengiriman atau antrean, elevasi, asal, atau pengikatan runtime ACP. Gunakan current atau session:<id> ketika tugas berulang sengaja harus dibangun berdasarkan konteks percakapan yang sama.
Giliran agen cron dan hook terisolasi secara eksplisit berjalan tanpa pengawasan: tidak ada orang yang hadir untuk mengklarifikasi atau menyetujui. Balasan akhir harus berupa hasil yang dapat diserahkan, bukan rencana, pengakuan, atau permintaan masukan. Agen mengembalikan HEARTBEAT_OK ketika tidak ada yang perlu dilakukan dan menyatakan kegagalan dengan jelas; cron mengelola kebijakan percobaan ulang dan peringatan kegagalan.Untuk tugas terjadwal tepercaya, instruksi tugas itu sendiri berlaku ketika secara sengaja meminta pertanyaan atau rencana, dan agen dapat menghapus tugas yang tidak lagi diperlukan. Giliran hook eksternal hanya menerima kontrak umum tanpa pengawasan; giliran tersebut tidak menerima penggantian atau panduan penghapusan mandiri tersebut saat melintasi batas konten eksternal.
Ketika eksekusi cron terisolasi mengorkestrasi subagen, pengiriman memprioritaskan keluaran turunan akhir daripada teks sementara induk yang kedaluwarsa. Jika turunan masih berjalan, OpenClaw menekan pembaruan parsial induk tersebut alih-alih mengumumkannya.Untuk target pengumuman Discord khusus teks, OpenClaw mengirim teks akhir kanonis dari asisten satu kali, alih-alih memutar ulang teks streaming/perantara sekaligus jawaban akhir. Media dan payload Discord terstruktur tetap dikirim secara terpisah agar lampiran dan komponen tidak terlewat.

Pengiriman dan output

Gunakan --announce --channel telegram --to "-1001234567890" untuk pengiriman kanal. Untuk topik forum Telegram, gunakan -1001234567890:topic:123; OpenClaw juga menerima bentuk singkat -1001234567890:123 milik Telegram. Pemanggil RPC/config langsung dapat meneruskan delivery.threadId sebagai string atau angka. Target Slack/Discord/Mattermost menggunakan prefiks eksplisit (channel:<id>, user:<id>). ID ruang Matrix peka huruf besar-kecil; gunakan ID ruang yang tepat atau bentuk room:!room:server dari Matrix. Ketika pengiriman pengumuman menggunakan channel: "last" atau menghilangkan channel, target berprefiks penyedia seperti telegram:123 dapat memilih kanal sebelum cron kembali menggunakan riwayat sesi atau satu kanal yang dikonfigurasi. Hanya prefiks yang diumumkan oleh plugin yang dimuat yang merupakan pemilih penyedia. Jika delivery.channel ditentukan secara eksplisit, prefiks target harus menyebutkan penyedia yang sama; channel: "whatsapp" dengan to: "telegram:123" ditolak, alih-alih membiarkan WhatsApp menafsirkan ID Telegram sebagai nomor telepon. Prefiks jenis target dan layanan (channel:<id>, user:<id>, imessage:<handle>, sms:<number>) tetap menjadi sintaks target milik kanal, bukan pemilih penyedia. Untuk pekerjaan terisolasi, pengiriman obrolan digunakan bersama: jika rute obrolan tersedia, agen dapat menggunakan alat message bahkan dengan --no-deliver. Jika agen mengirim ke target yang dikonfigurasi/saat ini, OpenClaw melewati pengumuman fallback. Jika tidak, announce, webhook, dan none hanya mengendalikan tindakan runner terhadap balasan akhir setelah giliran agen. Saat agen membuat pengingat terisolasi dari obrolan aktif, OpenClaw menyimpan target pengiriman langsung yang dipertahankan untuk rute pengumuman fallback. Kunci sesi internal mungkin menggunakan huruf kecil; target pengiriman penyedia tidak direkonstruksi dari kunci tersebut jika konteks obrolan saat ini tersedia. Pengiriman pengumuman implisit menggunakan daftar kanal yang diizinkan dalam konfigurasi untuk memvalidasi dan merutekan ulang target yang sudah usang. Persetujuan penyimpanan pemasangan DM bukan penerima otomatisasi fallback; tetapkan delivery.to atau konfigurasikan entri kanal allowFrom jika pekerjaan terjadwal harus mengirim secara proaktif ke DM.

Notifikasi kegagalan

Notifikasi kegagalan mengikuti jalur tujuan terpisah:
  • cron.failureDestination menetapkan nilai default global untuk notifikasi kegagalan.
  • job.delivery.failureDestination menggantikannya untuk setiap pekerjaan.
  • Jika keduanya tidak ditetapkan dan pekerjaan sudah melakukan pengiriman melalui announce, notifikasi kegagalan kembali menggunakan target pengumuman utama tersebut.
  • delivery.failureDestination hanya didukung pada pekerjaan sessionTarget="isolated", kecuali mode pengiriman utama adalah webhook.
  • failureAlert.includeSkipped: true mengikutsertakan kebijakan peringatan cron pekerjaan atau global ke dalam peringatan berulang untuk eksekusi yang dilewati. Eksekusi yang dilewati mempertahankan penghitung lompatan berturut-turut yang terpisah, sehingga tidak memengaruhi backoff kesalahan eksekusi.
  • openclaw cron edit menyediakan penyesuaian peringatan per pekerjaan: --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, dan --failure-alert-account-id.

Bahasa output

Pekerjaan Cron tidak menyimpulkan bahasa balasan dari kanal, lokal, atau pesan sebelumnya. Cantumkan aturan bahasa dalam pesan atau templat terjadwal:
Untuk berkas templat, pertahankan instruksi bahasa dalam prompt yang dirender dan pastikan placeholder seperti {{language}} telah diisi sebelum pekerjaan dijalankan. Jika output mencampur bahasa, buat aturannya eksplisit, misalnya: “Gunakan bahasa Tionghoa untuk teks naratif dan pertahankan istilah teknis dalam bahasa Inggris.”

Contoh CLI

Mengelola pekerjaan

Mengarsipkan sesi (Control UI, atau sessions.patch { archived: true } dari pemanggil operator-admin) menonaktifkan setiap pekerjaan cron aktif yang terikat pada sesi tersebut: sesi terisolasi cron:<jobId> miliknya, target session:<key>, atau jalur pengiriman/bangun sessionKey. Memulihkan sesi tidak mengaktifkan kembali pekerjaan tersebut; gunakan openclaw cron enable <jobId>. Sesi dengan pekerjaan terikat yang aktif menampilkan lencana jam di bilah sisi Control UI. openclaw cron run <jobId> kembali setelah memasukkan eksekusi manual ke antrean. Gunakan --wait untuk hook penonaktifan, skrip pemeliharaan, atau otomatisasi lain yang harus memblokir hingga eksekusi dalam antrean selesai; perintah ini melakukan polling terhadap runId yang dikembalikan (batas waktu default 10m, interval polling 2s) dan keluar dengan 0 untuk status ok, serta nilai bukan nol untuk error, skipped, atau batas waktu tunggu. Alat agen cron mengembalikan ringkasan pekerjaan ringkas (id, name, enabled, nextRunAtMs, scheduleKind, lastRunStatus) dari cron(action: "list"); gunakan cron(action: "get", jobId: "...") untuk satu definisi pekerjaan lengkap. Pemanggil Gateway langsung dapat meneruskan compact: true ke cron.list; menghilangkannya mempertahankan respons lengkap beserta pratinjau pengiriman. openclaw cron create adalah alias untuk openclaw cron add. Pekerjaan baru dapat menggunakan jadwal posisional ("0 9 * * 1", "every 1h", "20m", atau stempel waktu ISO) yang diikuti prompt agen posisional. Gunakan --webhook <url> pada cron add|create atau cron edit untuk melakukan POST terhadap payload eksekusi yang selesai ke endpoint HTTP; pengiriman webhook tidak dapat digabungkan dengan flag pengiriman obrolan (--announce, --channel, --to, --thread-id, --account). Pada cron edit, --clear-channel, --clear-to, --clear-thread-id, dan --clear-account, hapus penetapan setiap bidang perutean tersebut satu per satu (masing-masing ditolak bersama flag penetapannya yang sesuai) — berbeda dari --no-deliver, yang hanya menonaktifkan pengiriman fallback runner.
Catatan penggantian model:
  • openclaw cron add|edit --model ... mengubah model yang dipilih untuk pekerjaan.
  • Jika model diizinkan, penyedia/model yang tepat tersebut diteruskan ke eksekusi agen terisolasi.
  • Jika tidak diizinkan atau tidak dapat ditentukan, cron menggagalkan eksekusi dengan kesalahan validasi eksplisit.
  • Patch payload API cron.update dapat menetapkan model: null untuk menghapus penggantian model pekerjaan yang tersimpan.
  • openclaw cron edit <job-id> --clear-model menghapus penggantian tersebut dari CLI (efeknya sama dengan patch model: null) dan tidak dapat digabungkan dengan --model.
  • Rantai fallback yang dikonfigurasi tetap berlaku karena --model cron adalah model utama pekerjaan, bukan penggantian /model sesi.
  • openclaw cron add|edit --fallbacks ... menetapkan fallbacks payload, menggantikan fallback yang dikonfigurasi untuk pekerjaan tersebut; --fallbacks "" menonaktifkan fallback dan menjadikan eksekusi bersifat ketat. openclaw cron edit <job-id> --clear-fallbacks menghapus penggantian per pekerjaan.
  • --model biasa tanpa daftar fallback eksplisit atau yang dikonfigurasi tidak beralih ke model utama agen sebagai target percobaan ulang tambahan secara diam-diam.

Webhook

Gateway dapat menyediakan endpoint webhook HTTP untuk pemicu eksternal. Aktifkan dalam config:

Autentikasi

Setiap permintaan harus menyertakan token hook melalui header:
  • Authorization: Bearer <token> (direkomendasikan)
  • x-openclaw-token: <token>
Token string kueri ditolak.
Masukkan peristiwa sistem ke antrean untuk sesi utama:
string
wajib
Deskripsi peristiwa.
string
default:"now"
now atau next-heartbeat.
Jalankan giliran agen terisolasi:
Bidang: message (wajib), name, agentId, sessionKey (memerlukan hooks.allowRequestSessionKey=true), idempotencyKey, wakeMode, deliver, channel, to, model, thinking, timeoutSeconds.
Nama hook khusus di-resolve melalui hooks.mappings dalam konfigurasi. Pemetaan dapat mengubah payload arbitrer menjadi tindakan wake atau agent dengan templat atau transformasi kode.
Tempatkan endpoint hook di belakang loopback, tailnet, atau reverse proxy tepercaya.
  • Gunakan token hook khusus; jangan gunakan kembali token autentikasi gateway.
  • Pertahankan hooks.path pada subjalur khusus; / ditolak.
  • Tetapkan hooks.allowedAgentIds untuk membatasi agen efektif yang dapat ditargetkan hook, termasuk agen default ketika agentId tidak dicantumkan.
  • Pertahankan hooks.allowRequestSessionKey=false kecuali Anda memerlukan sesi yang dipilih pemanggil.
  • Jika Anda mengaktifkan hooks.allowRequestSessionKey, tetapkan juga hooks.allowedSessionKeyPrefixes untuk membatasi bentuk kunci sesi yang diizinkan.
  • Payload hook secara default dibungkus dengan batas keamanan.

Integrasi Gmail PubSub

Hubungkan pemicu kotak masuk Gmail ke OpenClaw melalui Google PubSub.
Prasyarat: CLI gcloud, gog (gogcli), hook OpenClaw diaktifkan, Tailscale untuk endpoint HTTPS publik.

Penyiapan dengan wizard (direkomendasikan)

Perintah ini menulis konfigurasi hooks.gmail, mengaktifkan preset Gmail, dan secara default menggunakan Tailscale Funnel untuk endpoint push (--tailscale funnel|serve|off).
Sesi per pesan pada preset Gmail memisahkan konteks percakapan; sesi tersebut tidak membatasi alat atau ruang kerja agen target. Tanpa pemetaan khusus yang menetapkan agentId, hook Gmail dijalankan sebagai agen default.Untuk kotak masuk yang tidak tepercaya, arahkan hook ke agen pembaca khusus, berikan agen tersebut akses hanya-baca atau tanpa akses ke ruang kerja, dan larang penulisan sistem berkas, shell, browser, serta alat lain yang tidak diperlukan. Jika agen tersebut perlu memberi tahu agen utama, izinkan hanya serah terima antaragen yang diperlukan. Lihat Injeksi prompt, Sandbox dan alat multiagen, serta tools.agentToAgent.

Mulai otomatis Gateway

Ketika hooks.enabled=true dan hooks.gmail.account ditetapkan, Gateway memulai gog gmail watch serve saat boot dan memperpanjang watch secara otomatis. Tetapkan OPENCLAW_SKIP_GMAIL_WATCHER=1 untuk menonaktifkannya.

Penyiapan manual satu kali

1

Pilih proyek GCP

Pilih proyek GCP yang memiliki klien OAuth yang digunakan oleh gog:
2

Buat topik dan berikan akses push Gmail

3

Mulai watch

Penggantian model Gmail

Gunakan model generasi terbaru dengan tingkat terbaik yang tersedia dari penyedia Anda untuk kotak masuk yang tidak tepercaya. Nilai di atas adalah contoh; model tersebut harus tersedia dalam katalog dan daftar izin yang telah Anda konfigurasi.

Konfigurasi

webhookToken dikirim sebagai Authorization: Bearer <token> pada POST webhook cron. cron.store adalah kunci penyimpanan logis dan jalur migrasi doctor, bukan berkas JSON aktif untuk diedit secara manual. Data pekerjaan berada di SQLite; gunakan CLI atau API Gateway untuk melakukan perubahan. Nonaktifkan cron: cron.enabled: false atau OPENCLAW_SKIP_CRON=1.
Percobaan ulang sekali jalan: kesalahan sementara (batas laju, beban berlebih, jaringan, batas waktu, kesalahan server) menggunakan jadwal percobaan ulang bawaan. Kesalahan permanen langsung menonaktifkan pekerjaan.Percobaan ulang berulang: kesalahan eksekusi berturut-turut menerapkan jeda mundur dengan jadwal yang diperpanjang (30s, 60s, 5m, 15m, 60m). Jeda mundur direset setelah eksekusi berikutnya berhasil.
cron.sessionRetention (default 24h, false menonaktifkannya) memangkas entri sesi eksekusi terisolasi. Riwayat eksekusi menyimpan 2000 baris terminal terbaru per pekerjaan; baris yang hilang tetap mempertahankan jangka waktu pembersihan 24 jam.
Saat peningkatan versi, jalankan openclaw doctor --fix untuk mengimpor berkas lama ~/.openclaw/cron/jobs.json, jobs-state.json, dan runs/*.jsonl ke SQLite serta mengganti namanya dengan akhiran .migrated. Baris pekerjaan yang formatnya salah dilewati oleh runtime dan disalin ke jobs-quarantine.json untuk diperbaiki atau ditinjau nanti.

Pemecahan masalah

Urutan perintah

  • Periksa cron.enabled dan variabel lingkungan OPENCLAW_SKIP_CRON.
  • Pastikan Gateway berjalan terus-menerus.
  • Untuk jadwal cron, verifikasi zona waktu (--tz) terhadap zona waktu host.
  • reason: not-due dalam keluaran eksekusi berarti eksekusi manual diperiksa dengan openclaw cron run <jobId> --due dan pekerjaan belum waktunya dijalankan.
  • Mode pengiriman none berarti pengiriman fallback runner tidak diharapkan. Agen masih dapat mengirim secara langsung dengan alat message ketika rute percakapan tersedia.
  • Target pengiriman tidak ada/tidak valid (channel/to) berarti pengiriman keluar dilewati.
  • Untuk Matrix, pekerjaan yang disalin atau lama dengan ID ruang delivery.to dalam huruf kecil dapat gagal karena ID ruang Matrix peka huruf besar-kecil. Edit pekerjaan dengan nilai !room:server atau room:!room:server yang persis dari Matrix.
  • Kesalahan autentikasi kanal (unauthorized, Forbidden) berarti pengiriman diblokir oleh kredensial.
  • Jika eksekusi terisolasi hanya mengembalikan token senyap (NO_REPLY / no_reply), OpenClaw menekan pengiriman keluar langsung dan jalur ringkasan antrean fallback, sehingga tidak ada yang dikirim kembali ke percakapan.
  • Jika agen seharusnya mengirim pesan kepada pengguna secara langsung, periksa apakah pekerjaan memiliki rute yang dapat digunakan (channel: "last" dengan percakapan sebelumnya, atau kanal/target eksplisit).
  • Kesegaran pengaturan ulang harian dan saat menganggur tidak didasarkan pada updatedAt; lihat Pengelolaan sesi.
  • Aktivasi cron, eksekusi Heartbeat, notifikasi exec, dan pembukuan gateway dapat memperbarui baris sesi untuk perutean/status, tetapi tidak memperpanjang sessionStartedAt atau lastInteractionAt.
  • Untuk baris lama yang dibuat sebelum kolom tersebut tersedia, OpenClaw dapat memulihkan sessionStartedAt dari header sesi transkrip JSONL jika berkasnya masih tersedia. Baris menganggur lama tanpa lastInteractionAt menggunakan waktu mulai yang dipulihkan tersebut sebagai acuan waktu menganggur.
  • Cron tanpa --tz menggunakan zona waktu host gateway.
  • Jadwal at tanpa zona waktu diperlakukan sebagai UTC.
  • Heartbeat activeHours menggunakan resolusi zona waktu yang dikonfigurasi.

Terkait