구독 계정으로 Claude를 직접 호출하기 — OAuth 토큰의 원리와 정책 변천사

2026.08.14

자체 제작한 AI 에이전트에서 Claude를 호출할 때, API 종량제 대신 이미 결제 중인 Pro/Max 구독을 쓸 수 없을까? 라는 질문은 자연스럽다. 실제로 가능하고, 오픈소스 SDK 몇 개가 그 방식을 지원한다. 다만 2026년 내내 이 영역의 정책이 크게 요동쳤기 때문에, 지금 시점에서 무엇이 허용되고 무엇이 회색지대인지 정리해 둘 가치가 있다.

이 글은 실제로 그렇게 굴러가는 에이전트 하나를 뜯어보며 정리한 내용이다.

요약

구독 OAuth 토큰(sk-ant-oat01-...)으로 Anthropic API를 직접 호출하는 것은 기술적으로 가능하다.
단, 그러려면 호출이 공식 Claude Code CLI인 것처럼 보여야 한다. 전용 헤더와 특정 시스템 프롬프트가 없으면 인증은 통과해도 rate_limit_error가 난다.
이 방식은 2026년 4월에 약관상 완전히 금지됐다가, 8월경 조건부로 다시 허용됐다. 다만 부활한 것은 “구독으로 3자 에이전트를 쓰는 것” 자체이고, Claude Code로 위장하는 부분은 여전히 회색지대다.
새로 시작한다면 위장 방식보다 공식 경로(Agent SDK 크레딧 시스템 또는 종량제 API 키)를 권한다.

1. 정책 타임라인 — 왜 막혔다가 풀렸나

시점	내용
2026-01-09	예고 없이 구독 OAuth 토큰이 공식 CLI 밖에서 차단됨. 커뮤니티 반발로 되돌림
2026-02-19	약관 명문화 — Free/Pro/Max의 OAuth 토큰은 Claude Code와 Claude.ai 전용. Agent SDK를 포함한 3자 도구 사용은 위반
2026-04-04	공식 시행. Pro/Max 구독이 3자 도구를 더 이상 커버하지 않음. API 키 + 종량제로 전환 강제
2026-08경	반전 — 3자 에이전트의 구독 사용을 다시 허용. 단 신규 Agent SDK 크레딧 시스템을 통하며, 요금제 티어별로 프로그래밍 사용량이 차등 배분됨

원래 막았던 이유는 명확하다. 월 20~200달러를 내는 구독자가 자율 에이전트를 붙여 수백에서 수천 달러어치 토큰을 태우고 있었기 때문이다. 정액 요금제가 감당할 수 있는 사용 패턴이 아니었다.

8월의 부활은 “무제한 복귀"가 아니라 사용량에 상한을 씌운 재개방에 가깝다. 크레딧을 다 쓰면 그 이상은 별도 과금이다.

2. 동작 원리

2-1. 토큰 얻기 — 두 가지 경로

경로 A: 브라우저 PKCE OAuth 플로우

오픈소스 SDK들이 쓰는 방식이다. 요점은 Claude Code CLI 자신의 공개 client_id를 그대로 재사용한다는 것이다.

claude.ai/oauth/authorize로 인가 요청 (PKCE S256, scope는 프로필·추론·API 키 생성)
사용자가 브라우저에서 승인 → 코드#상태 형태의 문자열을 받음
그걸 토큰 엔드포인트에서 교환 → {access, refresh, expires} 획득

여기서 나오는 access 토큰이 sk-ant-oat01-로 시작하는 값이다.

경로 B: claude setup-token (더 간단하고 실용적)

공식 CLI에 내장된 명령이다.

npm i -g @anthropic-ai/claude-code
claude setup-token

브라우저 승인을 거치면 유효기간 1년짜리 sk-ant-oat01- 토큰이 출력된다. 이걸 자격증명 파일에 직접 넣으면 2차 OAuth 플로우가 아예 필요 없다. 서버에서 운영할 때는 이쪽이 훨씬 편하다.

참고: setup-token은 TUI라 파이프로 값을 넘길 수 없다. 원격 서버라면 tmux 같은 걸로 세션을 띄워 인터랙티브하게 입력해야 한다.

2-2. 토큰 저장과 자동 갱신

자격증명은 보통 {refresh, access, expires} JSON 한 덩어리로 디스크에 둔다. 호출할 때마다 만료를 검사하고, 지났으면 refresh_token 그랜트로 새 access 토큰을 받아 파일에 다시 쓴다.

