Tugas latar belakang

Tugas latar belakang melacak pekerjaan yang berjalan di luar sesi percakapan utama Anda: eksekusi ACP, spawn subagent, eksekusi pekerjaan cron terisolasi, dan operasi yang dimulai CLI.

Tugas tidak menggantikan sesi, pekerjaan cron, atau heartbeat - tugas adalah buku besar aktivitas yang mencatat pekerjaan terlepas apa yang terjadi, kapan, dan apakah berhasil.

# TL;DR

• Tugas adalah catatan, bukan penjadwal - cron dan Heartbeat menentukan kapan pekerjaan berjalan, tugas melacak apa yang terjadi.
• ACP, subagent, semua pekerjaan cron, dan operasi CLI membuat tugas. Giliran Heartbeat tidak.
• Setiap tugas bergerak melalui queued → running → terminal (succeeded, failed, timed_out, cancelled, atau lost).
• Tugas cron tetap aktif selama runtime cron masih memiliki pekerjaan tersebut; jika status runtime dalam memori hilang, pemeliharaan tugas terlebih dahulu memeriksa riwayat eksekusi cron yang persisten sebelum menandai tugas sebagai lost.
• Penyelesaian didorong secara push: pekerjaan terlepas dapat memberi tahu secara langsung atau membangunkan sesi peminta/Heartbeat saat selesai, sehingga loop polling status biasanya merupakan bentuk yang keliru.
• Eksekusi cron terisolasi dan penyelesaian subagent melakukan pembersihan best-effort atas tab/proses browser yang terlacak untuk sesi anaknya sebelum pembukuan pembersihan akhir.
• Pengiriman cron terisolasi menekan balasan induk sementara yang kedaluwarsa selama pekerjaan subagent turunan masih mengalir, dan lebih memilih keluaran turunan akhir ketika keluaran itu tiba sebelum pengiriman.
• Notifikasi penyelesaian dikirim langsung ke channel atau diantrekan untuk Heartbeat berikutnya.
• openclaw tasks list menampilkan semua tugas; openclaw tasks audit memunculkan masalah.
• Catatan terminal disimpan selama 7 hari, lalu dipangkas otomatis.

# Mulai cepat

# List all tasks (newest first)
openclaw tasks list

# Filter by runtime or status
openclaw tasks list --runtime acp
openclaw tasks list --status running

# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show <lookup>

# Cancel a running task (kills the child session)
openclaw tasks cancel <lookup>

# Change notification policy for a task
openclaw tasks notify <lookup> state_changes

# Run a health audit
openclaw tasks audit

# Preview or apply maintenance
openclaw tasks maintenance
openclaw tasks maintenance --apply

# Inspect TaskFlow state
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>

# Apa yang membuat tugas

# Siklus hidup tugas

stateDiagram-v2
    [*] --> queued
    queued --> running : agent starts
    running --> succeeded : completes ok
    running --> failed : error
    running --> timed_out : timeout exceeded
    running --> cancelled : operator cancels
    queued --> lost : session gone > 5 min
    running --> lost : session gone > 5 min

Transisi terjadi otomatis - saat eksekusi agen terkait berakhir, status tugas diperbarui agar cocok.

Penyelesaian eksekusi agen bersifat otoritatif untuk catatan tugas aktif. Eksekusi terlepas yang berhasil difinalisasi sebagai succeeded, kesalahan eksekusi biasa difinalisasi sebagai failed, dan hasil timeout atau abort difinalisasi sebagai timed_out. Jika operator sudah membatalkan tugas, atau runtime sudah mencatat status terminal yang lebih kuat seperti failed, timed_out, atau lost, sinyal sukses yang datang kemudian tidak menurunkan status terminal tersebut.

lost sadar runtime:

• Tugas ACP: metadata sesi anak ACP pendukung menghilang.
• Tugas subagent: sesi anak pendukung menghilang dari penyimpanan agen target.
• Tugas Cron: runtime cron tidak lagi melacak pekerjaan sebagai aktif dan riwayat eksekusi cron persisten tidak menunjukkan hasil terminal untuk eksekusi itu. Audit CLI offline tidak memperlakukan status runtime cron dalam prosesnya sendiri yang kosong sebagai otoritas.
• Tugas CLI: tugas sesi anak terisolasi menggunakan sesi anak; CLI yang didukung chat menggunakan konteks eksekusi langsung sebagai gantinya, sehingga baris sesi channel/grup/langsung yang tersisa tidak menjaganya tetap aktif. Eksekusi openclaw agent yang didukung Gateway juga difinalisasi dari hasil eksekusinya, sehingga eksekusi yang selesai tidak tetap aktif sampai penyapu menandainya lost.

