24시간 돌아가던 에이전트 전체가 동시에 멈췄다 — Claude Code OAuth 토큰 만료 장애 복구기

-

장시간 무응답의 원인 분석과 5가지 재발 방지 조치까지

핵심 요약

  • 텔레그램+디스코드에 연결된 다수의 에이전트가 장시간 동시 무응답 — 원인은 Claude Code OAuth 토큰 만료
  • 이 문제는 특정 사례만의 문제가 아님 — GitHub Issue #12447에 24건+ 코멘트, 22+ 추천. Anthropic 공식 대응 없음 (이슈 제기 시점 기준)
  • claude setup-token으로 장기 토큰(1년) 설정 + 워치독 인증 체크 + 원격 인증까지 구축하여 재발 방지 체계 완성

배경

다수의 에이전트를 24시간 운영하면 코드 버그보다 인프라 레벨 장애가 더 조용하고 치명적으로 찾아옵니다.

텔레그램과 디스코드에 연결된 모든 에이전트가 동시에 응답을 멈춘 사례가 있었습니다. tmux 세션은 살아 있었고 메시지 수신도 되고 있었지만, Claude API 호출이 전부 실패하고 있었습니다.

장시간이 지나서야 이상이 감지되었습니다.

원인은 단순했습니다. OAuth 토큰 만료.

본문

1. 장애 구조

단계 상태
장애 발생 전체 에이전트 무응답 시작
장애 지속 장시간 무응답 지속
복구 claude /login 재인증 → 전체 재시작 → 복구

증상만 보면 심각해 보이지만, 원인은 인증 토큰 하나였습니다.

2. 왜 이런 일이 발생하는가

Claude Code의 Max 구독 기본 인증 방식은 OAuth입니다. 이 토큰의 수명이 2~4시간으로 짧고, 자동 갱신이 실패할 수 있는 구조입니다.

갱신이 실패하면 모든 세션이 동시에 인증 불가 상태가 됩니다.

구조적 취약점은 세 가지입니다:

  1. 만료 전 경고가 없습니다
  2. 토큰 TTL(남은 시간)을 확인할 방법이 없습니다
  3. 만료 시 실행 중인 모든 태스크가 불완전 상태로 중단됩니다

3. 커뮤니티에서 동일하게 보고된 문제 — GitHub 이슈 현황

이 문제는 GitHub에서 이미 다수 보고되어 있습니다.

이슈 내용 상태
#12447 OAuth 토큰 만료가 자율 워크플로우를 중단시킴 24건+ 코멘트, 22+ 추천
#33811 토큰 만료 후 login/logout 모두 401 실패 미해결
#36911 하루에도 여러 번 토큰 만료 미해결
#19456 macOS Keychain 권한 문제로 갱신 실패 미해결

Anthropic 공식 응답은 없습니다. (이슈 제기 시점 기준)

4. 해결: claude setup-token — 장기 토큰 설정

Claude Code는 setup-token 명령으로 1년 유효 OAuth 토큰을 생성할 수 있습니다.

claude setup-token

생성된 토큰은 sk-ant-oat01-xxxxx 형식이며, 환경변수로 설정합니다:

export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx

주의사항:

  1. Claude Pro 또는 Max 구독이 필요합니다
  2. CLI에서만 생성 가능합니다 (Desktop 앱에는 없음)
  3. 토큰은 안전하게 보관해야 합니다

5. Claude Code 인증 우선순위 (공식 문서)

Claude Code가 인증을 시도하는 순서입니다. 환경에 맞는 방식을 선택할 수 있습니다.

순위 방법 설명
1 Cloud Provider Bedrock / Vertex / Foundry 환경변수
2 ANTHROPIC_AUTH_TOKEN Bearer 토큰 (LLM 게이트웨이용)
3 ANTHROPIC_API_KEY Console API 키
4 apiKeyHelper 동적/회전 자격증명 스크립트
5 OAuth (/login) Pro/Max/Team/Enterprise 구독 기본값

순위 5번(OAuth)이 기본값이기 때문에, 별도 설정 없이 구독만 하면 자동으로 이 방식이 적용됩니다. 그리고 이것이 만료 장애의 원인이 됩니다.

6. 재발 방지 — 5가지 조치

복구 이후, 동일 장애가 재발하지 않도록 5가지 조치를 구축했습니다.

  1. claude setup-token 실행 → 장기 인증 토큰 설정 (1년 유효)

  2. 워치독에 인증 체크 추가 → 만료 감지 시 즉시 알림

  3. /auth 명령어 → 텔레그램/디스코드에서 인증 상태 원격 확인

  4. /login 명령어 → 원격 재인증 URL 발급 (핸드폰에서 탭으로 인증 가능)

  5. 대시보드에 Claude Auth 상태 표시 → 한눈에 인증 상태 모니터링

설계 관점에서의 함의

  • 인증은 단일 장애점(SPOF)이 됩니다. 다수의 에이전트가 같은 OAuth 토큰을 공유하면, 토큰 하나 만료로 전체가 멈춥니다.

  • 업계 권장 패턴은 듀얼 키 로테이션입니다. 구/신 키가 잠시 동시 유효한 Blue/Green 방식이 안전합니다. 하지만 Claude Code는 이를 지원하지 않으므로, 장기 토큰으로 우회하는 것이 현실적입니다.

  • 워치독 없이는 장애를 인지할 수 없습니다. 에이전트가 "죽었다"는 알림이 없으면 장시간 무응답 상태가 방치됩니다. 워치독의 인증 체크가 이 공백을 메웁니다.

마무리

자동화 시스템도 운영하면 장애가 옵니다.

중요한 건 장애가 안 나는 게 아니라, 빠르게 복구하고 재발을 막는 구조를 만드는 것입니다. 인증이라는 보이지 않는 의존성이 전체 시스템의 아킬레스건이 될 수 있다는 점을 이 사례는 보여줍니다.

Claude Code로 에이전트를 24시간 운영하고 있다면, claude setup-token은 선택이 아니라 필수입니다.

출처: - GitHub Issue #12447 — OAuth token expiration disrupts autonomous workflows - GitHub Issue #33811 — OAuth token expired, no recovery path - Claude Code Authentication Docs

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »