메인 콘텐츠로 건너뛰기

​
배경 작업

스케줄링을 찾고 계신가요? 적절한 메커니즘을 선택하려면 Automation & Tasks를 참조하세요. 이 페이지는 백그라운드 작업의 추적을 다루며, 스케줄링은 다루지 않습니다.
배경 작업은 기본 대화 세션 외부에서 실행되는 작업을 추적합니다: ACP 실행, 하위 에이전트 생성, 격리된 cron 작업 실행, 그리고 CLI로 시작된 작업입니다. 작업은 세션, cron 작업, heartbeat를 대체하지 않습니다 — 이것은 분리된 작업에서 무엇이 일어났는지, 언제 일어났는지, 그리고 성공했는지를 기록하는 활동 원장입니다.
모든 에이전트 실행이 작업을 생성하는 것은 아닙니다. Heartbeat 턴과 일반 대화형 채팅은 생성하지 않습니다. 모든 cron 실행, ACP 생성, 하위 에이전트 생성, 그리고 CLI 에이전트 명령은 생성합니다.

​
요약

  • 작업은 스케줄러가 아니라 기록입니다 — cron과 heartbeat가 작업 실행 시점 을 결정하고, 작업은 무슨 일이 있었는지 를 추적합니다.
  • ACP, 하위 에이전트, 모든 cron 작업, 그리고 CLI 작업은 작업을 생성합니다. Heartbeat 턴은 생성하지 않습니다.
  • 각 작업은 queued → running → terminal(succeeded, failed, timed_out, cancelled, 또는 lost) 단계를 거칩니다.
  • Cron 작업은 cron 런타임이 여전히 해당 작업을 소유하는 동안 활성 상태를 유지합니다. 채팅 기반 CLI 작업은 소유 실행 컨텍스트가 아직 활성일 때만 활성 상태를 유지합니다.
  • 완료는 푸시 방식으로 처리됩니다. 분리된 작업은 완료 시 직접 알리거나 요청자 세션/heartbeat를 깨울 수 있으므로, 상태를 폴링하는 루프는 대개 적절한 방식이 아닙니다.
  • 격리된 cron 실행과 하위 에이전트 완료는 최종 정리 bookkeeping 전에 해당 하위 세션의 추적된 브라우저 탭/프로세스를 best-effort로 정리합니다.
  • 격리된 cron 전달은 하위 하위 에이전트 작업이 아직 비워지는 동안 오래된 중간 부모 응답을 억제하고, 전달 전에 최종 하위 출력이 도착하면 그것을 우선합니다.
  • 완료 알림은 채널로 직접 전달되거나 다음 heartbeat를 위해 대기열에 들어갑니다.
  • openclaw tasks list는 모든 작업을 표시하고, openclaw tasks audit는 문제를 표시합니다.
  • 종료된 기록은 7일 동안 유지된 후 자동으로 정리됩니다.

​
빠른 시작

# 모든 작업 나열(최신순)
openclaw tasks list

# 런타임 또는 상태별로 필터링
openclaw tasks list --runtime acp
openclaw tasks list --status running

# 특정 작업의 세부 정보 표시(ID, run ID 또는 session key로 조회)
openclaw tasks show <lookup>

# 실행 중인 작업 취소(하위 세션 종료)
openclaw tasks cancel <lookup>

# 작업의 알림 정책 변경
openclaw tasks notify <lookup> state_changes

# 상태 감사 실행
openclaw tasks audit

# 유지 관리 미리보기 또는 적용
openclaw tasks maintenance
openclaw tasks maintenance --apply

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

​
작업을 생성하는 항목

소스런타임 유형작업 기록이 생성되는 시점기본 알림 정책
ACP 백그라운드 실행acp하위 ACP 세션 생성done_only
하위 에이전트 오케스트레이션subagentsessions_spawn을 통해 하위 에이전트를 생성할 때done_only
Cron 작업(모든 유형)cron모든 cron 실행(메인 세션 및 격리형)silent
CLI 작업cli게이트웨이를 통해 실행되는 openclaw agent 명령silent
메인 세션 cron 작업은 기본적으로 silent 알림 정책을 사용합니다 — 추적용 기록은 생성하지만 알림은 생성하지 않습니다. 격리된 cron 작업도 기본적으로 silent이지만 자체 세션에서 실행되므로 더 눈에 띕니다. 작업을 생성하지 않는 항목:
  • Heartbeat 턴 — 메인 세션, Heartbeat 참조
  • 일반 대화형 채팅 턴
  • 직접 /command 응답

​
작업 수명 주기

