Tác vụ nền

Tác vụ nền theo dõi công việc chạy bên ngoài phiên hội thoại chính của bạn: các lượt chạy ACP, việc sinh tác tử con, các lần thực thi cron job cô lập, và các thao tác do CLI khởi tạo.

Tác vụ không thay thế phiên, cron job, hay heartbeat - chúng là sổ cái hoạt động ghi lại công việc tách rời nào đã diễn ra, khi nào, và có thành công hay không.

# Tóm tắt nhanh

• Tác vụ là bản ghi, không phải bộ lập lịch - cron và heartbeat quyết định khi nào công việc chạy, tác vụ theo dõi điều gì đã xảy ra.
• ACP, tác tử con, tất cả cron job, và thao tác CLI tạo tác vụ. Các lượt Heartbeat thì không.
• Mỗi tác vụ đi qua queued → running → terminal (succeeded, failed, timed_out, cancelled, hoặc lost).
• Tác vụ Cron vẫn hoạt động khi runtime cron vẫn sở hữu công việc; nếu trạng thái runtime trong bộ nhớ không còn, bảo trì tác vụ trước tiên kiểm tra lịch sử chạy cron bền vững trước khi đánh dấu tác vụ là mất.
• Hoàn tất được điều khiển bằng đẩy: công việc tách rời có thể thông báo trực tiếp hoặc đánh thức phiên/heartbeat của bên yêu cầu khi hoàn tất, vì vậy các vòng lặp thăm dò trạng thái thường không phải là hình dạng phù hợp.
• Các lượt chạy cron cô lập và lần hoàn tất của tác tử con cố gắng tối đa để dọn dẹp các tab/quy trình trình duyệt được theo dõi cho phiên con của chúng trước khi ghi sổ dọn dẹp cuối cùng.
• Việc phân phối cron cô lập chặn các phản hồi cha tạm thời đã cũ trong khi công việc tác tử con hậu duệ vẫn đang xả, và ưu tiên đầu ra hậu duệ cuối cùng khi đầu ra đó đến trước lúc phân phối.
• Thông báo hoàn tất được gửi trực tiếp đến một kênh hoặc xếp hàng cho heartbeat tiếp theo.
• openclaw tasks list hiển thị tất cả tác vụ; openclaw tasks audit nêu ra vấn đề.
• Bản ghi cuối được giữ trong 7 ngày, rồi tự động cắt tỉa.

# Bắt đầu nhanh

# 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>

# Điều gì tạo ra tác vụ

# Vòng đời tác vụ

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

Chuyển trạng thái diễn ra tự động - khi lượt chạy tác tử liên quan kết thúc, trạng thái tác vụ cập nhật cho khớp.

Việc hoàn tất lượt chạy tác tử là nguồn có thẩm quyền cho các bản ghi tác vụ đang hoạt động. Một lượt chạy tách rời thành công sẽ kết thúc là succeeded, lỗi chạy thông thường kết thúc là failed, và kết quả hết thời gian chờ hoặc hủy bỏ kết thúc là timed_out. Nếu người vận hành đã hủy tác vụ, hoặc runtime đã ghi một trạng thái cuối mạnh hơn như failed, timed_out, hoặc lost, tín hiệu thành công đến sau sẽ không hạ cấp trạng thái cuối đó.

lost hiểu theo runtime:

• Tác vụ ACP: siêu dữ liệu phiên ACP con hậu thuẫn đã biến mất.
• Tác vụ tác tử con: phiên con hậu thuẫn đã biến mất khỏi kho tác tử đích.
• Tác vụ Cron: runtime cron không còn theo dõi công việc là đang hoạt động và lịch sử chạy cron bền vững không cho thấy kết quả cuối cho lượt chạy đó. Kiểm tra CLI ngoại tuyến không coi trạng thái runtime cron rỗng trong tiến trình của chính nó là có thẩm quyền.
• Tác vụ CLI: tác vụ phiên con cô lập dùng phiên con; tác vụ CLI có trò chuyện hậu thuẫn dùng ngữ cảnh chạy trực tiếp thay vào đó, nên các hàng phiên kênh/nhóm/trực tiếp còn sót lại không giữ chúng sống. Các lượt chạy openclaw agent có Gateway hậu thuẫn cũng kết thúc từ kết quả chạy của chúng, nên các lượt chạy đã hoàn tất không nằm ở trạng thái hoạt động cho đến khi trình quét đánh dấu chúng là lost.

