Tugas terjadwal

Cron adalah penjadwal bawaan Gateway. Cron mempertahankan job, membangunkan agent pada waktu yang tepat, dan dapat mengirimkan output kembali ke channel chat atau endpoint Webhook.

Mulai cepat

openclaw cron add \  --name "Reminder" \  --at "2026-02-01T16:00:00Z" \  --session main \  --system-event "Reminder: check the cron docs draft" \  --wake now \  --delete-after-run

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

openclaw cron runs --id <job-id>

Cara kerja cron

• Cron berjalan di dalam proses Gateway (bukan di dalam model).
• Definisi job dipertahankan di ~/.openclaw/cron/jobs.json sehingga jadwal tidak hilang saat restart.
• Status eksekusi runtime dipertahankan di sebelahnya dalam ~/.openclaw/cron/jobs-state.json. Jika Anda melacak definisi cron di git, lacak jobs.json dan masukkan jobs-state.json ke gitignore.
• Setelah pemisahan, versi OpenClaw lama dapat membaca jobs.json tetapi mungkin memperlakukan job sebagai baru karena field runtime kini berada di jobs-state.json.
• Saat jobs.json diedit ketika Gateway sedang berjalan atau berhenti, OpenClaw membandingkan field jadwal yang berubah dengan metadata slot runtime tertunda dan menghapus nilai nextRunAtMs yang usang. Penulisan ulang yang hanya mengubah format atau urutan key mempertahankan slot tertunda.
• Semua eksekusi cron membuat catatan tugas latar belakang.
• Saat Gateway startup, job agent-turn terisolasi yang terlambat dijadwalkan ulang keluar dari jendela koneksi channel alih-alih diputar ulang seketika, sehingga startup Discord/Telegram dan setup perintah native tetap responsif setelah restart.
• Job sekali jalan (--at) otomatis dihapus setelah berhasil secara default.
• Eksekusi cron terisolasi menutup tab/proses browser terlacak secara upaya terbaik untuk sesi cron:<jobId> miliknya saat eksekusi selesai, sehingga otomatisasi browser yang terlepas tidak meninggalkan proses yatim.
• Eksekusi cron terisolasi yang menerima izin sempit pembersihan mandiri cron tetap dapat membaca status penjadwal, daftar yang difilter mandiri dari job mereka saat ini, dan riwayat eksekusi job tersebut, sehingga pemeriksaan status/heartbeat dapat memeriksa jadwalnya sendiri tanpa memperoleh akses mutasi cron yang lebih luas.
• Eksekusi cron terisolasi juga melindungi dari balasan pengakuan yang usang. Jika hasil pertama hanya pembaruan status sementara (on it, pulling everything together, dan petunjuk serupa) dan tidak ada eksekusi subagent turunan yang masih bertanggung jawab atas jawaban akhir, OpenClaw meminta ulang sekali untuk hasil sebenarnya sebelum pengiriman.
• Eksekusi cron terisolasi lebih memilih metadata penolakan eksekusi terstruktur dari eksekusi tertanam, lalu fallback ke penanda ringkasan/output akhir yang dikenal seperti SYSTEM_RUN_DENIED dan INVALID_REQUEST, sehingga perintah yang diblokir tidak dilaporkan sebagai eksekusi hijau.
• Eksekusi cron terisolasi juga memperlakukan kegagalan agent tingkat eksekusi sebagai error job meskipun tidak ada payload balasan yang dihasilkan, sehingga kegagalan model/provider menambah penghitung error dan memicu notifikasi kegagalan alih-alih membersihkan job sebagai berhasil.
• Saat job agent-turn terisolasi mencapai timeoutSeconds, cron membatalkan eksekusi agent yang mendasarinya dan memberinya jendela pembersihan singkat. Jika eksekusi tidak selesai mengalir, pembersihan milik Gateway menghapus paksa kepemilikan sesi eksekusi tersebut sebelum cron mencatat timeout, sehingga pekerjaan chat yang mengantre tidak tertinggal di balik sesi pemrosesan yang usang.
• Jika agent-turn terisolasi macet sebelum runner dimulai atau sebelum panggilan model pertama, cron mencatat timeout spesifik fase seperti setup timed out before runner start atau stalled before first model call (last phase: context-engine). Watchdog ini mencakup provider tertanam dan provider berbasis CLI sebelum proses CLI eksternalnya benar-benar dimulai, dan dibatasi secara independen dari nilai timeoutSeconds yang panjang sehingga kegagalan cold-start/auth/context muncul cepat alih-alih menunggu seluruh anggaran job.