상태의미
queued생성되었고, 에이전트 시작을 기다리는 중
running에이전트 턴이 현재 실행 중
succeeded성공적으로 완료됨
failed오류와 함께 완료됨
timed_out구성된 제한 시간을 초과함
cancelled운영자가 openclaw tasks cancel로 중지함
lost5분 유예 기간 후 런타임이 권한 있는 백킹 상태를 잃음
전이는 자동으로 발생합니다 — 연결된 에이전트 실행이 끝나면 작업 상태가 이에 맞춰 업데이트됩니다. lost는 런타임 인식 방식으로 처리됩니다:
  • ACP 작업: 백킹 ACP 하위 세션 메타데이터가 사라졌습니다.
  • 하위 에이전트 작업: 대상 에이전트 저장소에서 백킹 하위 세션이 사라졌습니다.
  • Cron 작업: cron 런타임이 더 이상 해당 작업을 활성 상태로 추적하지 않습니다.
  • CLI 작업: 격리된 하위 세션 작업은 하위 세션을 사용하고, 채팅 기반 CLI 작업은 대신 활성 실행 컨텍스트를 사용하므로 남아 있는 채널/그룹/직접 세션 행만으로는 활성 상태가 유지되지 않습니다.

​
전달 및 알림

작업이 종료 상태에 도달하면 OpenClaw가 알립니다. 전달 경로는 두 가지입니다. 직접 전달 — 작업에 채널 대상(requesterOrigin)이 있으면 완료 메시지가 해당 채널(Telegram, Discord, Slack 등)로 바로 전송됩니다. 하위 에이전트 완료의 경우 OpenClaw는 가능하면 바인딩된 스레드/토픽 라우팅도 보존하며, 직접 전달을 포기하기 전에 요청자 세션의 저장된 경로(lastChannel / lastTo / lastAccountId)에서 누락된 to / 계정을 채울 수 있습니다. 세션 대기열 전달 — 직접 전달에 실패했거나 origin이 설정되지 않은 경우, 업데이트는 요청자 세션의 시스템 이벤트로 대기열에 들어가며 다음 heartbeat에서 표시됩니다.
작업 완료는 즉시 heartbeat 깨우기를 트리거하므로 결과를 빠르게 확인할 수 있습니다 — 다음 예약된 heartbeat 틱까지 기다릴 필요가 없습니다.
즉, 일반적인 워크플로는 푸시 기반입니다. 분리된 작업을 한 번 시작한 뒤, 완료 시 런타임이 깨우거나 알리도록 두세요. 디버깅, 개입, 또는 명시적인 감사가 필요할 때만 작업 상태를 폴링하세요.

​
알림 정책

각 작업에 대해 얼마나 많은 알림을 받을지 제어합니다.
정책전달되는 내용
done_only (기본값)종료 상태(succeeded, failed 등)만 전달 — 이 값이 기본값입니다
state_changes모든 상태 전이와 진행 상황 업데이트
silent아무것도 전달하지 않음
작업이 실행 중일 때 정책을 변경할 수 있습니다. 
openclaw tasks notify <lookup> state_changes

​
CLI 참조

​
tasks list

openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
출력 열: 작업 ID, 종류, 상태, 전달, Run ID, 하위 세션, 요약.

​
tasks show

openclaw tasks show <lookup>
조회 토큰은 작업 ID, run ID, 또는 session key를 받을 수 있습니다. 타이밍, 전달 상태, 오류, 종료 요약을 포함한 전체 기록을 표시합니다.

​
tasks cancel

openclaw tasks cancel <lookup>
ACP 및 하위 에이전트 작업의 경우 하위 세션을 종료합니다. 상태는 cancelled로 전이되며 전달 알림이 전송됩니다.

​
tasks notify

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

​
tasks audit

openclaw tasks audit [--json]
운영상 문제를 표시합니다. 문제가 감지되면 결과는 openclaw status에도 나타납니다.
항목심각도트리거
stale_queuedwarn10분 이상 queued 상태
stale_runningerror30분 이상 running 상태
losterror런타임 기반 작업 소유권이 사라짐
delivery_failedwarn전달이 실패했고 알림 정책이 silent가 아님
missing_cleanupwarncleanup 타임스탬프가 없는 종료 작업
inconsistent_timestampswarn타임라인 위반(예: 시작 전에 종료됨)

​
tasks maintenance

openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
이를 사용해 작업 및 Task Flow 상태의 조정, cleanup 스탬프 처리, 그리고 정리를 미리 보거나 적용할 수 있습니다. 조정은 런타임 인식 방식으로 처리됩니다.
  • ACP/하위 에이전트 작업은 백킹 하위 세션을 확인합니다.
  • Cron 작업은 cron 런타임이 여전히 해당 작업을 소유하는지 확인합니다.
  • 채팅 기반 CLI 작업은 채팅 세션 행만이 아니라 소유하는 활성 실행 컨텍스트를 확인합니다.