# Phân phối và thông báo

Khi một tác vụ đạt trạng thái cuối, OpenClaw thông báo cho bạn. Có hai đường phân phối:

Phân phối trực tiếp - nếu tác vụ có đích kênh (requesterOrigin), tin nhắn hoàn tất đi thẳng đến kênh đó (Telegram, Discord, Slack, v.v.). Đối với hoàn tất của tác tử con, OpenClaw cũng giữ định tuyến luồng/chủ đề đã ràng buộc khi có sẵn và có thể điền to / tài khoản bị thiếu từ tuyến đã lưu của phiên yêu cầu (lastChannel / lastTo / lastAccountId) trước khi từ bỏ phân phối trực tiếp.

Phân phối xếp hàng theo phiên - nếu phân phối trực tiếp thất bại hoặc không đặt nguồn gốc, bản cập nhật được xếp hàng như một sự kiện hệ thống trong phiên của bên yêu cầu và xuất hiện ở heartbeat tiếp theo.

Điều đó nghĩa là quy trình làm việc thông thường dựa trên đẩy: bắt đầu công việc tách rời một lần, rồi để runtime đánh thức hoặc thông báo cho bạn khi hoàn tất. Chỉ thăm dò trạng thái tác vụ khi bạn cần gỡ lỗi, can thiệp, hoặc kiểm tra rõ ràng.

# Chính sách thông báo

Kiểm soát mức độ bạn nghe về từng tác vụ:

Thay đổi chính sách trong khi tác vụ đang chạy:

openclaw tasks notify <lookup> state_changes

# Tham chiếu 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>

# Bảng tác vụ chat (/tasks)

Dùng /tasks trong bất kỳ phiên chat nào để xem các tác vụ nền được liên kết với phiên đó. Bảng hiển thị các tác vụ đang hoạt động và mới hoàn tất gần đây cùng runtime, trạng thái, thời gian, và chi tiết tiến độ hoặc lỗi.

Khi phiên hiện tại không có tác vụ liên kết hiển thị nào, /tasks sẽ quay lại số lượng tác vụ cục bộ của agent để bạn vẫn có được tổng quan mà không rò rỉ chi tiết của phiên khác.

Để xem sổ cái đầy đủ cho người vận hành, dùng CLI: openclaw tasks list.

# Tích hợp trạng thái (áp lực tác vụ)

openclaw status bao gồm bản tóm tắt tác vụ nhanh:

Tasks: 3 queued · 2 running · 1 issues

Bản tóm tắt báo cáo:

• active - số lượng queued + running
• failures - số lượng failed + timed_out + lost
• byRuntime - phân rã theo acp, subagent, cron, cli

Cả /status và công cụ session_status đều dùng ảnh chụp tác vụ có nhận biết dọn dẹp: ưu tiên các tác vụ đang hoạt động, ẩn các hàng đã hoàn tất cũ, và chỉ hiển thị lỗi gần đây khi không còn công việc đang hoạt động. Điều này giữ thẻ trạng thái tập trung vào những gì quan trọng ngay lúc này.

# Lưu trữ và bảo trì

# Nơi lưu tác vụ

Các bản ghi tác vụ được lưu bền vững trong SQLite tại:

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

Registry tải vào bộ nhớ khi gateway khởi động và đồng bộ các lần ghi vào SQLite để đảm bảo độ bền qua các lần khởi động lại. Gateway giữ nhật ký ghi trước của SQLite ở mức giới hạn bằng cách dùng ngưỡng autocheckpoint mặc định của SQLite cùng các checkpoint TRUNCATE định kỳ và khi tắt.

# Bảo trì tự động

Một sweeper chạy mỗi 60 giây và xử lý bốn việc:

# Cách tác vụ liên quan đến các hệ thống khác

# Liên quan

• Tự động hóa & Tác vụ - toàn bộ cơ chế tự động hóa trong nháy mắt
• CLI: Tác vụ - tham chiếu lệnh CLI
• Heartbeat - các lượt phiên chính định kỳ
• Tác vụ đã lên lịch - lên lịch công việc nền
• Task Flow - điều phối luồng phía trên tác vụ