백그라운드 작업

백그라운드 작업은 기본 대화 세션 밖에서 실행되는 작업을 추적합니다: ACP 실행, 하위 에이전트 생성, 격리된 cron 작업 실행, CLI에서 시작된 작업입니다.

작업은 세션, cron 작업 또는 Heartbeat를 대체하지 않습니다. 작업은 분리된 작업이 무엇을 했는지, 언제 했는지, 성공했는지를 기록하는 활동 원장입니다.

# 요약

• 작업은 스케줄러가 아니라 기록입니다. cron과 Heartbeat는 작업이 언제 실행될지 결정하고, 작업은 무슨 일이 일어났는지 추적합니다.
• ACP, 하위 에이전트, 모든 cron 작업, CLI 작업은 작업을 생성합니다. Heartbeat 턴은 생성하지 않습니다.
• 각 작업은 queued → running → terminal(succeeded, failed, timed_out, cancelled 또는 lost)을 거칩니다.
• cron 런타임이 아직 작업을 소유하고 있는 동안 cron 작업은 활성 상태로 유지됩니다. 메모리 내 런타임 상태가 사라지면 작업 유지 관리는 작업을 lost로 표시하기 전에 먼저 영구 cron 실행 기록을 확인합니다.
• 완료는 푸시 기반입니다. 분리된 작업은 완료 시 직접 알리거나 요청자 세션/Heartbeat를 깨울 수 있으므로, 상태 폴링 루프는 보통 적합한 형태가 아닙니다.
• 격리된 cron 실행과 하위 에이전트 완료는 최종 정리 부기 전에 자식 세션의 추적된 브라우저 탭/프로세스를 최선 노력으로 정리합니다.
• 격리된 cron 전달은 하위 descendant 에이전트 작업이 아직 비워지는 중일 때 오래된 중간 부모 응답을 억제하며, 전달 전에 최종 descendant 출력이 도착하면 이를 우선 사용합니다.
• 완료 알림은 채널로 직접 전달되거나 다음 Heartbeat를 위해 대기열에 추가됩니다.
• openclaw tasks list는 모든 작업을 표시하고, openclaw tasks audit는 문제를 드러냅니다.
• 터미널 기록은 7일 동안 보관된 뒤 자동으로 정리됩니다.

# 빠른 시작

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

# 작업을 생성하는 것

# 작업 수명 주기

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

전환은 자동으로 일어납니다. 연결된 에이전트 실행이 끝나면 작업 상태가 그에 맞게 업데이트됩니다.

에이전트 실행 완료는 활성 작업 기록에 대한 권한 있는 기준입니다. 성공한 분리 실행은 succeeded로 종료되고, 일반 실행 오류는 failed로 종료되며, 시간 초과 또는 중단 결과는 timed_out으로 종료됩니다. 작업자가 이미 작업을 취소했거나 런타임이 failed, timed_out, lost 같은 더 강한 터미널 상태를 이미 기록한 경우, 이후의 성공 신호는 해당 터미널 상태를 낮추지 않습니다.

lost는 런타임을 인식합니다.

• ACP 작업: 백업 ACP 자식 세션 메타데이터가 사라졌습니다.
• 하위 에이전트 작업: 대상 에이전트 저장소에서 백업 자식 세션이 사라졌습니다.
• cron 작업: cron 런타임이 더 이상 작업을 활성 상태로 추적하지 않으며, 영구 cron 실행 기록에도 해당 실행의 터미널 결과가 표시되지 않습니다. 오프라인 CLI 감사는 자체의 비어 있는 인프로세스 cron 런타임 상태를 권한으로 간주하지 않습니다.
• CLI 작업: 격리된 자식 세션 작업은 자식 세션을 사용하고, 채팅 기반 CLI 작업은 대신 라이브 실행 컨텍스트를 사용하므로 남아 있는 채널/그룹/직접 세션 행이 이를 활성 상태로 유지하지 않습니다. Gateway 기반 openclaw agent 실행도 실행 결과에서 종료되므로, 완료된 실행이 sweeper가 lost로 표시할 때까지 활성 상태로 남아 있지 않습니다.

