백그라운드 작업

백그라운드 작업은 기본 대화 세션 외부에서 실행되는 작업을 추적합니다. 여기에는 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 전달은 하위 에이전트 작업이 아직 마무리되는 동안 오래된 중간 상위 응답을 억제하며, 전달 전에 최종 하위 출력이 도착하면 이를 우선 사용합니다.
• 완료 알림은 채널로 직접 전달되거나 다음 Heartbeat를 위해 대기열에 추가됩니다.
• openclaw tasks list는 모든 작업을 표시하고, openclaw tasks audit은 문제를 보여 줍니다.
• 종료 상태 기록은 7일 동안 유지되며(lost 기록은 24시간), 이후 자동으로 정리됩니다.

빠른 시작

# 모든 작업 나열(최신 항목부터)openclaw tasks list # 런타임 또는 상태로 필터링openclaw tasks list --runtime acpopenclaw tasks list --status running

# 특정 작업의 세부 정보 표시(작업 ID, 실행 ID 또는 세션 키 기준)openclaw tasks show <lookup>

# 실행 중인 작업 취소(하위 세션 종료)openclaw tasks cancel <lookup> # 작업의 알림 정책 변경openclaw tasks notify <lookup> state_changes

# 상태 감사 실행openclaw tasks audit # 유지 관리 미리 보기 또는 적용openclaw tasks maintenanceopenclaw tasks maintenance --apply

# TaskFlow 상태 검사openclaw tasks flow listopenclaw tasks flow show <lookup>openclaw tasks flow cancel <lookup>

작업을 생성하는 항목

작업 수명 주기

stateDiagram-v2
    [*] --> queued
    queued --> running : 에이전트 시작
    running --> succeeded : 정상 완료
    running --> failed : 오류
    running --> timed_out : 시간 제한 초과
    queued --> cancelled : 운영자가 취소
    running --> cancelled : 운영자가 취소
    queued --> lost : 기반 상태가 5분 넘게 사라짐
    running --> lost : 기반 상태가 5분 넘게 사라짐

상태 전환은 자동으로 이루어집니다. 에이전트 실행 수명 주기 이벤트(시작, 종료, 오류)가 작업 상태를 업데이트하므로 수동으로 관리하지 않습니다.

활성 작업 기록에서는 에이전트 실행 완료 결과가 최종 기준입니다. 성공한 분리 실행은 succeeded, 일반 실행 오류는 failed, 시간 제한 초과는 timed_out, 취소/중단 결과는 cancelled로 확정됩니다. 작업이 종료 상태가 되면 이후의 수명 주기 신호가 상태를 낮추지 않습니다. 운영자가 취소했거나 이미 failed/timed_out/lost 상태인 작업은 나중에 성공 신호가 도착하더라도 그대로 유지됩니다.

lost 판정은 런타임을 인식합니다.

• ACP 작업: Gateway 프로세스 내에서 실제로 실행 중인 ACP 턴만 실행이 살아 있음을 증명하며, 영구 저장된 세션 메타데이터만으로는 충분하지 않습니다. 오프라인 CLI 감사는 보수적으로 동작하며 ACP 작업을 회수하지 않습니다.
• 하위 에이전트 작업: 기반 하위 세션이 대상 에이전트 저장소에서 사라졌거나 재시작 복구 툼스톤을 포함합니다.
• Cron 작업: Cron 런타임이 더 이상 해당 작업을 활성 상태로 추적하지 않고, 영구 Cron 실행 기록에도 해당 실행의 종료 결과가 없습니다. 오프라인 CLI 감사는 자체적인 빈 프로세스 내 Cron 런타임 상태를 최종 기준으로 취급하지 않습니다.
• CLI 작업: 실행 ID/소스 ID가 있는 작업은 현재 실행 컨텍스트를 사용하므로, Gateway가 소유한 실행이 사라진 후에도 남아 있는 하위 세션 또는 채팅 세션 행이 작업을 활성 상태로 유지하지 않습니다. 실행 식별 정보가 없는 레거시 CLI 작업은 여전히 하위 세션으로 대체 판정합니다. Gateway 기반 openclaw agent 실행도 실행 결과에 따라 확정되므로, 완료된 실행이 스위퍼에 의해 lost로 표시될 때까지 활성 상태로 남지 않습니다.

전달 및 알림

작업이 종료 상태에 도달하면 OpenClaw가 알림을 보냅니다. 전달 경로는 두 가지입니다.

