> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openclaw.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 크론 vs 하트비트

# 크론 vs 하트비트: 각 방법의 사용 시기

하트비트와 크론 작업 모두 스케줄에 따라 작업을 실행할 수 있습니다. 이 가이드는 사용 사례에 맞는 올바른 메커니즘을 선택하는 데 도움을 줍니다.

## 빠른 결정 가이드

| 사용 사례                | 추천 방법           | 이유                     |
| -------------------- | --------------- | ---------------------- |
| 인박스를 30분마다 확인        | 하트비트            | 다른 체크와 함께 일괄 처리, 상황 인식 |
| 매일 오전 9시에 일간 보고서 전송  | 크론 (격리된)        | 정확한 시간 필요              |
| 예정된 이벤트에 대한 캘린더 모니터링 | 하트비트            | 주기적인 인식을 위한 자연스러운 적합   |
| 매주 심층 분석 실행          | 크론 (격리된)        | 독립적인 작업이며, 다른 모델 사용 가능 |
| 20분 후 알림 설정          | 크론 (메인, `--at`) | 정확한 타이밍으로 일회성 실행       |
| 배경 프로젝트 상태 체크        | 하트비트            | 기존 사이클에 합류             |

## 하트비트: 주기적인 인식

하트비트는 **메인 세션**에서 일정 간격(기본값: 30분)으로 실행됩니다. 이것은 에이전트가 중요한 것을 확인하고 드러내도록 설계되었습니다.

### 하트비트를 사용할 때

* **여러 주기적 체크**: 인박스, 캘린더, 날씨, 알림, 프로젝트 상태를 확인하기 위해 별도의 5개 크론 작업 대신 하나의 하트비트로 일괄 처리할 수 있습니다.
* **상황에 따라 인식하는 결정**: 에이전트는 메인 세션의 전체 상황을 알고 있어 어떤 것이 긴급한지와 어떤 것이 기다릴 수 있는지를 스마트하게 결정할 수 있습니다.
* **대화의 연속성**: 하트비트 실행은 동일한 세션을 공유하므로 에이전트는 최근 대화를 기억하고 자연스럽게 후속 조치를 취할 수 있습니다.
* **낮은 오버헤드 모니터링**: 하나의 하트비트가 많은 작은 폴링 작업을 대체합니다.

### 하트비트의 장점

* **여러 체크를 일괄 처리**: 하나의 에이전트 턴이 인박스, 캘린더, 알림을 함께 확인할 수 있습니다.
* **API 호출 감소**: 단일 하트비트가 5개의 독립적인 크론 작업보다 비용이 적습니다.
* **상황 인식**: 에이전트는 사용자가 작업하고 있는 내용을 알고 이를 우선순위에 맞게 조정할 수 있습니다.
* **스마트 억제**: 주의가 필요하지 않으면 에이전트는 `HEARTBEAT_OK`를 반환하며 메시지가 전달되지 않습니다.
* **자연스러운 타이밍**: 대기열 부하에 따라 약간 변동되는데, 이는 대부분의 모니터링에 적합합니다.

### 하트비트 예시: HEARTBEAT.md 체크리스트

```md theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 하트비트 체크리스트

- 긴급 메시지가 있는 이메일 확인
- 향후 2시간 내 이벤트 확인
- 백그라운드 작업이 완료된 경우 결과 요약
- 8시간 이상 대기 상태일 경우 간단한 체크인 전송
```

에이전트는 각 하트비트에서 이를 읽고 모든 항목을 한 번에 처리합니다.