# 전달 및 알림

작업이 터미널 상태에 도달하면 OpenClaw가 사용자에게 알립니다. 전달 경로는 두 가지입니다.

직접 전달 - 작업에 채널 대상(requesterOrigin)이 있으면 완료 메시지가 해당 채널(Telegram, Discord, Slack 등)로 바로 이동합니다. 하위 에이전트 완료의 경우, OpenClaw는 가능할 때 바인딩된 스레드/토픽 라우팅도 보존하며, 직접 전달을 포기하기 전에 요청자 세션의 저장된 경로(lastChannel / lastTo / lastAccountId)에서 누락된 to / 계정을 채울 수 있습니다.

세션 대기열 전달 - 직접 전달이 실패하거나 origin이 설정되지 않은 경우, 업데이트는 요청자 세션의 시스템 이벤트로 대기열에 추가되고 다음 Heartbeat에서 표시됩니다.

즉, 일반적인 워크플로는 푸시 기반입니다. 분리된 작업을 한 번 시작한 뒤 런타임이 완료 시 사용자를 깨우거나 알리도록 두세요. 디버깅, 개입 또는 명시적 감사가 필요할 때만 작업 상태를 폴링하세요.

# 알림 정책

각 작업에 대해 얼마나 많은 알림을 받을지 제어합니다.

작업이 실행 중일 때 정책을 변경합니다.

openclaw tasks notify <lookup> state_changes

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

# 채팅 작업 보드(/tasks)

어떤 채팅 세션에서든 /tasks를 사용해 해당 세션에 연결된 백그라운드 작업을 확인합니다. 보드는 활성 작업과 최근 완료된 작업을 런타임, 상태, 타이밍, 진행 상황 또는 오류 상세와 함께 표시합니다.

현재 세션에 보이는 연결 작업이 없으면 /tasks는 에이전트 로컬 작업 수로 대체하므로 다른 세션의 세부 정보를 누출하지 않고도 개요를 볼 수 있습니다.

전체 운영자 원장을 보려면 CLI를 사용하세요: openclaw tasks list.

# 상태 통합(작업 압력)

openclaw status에는 한눈에 볼 수 있는 작업 요약이 포함됩니다.

Tasks: 3 queued · 2 running · 1 issues

요약은 다음을 보고합니다.

• active - queued + running의 개수
• failures - failed + timed_out + lost의 개수
• byRuntime - acp, subagent, cron, cli별 분류

/status와 session_status 도구는 모두 정리 인식 작업 스냅샷을 사용합니다. 활성 작업이 우선되고, 오래된 완료 행은 숨겨지며, 최근 실패는 활성 작업이 남아 있지 않을 때만 표시됩니다. 이렇게 하면 상태 카드가 지금 중요한 것에 집중됩니다.

# 저장소와 유지관리

# 작업이 저장되는 위치

작업 레코드는 SQLite에 다음 위치로 유지됩니다.

$OPENCLAW_STATE_DIR/tasks/runs.sqlite

레지스트리는 Gateway 시작 시 메모리에 로드되고, 재시작 후에도 지속성을 유지하도록 쓰기를 SQLite에 동기화합니다. Gateway는 SQLite의 기본 자동 체크포인트 임계값과 주기적 및 종료 시 TRUNCATE 체크포인트를 사용해 SQLite write-ahead log의 크기를 제한합니다.

# 자동 유지관리

스위퍼가 60초마다 실행되어 네 가지를 처리합니다.

# 작업과 다른 시스템의 관계

# 관련

• 자동화 및 작업 - 모든 자동화 메커니즘 한눈에 보기
• CLI: 작업 - CLI 명령 참조
• Heartbeat - 주기적인 기본 세션 턴
• 예약된 작업 - 백그라운드 작업 예약
• Task Flow - 작업 위의 흐름 오케스트레이션