이 갱신 로직은 SDK가 대신 해주는 경우가 많다. 직접 구현한다면 만료 시각에 5분 정도 버퍼를 두는 게 안전하다.

2-3. 핵심 — “나는 Claude Code다”

여기가 이 방식의 본질이다. SDK는 API 키에 sk-ant-oat가 포함되면 OAuth 모드로 전환하면서, 호출을 공식 CLI처럼 보이게 만든다.

인증 헤더를 x-api-key가 아니라 Authorization: Bearer <토큰>으로
베타 헤더에 Claude Code용 플래그와 OAuth 플래그를 추가
user-agent를 claude-cli/<버전> (external, cli) 형태로
x-app: cli 추가
시스템 프롬프트 첫 블록에 "You are Claude Code, Anthropic's official CLI for Claude."를 강제로 삽입
심지어 툴 이름까지 공식 CLI의 표준 표기(Read, Write, Edit, Bash, Grep, Glob …)로 변환

마지막 두 개가 특히 중요하다. 시스템 프롬프트 주입을 빼먹으면 인증은 성공하는데 rate_limit_error가 난다. 처음 붙일 때 가장 많이 걸리는 함정이다.

정리하면, 구독 토큰으로 API를 직접 때리되 서버 입장에서는 공식 CLI의 트래픽으로 보이게 하는 구조다. 4월 차단 때도 공식 CLI 자체는 계속 허용됐으므로, CLI인 척하면 그 예외를 그대로 탈 수 있었다.

2-4. 에이전트에 붙이기

살펴본 에이전트는 헥사고날 구조라 LLM 호출이 포트 인터페이스 뒤에 숨어 있었다. 실제 흐름은 단순하다.

요청 수신 → 자격증명에서 토큰 획득(필요시 갱신) → SDK 호출 → 응답 정규화

실무에서 유용했던 두 가지 설계 판단:

들어온 요청의 모델명을 무시하고 서버 자신의 환경변수를 쓴다. 덕분에 이 에이전트를 호출하는 클라이언트 쪽 설정을 하나도 건드리지 않고 모델을 교체할 수 있다.
SDK의 모델 레지스트리는 항상 최신 모델보다 뒤처진다. 신모델이 나와도 SDK가 모르면 호출이 안 된다. 모델 디스크립터를 로컬에 직접 등록해 두고, SDK가 나중에 따라오면 그쪽이 이기도록 우선순위를 두면 SDK 업그레이드를 기다릴 필요가 없다.

3. 따라 할 때 체크리스트

claude setup-token으로 1년짜리 토큰을 발급받는다. (가장 빠른 시작점)
토큰을 안전한 위치에 저장하고, 만료 갱신 로직을 붙인다.
호출 시 위장 헤더 + 시스템 프롬프트를 반드시 포함한다. 직접 구현하기보다 이걸 대신 해주는 SDK를 쓰는 편이 낫다.
신모델을 쓰려면 SDK 레지스트리를 우회할 경로를 미리 만들어 둔다.

4. 주의사항 — 읽고 결정할 것

위장은 회색지대다. 8월 정책 변경으로 구독을 통한 3자 에이전트 사용 자체는 다시 허용됐지만, 공식 CLI를 사칭하는 방식이 명시적으로 승인된 것은 아니다. 개인 실험용이라면 몰라도, 상용 서비스나 남에게 파는 제품에는 쓰지 말 것을 권한다.
차단은 예고 없이 온다. 1월 사례가 그랬다. 이 방식에 서비스 가용성을 걸어두면 어느 날 아침 조용히 죽어 있을 수 있다.
지금의 정도(正道)는 공식 경로다. 부활한 Agent SDK 크레딧 시스템을 쓰거나, 콘솔에서 발급한 API 키로 종량제를 쓰는 것. 안정적으로 굴릴 거라면 이쪽이다.
토큰은 계정 전체 권한을 갖는다. 서버에 둘 때 파일 권한과 백업 경로를 반드시 점검하자.

마무리

정리하자면, 기술적 난이도는 낮다. 토큰 하나 받아서 헤더 몇 개와 시스템 프롬프트 한 줄을 맞추면 끝이다. 진짜 판단이 필요한 부분은 구현이 아니라 어디에 쓸 것인가다.

개인 자동화와 실험이라면 충분히 매력적인 선택지다. 반대로 남이 의존하는 서비스라면, 정책이 한 번 뒤집힐 때마다 흔들리는 기반 위에 올리는 셈이라는 걸 감수해야 한다.