작업 흐름

Task Flow는 백그라운드 작업 위에 있는 오케스트레이션 계층입니다. 흐름은 자체 상태, JSON 상태 데이터, 리비전 카운터 및 연결된 작업 레코드를 갖는 다단계 작업의 영구 레코드입니다. 흐름은 Gateway 재시작 후에도 유지되며, 개별 작업은 분리 실행되는 작업의 단위로 남습니다.

Task Flow를 사용해야 하는 경우

동기화 모드

관리형 모드

관리형 흐름에는 컨트롤러가 있습니다. Plugin 코드는 목표와 필수 컨트롤러 ID를 사용하여 Plugin 런타임 Task Flow API를 통해 흐름을 생성한 다음, 이를 명시적으로 구동합니다.

• 각 단계는 흐름 아래에 생성된 백그라운드 작업으로 실행되며, 흐름의 소유자 키와 요청자 출처가 하위 작업에 승계됩니다.
• 컨트롤러는 흐름을 running, waiting 및 종료 상태 사이에서 진행시키고, 흐름 레코드에 임의의 JSON 단계 상태를 저장합니다.
• 모든 변경에는 흐름의 예상 리비전이 전달됩니다. 오래된 쓰기는 최신 상태를 덮어쓰는 대신 리비전 충돌로 거부됩니다.
• 취소가 요청되면 새로운 하위 작업이 거부되며, 활성 상태인 하위 작업이 남아 있지 않을 때 흐름은 cancelled로 종료됩니다.

예: (1) 데이터를 수집하고, (2) 보고서를 생성하며, (3) 전달하는 주간 보고서 흐름으로, 단계마다 하나의 백그라운드 작업을 사용합니다.

흐름: weekly-report  1단계: gather-data     → 작업 생성됨 → 성공  2단계: generate-report → 작업 생성됨 → 성공  3단계: deliver         → 작업 생성됨 → 실행 중

미러링형 모드

분리 실행되는 ACP 또는 하위 에이전트 실행이 시작되면 OpenClaw는 미러링된 단일 작업 흐름을 자동으로 생성합니다(전달 가능한 완료 결과가 있는 세션 범위 작업). 흐름 레코드는 단일 기반 작업의 상태, 목표 및 타이밍을 미러링하므로, 분리 실행되는 생성 작업은 컨트롤러 없이도 상태 확인 및 재시도 화면에서 사용할 수 있는 안정적인 흐름 핸들을 갖습니다. 미러링된 흐름은 CLI에서 동기화 모드가 task_mirrored로 표시됩니다.

흐름 상태

영구 상태 및 리비전 추적

흐름 레코드는 작업 레코드와 함께 공유 SQLite 상태 데이터베이스(~/.openclaw/state/openclaw.sqlite, flow_runs 테이블)에 영구 저장되므로 Gateway 재시작 후에도 진행 상황이 유지됩니다. 쓰기마다 흐름의 revision이 증가합니다. 오래된 예상 리비전을 전달한 동시 작성자는 충돌을 받고 다시 읽어야 합니다. WAL 증가는 SQLite 자동 체크포인트와 주기적인 수동형 체크포인트로 제한되며, 종료 시에는 잘라내기 체크포인트가 수행됩니다. 이전 설치에서 사용된 레거시 flows/registry.sqlite 사이드카는 openclaw doctor가 가져옵니다.

취소 동작

openclaw tasks flow cancel은 흐름에 지속적인 취소 의도를 설정하고, 활성 하위 작업을 취소하며, 새로운 관리형 하위 작업을 거부합니다. 활성 상태인 하위 작업이 남아 있지 않으면 흐름은 즉시 cancelled로 종료되며, 하위 작업의 종료에 시간이 더 걸리는 경우 유지관리 정리 작업을 통해 종료됩니다. 이 의도는 영구 저장되므로, 모든 하위 작업이 종료되기 전에 Gateway가 재시작되더라도 취소된 흐름은 취소 상태로 유지됩니다.

CLI 명령

# 활성 및 최근 흐름 나열openclaw tasks flow list [--status <status>] [--json] # 특정 흐름의 세부 정보 표시openclaw tasks flow show <lookup> [--json] # 실행 중인 흐름과 활성 작업 취소openclaw tasks flow cancel <lookup>

흐름은 openclaw tasks audit(오래되거나 손상된 흐름 발견) 및 openclaw tasks maintenance(중단된 취소를 완료하고 7일 후 종료된 흐름을 정리)에서도 다뤄집니다.

