---
name: KRX 휴장일 데이터·운영
description: 한국 주식시장 휴장일은 investing.com에서 주 1회 받아 state/market_holidays.json에 저장. 사용자가 휴장일 물어보면 이 파일 읽어서 답하거나 holiday_sync.py --show 호출. 자동매매 시각 판정·웹뷰 토글 동작에도 사용된다.
type: reference
---
한국 주식시장(KRX/KOSDAQ) **휴장일 single source of truth**.

## 데이터 위치
- `~/.openclaw/agents/stock/workspace/state/market_holidays.json`
- 스키마: `{ "fetched_at", "source", "years": [int...], "holidays": { "YYYY-MM-DD": "휴장명", ... } }`
- 올해+내년이 한 파일에 합쳐짐 (12월 → 1월 갭 방지). 단 investing.com이 다음해 데이터를 늦게 공개해서 11~12월 사이엔 내년분이 비어있을 수 있음.

## 갱신
- launchd `ai.openclaw.stock.holiday-sync` — 매주 일요일 03:00 KST.
- 출처: `https://kr.investing.com/holiday-calendar/service/getCalendarFilteredData` (POST, `country[]=11`)
- 거래소 필터: "서울 증권 거래소" (KOSDAQ는 같은 날 동시 휴장이라 첫 매칭만 저장)
- 실패 시 stderr만 남기고 기존 파일 유지 — 다운스트림(웹뷰)은 옛 데이터로 계속 동작.

## 진입점 명령
- 즉시 갱신: `python3 ~/.openclaw/agents/stock/workspace/scripts/holiday_sync.py`
- 저장 데이터만 출력 (네트워크 호출 없음): `python3 .../scripts/holiday_sync.py --show`
- 사용자가 "다음 휴장일 언제야?" / "5월 휴장일 알려줘" 등 물어보면 위 `--show` 결과를 그대로 쓰거나 JSON 파일을 직접 파싱해서 답할 것. 외부 검색 금지.

## 사용처
- `behive_web.py` `_market_active_now()` — 자동갱신 토글이 휴장일/주말/시간외에 비활성. mtime-cache로 lazy reload.
- `watchlist_monitor.py` `is_market_hours()` — 휴장일이면 거래 없음 → 키움 호출 자체 스킵.
- `stock_portfolio_report.py` `main()` (`mode='send'`만) — 휴장일 메일 발송 스킵 (시세·잔고 무변동이라 어제와 동일). `run` 모드(수동 미리보기)는 그대로 통과.
- `briefing_fallback.py` `main()` (retry/final) — 휴장일이면 폴백 자체 스킵. **특히 final 모드의 거짓 "스냅샷 없음" 텔레그램 알림 차단.**

**원칙: 평일/장시간 판정을 새로 짤 때는 반드시 `holiday_sync.is_market_day_today()` 또는 `is_holiday_today()`를 import해서 사용. 개별 스크립트에 휴장일·평일 로직 하드코딩 금지.**

## API
```python
from holiday_sync import is_holiday, is_holiday_today, is_market_day_today
is_holiday('2026-05-25')   # bool — 임의 날짜
is_holiday_today()          # bool — 오늘
is_market_day_today()       # bool — 오늘 평일 + 휴장일 아님 (가장 많이 쓰는 게이트)
```
모든 함수는 데이터 파일 누락/파싱 실패 시 안전 fallback (False = 휴장 아님 또는 평일이면 영업일 인정) — 검증 신호 가리지 않음.

## 누락·오류 대응
- 사용자가 "오늘 휴장인데 자동토글이 켜져있어" 같은 보고를 하면:
  1. `holiday_sync.py --show`로 오늘 날짜가 들어있는지 확인
  2. 누락이면 `holiday_sync.py` 즉시 실행 → 재확인
  3. 그래도 누락이면 investing.com 측 데이터 자체에 없는 케이스 → 사용자에게 확인 요청
- 사이트 HTML 구조가 바뀌어 파싱이 깨지면 `holiday_sync.py`가 exit 3 + stderr 메시지. 로그는 `~/.openclaw/logs/holiday-sync.err.log`.