# Pengiriman dan notifikasi

Saat tugas mencapai status terminal, OpenClaw memberi tahu Anda. Ada dua jalur pengiriman:

Pengiriman langsung - jika tugas memiliki target channel (requesterOrigin), pesan penyelesaian langsung menuju channel tersebut (Telegram, Discord, Slack, dan sebagainya). Untuk penyelesaian subagent, OpenClaw juga mempertahankan perutean thread/topik terikat saat tersedia dan dapat mengisi to / akun yang hilang dari rute tersimpan milik sesi peminta (lastChannel / lastTo / lastAccountId) sebelum menyerah pada pengiriman langsung.

Pengiriman antrean sesi - jika pengiriman langsung gagal atau tidak ada origin yang ditetapkan, pembaruan diantrekan sebagai peristiwa sistem dalam sesi peminta dan muncul pada Heartbeat berikutnya.

Itu berarti alur kerja biasa berbasis push: mulai pekerjaan terlepas sekali, lalu biarkan runtime membangunkan atau memberi tahu Anda saat selesai. Poll status tugas hanya saat Anda memerlukan debugging, intervensi, atau audit eksplisit.

# Kebijakan notifikasi

Kontrol seberapa banyak yang Anda dengar tentang setiap tugas:

Ubah kebijakan saat tugas sedang berjalan:

openclaw tasks notify <lookup> state_changes

# Referensi CLI

openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]

openclaw tasks show <lookup>

openclaw tasks cancel <lookup>

openclaw tasks notify <lookup> <done_only|state_changes|silent>

openclaw tasks audit [--json]

openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]

openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>

# Papan tugas chat (/tasks)

Gunakan /tasks di sesi chat mana pun untuk melihat tugas latar belakang yang tertaut ke sesi tersebut. Papan menampilkan tugas aktif dan yang baru selesai dengan runtime, status, waktu, serta detail progres atau error.

Ketika sesi saat ini tidak memiliki tugas tertaut yang terlihat, /tasks beralih ke jumlah tugas lokal agen sehingga Anda tetap mendapatkan gambaran umum tanpa membocorkan detail sesi lain.

Untuk ledger operator lengkap, gunakan CLI: openclaw tasks list.

# Integrasi status (tekanan tugas)

openclaw status menyertakan ringkasan tugas sekilas:

Tasks: 3 queued · 2 running · 1 issues

Ringkasan melaporkan:

• aktif - jumlah queued + running
• kegagalan - jumlah failed + timed_out + lost
• byRuntime - rincian berdasarkan acp, subagent, cron, cli

Baik /status maupun alat session_status menggunakan snapshot tugas yang sadar pembersihan: tugas aktif diutamakan, baris selesai yang basi disembunyikan, dan kegagalan terbaru hanya muncul ketika tidak ada pekerjaan aktif yang tersisa. Ini menjaga kartu status tetap fokus pada hal yang penting saat ini.

# Penyimpanan dan pemeliharaan

# Tempat tugas disimpan

Catatan tugas dipersistenkan di SQLite pada:

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

Registry dimuat ke memori saat gateway dimulai dan menyinkronkan penulisan ke SQLite agar tahan lama lintas mulai ulang. Gateway menjaga log write-ahead SQLite tetap terbatas dengan menggunakan ambang autocheckpoint default SQLite plus checkpoint TRUNCATE berkala dan saat shutdown.

# Pemeliharaan otomatis

Sweeper berjalan setiap 60 detik dan menangani empat hal:

# Bagaimana tugas berhubungan dengan sistem lain

# Terkait

• Otomatisasi & Tugas - semua mekanisme otomatisasi secara sekilas
• CLI: Tugas - referensi perintah CLI
• Heartbeat - giliran sesi utama berkala
• Tugas Terjadwal - menjadwalkan pekerjaan latar belakang
• Alur Tugas - orkestrasi alur di atas tugas