직접 전달 - 작업에 채널 대상(requesterOrigin)이 있으면 완료 메시지가 해당 채널(Discord, Slack, Telegram 등)로 바로 전달됩니다. 그룹 및 채널 작업 완료는 대신 요청자 세션을 통해 라우팅되므로 상위 에이전트가 표시할 응답을 작성할 수 있습니다. 하위 에이전트 완료의 경우 OpenClaw는 가능하면 바인딩된 스레드/주제 라우팅도 유지하며, 직접 전달을 포기하기 전에 요청자 세션에 저장된 경로(lastChannel / lastTo / lastAccountId)에서 누락된 to / 계정을 채울 수 있습니다.

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

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

알림 정책

각 작업에 대해 어느 정도의 알림을 받을지 제어합니다.

작업이 실행 중일 때 정책을 변경할 수 있습니다.

openclaw tasks notify <lookup> state_changes

CLI 참조

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

openclaw tasks show <lookup> [--json]

openclaw tasks cancel <lookup>

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

openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--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를 사용하면 해당 세션에 연결된 백그라운드 작업을 볼 수 있습니다. 보드에는 실행 중이거나 최근 완료된 작업이 최대 5개까지 런타임, 상태, 시간 정보, 진행 상황 또는 오류 세부 정보와 함께 표시됩니다.

현재 세션에 표시 가능한 연결 작업이 없으면 /tasks는 에이전트 로컬 작업 수로 대체하여 다른 세션의 세부 정보를 노출하지 않고도 개요를 제공합니다.

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

제어 UI

웹 제어 UI의 사이드바에는 실행 중이거나 최근 완료된 백그라운드 작업을 실시간으로 보여 주는 작업 페이지가 있습니다. 이 페이지에서 진행 상황을 점검하고, 연결된 세션을 열고, 원장을 새로 고치거나, 대기열 및 실행 중인 작업을 취소할 수 있습니다.

채팅 창에는 해당 창의 에이전트로 범위가 지정된 접을 수 있는 백그라운드 작업 레일도 있습니다. 여기에는 중지 컨트롤이 있는 실행 중 작업과 하위 에이전트, 완료 섹션, 각 작업의 하위 세션으로 이동하는 대화 내용 보기 링크가 표시됩니다. 창 헤더의 활동 토글(또는 단일 창 채팅의 플로팅 활동 버튼)에서 여세요.

상태 통합(작업 부하)

openclaw status에는 작업 현황을 한눈에 볼 수 있는 줄이 포함됩니다.

작업    활성 2개 · 대기열 1개 · 실행 중 1개 · 문제 1개 · 감사 이상 없음 · 추적 6개

요약에는 활성 작업(queued + running), 실패(failed + timed_out + lost), 감사 발견 항목 및 추적 중인 전체 레코드 수가 집계됩니다. JSON 페이로드는 런타임별(acp, subagent, cron, cli) 개수도 세분화합니다.

/status와 session_status 도구는 모두 정리를 인식하는 작업 스냅샷을 사용합니다. 활성 작업을 우선하고, 만료된 행은 숨기며, 종료 작업은 짧은 최근 기간(5분) 동안만 표시합니다. 활성 작업이 남아 있지 않으면 실패에 초점을 맞춥니다. 이를 통해 상태 카드가 지금 중요한 내용에 집중합니다.

저장소 및 유지 관리

작업 저장 위치

작업 레코드와 전달 상태는 공유 OpenClaw SQLite 상태 데이터베이스에 영구 저장됩니다.

~/.openclaw/state/openclaw.sqlite   (테이블: task_runs, task_delivery_state, flow_runs)

전체 상태 루트(기본값 ~/.openclaw)를 다른 위치로 옮기려면 OPENCLAW_STATE_DIR을 설정하세요. 공유 데이터베이스 경로도 함께 이동합니다.

레지스트리는 처음 사용할 때 메모리로 로드되며 모든 쓰기를 SQLite에 다시 영구 저장하므로 Gateway가 재시작되어도 레코드가 유지됩니다. WAL 증가는 SQLite의 기본 자동 체크포인트 임계값과 주기적인 PASSIVE 체크포인트를 통해 제한됩니다. 종료 및 명시적 유지 관리 체크포인트는 TRUNCATE를 사용하므로 백그라운드 스위퍼가 활성 리더를 기다리게 하지 않으면서 정상 종료 시 WAL 공간을 회수합니다.

이전 설치의 레거시 사이드카 저장소(tasks/runs.sqlite, flows/registry.sqlite)는 openclaw doctor가 공유 데이터베이스로 가져옵니다.

자동 유지 관리

스위퍼는 60초마다 실행되며(Gateway 시작 후 약 5초 뒤 첫 실행), 다음 네 가지를 처리합니다.

작업과 다른 시스템의 관계

관련 문서

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