Jenis jadwal

Timestamp tanpa zona waktu diperlakukan sebagai UTC. Tambahkan --tz America/New_York untuk penjadwalan waktu dinding lokal.

Ekspresi berulang di awal jam otomatis disebar hingga 5 menit untuk mengurangi lonjakan beban. Gunakan --exact untuk memaksa waktu yang presisi atau --stagger 30s untuk jendela eksplisit.

Day-of-month dan day-of-week menggunakan logika OR

Ekspresi cron diurai oleh croner. Saat field day-of-month dan day-of-week sama-sama bukan wildcard, croner cocok ketika salah satu field cocok — bukan keduanya. Ini adalah perilaku cron Vixie standar.

# Intended: "9 AM on the 15th, only if it's a Monday"# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"0 9 15 * 1

Ini berjalan sekitar 5–6 kali per bulan alih-alih 0–1 kali per bulan. OpenClaw menggunakan perilaku OR default Croner di sini. Untuk mewajibkan kedua kondisi, gunakan modifier day-of-week + milik Croner (0 9 15 * +1) atau jadwalkan pada satu field dan lindungi field lainnya dalam prompt atau perintah job Anda.

Gaya eksekusi

Opsi payload untuk job terisolasi

--model menggunakan model yang diizinkan dan dipilih sebagai model utama job tersebut. Ini tidak sama dengan override /model sesi chat: chain fallback yang dikonfigurasi tetap berlaku saat model utama job gagal. Jika model yang diminta tidak diizinkan atau tidak dapat di-resolve, cron menggagalkan eksekusi dengan error validasi eksplisit alih-alih fallback diam-diam ke pemilihan model agent/default job.

Job cron juga dapat membawa fallbacks tingkat payload. Jika ada, daftar tersebut menggantikan chain fallback yang dikonfigurasi untuk job. Gunakan fallbacks: [] dalam payload/API job saat Anda menginginkan eksekusi cron ketat yang hanya mencoba model yang dipilih. Jika job memiliki --model tetapi tidak memiliki fallback payload maupun yang dikonfigurasi, OpenClaw meneruskan override fallback kosong eksplisit sehingga model utama agent tidak ditambahkan sebagai target percobaan ulang ekstra tersembunyi.

Prioritas pemilihan model untuk job terisolasi adalah:

1. Override model hook Gmail (saat eksekusi berasal dari Gmail dan override tersebut diizinkan)
2. model payload per job
3. Override model sesi cron tersimpan yang dipilih pengguna
4. Pemilihan model agent/default

Mode cepat juga mengikuti pemilihan live yang di-resolve. Jika konfigurasi model yang dipilih memiliki params.fastMode, cron terisolasi menggunakannya secara default. Override fastMode sesi tersimpan tetap menang atas konfigurasi di kedua arah.

Jika eksekusi terisolasi terkena handoff pengalihan model live, cron mencoba ulang dengan provider/model yang dialihkan dan mempertahankan pemilihan live tersebut untuk eksekusi aktif sebelum mencoba ulang. Saat pengalihan juga membawa profil auth baru, cron juga mempertahankan override profil auth tersebut untuk eksekusi aktif. Percobaan ulang dibatasi: setelah upaya awal plus 2 percobaan ulang pengalihan, cron membatalkan alih-alih berulang selamanya.

Sebelum eksekusi cron terisolasi memasuki runner agen, OpenClaw memeriksa endpoint penyedia lokal yang dapat dijangkau untuk penyedia api: "ollama" dan api: "openai-completions" yang dikonfigurasi dengan baseUrl berupa loopback, jaringan privat, atau .local. Jika endpoint tersebut mati, eksekusi dicatat sebagai skipped dengan error penyedia/model yang jelas, bukan memulai panggilan model. Hasil endpoint di-cache selama 5 menit, sehingga banyak job jatuh tempo yang menggunakan server lokal Ollama, vLLM, SGLang, atau LM Studio yang sama-sama mati berbagi satu probe kecil alih-alih membuat badai permintaan. Eksekusi preflight penyedia yang dilewati tidak menambah backoff error eksekusi; aktifkan failureAlert.includeSkipped saat Anda menginginkan notifikasi skip berulang.

Pengiriman dan keluaran

Gunakan --announce --channel telegram --to "-1001234567890" untuk pengiriman channel. Untuk topik forum Telegram, gunakan -1001234567890:topic:123; pemanggil RPC/konfigurasi langsung juga dapat meneruskan delivery.threadId sebagai string atau angka. Target Slack/Discord/Mattermost sebaiknya menggunakan prefiks eksplisit (channel:<id>, user:<id>). ID ruang Matrix peka huruf besar-kecil; gunakan ID ruang persisnya atau bentuk room:!room:server dari Matrix.

Saat pengiriman announce menggunakan channel: "last" atau menghilangkan channel, target berprefiks penyedia seperti telegram:123 dapat memilih channel sebelum cron kembali ke riwayat sesi atau satu channel terkonfigurasi. Hanya prefiks yang diiklankan oleh Plugin yang dimuat yang menjadi pemilih penyedia. Jika delivery.channel eksplisit, prefiks target harus menyebut penyedia yang sama; misalnya, channel: "whatsapp" dengan to: "telegram:123" ditolak alih-alih membiarkan WhatsApp menafsirkan ID Telegram sebagai nomor telepon. Prefiks jenis target dan layanan seperti channel:<id>, user:<id>, imessage:<handle>, dan sms:<number> tetap menjadi sintaks target yang dimiliki channel, bukan pemilih penyedia.

Untuk job terisolasi, pengiriman chat dibagikan. Jika rute chat tersedia, agen dapat menggunakan tool message bahkan saat job menggunakan --no-deliver. Jika agen mengirim ke target yang dikonfigurasi/saat ini, OpenClaw melewati announce fallback. Jika tidak, announce, webhook, dan none hanya mengontrol apa yang dilakukan runner dengan balasan akhir setelah giliran agen.

Saat agen membuat pengingat terisolasi dari chat aktif, OpenClaw menyimpan target pengiriman live yang dipertahankan untuk rute announce fallback. Kunci sesi internal dapat berupa huruf kecil; target pengiriman penyedia tidak direkonstruksi dari kunci tersebut saat konteks chat saat ini tersedia.

Pengiriman announce implisit menggunakan allowlist channel yang dikonfigurasi untuk memvalidasi dan mengalihkan target basi. Persetujuan pairing-store DM bukan penerima otomatisasi fallback; tetapkan delivery.to atau konfigurasikan entri channel allowFrom saat job terjadwal harus mengirim secara proaktif ke DM.

Notifikasi kegagalan mengikuti jalur tujuan terpisah:

• cron.failureDestination menetapkan default global untuk notifikasi kegagalan.
• job.delivery.failureDestination menimpanya per job.
• Jika keduanya tidak ditetapkan dan job sudah mengirim melalui announce, notifikasi kegagalan sekarang kembali ke target announce utama tersebut.
• delivery.failureDestination hanya didukung pada job sessionTarget="isolated" kecuali mode pengiriman utama adalah webhook.
• failureAlert.includeSkipped: true memasukkan job atau kebijakan peringatan cron global ke dalam peringatan eksekusi yang dilewati secara berulang. Eksekusi yang dilewati mempertahankan penghitung skip berurutan terpisah, sehingga tidak memengaruhi backoff error eksekusi.

Contoh CLI

