Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
일정 예약을 찾고 있나요? 적절한 메커니즘을 선택하려면 Automation을 참고하세요. 이 페이지는 스케줄러가 아니라 백그라운드 작업의 활동 원장입니다.
모든 에이전트 실행이 작업을 생성하지는 않습니다. Heartbeat 턴과 일반 대화형 채팅은 생성하지 않습니다. 모든 cron 실행, ACP 생성, 하위 에이전트 생성, CLI 에이전트 명령은 생성합니다.
요약
- 작업은 스케줄러가 아니라 기록입니다. 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일 동안 보관된 뒤 자동으로 정리됩니다.
빠른 시작
- 목록 및 필터
- 검사
- 취소 및 알림
- 감사 및 유지 관리
- TaskFlow
작업을 생성하는 항목
| 소스 | 런타임 유형 | 작업 기록이 생성되는 시점 | 기본 알림 정책 |
|---|---|---|---|
| ACP 백그라운드 실행 | acp | 자식 ACP 세션 생성 | done_only |
| 하위 에이전트 오케스트레이션 | subagent | sessions_spawn을 통해 하위 에이전트 생성 | done_only |
| Cron 작업(모든 유형) | cron | 모든 cron 실행(기본 세션 및 격리) | silent |
| CLI 작업 | cli | Gateway를 통해 실행되는 openclaw agent 명령 | silent |
| 에이전트 미디어 작업 | cli | 세션 기반 music_generate/video_generate 실행 | silent |
cron 및 미디어의 알림 기본값
cron 및 미디어의 알림 기본값
기본 세션 cron 작업은 기본적으로
silent 알림 정책을 사용합니다. 추적을 위한 기록은 생성하지만 알림은 생성하지 않습니다. 격리된 cron 작업도 기본값은 silent이지만 자체 세션에서 실행되므로 더 잘 보입니다.세션 기반 music_generate 및 video_generate 실행도 silent 알림 정책을 사용합니다. 이 실행은 여전히 작업 기록을 생성하지만, 완료는 내부 깨우기로 원래 에이전트 세션에 반환되어 에이전트가 후속 메시지를 작성하고 완성된 미디어를 직접 첨부할 수 있게 합니다. 그룹/채널 완료는 일반적인 표시 응답 정책을 따르므로, 소스 전달에 필요할 때 에이전트는 메시지 도구를 사용합니다. 완료 에이전트가 도구 전용 경로에서 메시지 도구 전달 증거를 생성하지 못하면, OpenClaw는 미디어를 비공개로 남겨두는 대신 완료 대체 메시지를 원래 채널로 직접 보냅니다.동시 video_generate 보호 장치
동시 video_generate 보호 장치
세션 기반
video_generate 작업이 아직 활성 상태인 동안에는 해당 도구도 보호 장치로 작동합니다. 같은 세션에서 video_generate를 반복 호출하면 두 번째 동시 생성을 시작하지 않고 활성 작업 상태를 반환합니다. 에이전트 측에서 명시적인 진행/상태 조회를 원할 때는 action: "status"를 사용하세요.작업을 생성하지 않는 항목
작업을 생성하지 않는 항목
- Heartbeat 턴 - 기본 세션. Heartbeat를 참고하세요.
- 일반 대화형 채팅 턴
- 직접
/command응답
작업 수명 주기
| 상태 | 의미 |
|---|---|
queued | 생성되었으며 에이전트 시작을 기다리는 중 |
running | 에이전트 턴이 활발히 실행 중 |
succeeded | 성공적으로 완료됨 |
failed | 오류와 함께 완료됨 |
timed_out | 구성된 제한 시간을 초과함 |
cancelled | 운영자가 openclaw tasks cancel로 중지함 |
lost | 5분의 유예 기간 후 런타임이 권한 있는 백업 상태를 잃음 |
succeeded로 최종화되고, 일반 실행 오류는 failed로 최종화되며, 시간 초과 또는 중단 결과는 timed_out으로 최종화됩니다. 운영자가 이미 작업을 취소했거나 런타임이 이미 failed, timed_out, lost 같은 더 강한 터미널 상태를 기록한 경우, 이후의 성공 신호는 해당 터미널 상태를 낮추지 않습니다.
lost는 런타임을 인식합니다:
- ACP 작업: 백업 ACP 자식 세션 메타데이터가 사라졌습니다.
- 하위 에이전트 작업: 백업 자식 세션이 대상 에이전트 저장소에서 사라졌습니다.
- Cron 작업: cron 런타임이 더 이상 작업을 활성 상태로 추적하지 않고, 영구 cron 실행 기록에 해당 실행의 터미널 결과가 표시되지 않습니다. 오프라인 CLI 감사는 자체의 빈 인프로세스 cron 런타임 상태를 권한으로 간주하지 않습니다.
- CLI 작업: 실행 id/source id가 있는 작업은 라이브 실행 컨텍스트를 사용하므로, Gateway가 소유한 실행이 사라진 뒤에도 남아 있는 자식 세션 또는 채팅 세션 행이 작업을 활성 상태로 유지하지 않습니다. 실행 ID가 없는 레거시 CLI 작업은 여전히 자식 세션으로 대체합니다. Gateway 기반
openclaw agent실행도 실행 결과에서 최종화되므로, 완료된 실행이 스위퍼가lost로 표시할 때까지 활성 상태로 남아 있지 않습니다.
전달 및 알림
작업이 터미널 상태에 도달하면 OpenClaw가 알립니다. 전달 경로는 두 가지입니다: 직접 전달 - 작업에 채널 대상(requesterOrigin)이 있으면 완료 메시지가 해당 채널(Telegram, Discord, Slack 등)로 바로 전달됩니다. 그룹 및 채널 작업 완료는 대신 요청자 세션을 통해 라우팅되어 부모 에이전트가 표시되는 응답을 작성할 수 있게 합니다. 하위 에이전트 완료의 경우, OpenClaw는 사용 가능할 때 바인딩된 스레드/토픽 라우팅도 보존하며, 직접 전달을 포기하기 전에 요청자 세션에 저장된 경로(lastChannel / lastTo / lastAccountId)에서 누락된 to / 계정을 채울 수 있습니다.
세션 대기열 전달 - 직접 전달이 실패하거나 origin이 설정되지 않은 경우, 업데이트는 요청자의 세션에 시스템 이벤트로 대기열에 추가되고 다음 Heartbeat에서 나타납니다.
즉, 일반적인 워크플로는 푸시 기반입니다. 분리된 작업을 한 번 시작한 뒤, 완료 시 런타임이 깨우거나 알리도록 두면 됩니다. 디버깅, 개입 또는 명시적인 감사가 필요할 때만 작업 상태를 폴링하세요.
알림 정책
각 작업에 대해 얼마나 들을지 제어합니다:| 정책 | 전달되는 내용 |
|---|---|
done_only (기본값) | 터미널 상태(성공, 실패 등)만 전달 - 이것이 기본값입니다 |
state_changes | 모든 상태 전환 및 진행 업데이트 |
silent | 아무것도 전달하지 않음 |
CLI 참조
tasks list
tasks list
tasks show
tasks show
tasks cancel
tasks cancel
cancelled로 전환되고, 해당하는 경우 전달 알림이 전송됩니다.tasks notify
tasks notify
tasks audit
tasks audit
openclaw status에도 나타납니다.| 발견 항목 | 심각도 | 트리거 |
|---|---|---|
stale_queued | warn | 10분 넘게 대기열에 있음 |
stale_running | error | 30분 넘게 실행 중 |
lost | warn/error | 런타임 기반 작업 소유권이 사라졌습니다. 유지된 손실 작업은 cleanupAfter까지 경고로 남았다가 이후 오류가 됩니다 |
delivery_failed | warn | 전달에 실패했고 알림 정책이 silent가 아님 |
missing_cleanup | warn | 정리 타임스탬프가 없는 종료 작업 |
inconsistent_timestamps | warn | 타임라인 위반(예: 시작 전에 종료됨) |
tasks maintenance
tasks maintenance
- ACP/서브에이전트 작업은 해당 백킹 자식 세션을 확인합니다.
- 자식 세션에 재시작 복구 툼스톤이 있는 서브에이전트 작업은 복구 가능한 백킹 세션으로 처리되는 대신 손실로 표시됩니다.
- Cron 작업은 Cron 런타임이 여전히 작업을 소유하는지 확인한 다음,
lost로 폴백하기 전에 영구 저장된 Cron 실행 로그/작업 상태에서 종료 상태를 복구합니다. 메모리 내 Cron 활성 작업 집합에 대해서는 Gateway 프로세스만 권한을 가집니다. 오프라인 CLI 감사는 내구성 있는 기록을 사용하지만, 로컬 Set이 비어 있다는 이유만으로 Cron 작업을 손실로 표시하지는 않습니다. - 실행 ID가 있는 CLI 작업은 자식 세션이나 채팅 세션 행만이 아니라 소유 중인 라이브 실행 컨텍스트를 확인합니다.
- 서브에이전트 완료는 알림 정리가 계속되기 전에 자식 세션에 대해 추적된 브라우저 탭/프로세스를 최선의 노력으로 닫습니다.
- 격리된 Cron 완료는 실행이 완전히 해제되기 전에 Cron 세션에 대해 추적된 브라우저 탭/프로세스를 최선의 노력으로 닫습니다.
- 격리된 Cron 전달은 필요할 때 하위 서브에이전트 후속 작업이 끝날 때까지 기다리며, 오래된 부모 확인 텍스트를 알리는 대신 억제합니다.
- 서브에이전트 완료 전달은 가장 최근에 표시된 어시스턴트 텍스트를 우선 사용합니다. 비어 있으면 정제된 최신 도구/toolResult 텍스트로 폴백하며, 시간 초과만 발생한 도구 호출 실행은 짧은 부분 진행 요약으로 축약될 수 있습니다. 종료된 실패 실행은 캡처된 응답 텍스트를 다시 재생하지 않고 실패 상태를 알립니다.
- 정리 실패는 실제 작업 결과를 가리지 않습니다.
cron:<jobId>:run:<uuid> 세션 레지스트리 행도 제거합니다.tasks flow list | show | cancel
tasks flow list | show | cancel
채팅 작업 보드(/tasks)
채팅 세션에서 해당 세션에 연결된 백그라운드 작업을 보려면 /tasks를 사용합니다. 보드에는 활성 작업과 최근 완료된 작업이 런타임, 상태, 시간 정보, 진행 상황 또는 오류 세부 정보와 함께 표시됩니다.
현재 세션에 표시 가능한 연결 작업이 없으면 /tasks는 다른 세션의 세부 정보를 누출하지 않고도 개요를 볼 수 있도록 에이전트 로컬 작업 수로 폴백합니다.
전체 운영자 원장은 CLI를 사용하세요: openclaw tasks list.
상태 통합(작업 압박)
openclaw status에는 한눈에 보는 작업 요약이 포함됩니다.
- 활성 -
queued+running개수 - 실패 -
failed+timed_out+lost개수 - 런타임별 -
acp,subagent,cron,cli별 분석
/status와 session_status 도구는 모두 정리 인식 작업 스냅샷을 사용합니다. 활성 작업이 우선 표시되고, 오래된 완료 행은 숨겨지며, 최근 실패는 활성 작업이 남아 있지 않을 때만 표시됩니다. 이렇게 하면 상태 카드가 지금 중요한 것에 집중됩니다.
저장소 및 유지 관리
작업이 저장되는 위치
작업 레코드는 SQLite에 다음 위치로 영구 저장됩니다.TRUNCATE 체크포인트를 사용하여 SQLite write-ahead log의 크기를 제한합니다.
자동 유지 관리
스위퍼는 60초마다 실행되며 네 가지를 처리합니다.조정
활성 작업에 여전히 권한 있는 런타임 백킹이 있는지 확인합니다. ACP/서브에이전트 작업은 자식 세션 상태를 사용하고, Cron 작업은 활성 작업 소유권을 사용하며, 실행 ID가 있는 CLI 작업은 소유 중인 실행 컨텍스트를 사용합니다. 해당 백킹 상태가 5분 넘게 사라져 있으면 작업이
lost로 표시됩니다.ACP 세션 복구
종료되었거나 고아가 된 부모 소유 일회성 ACP 세션을 닫고, 활성 대화 바인딩이 남아 있지 않을 때만 오래된 종료 상태 또는 고아 상태의 영구 ACP 세션을 닫습니다.
정리 스탬프 지정
종료 작업에
cleanupAfter 타임스탬프를 설정합니다(endedAt + 7일). 보존 기간 동안 손실 작업은 감사에서 계속 경고로 표시됩니다. cleanupAfter가 만료되거나 정리 메타데이터가 누락되면 오류가 됩니다.보존: 종료 작업 레코드는 7일 동안 보관된 뒤 자동으로 가지치기됩니다. 구성이 필요하지 않습니다.
작업과 다른 시스템의 관계
작업과 Task Flow
작업과 Task Flow
작업과 Cron
작업과 Cron
Cron 작업 정의는
~/.openclaw/cron/jobs.json에 있고, 런타임 실행 상태는 그 옆의 ~/.openclaw/cron/jobs-state.json에 있습니다. 모든 Cron 실행은 메인 세션과 격리 실행 모두에서 작업 레코드를 만듭니다. 메인 세션 Cron 작업은 기본적으로 silent 알림 정책을 사용하므로 알림을 생성하지 않고 추적됩니다.Cron 작업을 참조하세요.작업과 Heartbeat
작업과 Heartbeat
Heartbeat 실행은 메인 세션 턴이며 작업 레코드를 만들지 않습니다. 작업이 완료되면 Heartbeat 깨우기를 트리거하여 결과를 신속하게 볼 수 있습니다.Heartbeat를 참조하세요.
작업과 세션
작업과 세션
작업은
childSessionKey(작업이 실행되는 위치)와 requesterSessionKey(작업을 시작한 주체)를 참조할 수 있습니다. 세션은 대화 컨텍스트이고, 작업은 그 위의 활동 추적입니다.작업과 에이전트 실행
작업과 에이전트 실행
작업의
runId는 작업을 수행하는 에이전트 실행에 연결됩니다. 에이전트 수명 주기 이벤트(시작, 종료, 오류)는 작업 상태를 자동으로 업데이트합니다. 수명 주기를 수동으로 관리할 필요가 없습니다.