### 하트비트 설정

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 간격
        target: "last", // 명시적 경고 전달 대상 (기본값: "none")
        activeHours: { start: "08:00", end: "22:00" }, // 선택 사항
      },
    },
  },
}
```

전체 설정은 [Heartbeat](/gateway/heartbeat)를 참조하세요.

## 크론: 정확한 스케줄링

크론 작업은 정확한 시간에 실행되며, 메인 컨텍스트에 영향을 미치지 않고 독립된 세션에서 실행될 수 있습니다.
시간 정해진 스케줄은 0-5분 창의 결정적 오프셋에 의해 자동으로 분산됩니다.

### 크론을 사용할 때

* **정확한 타이밍이 필요한 경우**: "매주 월요일 오전 9:00에 보내기" (약 9시가 아닌 정확히).
* **독립적인 작업**: 대화 문맥이 필요 없는 작업.
* **다른 모델/생각**: 더 강력한 모델이 필요한 무거운 분석.
* **일회성 알림**: `--at`과 함께 "20분 후 알림".
* **소음/빈도 높은 작업**: 메인 세션 기록을 어지럽힐 만한 작업.
* **외부 트리거**: 에이전트 상태와 관계없이 독립적으로 실행되어야 하는 작업.

### 크론의 장점

* **정확한 타이밍**: 5필드 또는 6필드(초 단위) 크론 표현식과 시간대 지원.
* **내장 로드 분산**: 시간을 정한 스케줄은 기본적으로 최대 5분까지 분산됩니다.
* **작업 별 제어**: `--stagger <duration>`으로 분산을 덮어쓰거나 `--exact`으로 정확한 타이밍 강제 가능.
* **세션 격리**: `cron:<jobId>`에서 실행되어 메인 기록 오염을 방지.
* **모델 덮어쓰기**: 작업마다 더 저렴하거나 강력한 모델 사용 가능.
* **전달 제어**: 격리된 작업은 기본적으로 `announce`(요약)이며, 필요에 따라 `none` 선택 가능.
* **즉시 전달**: 알림 모드는 하트비트를 기다리지 않고 직접 게시.
* **에이전트 문맥 불필요**: 메인 세션이 비어 있거나 압축되었어도 실행 가능.
* **일회성 지원**: 미래의 정확한 타임스탬프를 위한 `--at`.

### 크론 예시: 매일 아침 브리핑

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw cron add \
  --name "아침 브리핑" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "오늘의 브리핑 생성: 날씨, 캘린더, 중요한 이메일, 뉴스 요약." \
  --model opus \
  --announce \
  --channel whatsapp \
  --to "+15551234567"
```

이 작업은 뉴욕 시간으로 정확히 오전 7시에 실행되며, Opus 모델을 사용해 품질을 보장하고, 요약을 WhatsApp에 직접 발표합니다.

### 크론 예시: 일회성 알림

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw cron add \
  --name "회의 알림" \
  --at "20m" \
  --session main \
  --system-event "알림: 스탠드업 미팅이 10분 후 시작합니다." \
  --wake now \
  --delete-after-run
```

전체 CLI 참조는 [Cron jobs](/automation/cron-jobs)를 참조하세요.

## 결정 흐름도

```
작업이 정확한 시간에 실행되어야 합니까?
  예 -> 크론 사용
  아니요  -> 계속...

작업이 메인 세션에서 격리되어야 합니까?
  예 -> 크론 사용 (격리된)
  아니요  -> 계속...

이 작업을 다른 주기적 체크와 함께 일괄 처리할 수 있습니까?
  예 -> 하트비트 사용 (HEARTBEAT.md에 추가)
  아니요  -> 크론 사용

일회성 알림입니까?
  예 -> --at과 함께 크론 사용
  아니요  -> 계속...

다른 모델 또는 사고 레벨이 필요합니까?
  예 -> --model/--thinking과 함께 크론 (격리된) 사용
  아니요  -> 하트비트 사용
```

## 둘 다 결합하기

가장 효율적인 설정은 **둘 다 사용하는 것**입니다:

1. **하트비트**는 30분마다 한 번씩 일괄적으로 (인박스, 캘린더, 알림) 루틴 모니터링을 처리합니다.
2. **크론**은 정확한 일정 (일일 보고, 주간 검토)과 일회성 알림을 처리합니다.

### 예시: 효율적인 자동화 설정

**HEARTBEAT.md** (매 30분마다 확인):

```md theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 하트비트 체크리스트

- 긴급 이메일 확인
- 향후 2시간 내의 캘린더 이벤트 확인
- 대기 중인 작업 검토
- 8시간 이상 조용한 경우 간단한 체크인
```

**크론 작업** (정확한 타이밍):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 매일 아침 브리핑 오전 7시
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# 매주 월요일 오전 9시에 프로젝트 리뷰
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# 일회성 알림
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now
```

## Lobster: 승인과 함께 결정적 워크플로우

Lobster는 **다단계 도구 파이프라인**을 위한 워크플로우 런타임으로, 결정적인 실행과 명확한 승인이 필요합니다.
에이전트 턴 이상의 작업이고, 대화 가능한 워크플로우가 필요할 때 사용하세요.

### Lobster가 적합할 때

