매일 저녁 6시, 자동으로

키즈노트 알림장이
구글 캘린더로 쏙 들어가요

선생님이 올린 행사·준비물을 AI가 읽고 정리해서, 우리집 캘린더에 알아서 등록해 주는 작은 도우미예요.

운영 중 매일 18:00 KST 한 번 설정, 평생 자동
1 이게 뭐예요

3단계로 끝나는 작은 마법

사람이 하던 번거로운 옮겨적기를, 매일 알아서 해주는 작은 비서를 만들었어요.

알림장이 도착해요

선생님이 올린 행사·준비물 글이 키즈노트에 올라옵니다.

AI가 읽고 정리해요

"몇 월 며칠, 무슨 행사, 뭘 챙겨야 하는지" 똑똑하게 뽑아냅니다.

캘린더에 등록돼요

구글 캘린더에 일정이 자동으로 들어가고, 원문도 함께 붙어요.

핵심: 같은 행사가 여러 알림장에 또 적혀도 캘린더엔 한 번만 등록됩니다. 사람이 검토할 필요 없이 그냥 두면 돼요.

캘린더에선 이렇게 보여요

자동으로 들어간 일정은 항상 @새솔로 시작해요. 직접 적은 일정과 한눈에 구분됩니다.

2 처음 설정

딱 한 번, 5분이면 끝

아래 다섯 단계만 차례로 따라오면 됩니다. 어렵게 느껴지는 부분은 그림으로 정리했어요.

키즈노트 정보 모으기
PC 브라우저에서 잠깐만 필요해요

PC에서 키즈노트 웹사이트에 로그인한 뒤, F12(개발자 도구) → Network 탭을 열어요. 새로고침하면 보이는 reports 요청 한 줄에서 5가지 값을 메모합니다.

  • 요청 URL의 children/여기 → CHILD_ID
  • 같은 URL의 ?cls=여기 → CLASS_ID
  • 같은 URL의 ¢er_id=여기 → CENTER_ID
  • 요청 헤더 x-enrollment: 여기 → ENROLLMENT_ID
  • 그리고 키즈노트 로그인 아이디 / 비밀번호
카카오 로그인은 안 돼요. 키즈노트 자체 아이디/비밀번호를 쓰는 계정만 동작합니다. 카카오만 쓰던 분은 키즈노트 앱에서 비밀번호를 먼저 만들어주세요.
AI 준비하기 (Claude Code)
알림장을 읽어줄 AI에 한 번 로그인해 두기

도우미를 돌릴 컴퓨터에 Claude Code를 설치하고 한 번 로그인해 두세요. 도우미가 이 claude 명령으로 알림장을 읽습니다. 따로 발급할 API 키는 없어요.

curl -fsSL https://claude.ai/install.sh | bash
claude              # 처음 한 번 실행해서 로그인
which claude        # 나온 경로를 .env 의 CLAUDE_BIN 에
비용: 로그인한 Claude 구독 사용량 안에서 처리돼요. 알림장 한 건은 짧은 요청 한 번이라, 매일 몇 건 들어와도 부담이 거의 없습니다.
.env 파일 채우기
모은 정보를 한 곳에 적어두기

프로젝트 폴더에서 예시 파일을 복사한 뒤, 1번에서 모은 값과 2번의 claude 경로로 채웁니다.

cp .env.example .env
# 에디터로 .env 열고 위에서 모은 값 채우기
매일 저녁 자동 실행 걸기
crontab 한 줄이면 도우미가 깨어나요

Node.js 18 이상이 필요해요. 패키지를 설치한 뒤, 매일 18시에 한 번 돌도록 crontab 에 등록합니다. 도우미가 같은 컴퓨터의 claude 를 불러 쓰기 때문에 도커 없이 그 컴퓨터에서 바로 실행합니다.

npm install --omit=dev
mkdir -p logs
crontab -e          # 아래 한 줄 추가
0 18 * * * cd ~/kidsnote-calendar-sync && DATA_DIR=./data /usr/bin/node src/main.js --once >> logs/cron.log 2>&1

컴퓨터 시간대가 한국이 아니면 시각을 맞춰 바꾸세요 (UTC 컴퓨터라면 0 9 * * *). node 경로는 which node로 확인해 적어요. 컴퓨터를 껐다 켜도 예약은 그대로 남습니다.

