Automation
Tugas latar belakang
Tugas latar belakang melacak pekerjaan yang berjalan di luar sesi percakapan utama Anda: proses ACP, pembuatan subagen, eksekusi tugas cron, dan operasi yang dimulai melalui CLI.
Tugas tidak menggantikan sesi, tugas cron, atau heartbeat—tugas merupakan catatan aktivitas yang mencatat pekerjaan terpisah apa yang terjadi, kapan terjadinya, dan apakah pekerjaan tersebut berhasil.
Ringkasan singkat
- Tugas adalah catatan, bukan penjadwal—cron dan heartbeat menentukan kapan pekerjaan berjalan, sedangkan tugas melacak apa yang terjadi.
- ACP, subagen, semua tugas cron, dan operasi CLI membuat tugas. Giliran Heartbeat tidak.
- Setiap tugas bergerak melalui
queued → running → terminal(berhasil, gagal, kehabisan waktu, dibatalkan, atau hilang). - Tugas cron tetap aktif selama runtime cron masih memiliki tugas tersebut; jika status runtime dalam memori telah hilang, pemeliharaan tugas terlebih dahulu memeriksa riwayat proses cron permanen sebelum menandai tugas sebagai hilang.
- Penyelesaian didorong oleh notifikasi: pekerjaan terpisah dapat memberi tahu secara langsung atau membangunkan sesi pemohon/heartbeat saat selesai, sehingga perulangan polling status biasanya bukan pendekatan yang tepat.
- Proses cron terisolasi dan penyelesaian subagen berupaya sebaik mungkin untuk membersihkan tab/proses peramban yang dilacak untuk sesi turunannya sebelum pembukuan pembersihan akhir.
- Pengiriman cron terisolasi menekan balasan induk sementara yang sudah tidak relevan saat pekerjaan subagen turunan masih diselesaikan, dan mengutamakan keluaran akhir turunan jika keluaran tersebut tiba sebelum pengiriman.
- Notifikasi penyelesaian dikirim langsung ke kanal atau dimasukkan ke antrean untuk heartbeat berikutnya.
openclaw tasks listmenampilkan semua tugas;openclaw tasks auditmenampilkan masalah.- Catatan terminal disimpan selama 7 hari (catatan
lostselama 24 jam), lalu dibersihkan secara otomatis.
Mulai cepat
Cantumkan dan filter
# Cantumkan semua tugas (yang terbaru lebih dahulu)openclaw tasks list # Filter berdasarkan runtime atau statusopenclaw tasks list --runtime acpopenclaw tasks list --status runningPeriksa
# Tampilkan detail tugas tertentu (berdasarkan ID tugas, ID proses, atau kunci sesi)openclaw tasks show <lookup>Batalkan dan beri tahu
# Batalkan tugas yang sedang berjalan (menghentikan sesi turunan)openclaw tasks cancel <lookup> # Ubah kebijakan notifikasi untuk tugasopenclaw tasks notify <lookup> state_changesAudit dan pemeliharaan
# Jalankan audit kesehatanopenclaw tasks audit # Pratinjau atau terapkan pemeliharaanopenclaw tasks maintenanceopenclaw tasks maintenance --applyAlur tugas
# Periksa status TaskFlowopenclaw tasks flow listopenclaw tasks flow show <lookup>openclaw tasks flow cancel <lookup>Hal yang membuat tugas
| Sumber | Jenis runtime | Saat catatan tugas dibuat | Kebijakan notifikasi bawaan |
|---|---|---|---|
| Proses latar belakang ACP | acp |
Saat membuat sesi ACP turunan | done_only |
| Orkestrasi subagen | subagent |
Saat membuat subagen melalui sessions_spawn |
done_only |
| Tugas cron (semua jenis) | cron |
Setiap eksekusi cron (sesi utama dan terisolasi) | silent |
| Operasi CLI | cli |
Perintah openclaw agent yang berjalan melalui Gateway |
silent |
| Tugas media agen | cli |
Proses image_generate/music_generate/video_generate berbasis sesi |
silent |
Bawaan notifikasi untuk cron dan media
Tugas cron (sesi utama dan terisolasi) menggunakan kebijakan notifikasi silent—tugas tersebut membuat catatan untuk pelacakan tetapi tidak menghasilkan notifikasi tugas sendiri; cron mengelola jalur pengirimannya.
Proses image_generate, music_generate, dan video_generate berbasis sesi juga menggunakan kebijakan notifikasi silent. Proses tersebut tetap membuat catatan tugas, tetapi penyelesaiannya dikembalikan ke sesi agen asal sebagai pemicu internal agar agen dapat menulis pesan tindak lanjut dan melampirkan sendiri media yang telah selesai. Agen pemohon mengikuti kontrak balasan terlihat seperti biasa: balasan akhir otomatis jika dikonfigurasi, atau message(action="send") ditambah NO_REPLY jika sesi mengharuskan balasan melalui alat pesan. Jika sesi pemohon sudah tidak aktif atau pemicu aktifnya gagal, dan agen penyelesaian melewatkan sebagian atau seluruh media yang dihasilkan, OpenClaw mengirim pengiriman cadangan langsung yang idempoten dan hanya berisi media yang hilang ke target kanal asal.
Pengaman pembuatan media serentak
Selama tugas pembuatan media berbasis sesi masih aktif, image_generate, music_generate, dan video_generate mencegah percobaan ulang yang tidak disengaja: pengulangan panggilan untuk perintah/permintaan yang sama akan mengembalikan status tugas aktif yang cocok, alih-alih memulai duplikat, sedangkan perintah yang berbeda dapat memulai tugasnya sendiri. Gunakan action: "status" jika Anda menginginkan pencarian kemajuan/status secara eksplisit dari sisi agen.
Hal yang tidak membuat tugas
- Giliran Heartbeat—sesi utama; lihat Heartbeat
- Giliran percakapan interaktif biasa
- Respons langsung
/command
Siklus hidup tugas
stateDiagram-v2
[*] --> queued
queued --> running : agen dimulai
running --> succeeded : selesai dengan baik
running --> failed : kesalahan
running --> timed_out : batas waktu terlampaui
queued --> cancelled : operator membatalkan
running --> cancelled : operator membatalkan
queued --> lost : status pendukung hilang > 5 menit
running --> lost : status pendukung hilang > 5 menit| Status | Artinya |
|---|---|
queued |
Dibuat, menunggu agen dimulai |
running |
Giliran agen sedang aktif dieksekusi |
succeeded |
Berhasil diselesaikan |
failed |
Selesai dengan kesalahan |
timed_out |
Melampaui batas waktu yang dikonfigurasi |
cancelled |
Dihentikan oleh operator melalui openclaw tasks cancel, atau proses dibatalkan |
lost |
Runtime kehilangan status pendukung otoritatif setelah masa tenggang 5 menit |
Transisi terjadi secara otomatis—peristiwa siklus hidup proses agen (mulai, selesai, kesalahan) memperbarui status tugas; Anda tidak mengelolanya secara manual.
Penyelesaian proses agen bersifat otoritatif untuk catatan tugas aktif. Proses terpisah yang berhasil diselesaikan ditetapkan sebagai succeeded, kesalahan proses biasa ditetapkan sebagai failed, kehabisan waktu ditetapkan sebagai timed_out, dan hasil pembatalan/penghentian ditetapkan sebagai cancelled. Setelah tugas mencapai status terminal, sinyal siklus hidup berikutnya tidak menurunkan statusnya—tugas yang dibatalkan operator atau sudah berstatus failed/timed_out/lost tetap demikian meskipun sinyal keberhasilan tiba setelahnya.
lost bergantung pada runtime:
- Tugas ACP: hanya giliran ACP dalam proses yang aktif di Gateway yang membuktikan bahwa proses masih berjalan; metadata sesi permanen saja tidak membuktikannya. Audit CLI luring bersifat konservatif dan tidak pernah mengambil alih kembali tugas ACP.
- Tugas subagen: sesi turunan pendukung menghilang dari penyimpanan agen target (atau memiliki penanda pemulihan setelah dimulai ulang).
- Tugas cron: runtime cron tidak lagi melacak tugas sebagai aktif dan riwayat proses cron permanen tidak menunjukkan hasil terminal untuk proses tersebut. Audit CLI luring tidak menganggap status runtime cron dalam prosesnya sendiri yang kosong sebagai sumber otoritatif.
- Tugas CLI: tugas dengan ID proses/ID sumber menggunakan konteks proses aktif, sehingga baris sesi turunan atau sesi percakapan yang tertinggal tidak membuatnya tetap aktif setelah proses milik Gateway menghilang. Tugas CLI lama tanpa identitas proses masih menggunakan sesi turunan sebagai cadangan. Proses
openclaw agentberbasis Gateway juga diselesaikan berdasarkan hasil prosesnya, sehingga proses yang telah selesai tidak tetap aktif sampai pembersih menandainya sebagailost.
Pengiriman dan notifikasi
Saat tugas mencapai status terminal, OpenClaw memberi tahu Anda. Terdapat dua jalur pengiriman:
Pengiriman langsung—jika tugas memiliki target kanal (requesterOrigin), pesan penyelesaian dikirim langsung ke kanal tersebut (Discord, Slack, Telegram, dan sebagainya). Penyelesaian tugas grup dan kanal dialihkan melalui sesi pemohon agar agen induk dapat menulis balasan yang terlihat. Untuk penyelesaian subagen, OpenClaw juga mempertahankan perutean utas/topik terikat jika tersedia dan dapat mengisi to / akun yang tidak ada dari rute tersimpan milik sesi pemohon (lastChannel / lastTo / lastAccountId) sebelum menghentikan upaya pengiriman langsung.
Pengiriman dalam antrean sesi—jika pengiriman langsung gagal atau asal tidak ditetapkan, pembaruan dimasukkan ke antrean sebagai peristiwa sistem dalam sesi pemohon dan muncul pada heartbeat berikutnya.
Artinya, alur kerja yang lazim berbasis notifikasi: mulai pekerjaan terpisah satu kali, lalu biarkan runtime membangunkan atau memberi tahu Anda saat pekerjaan selesai. Lakukan polling status tugas hanya ketika Anda perlu melakukan debug, intervensi, atau audit eksplisit.
Kebijakan notifikasi
Kendalikan seberapa banyak informasi yang Anda terima mengenai setiap tugas:
| Kebijakan | Hal yang dikirim |
|---|---|
done_only (bawaan) |
Hanya status terminal (berhasil, gagal, dan sebagainya) |
state_changes |
Setiap transisi status dan pembaruan kemajuan |
silent |
Tidak ada sama sekali (bawaan untuk tugas cron, CLI, dan media) |
Ubah kebijakan saat tugas sedang berjalan:
openclaw tasks notify <lookup> state_changesReferensi CLI
tasks list
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]Kolom keluaran: Tugas, Jenis, Status, Pengiriman, Proses, Sesi Turunan, Ringkasan. openclaw tasks tanpa argumen berperilaku seperti openclaw tasks list.
tasks show
openclaw tasks show <lookup> [--json]Token pencarian menerima ID tugas, ID proses, atau kunci sesi. Menampilkan catatan lengkap termasuk waktu, status pengiriman, kesalahan, dan ringkasan terminal.
tasks cancel
openclaw tasks cancel <lookup>Untuk tugas ACP dan subagen, perintah ini menghentikan sesi turunan; pembatalan ACP dan cron dirutekan melalui Gateway yang sedang berjalan (tasks.cancel). Untuk tugas yang dilacak CLI, pembatalan dicatat dalam registri tugas (tidak ada pegangan runtime turunan yang terpisah). Status beralih menjadi cancelled dan notifikasi pengiriman dikirim jika berlaku.
tasks notify
openclaw tasks notify <lookup> <done_only|state_changes|silent>tasks audit
openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--json]Menampilkan masalah operasional untuk tugas dan TaskFlow dalam satu laporan. Temuan juga muncul di openclaw status ketika masalah terdeteksi.
Temuan tugas:
| Temuan | Tingkat keparahan | Pemicu |
|---|---|---|
stale_queued |
peringatan | Mengantre selama lebih dari 10 menit |
stale_running |
kesalahan | Berjalan selama lebih dari 30 menit |
lost |
peringatan/kesalahan | Kepemilikan tugas yang didukung runtime menghilang; tugas hilang yang dipertahankan menghasilkan peringatan hingga cleanupAfter, lalu menjadi kesalahan |
delivery_failed |
peringatan | Pengiriman gagal dan kebijakan notifikasi bukan silent |
missing_cleanup |
peringatan | Tugas terminal tanpa stempel waktu pembersihan |
inconsistent_timestamps |
peringatan | Pelanggaran lini waktu (misalnya berakhir sebelum dimulai) |
Temuan TaskFlow:
| Temuan | Tingkat keparahan | Pemicu |
|---|---|---|
restore_failed |
kesalahan | Pemulihan registri alur dari SQLite gagal |
stale_running |
kesalahan | Alur yang berjalan belum mengalami kemajuan selama lebih dari 30 menit |
stale_waiting |
peringatan | Alur yang menunggu belum mengalami kemajuan selama lebih dari 30 menit |
stale_blocked |
peringatan | Alur yang diblokir belum mengalami kemajuan selama lebih dari 30 menit |
cancel_stuck |
peringatan | Pembatalan diminta lebih dari 5 menit lalu, tidak ada tugas anak aktif, tetapi masih belum terminal |
missing_linked_tasks |
peringatan/kesalahan | Alur terkelola yang kedaluwarsa tanpa tugas tertaut atau status tunggu |
blocked_task_missing |
peringatan | Alur yang diblokir menunjuk ke ID tugas yang sudah tidak ada |
pemeliharaan tugas
openclaw tasks maintenance [--json]openclaw tasks maintenance --apply [--json]Gunakan ini untuk melihat pratinjau atau menerapkan rekonsiliasi, pemberian stempel pembersihan, dan pemangkasan bagi tugas, status TaskFlow, serta baris registri sesi eksekusi cron yang kedaluwarsa.
Rekonsiliasi memperhitungkan runtime:
- Tugas ACP memerlukan giliran aktif dalam proses di Gateway; tugas subagen memeriksa sesi anak yang mendukungnya.
- Tugas subagen yang sesi anaknya memiliki penanda pemulihan setelah mulai ulang ditandai sebagai hilang, alih-alih diperlakukan sebagai sesi pendukung yang dapat dipulihkan.
- Tugas Cron memeriksa apakah runtime cron masih memiliki pekerjaan tersebut, lalu memulihkan status terminal dari log eksekusi cron/status pekerjaan yang dipersistenkan sebelum beralih ke
lost. Hanya proses Gateway yang berwenang atas kumpulan pekerjaan cron aktif dalam memori; audit CLI luring menggunakan riwayat tahan lama, tetapi tidak menandai tugas cron sebagai hilang hanya karena kumpulan lokal tersebut kosong. - Tugas CLI dengan identitas eksekusi memeriksa konteks eksekusi aktif yang memilikinya, bukan hanya baris sesi anak atau sesi percakapan.
Pembersihan penyelesaian juga memperhitungkan runtime:
- Penyelesaian subagen berupaya sebaik mungkin menutup tab/proses peramban yang dilacak untuk sesi anak sebelum pembersihan pengumuman dilanjutkan.
- Penyelesaian cron terisolasi berupaya sebaik mungkin menutup tab/proses peramban yang dilacak untuk sesi cron sebelum eksekusi sepenuhnya dihentikan.
- Pengiriman cron terisolasi menunggu tindak lanjut subagen turunan selesai bila diperlukan dan menekan teks konfirmasi induk yang kedaluwarsa alih-alih mengumumkannya.
- Pengiriman penyelesaian subagen hanya menggunakan teks asisten terbaru yang terlihat dari anak tersebut. Keluaran tool/toolResult tidak dijadikan teks hasil anak. Eksekusi terminal yang gagal mengumumkan status kegagalan tanpa memutar ulang teks balasan yang direkam.
- Kegagalan pembersihan tidak menyamarkan hasil tugas yang sebenarnya.
Saat menerapkan pemeliharaan, OpenClaw juga menghapus baris registri sesi cron:<jobId>:run:<runId> yang berusia lebih dari 7 hari, sambil mempertahankan baris untuk pekerjaan cron yang sedang berjalan dan membiarkan baris sesi non-cron tetap utuh.
daftar | tampilkan | batalkan alur tugas
openclaw tasks flow list [--status <status>] [--json]openclaw tasks flow show <lookup> [--json]openclaw tasks flow cancel <lookup>Token pencarian alur menerima ID alur atau kunci pemilik. Gunakan perintah ini ketika Alur Tugas yang mengorkestrasi merupakan hal yang ingin Anda periksa, bukan satu catatan tugas latar belakang tertentu.
Papan tugas percakapan (/tasks)
Gunakan /tasks dalam sesi percakapan apa pun untuk melihat tugas latar belakang yang tertaut ke sesi tersebut. Papan menampilkan hingga lima tugas aktif dan yang baru saja selesai beserta runtime, status, waktu, serta detail kemajuan atau kesalahan.
Jika sesi saat ini tidak memiliki tugas tertaut yang terlihat, /tasks akan beralih ke jumlah tugas lokal agen sehingga Anda tetap memperoleh gambaran umum tanpa membocorkan detail sesi lain.
Untuk buku besar operator lengkap, gunakan CLI: openclaw tasks list.
UI Kontrol
UI Kontrol web memiliki halaman Tugas di bilah samping yang menampilkan tugas latar belakang aktif dan terkini secara langsung. Gunakan halaman ini untuk memeriksa kemajuan, membuka sesi tertaut, menyegarkan buku besar, atau membatalkan tugas yang mengantre dan sedang berjalan.
Panel percakapan juga memiliki panel Tugas latar belakang yang dapat diciutkan dan dibatasi pada agen panel tersebut: tugas dan subagen yang sedang berjalan dengan kontrol berhenti, bagian yang telah selesai, serta tautan Lihat transkrip menuju sesi anak setiap tugas. Buka melalui tombol aktivitas pada header panel (atau tombol aktivitas mengambang dalam percakapan panel tunggal).
Integrasi status (tekanan tugas)
openclaw status menyertakan baris ringkasan tugas:
Tugas 2 aktif · 1 mengantre · 1 berjalan · 1 masalah · audit bersih · 6 terlacakRingkasan menghitung pekerjaan aktif (queued + running), kegagalan (failed + timed_out + lost), temuan audit, dan total catatan terlacak; muatan JSON juga menguraikan jumlah berdasarkan runtime (acp, subagent, cron, cli).
Baik /status maupun alat session_status menggunakan cuplikan tugas yang memperhitungkan pembersihan: tugas aktif diprioritaskan, baris kedaluwarsa disembunyikan, dan tugas terminal hanya muncul dalam jangka waktu terkini yang singkat (5 menit), dengan kegagalan ditonjolkan saat tidak ada pekerjaan aktif tersisa. Hal ini menjaga kartu status tetap berfokus pada hal yang penting saat ini.
Penyimpanan dan pemeliharaan
Lokasi penyimpanan tugas
Catatan tugas dan status pengiriman dipersistenkan dalam basis data status SQLite bersama milik OpenClaw:
~/.openclaw/state/openclaw.sqlite (tables: task_runs, task_delivery_state, flow_runs)Atur OPENCLAW_STATE_DIR untuk memindahkan seluruh akar status (bawaan ~/.openclaw) ke lokasi lain; jalur basis data bersama akan ikut berpindah.
Registri dimuat ke memori saat pertama kali digunakan dan setiap penulisan dipersistenkan kembali ke SQLite, sehingga catatan tetap bertahan setelah Gateway dimulai ulang. Pertumbuhan WAL tetap terbatas melalui ambang pemeriksaan otomatis bawaan SQLite ditambah pemeriksaan PASSIVE berkala; penghentian dan pemeriksaan pemeliharaan eksplisit menggunakan TRUNCATE agar penutupan normal memperoleh kembali ruang WAL tanpa membuat penyapu latar belakang menunggu pembaca aktif.
Penyimpanan pendamping lama dari instalasi terdahulu (tasks/runs.sqlite, flows/registry.sqlite) diimpor ke basis data bersama oleh openclaw doctor.
Pemeliharaan otomatis
Penyapu berjalan setiap 60 detik (putaran pertama sekitar 5 detik setelah Gateway dimulai) dan menangani empat hal:
Rekonsiliasi
Memeriksa apakah tugas aktif masih memiliki dukungan runtime yang berwenang. Tugas ACP memerlukan giliran aktif dalam proses, tugas subagen menggunakan status sesi anak, tugas cron menggunakan kepemilikan pekerjaan aktif beserta riwayat eksekusi tahan lama, dan tugas CLI dengan identitas eksekusi menggunakan konteks eksekusi pemiliknya. Jika status pendukung hilang selama lebih dari 5 menit (30 menit untuk tugas subagen native tanpa anak), tugas ditandai sebagai lost.
Perbaikan sesi ACP
Menutup sesi ACP sekali jalan milik induk yang terminal atau terlantar, serta menutup sesi ACP persisten yang terminal atau terlantar dan kedaluwarsa hanya jika tidak ada pengikatan percakapan aktif yang tersisa.
Pemberian stempel pembersihan
Menetapkan stempel waktu cleanupAfter pada tugas terminal (waktu terminal + periode retensi). Selama retensi, tugas yang hilang masih muncul dalam audit sebagai peringatan; setelah cleanupAfter kedaluwarsa atau jika metadata pembersihan tidak ada, tugas tersebut menjadi kesalahan.
Pemangkasan
Menghapus catatan yang telah melewati tanggal cleanupAfter.
Hubungan tugas dengan sistem lain
Tugas dan Alur Tugas
Alur Tugas adalah lapisan orkestrasi alur di atas tugas latar belakang. Satu alur dapat mengoordinasikan beberapa tugas sepanjang masa aktifnya menggunakan mode sinkronisasi terkelola atau tercermin. Gunakan openclaw tasks untuk memeriksa catatan tugas individual dan openclaw tasks flow untuk memeriksa alur yang mengorkestrasi.
Tugas dan cron
Definisi pekerjaan Cron, status eksekusi runtime, dan riwayat eksekusi berada dalam basis data status SQLite bersama milik OpenClaw. Setiap eksekusi cron membuat catatan tugas—baik sesi utama maupun terisolasi—dengan kebijakan notifikasi silent, sehingga eksekusi cron dilacak tanpa menghasilkan notifikasi tugas tersendiri.
Lihat Pekerjaan Cron.
Tugas dan Heartbeat
Eksekusi Heartbeat adalah giliran sesi utama—eksekusi tersebut tidak membuat catatan tugas. Saat tugas selesai, tugas tersebut dapat memicu pembangkitan Heartbeat agar Anda segera melihat hasilnya.
Lihat Heartbeat.
Tugas dan sesi
Sebuah tugas dapat merujuk pada childSessionKey (tempat pekerjaan berjalan) dan requesterSessionKey (pihak yang memulainya). agentId mengidentifikasi agen yang menjalankan pekerjaan, sedangkan bidang peminta dan pemilik mempertahankan konteks peluncuran dan kontrol. Sesi merupakan konteks percakapan; tugas merupakan pelacakan aktivitas di atasnya.
Tugas dan eksekusi agen
runId milik tugas tertaut ke eksekusi agen yang mengerjakan tugas tersebut. Peristiwa siklus hidup agen (mulai, selesai, kesalahan) secara otomatis memperbarui status tugas—Anda tidak perlu mengelola siklus hidup secara manual.
Terkait
- Otomatisasi - semua mekanisme otomatisasi secara ringkas
- CLI: Tugas - referensi perintah CLI
- Heartbeat - giliran sesi utama berkala
- Tugas Terjadwal - penjadwalan pekerjaan latar belakang
- Alur Tugas - orkestrasi alur di atas tugas