Claude Agent SDK 5시간 한도 소진: 보고된 차이와 확인 방법
Claude Agent SDK 앱, claude -p, 대화형 Claude Code에서 보고된 5시간 사용 한도 소진량을 비교합니다. 클라이언트 라벨과 사용량 이벤트를 확인하고 커뮤니티 우회 방법의 한계를 살펴봅니다. 무인 작업을 API 과금이나 이용 자격이 있는 Max·Team API 크레딧으로 전환하는 절차도 설명합니다.
목차
Claude Agent SDK 앱이나 claude -p에서 5시간 사용 한도가 빨리 소진된다면 같은 작업을 대화형 Claude Code에서 실행해 비교합니다. 커뮤니티 테스트에서는 약 1.6×–2.97× 빠른 소진이 보고됐지만, 모든 환경에 적용되는 배수는 아닙니다. 정기적인 자동화에는 별도 사용 잔액과 측정 가능한 토큰 요금을 제공하는, 문서화된 API 과금 경로를 검토합니다.
2026-10-27 기준으로 Anthropic 이슈 #97074는 열려 있습니다. 보고 내용은 클라이언트의 entrypoint에 따라 사용 한도 소진량이 다르다는 근거를 제공합니다. 다만 Anthropic이 의도한 차이인지, 결함으로 판단하는지는 확인되지 않았습니다.
통제된 비교 실험에서 실제로 측정한 내용
여러 작성자가 비슷한 작업을 claude -p나 Agent SDK 앱에서 실행할 때 5시간 한도 사용률이 더 크게 증가했다고 보고했습니다. 각 실험은 버전, 모델, 토큰 구성, 비교 대상 클라이언트가 서로 다릅니다.
| 보고 | 테스트 조건 | 보고된 결과 |
|---|---|---|
| qvarker, 9월 25일 | Max, Claude Code 2.1.282, claude-opus-5, effort 설정 high | 헤드리스 모드에서 대화형 터미널보다 약 1.8× 빠르게 한도 소진 |
| kler, 10월 17일 | Team, Claude Code 2.1.300, claude-opus-5-5, effort 설정 high | claude-vscode 라벨을 사용하는 테스트 실행 도구와 비교해 sdk-ts: 2.97×, sdk-cli: 2.83× |
| Theo의 T3 Code 보고, 10월 25일 | Max 계정 하나, 일치시킨 작업량, 대화형 터미널·T3 Code·claude -p 비교 | 보고서의 캐시 비교를 거친 결과 SDK·헤드리스 경로에서 약 1.6×–1.7× 빠르게 소진 |
| frostfire575, 10월 26일 | Windows 11, Claude Code 2.1.310, claude-opus-5-5, effort 설정 low | claude -p가 대화형 터미널보다 가중 토큰당 약 2.4× 많은 한도 사용 |
가장 큰 수치를 해석할 때는 조건을 확인해야 합니다. kler의 테스트 실행 도구는 VS Code 확장 프로그램의 라벨을 모방했습니다. 실제 확장 프로그램의 화면을 조작한 것은 아닙니다. 이 결과는 해당 실험 안에서 라벨과 관련된 차이를 분리해 보여줍니다.
qvarker 보고서의 달러 금액은 작업량을 정규화하기 위한 API 요금 상당의 추정값입니다. 구독에 추가로 부과된 요금이 아닙니다. 한도 1%당 처리한 작업의 달러 환산값이 낮을수록 한도가 더 빨리 소진됐다는 뜻입니다.
주간 한도는 별도로 살펴봐야 합니다. Theo는 각 실행에서 주간 사용률이 동일하게 2퍼센트포인트 증가했다고 기록했습니다. frostfire575의 주간 사용률은 0%에서 1%로만 변해, 결론을 내리기에는 측정 간격이 너무 컸습니다. 근거가 뒷받침하는 범위는 Theo의 실험에서 주간 소진량이 같았다는 점입니다. 모든 계정에서 동일하다는 보장은 아닙니다.
sdk-cli와 sdk-ts로 확인할 수 있는 범위
entrypoint는 호출한 클라이언트를 식별하는 값입니다. 이 값이 있다고 해서 Anthropic 서버의 사용량 계산 공식까지 알 수 있는 것은 아닙니다.
공개된 @anthropic-ai/claude-agent-sdk 0.3.311 패키지의 sdk.mjs에는 다음 기본값 설정이 있습니다.
if(!c.CLAUDE_CODE_ENTRYPOINT)c.CLAUDE_CODE_ENTRYPOINT="sdk-ts"따라서 해당 환경 값이 없으면 SDK가 sdk-ts를 설정합니다. 커뮤니티가 확인한 세션 기록에는 일반적인 claude -p 실행이 sdk-cli, 대화형 터미널 실행이 cli로 기록돼 있습니다.
qvarker의 네트워크 비교에서는 요청의 x-anthropic-billing-header 시스템 블록 안에 있는 cc_entrypoint 값이 달랐습니다. 작성자는 User-Agent와 베타 플래그 하나에서도 차이를 확인했습니다.
이는 커뮤니티가 요청 내용을 관찰한 결과입니다. 공식 문서에 정의된 과금 헤더 인터페이스가 아닙니다. 필드 하나가 모든 차이를 설명한다는 증거도 아닙니다.
Claude Code 2.1.311 변경 기록에는 이 한도 소진 차이를 수정했다는 공지가 없습니다. 하지만 기록이 없다는 이유만으로 서버 동작이 변경됐는지 여부를 판단할 수는 없습니다.
실제 작업 흐름을 확인하는 방법
설정을 바꾸기 전에 실제 클라이언트, 인증 경로, 작업량을 확인하고 측정합니다.
인증 방식과 비교 조건 확인
애플리케이션의 Claude 프로세스가 사용하는 환경을 확인합니다. 인증 문서에 따르면 -p 모드에서는 API 키가 구독 인증보다 우선할 수 있습니다.
실행 파일, CLI 버전, SDK 패키지 버전, 계정 요금제, 정확한 모델 ID, effort 설정을 기록합니다. 프런트엔드가 터미널과 다른 실행 파일을 시작할 수도 있습니다.
비교 조건은 다음과 같이 맞춥니다.
- 같은 계정, 프로젝트 스냅샷, 프롬프트 목록, 도구, 캐시 설정을 사용합니다.
- 해당 계정의 다른 작업을 일시 중지합니다.
- 새 세션을 시작하고 두 실행을 같은 5시간 구간 안에서 진행합니다.
- 구간이 초기화되거나 유료 추가 사용으로 전환되면 비교를 중단합니다.
같은 소스 파일을 요약하는 등 실제 사용을 대표하는 작업을 선택합니다. 입력, 출력, 캐시 읽기, 캐시 쓰기 토큰의 합계를 각각 기록합니다. 출력 길이가 같다는 사실만으로 작업량이 같다고 판단할 수는 없습니다.
사용률과 기록된 entrypoint 수집
버전마다 제공하는 필드가 다르므로 레이트 제한 이벤트의 전체 데이터를 보존합니다.
다음 Bash 점검에는 jq와 기존 구독 로그인이 필요합니다. 실행하면 사용 한도가 소진됩니다. 이 코드는 측정 데이터와 인증을 확인하는 용도입니다. 단어 하나로 된 응답만으로 소진 배수를 측정할 수는 없습니다.
set -o pipefail
claude --version
claude auth status | jq '{authMethod}'
claude -p "Reply with exactly OK." \
--model claude-sonnet-5-5 \
--max-turns 1 \
--disallowedTools "*" \
--output-format stream-json --verbose |
jq -c '
if .type == "rate_limit_event" then
{type, session_id, rate_limit_info}
elif .type == "result" then
{type, subtype, is_error, session_id,
usage, modelUsage, total_cost_usd, result}
else empty end
'CLI 참조 문서는 이 플래그들과 인증 상태 명령을 설명합니다. 성공한 응답에는 subtype: "success"와 is_error: false가 설정된 result 레코드가 있어야 합니다.
이슈에서 사용한 계측용 빌드는 다음 경로를 이용했습니다.
rate_limit_event.rate_limit_info.unifiedWindows.five_hour.utilization
하지만 공개된 0.3.311 SDK 이벤트 타입에는 unifiedWindows가 없습니다. 대신 rateLimitType, utilization 같은 필드를 선언합니다. 필드나 이벤트가 없다고 해서 소진량이 0이라고 해석하면 안 됩니다. 스트림에서 사용할 수 있는 측정값을 얻지 못하면 계정의 Usage 페이지를 확인합니다.
측정값은 같은 인터페이스와 같은 척도에서 비교해야 합니다. 이벤트의 사용률과 SDK의 별도 사용량 제어 응답은 서로 다른 스키마를 사용합니다. 두 응답의 수치를 서로 바꿔 사용할 수는 없습니다.
반환된 session_id로 해당 세션 기록을 찾습니다. 세션 문서에 따르면 기록은 ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl 아래에 저장됩니다. CLAUDE_CONFIG_DIR을 별도로 설정하면 루트 디렉터리가 달라집니다.
Bash에서 기록된 entrypoint만 확인합니다.
read -r -p "Transcript path: " CLAUDE_TRANSCRIPT
jq -r 'select(.entrypoint? | type == "string") | .entrypoint' \
"$CLAUDE_TRANSCRIPT" | sort -u결과가 비어 있으면 해당 필드를 사용할 수 없었다는 뜻입니다. 그 세션이 대화형이었다는 뜻은 아닙니다.
터미널과 비교할 때는 환경이 정리된 셸에서 실제 대화형 Claude Code를 시작합니다. qvarker는 tmux 서버가 CLAUDE_CODE_ENTRYPOINT를 상속해 이후 터미널 세션에도 전달했다고 보고했습니다. 화면 형태가 라벨을 결정한다고 가정하지 말고, 생성된 세션 기록을 확인해야 합니다.
작업 단위당 한도 소진량 비교
사용 시간이나 프롬프트 수 대신, 같은 작업 단위당 사용률이 몇 퍼센트포인트 증가했는지 비교합니다.
Frostfire575는 터미널 실행에서 가중 토큰 1.43백만 개를 사용했고 사용률은 5퍼센트포인트 증가했다고 보고했습니다. 헤드리스 실행에서는 가중 토큰 1.32백만 개를 사용했고 11퍼센트포인트 증가했습니다. 보고된 값으로 계산하면 다음과 같습니다.
Headless / terminal = (11 / 1.32) / (5 / 1.43) = 2.38
이 계산이 보고된 2.4× 결과를 설명합니다. 작성자가 정의한 가중 토큰 지표를 사용하며, 해당 비교에만 적용됩니다.
1퍼센트포인트 단위 변화는 짧은 실행을 유의미하게 비교하기에 너무 거칩니다. 필요하면 일반적인 작업을 역순으로 다시 실행합니다. 이때 한도 초기화나 같은 계정의 동시 작업이 겹치지 않도록 해야 합니다.
비용을 추정할 때는 새 세션의 최종 결과를 사용합니다. 재개한 세션의 누적 결과 레코드를 합산하면 안 됩니다. 비용 추적 문서는 토큰 집계와 실제 과금을 구분합니다. total_cost_usd와 modelUsage 모두 구독 사용 한도 측정값이 아닙니다.
캐시 동작을 맞추거나 동시 작업을 없앤 뒤 차이가 사라진다면, 먼저 그 원인부터 조사합니다.
CLAUDE_CODE_ENTRYPOINT를 변경해야 하는가
클라이언트 라벨 변경은 공식 지원이 확인되지 않은 실험으로 취급해야 합니다.
10월 26일 qvarker와 oviano는 자체 도구 이름을 사용했을 때 소진량이 줄었다고 보고했습니다. 각 비교에서는 기본 sdk-cli의 소진량이 약 1.9×–2.4× 높았습니다.
이 보고가 다른 한도 적용을 받는 승인된 방법을 입증하지는 않습니다. 사용자 지정 라벨은 사용량 계산과 관련이 있어 보이는 클라이언트 식별 정보를 바꿉니다. 처리 방식이 바뀔 수 있으며, 정책상 허용 여부도 해결되지 않았습니다.
다른 클라이언트와 같은 대우를 받기 위해 애플리케이션에 cli나 claude-vscode 라벨을 붙이면 안 됩니다. 이 이름들은 서로 다른 클라이언트를 식별합니다.
관련 T3 Code 풀 리퀘스트 #25597는 2026-10-27 확인 당시 열려 있었고 병합되지 않았습니다. 이 PR이 있다는 사실만으로 T3 Code 수정 버전이 출시됐거나 Anthropic이 승인했다고 판단할 수는 없습니다.
대화형 작업은 실제 터미널 클라이언트로 테스트합니다. 구조화된 입력과 출력을 유지해야 하는 자동화라면 API 과금을 검토합니다.
Agent SDK 자동화에는 어떤 잔액이 사용되는가
인증 방식에 따라 작업이 구독 사용 한도를 소진할지, API 크레딧을 사용할지가 결정됩니다.
Anthropic의 10월 7일 과금 업데이트는 Agent SDK, claude -p, 서드파티 앱의 구독 사용을 유지합니다. 연결한 Console 조직의 API 키로 인증하는 자체 실행 SDK 및 claude -p 작업에는 대상 Max·Team API 크레딧도 허용합니다.
다음 잔액과 한도를 구분해야 합니다.
| 과금 경로 | 작업에서 사용하는 항목 |
|---|---|
| Claude 구독 로그인 | 5시간 구간을 포함한 구독 사용 한도 |
| 활성화한 추가 사용, usage credits라고도 부름 | 포함된 한도를 소진한 뒤 별도로 비용을 내고 계속 사용 |
| Anthropic API 키 | Console 조직의 대상 API 크레딧 또는 유료 API 잔액 |
| 독립 API 게이트웨이 | 해당 제공업체의 잔액과 과금 규칙 |
API 과금으로 전환하면 작업이 구독의 5시간 한도에 의존하지 않습니다. 다만 API 레이트 제한, 지출 한도, 사용 가능한 자금은 계속 적용됩니다.
2026-10-27 기준으로 월간 API 크레딧 프로그램은 다음 금액을 안내합니다.
| 대상 요금제 | 월간 API 크레딧 |
|---|---|
| Max 5x | $100 USD |
| Max 20x | $200 USD |
| Team Standard | 시트당 $20 USD |
| Team Premium | 시트당 $100 USD |
Team 크레딧은 하나의 공유 풀로 합쳐지며 최대 $500 USD입니다. Pro는 대상이 아닙니다. 신규 가입자는 대상 요금제를 7일간 유지해야 합니다.
크레딧을 받으려면 Max에서는 Settings > Billing, Team에서는 Organization settings > Billing을 엽니다. API credits 아래에서 Link organization을 선택합니다. 필요한 구독자 또는 소유자 역할과 Console 결제 권한이 있어야 합니다. API 키는 연결한 조직에서 생성합니다.
이 프로그램은 대화형 Claude Code, 추가 사용, Claude Code GitHub Action·IDE 확장 프로그램·Claude 데스크톱 앱이 시작한 실행을 제외합니다. -p를 추가해도 이 제외 조건은 없어지지 않습니다.
Platform 크레딧 문서에 따르면 사용하지 않은 크레딧은 이월되지 않고 만료됩니다. 포함된 크레딧을 구매한 크레딧보다 먼저 사용합니다. 모두 소진하면 구매한 잔액이나 적용 가능한 청구서 결제로 서비스를 계속 사용할 수 있습니다. 그렇지 않으면 요청이 중단됩니다. 구독 사용 한도로 자동 전환되지는 않습니다.
정기 작업을 옮기기 전에 API 과금 확인
작업 대기열을 이전하기 전에 API 키로 직접 한 번 실행하고, Console에 기록된 사용량을 확인합니다.
Anthropic에 직접 접속하도록 설정된 Bash 터미널을 사용합니다. 먼저 기존 ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, 클라우드 제공업체 설정을 확인합니다. 이 설정들이 다른 엔드포인트나 인증 정보 출처를 선택할 수 있습니다.
대상 Console 조직에서 API 키를 생성합니다. 키가 화면에 표시되지 않도록 입력합니다.
read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
claude --bare -p \
--model claude-sonnet-5-5 \
--tools "" \
--max-turns 1 \
--max-budget-usd 1.00 \
--output-format json \
"Reply with exactly OK."프로그래밍 방식 사용 문서는 --bare가 구독 OAuth 인증 정보와 자동으로 발견한 사용자 지정 설정을 건너뛴다고 설명합니다. 따라서 API 점검에 적합합니다. 구독 사용량 비교에 적용하면 인증 경로가 바뀌게 됩니다.
응답이 포함된 성공 JSON 결과가 반환되는지 확인합니다. 그다음 Console에서 올바른 조직의 사용량과 잔액을 확인합니다. CLI 비용 추정값만으로는 프로모션 크레딧이 요청 비용을 지불했는지 입증할 수 없습니다.
인증에 실패하면 API 키와 활성 제공업체를 확인합니다. 잔액이 소진됐으면 Console 결제를 확인합니다. 구독 한도가 남아 있어도 API 레이트 제한이나 지출 한도 오류가 발생하면 해당 제한을 점검해야 합니다.
CLI의 $1.00 예산은 실행 중단을 위한 추정 임계값입니다. 요청 비용이 이를 넘을 수 있으므로 Console에도 적절한 지출 한도를 설정합니다.
예산 계산의 예로, Anthropic의 현재 요금은 claude-sonnet-5-5의 캐시하지 않은 입력 토큰 100만 개당 $2를 안내합니다. 출력 토큰 요금은 100만 개당 $10입니다. 2026-10-27 기준으로 입력 100만 토큰과 출력 100,000 토큰의 추정 토큰 요금은 다음과 같습니다.
(1 × $2) + (0.1 × $10) = $3
이 계산은 표준 동기식 글로벌 라우팅을 사용하고, 캐시와 별도 과금되는 서버 도구를 사용하지 않는다는 가정입니다. 적용되는 세금은 제외합니다. 같은 컨텍스트를 반복한다면 캐시 쓰기와 읽기를 각각의 요율로 계산해야 합니다.
독립 게이트웨이도 다른 선택지입니다. BetterToken의 실시간 카탈로그에는 2026-10-27 기준으로 claude-sonnet-5-5와 claude-opus-5-5가 등록돼 있었습니다. Claude Code 가이드는 본인의 BetterToken 키와 /v1을 붙이지 않은 기본 URL https://bettertoken.ai를 사용합니다. 실제 작업량을 기준으로 현재 요금과 필요한 도구 호환성을 비교합니다. Anthropic에서 제공한 API 크레딧은 이 별도 과금 경로로 이전되지 않습니다.