구글 캘린더 연결 (1회만)
캘린더에 글 쓸 권한을 한 번 허락하기
  1. Google Cloud Console에서 새 프로젝트 만들기
  2. API 라이브러리에서 "Google Calendar API" 검색 → 사용 설정
  3. OAuth 동의 화면 → 외부 → 테스트 사용자에 내 Gmail 추가
  4. OAuth 클라이언트 ID 생성 → 유형 데스크톱 앱 → JSON 다운로드 → data/credentials.json으로 저장
  5. 아래 한 줄로 인증 진행 (브라우저 한 번 열림)
DATA_DIR=./data node scripts/google-auth.js

브라우저가 localhost로 리다이렉트 되며 연결 실패 페이지가 떠도 정상이에요. 주소창 code= 뒤 값을 복사해 터미널에 붙여넣으면 끝.

"외부 + 테스트 모드"에선 테스트 사용자 목록에 있는 Gmail만 인증돼요. 캘린더 받을 본인 계정 꼭 추가하세요.
3 매일 동작

저녁 6시, 조용히 일어나요

설정이 끝났다면 더는 신경 쓸 게 없어요. 안에서 일어나는 일은 이렇습니다.

  1. 18:00 KST
    스케줄러가 깨어납니다
    매일 정해진 시간에 자동 실행돼요.
  2. 알림장 가져오기
    키즈노트에서 새 글만 골라옵니다
    이미 본 알림장은 다시 분석하지 않아요 (비용 절약).
  3. AI 분석
    행사·준비물·날짜를 뽑아냅니다
    선생님 글 본문이 20자 이상일 때만 호출해요.
  4. 캘린더 등록
    제목 앞에 @새솔 표시가 붙어요
    내가 적은 일정과 한눈에 구분되고, 같은 행사는 중복 없이 한 번만 들어갑니다.
  5. 완료
    잘 자고 내일 다시 만나요
    기록은 logs/cron.log에 쌓여요.

잘 동작하는지 확인하고 싶을 때

가끔 한 번 들여다보고 싶다면 아래 명령으로 충분합니다.

crontab -l | grep kidsnote      # 예약 걸려 있나?
tail -n 50 logs/cron.log        # 최근에 뭐 했나?
DATA_DIR=./data node src/main.js --once
                                # 지금 바로 한 번 더 돌려보기
4 문제 해결

자주 마주치는 다섯 가지

대부분의 문제는 아래에서 해결돼요. 카드를 눌러 펼쳐 보세요.

! 구글에서 "확인되지 않은 앱" 경고가 떠요

OAuth 동의 화면이 테스트 모드일 때 발생합니다. Google Cloud Console → OAuth 동의 화면 → 테스트 사용자에 본인 Gmail을 추가하면 사라져요.

? 키즈노트 로그인이 자꾸 실패해요

1) 비밀번호가 정확한지 다시 확인해주세요. 2) 카카오 OAuth 계정은 지원되지 않습니다 — 키즈노트 자체 비밀번호가 있어야 해요. 3) 그래도 안 되면 data/cookies.json을 삭제하고 다시 시도하세요 (자동 재로그인).

↻ 같은 행사가 캘린더에 또 안 등록돼요

의도된 동작이에요. 다른 알림장에서 같은 행사가 또 언급돼도, 캘린더엔 한 번만 들어가도록 막아두었습니다. 정말 다시 등록해야 한다면 data/state.db의 해당 행을 삭제하세요.

✎ 일정이 이상하게 추출돼요

알림장 글이 짧거나 날짜 표현이 모호한 경우입니다. src/extractor.js의 SYSTEM_PROMPT를 조정하면 다음 실행부터 바로 적용돼요. 같은 리포트를 다시 분석하려면 state.db의 해당 행도 함께 지워야 합니다.

⟳ 구글 토큰이 만료된 것 같아요

대부분 자동 갱신되지만, 가끔 갱신이 막힐 때가 있어요. data/token.json 파일을 지우고 설정 5단계의 인증 명령을 한 번 더 실행하면 깨끗하게 풀립니다.

5 더 알아보기

속을 들여다 보고 싶다면

동작 원리, 파일 구조, 데이터 흐름까지 자세히 알고 싶다면 개발자용 문서를 참고하세요.

📐 시스템 구조도와 파일 트리

매 단계가 어떤 파일에서 어떻게 일어나는지, ASCII 다이어그램과 함께 정리된 원본 문서가 있어요.

🧠 AI 프롬프트의 정확한 모습

알림장에서 어떤 규칙으로 행사·준비물을 뽑아내는지, 정확한 지시문이 마크다운으로 정리돼 있어요.