신뢰할 수 있는 예약 워크플로 패턴

시장 정보 브리핑과 같은 반복 워크플로에서는 일정, 오케스트레이션 및 신뢰성 검사를 별도의 계층으로 취급합니다.

1. 실행 시점에는 예약 작업을 사용합니다.
2. 워크플로가 이전 컨텍스트를 기반으로 계속 진행되어야 한다면 영구 Cron 세션을 사용합니다.
3. 결정론적 단계, 승인 게이트 및 재개 토큰에는 Lobster를 사용합니다.
4. 하위 작업, 대기, 재시도 및 Gateway 재시작에 걸친 다단계 실행을 추적하려면 Task Flow를 사용합니다.

Cron 구성 예시:

openclaw cron add \  --name "Market intelligence brief" \  --cron "0 7 * * 1-5" \  --tz "America/New_York" \  --session session:market-intel \  --message "Run the market-intel Lobster workflow. Verify source freshness before summarizing." \  --announce \  --channel slack \  --to "channel:C1234567890"

반복 워크플로에 의도적으로 유지되는 기록, 이전 실행 요약 또는 상시 컨텍스트가 필요하다면 isolated 대신 --session session:<id>를 사용합니다. 각 실행을 새로 시작해야 하고 필요한 모든 상태가 워크플로에 명시되어 있다면 isolated를 사용합니다.

워크플로 내부에서는 LLM 요약 단계 전에 신뢰성 검사를 배치합니다.

name: market-intel-briefsteps:  - id: preflight    command: market-intel check --json  - id: collect    command: market-intel collect --json    stdin: $preflight.json  - id: summarize    command: market-intel summarize --json    stdin: $collect.json  - id: approve    command: market-intel deliver --preview    stdin: $summarize.json    approval: required  - id: deliver    command: market-intel deliver --execute    stdin: $summarize.json    condition: $approve.approved

권장 사전 검사:

• 브라우저 사용 가능 여부와 프로필 선택. 예를 들어 관리형 상태에는 openclaw, 로그인된 Chrome 세션이 필요할 때는 user를 사용합니다. 브라우저를 참조하세요.
• 각 소스의 API 자격 증명 및 할당량.
• 필수 엔드포인트에 대한 네트워크 연결 가능 여부.
• lobster, browser, llm-task 등 에이전트에 필요한 도구가 활성화되어 있는지 여부.
• 사전 검사 실패를 확인할 수 있도록 Cron의 실패 대상이 구성되어 있는지 여부. 예약 작업을 참조하세요.

수집된 모든 항목에 권장되는 데이터 출처 필드:

{  "sourceUrl": "https://example.com/report",  "retrievedAt": "2026-04-24T12:00:00Z",  "asOf": "2026-04-24",  "title": "Example report",  "content": "..."}

워크플로가 요약 전에 오래된 항목을 거부하거나 오래된 것으로 표시하도록 합니다. LLM 단계에는 구조화된 JSON만 전달해야 하며, 출력에서 sourceUrl, retrievedAt 및 asOf를 유지하도록 요청해야 합니다. 워크플로 내부에 스키마 검증을 거친 모델 단계가 필요하면 LLM 작업을 사용합니다.

팀이나 커뮤니티에서 재사용할 수 있는 워크플로의 경우 CLI, .lobster 파일 및 모든 설정 참고 사항을 Skills 또는 Plugin으로 패키징하고 ClawHub를 통해 게시합니다. Plugin API에 필요한 범용 기능이 없는 경우가 아니라면 워크플로별 보호 장치는 해당 패키지에 유지합니다.

흐름과 작업의 관계

흐름은 작업을 대체하는 것이 아니라 조정합니다. 하나의 흐름은 수명 주기 동안 여러 백그라운드 작업을 구동할 수 있습니다. 개별 작업 레코드를 검사하려면 openclaw tasks를 사용하고, 오케스트레이션 흐름을 검사하려면 openclaw tasks flow를 사용합니다.

관련 문서

• 백그라운드 작업 - 흐름이 조정하는 분리 실행 작업 원장
• CLI: 작업 - openclaw tasks flow의 CLI 명령 참고 문서
• 자동화 개요 - 모든 자동화 메커니즘을 한눈에 확인
• Cron 작업 - 흐름에 입력될 수 있는 예약 작업