완료 cleanup도 런타임 인식 방식으로 처리됩니다.
  • 하위 에이전트 완료는 알림 cleanup이 계속되기 전에 하위 세션의 추적된 브라우저 탭/프로세스를 best-effort로 닫습니다.
  • 격리된 cron 완료는 실행이 완전히 종료되기 전에 cron 세션의 추적된 브라우저 탭/프로세스를 best-effort로 닫습니다.
  • 격리된 cron 전달은 필요할 때 하위 하위 에이전트 후속 작업이 끝날 때까지 기다리고, 이를 알리는 대신 오래된 부모 확인 텍스트를 억제합니다.
  • 하위 에이전트 완료 전달은 가장 최신의 표시 가능한 assistant 텍스트를 우선하며, 이것이 비어 있으면 정리된 최신 tool/toolResult 텍스트로 대체하고, 타임아웃만 발생한 tool-call 실행은 짧은 부분 진행 요약으로 축약될 수 있습니다.
  • Cleanup 실패가 실제 작업 결과를 가리지는 않습니다.

​
tasks flow list|show|cancel

openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
개별 백그라운드 작업 기록 하나보다 이를 오케스트레이션하는 Task Flow 자체가 더 중요할 때 사용하세요.

​
채팅 작업 보드(/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 도구는 모두 cleanup 인식 작업 스냅샷을 사용합니다. 활성 작업이 우선되고, 오래된 완료 행은 숨겨지며, 최근 실패는 활성 작업이 남아 있지 않을 때만 표시됩니다. 이렇게 하면 상태 카드가 지금 중요한 내용에 집중됩니다.

​
저장소 및 유지 관리

​
작업이 저장되는 위치

작업 기록은 다음 SQLite 위치에 유지됩니다. 
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
레지스트리는 게이트웨이 시작 시 메모리에 로드되며, 재시작 간 내구성을 위해 쓰기 내용을 SQLite에 동기화합니다.

​
자동 유지 관리

스위퍼는 60초마다 실행되며 세 가지를 처리합니다.
  1. 조정 — 활성 작업이 여전히 권한 있는 런타임 백킹을 가지고 있는지 확인합니다. ACP/하위 에이전트 작업은 하위 세션 상태를 사용하고, cron 작업은 활성 작업 소유권을 사용하며, 채팅 기반 CLI 작업은 소유하는 실행 컨텍스트를 사용합니다. 이 백킹 상태가 5분 이상 사라져 있으면 작업은 lost로 표시됩니다.
  2. Cleanup 스탬프 처리 — 종료 작업에 cleanupAfter 타임스탬프를 설정합니다(endedAt + 7 days).
  3. 정리 — cleanupAfter 날짜가 지난 기록을 삭제합니다.
보존 기간: 종료된 작업 기록은 7일 동안 유지된 후 자동으로 정리됩니다. 별도의 구성은 필요하지 않습니다.

​
작업이 다른 시스템과 어떤 관련이 있는가

​
작업과 Task Flow

Task Flow는 백그라운드 작업 위에 있는 플로우 오케스트레이션 계층입니다. 단일 플로우는 관리형 또는 미러링된 동기화 모드를 사용해 수명 주기 동안 여러 작업을 조정할 수 있습니다. 개별 작업 기록을 검사하려면 openclaw tasks를, 오케스트레이션 플로우를 검사하려면 openclaw tasks flow를 사용하세요. 자세한 내용은 Task Flow를 참조하세요.

​
작업과 cron

Cron 작업 정의는 ~/.openclaw/cron/jobs.json에 있습니다. 모든 cron 실행은 작업 기록을 생성합니다 — 메인 세션과 격리형 모두 포함됩니다. 메인 세션 cron 작업은 기본적으로 silent 알림 정책을 사용하므로 알림을 생성하지 않고 추적만 합니다. Scheduled Tasks를 참조하세요.

​
작업과 heartbeat

Heartbeat 실행은 메인 세션 턴입니다 — 작업 기록을 생성하지 않습니다. 작업이 완료되면 heartbeat 깨우기를 트리거해 결과를 빠르게 확인할 수 있습니다. Heartbeat를 참조하세요.

​
작업과 세션

작업은 childSessionKey(작업이 실행되는 곳)와 requesterSessionKey(누가 시작했는지)를 참조할 수 있습니다. 세션은 대화 컨텍스트이고, 작업은 그 위에서 활동을 추적합니다.

​
작업과 에이전트 실행

작업의 runId는 작업을 수행하는 에이전트 실행과 연결됩니다. 에이전트 수명 주기 이벤트(시작, 종료, 오류)는 작업 상태를 자동으로 업데이트합니다 — 수명 주기를 수동으로 관리할 필요가 없습니다.

​
관련 항목