openclaw cron add \  --name "Calendar check" \  --at "20m" \  --session main \  --system-event "Next heartbeat: check calendar." \  --wake now

openclaw cron add \  --name "Morning brief" \  --cron "0 7 * * *" \  --tz "America/Los_Angeles" \  --session isolated \  --message "Summarize overnight updates." \  --announce \  --channel slack \  --to "channel:C1234567890"

openclaw cron add \  --name "Deep analysis" \  --cron "0 6 * * 1" \  --tz "America/Los_Angeles" \  --session isolated \  --message "Weekly deep analysis of project progress." \  --model "opus" \  --thinking high \  --announce

Webhook

Gateway dapat mengekspos endpoint Webhook HTTP untuk pemicu eksternal. Aktifkan di konfigurasi:

{  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 query-string ditolak.

curl -X POST http://127.0.0.1:18789/hooks/wake \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \  -H 'Authorization: Bearer SECRET' \  -H 'Content-Type: application/json' \  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'

Integrasi Gmail PubSub

Hubungkan pemicu inbox Gmail ke OpenClaw melalui Google PubSub.

Penyiapan wizard (direkomendasikan)

openclaw webhooks gmail setup --account [email protected]

Ini menulis konfigurasi hooks.gmail, mengaktifkan preset Gmail, dan menggunakan Tailscale Funnel untuk endpoint push.

Auto-start Gateway

Saat hooks.enabled=true dan hooks.gmail.account ditetapkan, Gateway memulai gog gmail watch serve saat boot dan memperbarui watch secara otomatis. Tetapkan OPENCLAW_SKIP_GMAIL_WATCHER=1 untuk tidak ikut.

Penyiapan manual sekali jalan

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

gcloud pubsub topics create gog-gmail-watchgcloud pubsub topics add-iam-policy-binding gog-gmail-watch \  --member=serviceAccount:[email protected] \  --role=roles/pubsub.publisher

gog gmail watch start \  --account [email protected] \  --label INBOX \  --topic projects/<project-id>/topics/gog-gmail-watch

Override model Gmail

{  hooks: {    gmail: {      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",      thinking: "off",    },  },}

Mengelola job

# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent opsopenclaw cron edit <jobId> --clear-agent

Konfigurasi

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    maxConcurrentRuns: 1,    retry: {      maxAttempts: 3,      backoffMs: [60000, 120000, 300000],      retryOn: ["rate_limit", "overloaded", "network", "server_error"],    },    webhookToken: "replace-with-dedicated-webhook-token",    sessionRetention: "24h",    runLog: { maxBytes: "2mb", keepLines: 2000 },  },}

maxConcurrentRuns membatasi dispatch cron terjadwal sekaligus eksekusi giliran agen terisolasi. Giliran agen cron terisolasi menggunakan lane eksekusi khusus antrean cron-nested secara internal, sehingga menaikkan nilai ini memungkinkan eksekusi LLM cron independen berjalan paralel alih-alih hanya memulai wrapper cron luarnya. Lane nested non-cron bersama tidak diperlebar oleh pengaturan ini.

Sidecar status runtime diturunkan dari cron.store: store .json seperti ~/clawd/cron/jobs.json menggunakan ~/clawd/cron/jobs-state.json, sedangkan path store tanpa sufiks .json menambahkan -state.json.

Jika Anda mengedit jobs.json secara manual, jangan masukkan jobs-state.json ke kontrol sumber. OpenClaw menggunakan sidecar tersebut untuk slot tertunda, penanda aktif, metadata eksekusi terakhir, dan identitas jadwal yang memberi tahu scheduler kapan job yang diedit secara eksternal memerlukan nextRunAtMs baru.

Nonaktifkan cron: cron.enabled: false atau OPENCLAW_SKIP_CRON=1.

Pemecahan masalah

Tangga perintah

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

Terkait

• Automasi — semua mekanisme automasi sekilas
• Tugas Latar Belakang — ledger tugas untuk eksekusi cron
• Heartbeat — giliran sesi utama berkala
• Zona Waktu — konfigurasi zona waktu