증상: Claude Code CLI가 수 초 만에 끝나고, 로그에 OAuth access token has expired 또는 Invalid authentication credentials(HTTP 401)가 남는다. sonnet·opus 모델 이름과 무관하게 같은 패턴이면 토큰 만료다.
대화형 터미널에서 claude auth login으로 재로그인한 뒤 claude -p "ping" --model sonnet이 정상 응답하는지 확인한다. launchd·cron이 쓰는 바이너리 경로와 홈 디렉터리의 자격 증명이 수동 세션과 같은지도 같이 본다. 인증을 안 고치면 일일 포스팅 잡이 호출만 나가고 본문 0건으로 끝난다.
자동화 로그에 FAIL rc=1만 잔뜩 쌓이면 “모델 한도” “네트워크” “프롬프트”를 한꺼번에 의심하기 쉽다. 먼저 메시지 문자열로 원인을 갈라야 한다.
| 증상·로그 |
추정 원인 |
우선 조치 |
OAuth access token has expired |
CLI OAuth 세션 만료 |
claude auth login 후 스모크 테스트 |
Invalid authentication credentials / 401 |
토큰 손상·계정 불일치·로그아웃 |
재로그인 + 바이너리·HOME 경로 확인 |
429 / rate limit / too many requests |
단위 시간 호출 한도 |
백오프 재시도 (인증 재로그인 아님) |
| usage limit / billing / 402 |
구독 한도 또는 API 크레딧 |
갱신·충전. 재로그인은 무의미 |
| command not found: claude |
PATH·비대화형 환경 PATH |
절대 경로(/opt/homebrew/bin/claude) 고정 |
401 계열은 모델 선택과 무관하다. 같은 프롬프트로 수동 대화형은 되고 headless만 죽는다면 PATH·HOME·실행 사용자(uid) 차이를 먼저 본다. 자세한 리밋 대응은 클로드 코드 자동화 | 리밋과 재개를 참고하면 된다.
비대화형 잡(launchd, cron, CI) 안에서는 브라우저 로그인이 열리지 않는다. 반드시 사람 손이 닿는 터미널에서 재인증한다.
- 로그인 사용자로 로컬 터미널을 연다. (자동화 전용 계정이 있으면 그 계정 셸로 전환)
which claude와 claude --version으로 실제 바이너리를 확인한다. Homebrew면 보통 /opt/homebrew/bin/claude다.claude auth login을 실행하고, CLI가 안내하는 브라우저·디바이스 코드를 완료한다. 버전에 따라 re-auth 안내 문구가 다를 수 있다.- 스모크:
claude -p "ping" --model sonnet. 수 초 안에 텍스트가 나오고 exit code 0이면 세션 복구.
- 같은 절대 경로로 자동화 스크립트·plist의
ProgramArguments를 맞춘다. 셸 alias만 고치고 잡은 옛 경로를 쓰면 다시 401이 난다.
설치·초기 로그인 흐름은 Claude Code 가이드 #1 설치, 인증 트러블슈팅 시리즈는 설치·인증 트러블슈팅과 겹치는 항목이 있다. 이 글은 만료 후 복구와 자동화 연쇄 실패에 초점을 둔다.
# 1) 재인증 (대화형 터미널)
claude auth login
# 2) headless 스모크
claude -p "ping" --model sonnet
# 3) 바이너리 경로 고정 확인
which claude
ls -la /opt/homebrew/bin/claude
일일 포스팅·콘텐츠 에이전트가 Claude를 한 번이라도 호출하는 구조라면, 토큰 만료 시 스케줄은 “성공한 것처럼” 보이면서 산출물만 비는 경우가 많다.
- 상위 래퍼가 exit code만 보고 재시도 큐에 넣고, 로그에는 401이 반복된다.
- staged 글 소진·키워드 큐 고갈과 증상이 비슷해 보인다. 인증 실패를 먼저 배제해야 한다.
- macOS launchd는 로그인 세션과 다른 환경 변수(PATH, HOME, 키체인 접근)를 가질 수 있다. plist에 절대 경로와 명시적
EnvironmentVariables를 넣는 편이 안전하다.
- 여러 Homebrew 설치(Apple Silicon vs Rosetta, 사용자별 prefix)가 섞이면 “수동은 되고 잡은 안 됨”이 재발한다.
스케줄 설계 자체는 Claude Code 자동화 | cron 스케줄 글을 보면 된다. 권한 플래그와 headless 패턴은 skip-permissions 자동화와 함께 점검한다.
복구 직후 잡 한 번을 수동으로 트리거해, content-agent 로그에 401·Failed to authenticate·연속 FAIL rc=1이 사라졌는지 확인한다. 사이트별 daily 로그에도 동일 문자열이 없어야 한다.
Claude Code CLI는 기본적으로 Anthropic 계정 OAuth 로그인 세션을 쓴다. Console API 키(ANTHROPIC_API_KEY 등)를 넘기면 과금·한도 경로가 달라진다. 로그에 OAuth가 보이면 키 충전이 아니라 로그인 세션 문제다.
| 구분 |
OAuth (CLI 로그인) |
API 키 |
| 설정 방법 |
claude auth login |
환경변수·키 파일 |
| 만료 시 신호 |
401 / token expired |
401 invalid key 또는 billing |
| 자동화 리스크 |
장기 잡에서 세션 만료 |
키 유출·크레딧 소진 |
| 복구 |
대화형 재로그인 |
키 교체·충전 |
OAuth 2.1 쪽 일반 개념은 OAuth 2.1 실무 가이드를 보면 된다. Claude Code 맥락에서는 “브라우저 로그인으로 받은 액세스 토큰이 로컬에 캐시되고, 만료되면 headless 호출이 즉시 401”이라는 운영 사실만 기억하면 충분하다.
만료 주기는 보안 정책·기기 로그아웃·계정 쪽 세션 무효화에 따라 달라진다. “자주 끊긴다”면 자동화 로그에 401 패턴 알림을 붙여, 큐가 비기 전에 사람이 재로그인하도록 하는 편이 낫다.
재로그인만 하고 끝내면 launchd가 다음날 새벽에 또 깨질 수 있다. 아래를 순서대로 닫는다.
- 수동 1회 생성 스모크: 실제 잡과 같은 플래그(
-p, 모델, 작업 디렉터리)로 한 건 실행
- content-agent·래퍼 로그에서
FAIL rc=1 폭주 중단 여부
- 사이트별 daily 로그에
401·OAuth·Failed to authenticate 부재
- plist·cron의
claude가 which claude 결과와 동일 절대 경로인지
- 잡 실행 사용자와 재로그인한 사용자가 같은지 (sudo·다른 uid 금지)
- 디스크 용량·staged 큐 잔량: 인증 복구 후에도 0건이면 콘텐츠 파이프라인 쪽을 본다
# 최근 로그에서 인증 실패 잔존 여부 (경로는 환경에 맞게)
rg -n "401|OAuth|Failed to authenticate|Invalid authentication" ~/logs/content-agent*.log || true
# 잡이 쓰는 바이너리와 대화형 바이너리 비교
type -a claude
/opt/homebrew/bin/claude -p "ping" --model sonnet
CLI 명령 전반은 Claude Code CLI 명령 가이드, 런타임 오류는 런타임 트러블슈팅과 함께 보면 원인 분기가 빨라진다.
※ CLI UI·인증 절차·에러 문구는 Anthropic 정책·버전 업데이트에 따라 바뀔 수 있다. 화면 안내가 다르면 공식 CLI 메시지를 우선한다.
도구 UI·인증 절차는 Anthropic 정책 변경에 따라 달라질 수 있습니다. 운영 로그의 401 패턴을 고정 모니터링하는 쪽을 권장합니다.
