Claude 구독 한도가 리셋되면 ntfy로 폰에 알림 받기

Claude 구독 한도가 리셋되면 폰으로 알려주는 작은 도구를 만들어 집 서버에 올려두었습니다. 새 모델 Fable을 구독으로 쓸 수 있는 기간이 6월 22일까지였는데, 분석은 Fable에 맡기고 실제 작업은 평소 쓰던 모델에 넘기다 보니 한도가 금방 찼습니다. 남은 열흘 동안 한도가 풀리는 대로 바로 이어서 쓰고 싶었고, 자리에 없을 때도 알 수 있어야 했습니다.

결론부터 적으면 이렇습니다. 남은 한도가 얼마인지 알려주는 공식 API는 없어서 “잔액 알림”은 만들 수 없고, 만들 수 있는 건 “한도가 리셋됐다”는 신호입니다. 사용량 응답에 들어 있는 다음 리셋 시각(resets_at)과 사용률을 읽다가, 사용률이 뚝 떨어지면 ntfy로 폰에 푸시를 보냅니다. 서버에서는 사용량을 읽어 리셋을 감지하는 작업과, 공식 claude CLI를 3시간마다 실행해 토큰을 최신으로 유지하는 작업이 백그라운드로 돕니다.

Claude 남은 한도를 조회하는 공식 API가 있나

없습니다. 구독 사용량은 Claude를 쓰고 있는 화면 안에서만 보이고, 밖에서 남은 한도를 조회하는 공개 엔드포인트는 없습니다. 그래서 이런 알림을 만드는 도구들은 전부 Claude Code가 쓰는 비공식 사용량 엔드포인트(/api/oauth/usage)를 읽습니다.

이 응답에는 사용률과 함께 다음 리셋 예정 시각(resets_at)이 들어 있습니다. 5시간 세션 한도와 주간 한도가 언제 풀리는지는 이 값으로 알 수 있습니다. 폰으로는 “지금 몇 퍼센트 남았다”를 계속 보내지 않고, 리셋 순간에 한 번만 알리게 했습니다.

리셋을 감지하는 방법: 사용률 급락과 resets_at

판단 기준은 단순합니다. 사용량을 주기적으로 읽어서 직전 값과 비교하고, 사용률이 거의 찼다가 크게 내려가면 리셋으로 봅니다. 실제로 받은 알림에는 “이전 90% → 현재 5%“처럼 직전 값과 현재 값이 같이 찍힙니다.

24시간 내내 같은 간격으로 읽으면 요청만 낭비됩니다. 그래서 응답의 resets_at을 보고 그 시각 부근에서만 촘촘하게 확인하게 했습니다.

도구는 외부 라이브러리 없이 파이썬 기본 모듈만 씁니다. 토큰은 읽기만 하고, 파일로 남기거나 다른 곳으로 보내지 않습니다.

ntfy로 폰과 애플워치에 푸시 보내기

처음에는 텔레그램으로 보내려다 ntfy로 바꿨습니다. 폰에 ntfy 앱을 깔고 토픽 하나만 구독하면 되고, 가입 절차가 없습니다. 보내는 쪽은 curl 한 줄입니다.

# 리셋 감지 시 폰으로 푸시 (토픽 이름이 곧 주소 = 무작위로 길게)
curl -H "Title: Claude reset" -d "한도가 리셋됐어요" https://ntfy.sh/<내가-정한-토픽>

설정할 때 확인할 것은 세 가지입니다.

• 토픽 이름은 길고 무작위로 짓습니다. ntfy 공식 문서도 가입 절차가 없으니 토픽 이름이 사실상 비밀번호라고 설명합니다. 이름을 맞히는 사람은 누구나 같은 토픽을 볼 수 있습니다.
• 제목은 Title 헤더로 바꿉니다. 공식 문서 기준으로 X-Title, Title, t 모두 됩니다. 우선순위는 X-Priority(또는 Priority) 헤더에 1~5를 넣고, 기본값은 3입니다(2026년 10월 확인).
• 잘 때도 받으려면 집중 모드(수면)의 허용 앱에 ntfy를 넣습니다. 애플워치는 폰 알림을 그대로 받아서 따로 설정할 것이 없었습니다.

실제로 받은 알림 문구는 “5시간 세션 한도가 리셋됐어요. 다시 사용 가능합니다 — 이전 90% → 현재 5%, 다음 리셋 20:49”였습니다.

오래된 맥에서 Illegal instruction: 4 가 나는 이유 (AVX2)

처음에는 24시간 켜두는 2012년식 맥(i5-3210M)에 올리려고 했습니다. 그런데 Claude Code를 설치하는 도중 Illegal instruction: 4로 죽었습니다.

원인은 CPU였습니다. 이 CPU에는 AVX2 명령어가 없는데, Claude Code의 네이티브 바이너리는 AVX2를 씁니다. CPU가 모르는 명령어를 만나면 프로그램이 그 자리에서 죽습니다. 설치 방법을 바꿔도 해결되지 않는 하드웨어 문제입니다.

