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

# 능동적 에이전트 패턴

> AI가 먼저 행동하는 패턴 설계하기

좋은 AI 비서는 **물어보기 전에 알려줍니다**.
OpenClaw에서 능동적 행동을 설계하는 핵심 패턴들을 알아봅시다.

## 하트비트 체크리스트 패턴

가장 기본적인 패턴입니다. HEARTBEAT.md에 체크리스트를 작성하면
AI가 30분마다 깨어나서 순회합니다.

```markdown theme={null}
# HEARTBEAT.md

## 순회 체크 (하루 2-4회, 돌아가며)
- [ ] 이메일 - 긴급 메일 있나?
- [ ] 캘린더 - 24시간 내 일정?
- [ ] 날씨 - 급변 예보?
- [ ] GitHub - 중요 PR/이슈?

## 판단 기준
- 긴급: 즉시 알림
- 참고: 다음 대화 때 언급
- 무관: HEARTBEAT_OK
```

### 상태 추적: heartbeat-state.json

```json theme={null}
{
  "lastChecks": {
    "email": 1707620400,
    "calendar": 1707616800,
    "weather": 1707606000,
    "github": null
  },
  "lastNotification": 1707620400
}
```

AI는 이 파일을 읽어서 **가장 오래된 항목부터** 체크합니다.
매번 모든 걸 확인하지 않아 토큰을 절약합니다.

<Tip>
  체크 항목이 많으면 `heartbeat-state.json`으로 라운드 로빈 순회하세요.
  매 하트비트마다 1-2개만 확인하면 비용이 크게 줄어듭니다.
</Tip>

## 이메일 순회 패턴

```markdown theme={null}
# HEARTBEAT.md 이메일 섹션

## 이메일 체크
- 마지막 체크 이후 새 메일 확인
- 긴급도 판단:
  - 🔴 상사/중요인물 → 즉시 알림
  - 🟡 프로젝트 관련 → 요약해서 다음 대화 때
  - ⚪ 뉴스레터/프로모션 → 무시
```

AI가 이메일 스킬로 실제 확인하는 흐름:

```
[하트비트 발동]
→ HEARTBEAT.md 읽기
→ heartbeat-state.json에서 email 마지막 체크 확인
→ 2시간 이상 경과 → 이메일 체크 실행
→ 새 메일 3통 발견
→ 1통 긴급 (상사) → 사용자에게 알림
→ 2통 일반 → memory에 기록
→ heartbeat-state.json 업데이트
```

## 캘린더 순회 패턴

```markdown theme={null}
# HEARTBEAT.md 캘린더 섹션

## 캘린더 체크
- 향후 2시간 내 일정 → 알림
- 내일 일정 → 저녁 브리핑에 포함
- 일정 변경 감지 → 즉시 알림
```

<Steps>
  <Step title="일정 확인">
    AI가 캘린더 API로 다가오는 일정을 조회합니다
  </Step>

  <Step title="시간 계산">
    현재 시간 기준으로 얼마나 남았는지 판단합니다
  </Step>

  <Step title="알림 결정">
    2시간 이내면 알림, 아니면 기록만 합니다
  </Step>

  <Step title="준비 사항">
    회의라면 관련 문서나 이전 회의록을 미리 찾아둡니다
  </Step>
</Steps>

## 날씨 순회 패턴

```markdown theme={null}
# HEARTBEAT.md 날씨 섹션

## 날씨 체크 (하루 1-2회)
- 급격한 기온 변화 예보?
- 비/눈 예보? → 외출 계획 있으면 알림
- 미세먼지 나쁨? → 환기 주의
```

## 복합 패턴: 컨텍스트 기반 판단

진짜 능동적 에이전트는 여러 정보를 **조합해서 판단**합니다:

```markdown theme={null}
# HEARTBEAT.md

## 스마트 알림 규칙
1. 캘린더에 외출 일정 + 비 예보 → "우산 챙기세요"
2. 중요 회의 1시간 전 + 관련 이메일 → 브리핑 + 메일 요약
3. 8시간 이상 무소식 + 긴급 메일 → 알림
4. 주말 + 특별한 일 없음 → HEARTBEAT_OK
```

<Info>
  복합 판단이 능동적 에이전트의 핵심입니다.
  단순 체크 나열이 아니라, "상황을 읽고 판단하라"는 지시를 주세요.
</Info>

## 크론 + 하트비트 조합

```bash theme={null}
# 정확한 시간이 필요한 것 → 크론
openclaw cron add --name "morning-briefing" \
  --cron "0 7 * * *" --tz "Asia/Seoul" \
  --message "모닝 브리핑 해줘" --announce

# 주기적 순회 → 하트비트
# HEARTBEAT.md에 체크리스트로 관리
```

<CardGroup cols={2}>
  <Card title="하트비트가 적합" icon="heart-pulse">
    * 여러 체크를 묶을 때
    * 대화 맥락이 필요할 때
    * 약간의 타이밍 편차 OK
    * 비용 절약
  </Card>

  <Card title="크론이 적합" icon="clock">
    * 정확한 시간 필요
    * 독립된 세션 필요
    * 다른 모델 사용
    * 결과를 채널로 직접 전달
  </Card>
</CardGroup>

## 안티패턴: 피해야 할 것들

<Warning>
  **과도한 알림:** 모든 이메일을 알리면 알림 피로가 옵니다. 긴급도 필터를 반드시 설정하세요.

  **너무 짧은 간격:** 5분 간격 하트비트는 비용만 늘립니다. 30분이면 충분합니다.

  **모호한 지시:** "필요하면 알려줘"보다 "상사 이메일이면 즉시, 나머지는 무시"가 좋습니다.
</Warning>