* **다단계 자동화**: 일회성 프롬프트가 아닌 고정 파이프라인에서 도구 호출이 필요할 때.
* **승인 관문**: 부작용이 승인될 때까지 일시 정지하고, 그 후에 다시 실행.
* **재개 가능한 실행**: 이전 단계의 재실행 없이 일시 중단된 워크플로우 지속.

### 하트비트 및 크론과의 연계

* **하트비트/크론**은 실행 시점을 결정합니다.
* **Lobster**는 실행이 시작되면 발생할 단계들을 정의합니다.

일정한 워크플로우에는 하트비트나 크론을 사용하여 에이전트 턴을 트리거하고 Lobster를 호출합니다.
즉석 워크플로우는 Lobster를 직접 호출하세요.

### 코드에서 가져온 운영 노트

* Lobster는 **로컬 서브프로세스**(`lobster` CLI)로 도구 모드에서 실행되며 **JSON 봉투**를 반환합니다.
* 도구가 `needs_approval`를 반환하면, `resumeToken`과 `approve` 플래그로 재개합니다.
* 도구는 **옵션 플러그인**으로, `tools.alsoAllow: ["lobster"]`를 통해 추가적으로 사용할 수 있습니다(권장).
* `lobsterPath`를 전달할 경우, **절대 경로**여야 합니다.

전체 사용법과 예시는 [Lobster](/tools/lobster)를 참조하세요.

## 메인 세션 vs 격리된 세션

하트비트와 크론 모두 메인 세션과 상호 작용할 수 있지만, 서로 다르게 작동합니다:

|    | 하트비트                   | 크론 (메인)         | 크론 (격리된)                               |
| -- | ---------------------- | --------------- | -------------------------------------- |
| 세션 | 메인                     | 메인 (시스템 이벤트로)   | `cron:<jobId>` 또는 사용자 지정 세션            |
| 기록 | 공유                     | 공유              | 매 실행마다 새로 생성 (isolated) / 유지됨 (custom) |
| 문맥 | 전체                     | 전체              | 없음 (isolated) / 누적됨 (custom)           |
| 모델 | 메인 세션 모델               | 메인 세션 모델        | 덮어쓰기 가능                                |
| 출력 | `HEARTBEAT_OK` 아닐 시 전달 | 하트비트 프롬프트 + 이벤트 | 알림 요약 (기본값)                            |

### 메인 세션 크론을 사용할 때

`--session main`과 `--system-event`를 사용할 때 다음과 같은 경우가 있습니다:

* 메인 세션 문맥에 나타날 알림/이벤트가 필요한 경우
* 에이전트가 전체 문맥을 가지고 다음 하트비트 중 다루기를 원하는 경우
* 별도 격리 실행이 필요 없는 경우

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw cron add \
  --name "프로젝트 체크" \
  --every "4h" \
  --session main \
  --system-event "프로젝트 상태 점검 시간입니다" \
  --wake now
```

### 격리된 크론을 사용할 때

`--session isolated`를 사용할 때 다음과 같은 경우가 있습니다:

* 이전 컨텍스트 없이 깨끗한 시작을 원하는 경우
* 다른 모델이나 사고 설정이 필요한 경우
* 알림 요약을 채널에 직접 발표하는 경우
* 메인 세션을 어지럽히지 않는 기록을 원하는 경우

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw cron add \
  --name "심층 분석" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "주간 코드베이스 분석..." \
  --model opus \
  --thinking high \
  --announce
```

## 비용 고려 사항

| 메커니즘     | 비용 프로파일                          |
| -------- | -------------------------------- |
| 하트비트     | N분마다 한 턴; HEARTBEAT.md 크기에 따라 확장 |
| 크론 (메인)  | 다음 하트비트에 이벤트 추가 (격리 턴 없음)        |
| 크론 (격리된) | 작업 당 전체 에이전트 턴; 더 저렴한 모델 사용 가능   |

**팁**:

* `HEARTBEAT.md`를 작게 유지하여 토큰 오버헤드를 최소화하세요.
* 비슷한 체크를 하트비트에 일괄 처리하여 여러 크론 작업 대신 사용하세요.
* 내부 처리만 원하는 경우 하트비트에 `target: "none"`을 사용하세요.
* 일상 작업에 대해서는 더 저렴한 모델의 격리된 크론을 사용하세요.

## 관련 자료

* [Heartbeat](/gateway/heartbeat) - 전체 하트비트 설정
* [Cron jobs](/automation/cron-jobs) - 전체 크론 CLI 및 API 참조
* [System](/cli/system) - 시스템 이벤트 + 하트비트 제어설정