# CPU가 AVX2를 지원하는지 한 줄로 확인
sysctl -n machdep.cpu.leaf7_features | grep -o AVX2 || echo "AVX2 없음 = 최신 바이너리 실행 불가"

결국 AVX2가 있는 2018년식 서버로 옮겨서 해결했습니다. 같은 macOS가 돌아가도 CPU 세대에 따라 최신 도구가 안 깔릴 수 있습니다. 이 오류만 따로 정리한 글은 오래된 맥에서 최신 CLI가 죽는 이유에 있고, 옮겨 간 서버 구성은 중고 Mac mini 2018을 회사 서버로 쓰는 구성과 비용에 적었습니다.

SSH에서 Keychain 토큰을 못 읽을 때 (User interaction is not allowed)

macOS의 Claude Code는 로그인 정보를 Keychain에 둡니다. 서버에 SSH로 접속해 security ... -w로 토큰을 읽으려 하니 rc=36, User interaction is not allowed 오류가 났습니다. 같은 명령이 메인 맥의 터미널에서는 됐습니다.

로그인 Keychain은 화면에 로그인된 GUI 세션에서만 잠금이 풀립니다. SSH는 화면 없는 세션이라 Keychain이 잠긴 채로 남고, 잠긴 Keychain을 비대화식으로 열려다 거부당합니다.

해결은 작업을 GUI 세션 안에서 돌게 하는 것이었습니다. launchctl로 LaunchAgent를 GUI 도메인(gui/<사용자 ID>)에 등록하면 그 프로세스는 화면 세션에서 도는 것으로 취급되어 Keychain이 열려 있습니다. 토큰을 읽는 감지 작업과 토큰 갱신 작업을 모두 이렇게 띄웠습니다.

# SSH(비-GUI) 세션이 아니라, 화면 로그인된 GUI 도메인에 등록해야 Keychain이 열린다
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<라벨>.plist

Claude Code 인증 문서의 Credential management 항목에는, SSH 세션처럼 Keychain이 잠겨 저장이 거부되면 로그인 정보를 ~/.claude/.credentials.json(권한 0600)에 대신 저장한다고 적혀 있습니다(2026년 10월 확인). 그래서 지금 버전에서는 토큰이 Keychain이 아니라 이 파일에 있을 수도 있습니다. 토큰을 못 찾으면 두 곳을 다 확인해 보면 됩니다.

Claude OAuth 토큰 갱신은 공식 CLI에 맡긴다

서버에서 Claude를 한동안 쓰지 않으면 토큰이 만료됩니다. 갱신하는 방법은 두 가지였습니다. refresh 토큰을 갱신 엔드포인트로 직접 보내는 방법과, 공식 claude CLI를 실행해 갱신을 맡기는 방법입니다.

처음에는 직접 보내는 코드를 짰습니다. 그런데 같은 일을 하는 오픈소스 도구 usage-monitor-for-claude(GitHub 별 110개, MIT 라이선스)를 뜯어보니 이 방식을 일부러 쓰지 않고 있었습니다. 자격 증명을 직접 다루지 않고 공식 CLI를 실행해 갱신을 맡긴 뒤, 결과만 읽는 구조였습니다. 배포 직전에는 안전 분류기가 “역설계한 엔드포인트로 자격 증명을 보낸다”며 한 번 막기도 했습니다.

그래서 직접 갱신하는 코드는 버리고 아래처럼 바꿨습니다.

• claude-refresh 작업이 3시간마다 claude -p "ok"를 실행합니다. 공식 경로로 토큰이 갱신됩니다.
• claude-reset 작업은 토큰을 읽기만 하고, 갱신은 하지 않습니다.

최종 구성: LaunchAgent 두 개

작업	도는 방식	하는 일
claude-refresh	3시간마다	claude -p "ok" 실행, 토큰 갱신
claude-reset	상주	사용량 읽기, 리셋 감지, ntfy 푸시

두 작업 모두 2018년식 서버의 GUI 도메인에 LaunchAgent로 등록되어 있습니다. 폰에서는 ntfy 토픽 하나만 구독해 둡니다.

안 되는 것과 한계

• 남은 한도 알림은 안 됩니다. 잔액을 알려주는 공식 API가 없어서, 이 도구가 보내는 건 “리셋됐다”는 신호뿐입니다.
• 사용량 엔드포인트는 비공식입니다. 공개 문서로 약속된 API가 아니라서 응답 형식이 바뀌면 감지가 멈출 수 있습니다.
• AVX2가 없는 맥에서는 돌릴 수 없습니다. 토큰 갱신을 공식 CLI에 맡기는 구조라 서버에서 Claude Code가 실행되어야 합니다.
• SSH로 띄우면 Keychain이 잠깁니다. 서버에 화면 로그인이 되어 있고, 작업이 GUI 도메인에 등록되어 있어야 합니다.
• ntfy 공개 서버의 토픽은 이름만 알면 누구나 봅니다. 알림 문구에 토큰이나 계정 정보는 넣지 않습니다.