OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Automation

Tugas terjadwal

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

  • Tambahkan pengingat sekali jalan

    bash
    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

  • Periksa pekerjaan Anda

    bash
    openclaw cron listopenclaw cron get <job-id>openclaw cron show <job-id>

  • Lihat riwayat eksekusi

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

    • 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.
    Penguatan eksekusi terisolasi
    • 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

    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

    Jenis Flag CLI Deskripsi
    at --at Stempel waktu sekali jalan (ISO 8601 atau relatif seperti 20m)
    every --every Interval tetap (10m, 1h, 1d)
    cron --cron Ekspresi Cron 5 bidang atau 6 bidang dengan --tz opsional
    on-exit --on-exit Dipicu sekali saat perintah yang dipantau berhenti (pemicu peristiwa; bertahan setelah pembongkaran giliran; --on-exit-cwd opsional)

    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.

    bash
    # Tujuan: "Pukul 09.00 pada tanggal 15, hanya jika hari Senin"# Aktual: "Pukul 09.00 setiap tanggal 15, DAN pukul 09.00 setiap hari Senin"0 9 15 * 1

    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:

    json5
    {  schedule: { kind: "every", everyMs: 30000 },  trigger: {    // Hanya dipicu ketika status yang diamati berbeda dari evaluasi terakhir.    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." },}

    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.

    Buat pemantau dari berkas skrip lokal (- membaca skrip dari stdin):

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

    Muatan

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

    Payload Flag Menjalankan
    Peristiwa sistem --system-event <text> Diantrekan ke sesi utama, tidak memanggil model dengan sendirinya
    Pesan agen --message <text> Giliran agen yang didukung model
    Perintah --command <shell> atau --command-argv <json> Shell/proses pada host Gateway, tanpa panggilan model
    Skrip --script <file|-> Skrip mode kode tanpa antarmuka yang menggunakan alat milik agen

    Opsi giliran agen

    --messagestringrequired

    Teks prompt (wajib untuk tugas sesi terisolasi/saat ini/kustom).

    --modelstring

    Penggantian model; harus merujuk ke model yang diizinkan atau eksekusi gagal dengan kesalahan validasi.

    --fallbacksstring

    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.

    --clear-fallbacksboolean

    Pada cron edit, menghapus penggantian cadangan per tugas agar tugas mengikuti prioritas cadangan yang dikonfigurasi. Tidak dapat digabungkan dengan --fallbacks.

    --clear-modelboolean

    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.

    --thinkingstring

    Penggantian tingkat penalaran (off|minimal|low|medium|high|xhigh|adaptive|max|ultra). Tingkat yang tersedia tetap bergantung pada model dan runtime agen yang dipilih.

    --clear-thinkingboolean

    Pada cron edit, menghapus penggantian penalaran per tugas. Tidak dapat digabungkan dengan --thinking.

    --light-contextboolean

    Lewati injeksi berkas bootstrap ruang kerja.

    --toolsstring

    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.

    bash
    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 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.

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

    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

    Gaya Nilai --session Berjalan di Paling cocok untuk
    Sesi utama main Jalur bangun cron khusus Pengingat, peristiwa sistem
    Terisolasi isolated cron:<jobId> khusus Laporan, tugas latar belakang
    Sesi saat ini current Diikat saat pembuatan Pekerjaan berulang yang mempertimbangkan konteks
    Sesi kustom session:custom-id Sesi bernama persisten Alur kerja yang dibangun berdasarkan riwayat
    Sesi utama vs terisolasi vs kustom

    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.

    Arti 'sesi baru' untuk tugas terisolasi

    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.

    Kontrak eksekusi tanpa pengawasan

    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.

    Pengiriman subagen dan Discord

    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

    Mode Yang terjadi
    announce Mengirim teks akhir sebagai fallback ke target jika agen tidak mengirim
    webhook Melakukan POST terhadap payload peristiwa selesai ke URL
    none Tidak ada pengiriman fallback oleh runner

    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:

    bash
    openclaw cron edit <jobId> \  --message "Ringkas pembaruan. Berikan respons dalam bahasa Tionghoa; jangan ubah URL, kode, dan nama produk."

    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

    Pengingat sekali jalan

    bash
    openclaw cron add \  --name "Pemeriksaan kalender" \  --at "20m" \  --session main \  --system-event "Heartbeat berikutnya: periksa kalender." \  --wake now

    Pekerjaan terisolasi berulang

    bash
    openclaw cron create "0 7 * * *" \  "Ringkas pembaruan semalam." \  --name "Ringkasan pagi" \  --tz "America/Los_Angeles" \  --session isolated \  --announce \  --channel slack \  --to "channel:C1234567890"

    Penggantian model dan pemikiran

    bash
    openclaw cron add \  --name "Analisis mendalam" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "Analisis mendalam mingguan mengenai kemajuan proyek." \  --model "opus" \  --thinking high \  --announce

    Output Webhook

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

    Output perintah

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

    Mengelola pekerjaan

    bash
    # Cantumkan semua pekerjaanopenclaw cron list # Dapatkan satu pekerjaan tersimpan sebagai JSONopenclaw cron get <jobId> # Tampilkan satu pekerjaan, termasuk rute pengiriman yang telah ditentukanopenclaw cron show <jobId> # Aktifkan/nonaktifkan tanpa menghapusopenclaw cron enable <jobId>openclaw cron disable <jobId> # Edit pekerjaanopenclaw cron edit <jobId> --message "Prompt yang diperbarui" --model "opus" # Paksa jalankan pekerjaan sekarangopenclaw cron run <jobId> # Paksa jalankan pekerjaan sekarang dan tunggu status terminalnyaopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Jalankan hanya jika waktunya tibaopenclaw cron run <jobId> --due # Lihat riwayat eksekusiopenclaw cron runs --id <jobId> --limit 50 # Lihat satu eksekusi tertentuopenclaw cron runs --id <jobId> --run-id <runId> # Hapus pekerjaanopenclaw cron remove <jobId> # Pemilihan agen (penyiapan multiagen)openclaw cron create "0 6 * * *" "Periksa antrean operasi" --name "Penyisiran operasi" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

    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.

    Webhook

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

    json5
    {  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",  },}

    Autentikasi

    Setiap permintaan harus menyertakan token hook melalui header:

    • Authorization: Bearer <token> (direkomendasikan)
    • x-openclaw-token: <token>

    Token string kueri ditolak.

    POST /hooks/wake

    Masukkan peristiwa sistem ke antrean untuk sesi utama:

    bash
    curl -X POST http://127.0.0.1:18789/hooks/wake \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"text":"Email baru diterima","mode":"now"}'
    textstringrequired

    Deskripsi peristiwa.

    modestringdefault: now

    now atau next-heartbeat.

    POST /hooks/agent

    Jalankan giliran agen terisolasi:

    bash
    curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"Ringkas kotak masuk","name":"Email","model":"openai/gpt-5.6-sol"}'

    Bidang: message (wajib), name, agentId, sessionKey (memerlukan hooks.allowRequestSessionKey=true), idempotencyKey, wakeMode, deliver, channel, to, model, thinking, timeoutSeconds.

    OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJIb29rIHlhbmcgZGlwZXRha2FuIChQT1NUIC9ob29rcy88bmFtZQ )"> 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.

    Integrasi Gmail PubSub

    Hubungkan pemicu kotak masuk Gmail ke OpenClaw melalui Google PubSub.

    Penyiapan dengan wizard (direkomendasikan)

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

    Perintah ini menulis konfigurasi hooks.gmail, mengaktifkan preset Gmail, dan secara default menggunakan Tailscale Funnel untuk endpoint push (--tailscale funnel|serve|off).

    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

  • Pilih proyek GCP

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

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

  • Buat topik dan berikan akses push Gmail

    bash
    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

  • Mulai watch

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

    • Penggantian model Gmail

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

    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

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

    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.

    Perilaku percobaan ulang

    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.

    Pemeliharaan

    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.

    Migrasi penyimpanan lama

    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

    bash
    openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor
    Cron tidak terpicu
    • 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.
    Cron terpicu tetapi tidak ada pengiriman
    • 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).
    Cron atau Heartbeat tampaknya mencegah pergantian bergaya /new
    • 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.
    Kendala zona waktu
    • 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

    Was this useful?
    On this page

    On this page