Claude Code 1M Context 설정 가이드 - beta header 없이 자동 활성화 하기(Claude Code 1M Context 정식 출시)

안녕하세요! 갓대희 입니다.

오늘은 2026년 3월 13일부로 정식 지원이 시작된 Claude Code의 1M Context 기능에 대해 깊이 있게 알아보려고 한다.

Opus 4.6부터 1M 토큰 컨텍스트 윈도우가 Max, Team, Enterprise 플랜에서 기본 활성화되었다. 추가 요금도 없고, Rate Limit 불이익도 없다. 기존 코드 변경도 필요 없다.

목차

1. 컨텍스트 윈도우란? — 기초부터 이해하기
   • 컨텍스트 윈도우 개념
   • 왜 1M이 필요한가
2. Opus 4.6 1M Context — 무엇이 달라졌나
   • 출시 타임라인
   • 이전 상황 (200K 제한과 beta header)
   • 2026년 3월 13일의 변화
   • 지원 플랜 및 모델
   • 클라우드 플랫폼별 지원 현황 (Bedrock, Vertex AI)
3. 핵심 변경사항 상세 분석
   • 자동 활성화 — beta header 불필요
   • 요금 정책 — 900K도 9K와 같은 단가
   • Rate Limit 정책 변화
   • 성능 벤치마크 — "Context Rot" 해결
4. Claude Code에서의 실제 활용
   • 모델 선택 방법
   • Opus 4.6 vs Sonnet 4.6 — 어떤 모델을 써야 할까?
   • Compaction 동작 변화
   • 대규모 코드베이스 작업
   • Agent Teams와의 시너지
   • Prompt Caching으로 비용·속도 최적화
   • 실전 활용 시나리오
5. 환경변수 설정 완전 가이드
   • CLAUDE_CODE_DISABLE_1M_CONTEXT
   • Compaction 관련 환경변수
   • settings.json 설정 방법
6. 성능 최적화 팁
   • 최적 컨텍스트 크기 (700~800K 권장)
   • Compaction 임계값 튜닝
   • 메모리 관리 전략
7. 주의사항 및 제한
8. 트러블슈팅 Q&A
9. 결론

Claude Code 1M Context 완전 가이드
2026년 3월 13일, Anthropic은 Claude Opus 4.6과 Sonnet 4.6의 1M 토큰 컨텍스트 윈도우를 정식 지원(GA)으로 전환했다.
추가 요금 없이, Rate Limit 불이익 없이, 기존 코드 변경 없이 — Max, Team, Enterprise 사용자라면 오늘부터 바로 1M 컨텍스트를 활용할 수 있다.

 

1. 컨텍스트 윈도우란? — 기초부터 이해하기

컨텍스트 윈도우 개념

컨텍스트 윈도우(Context Window)는 AI 모델이 한 번의 요청에서 처리할 수 있는 텍스트의 최대 크기다. 단위는 토큰(Token)이며, 대략적으로 영어 기준 1토큰 ≈ 0.75단어, 한국어 기준으로는 1토큰 ≈ 0.3~0.5글자 정도로 이해하면 된다.

토큰 크기 체감 예시

• 1K 토큰 ≈ 영어 소설 1~2쪽 분량
• 10K 토큰 ≈ 단편 소설 한 편, 소형 소스 파일 10~15개
• 200K 토큰 ≈ 중편 소설 한 권, 소스 파일 200~300개
• 1M 토큰 ≈ 두꺼운 소설 5~7권, 대규모 모노레포 전체

Claude Code에서는 이 컨텍스트 윈도우에 다음이 모두 포함된다:

• 대화 히스토리: 현재 세션의 모든 질문과 답변
• 읽어들인 파일: 분석하도록 요청한 소스 파일들
• 도구 실행 결과: 실행한 명령어 출력, 검색 결과 등
• 시스템 프롬프트: CLAUDE.md, 설정 파일 내용

 

왜 1M이 필요한가

실제 개발 현장에서는 200K 제한이 자주 걸렸다. 특히 다음 상황에서 컨텍스트 한계에 부딪혔다:

• 대규모 리팩터링: 수십 개 파일을 동시에 분석하며 일관성 있는 변경 필요
• 장기 디버깅 세션: 에러 로그, 스택 트레이스, 연관 코드가 쌓이면 빠르게 한계 도달
• 레거시 코드베이스 이해: 수십만 줄짜리 오래된 코드를 AI에게 파악시키는 작업
• 복잡한 아키텍처 분석: 여러 서비스의 상호작용을 전체적으로 파악하는 작업

Compaction이란?

컨텍스트가 한계에 가까워지면 Claude Code는 자동으로 Compaction(압축)을 수행한다. 이전 대화 내용을 요약하여 토큰을 절약하는 방식인데, 이 과정에서 미묘한 컨텍스트 손실이 발생할 수 있다. 1M 윈도우가 생기면 Compaction이 훨씬 늦게 발생하여, 더 긴 세션을 완전한 컨텍스트 품질로 유지할 수 있다.

 

2. Opus 4.6 1M Context — 무엇이 달라졌나

출시 타임라인

날짜	주요 변화	상태
2025년 8월 (정확한 날짜는 공식 문서 미기재)	Sonnet 4에서 1M 컨텍스트 최초 지원 (beta). 200K 초과 시 프리미엄 요금 부과. beta header 필수.	베타 (프리미엄 요금)
2026년 2월 5일	Claude Opus 4.6 정식 출시. 1M 컨텍스트 베타 지원 시작 (beta header 필요).	베타
2026년 2월 17일	Claude Sonnet 4.6 정식 출시. 1M 컨텍스트 베타 지원 (beta header 필요). Claude Code v2.1.75에서 Max/Team/Enterprise에 Opus 4.6 1M 기본 활성화.	베타 확장
2026년 3월 13일	Opus 4.6 / Sonnet 4.6 1M 컨텍스트 정식 지원(GA). 표준 요금 적용. beta header 불필요. Rate Limit 통합.	GA (정식 지원)

 

이전 상황 — 200K 제한과 beta header

2026년 3월 이전, 1M 컨텍스트를 사용하려면 다음이 필요했다:

# 이전 방식: beta header 필수, 프리미엄 요금 부과
curl https://api.anthropic.com/v1/messages \
  -H "anthropic-beta: context-1m-2025-08-07" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  --data '{
    "model": "claude-opus-4-6",
    "max_tokens": 8096,
    "messages": [...]
  }'

# 200K 토큰 초과 시 프리미엄 요금 적용:
# - Sonnet 4 기준: 입력 $6/MTok, 출력 $22.50/MTok (기존 대비 약 2배)
# - 구 beta 방식은 Sonnet 4, Sonnet 4.5에 여전히 적용됨

 

2026년 3월 13일의 변화

Anthropic은 2026년 3월 13일 릴리스 노트를 통해 세 가지 핵심 변화를 발표했다:

2026년 3월 13일 핵심 변화 3가지

1. beta header 불필요: 200K 초과 요청이 자동으로 동작. 기존 코드 변경 불필요
2. 표준 요금 적용: 900K 토큰 요청도 9K 요청과 동일한 토큰당 단가
3. Rate Limit 통합: 전용 1M Rate Limit 제거. 표준 계정 처리량이 모든 컨텍스트 길이에 동일하게 적용

 

지원 플랜 및 모델

1M 컨텍스트 지원 현황 (2026년 3월 기준):

모델	Max/Team/Enterprise	Pro	API
Opus 4.6	기본 포함	추가 사용량 필요	표준 요금으로 전체 지원
Sonnet 4.6	추가 사용량 필요	추가 사용량 필요	표준 요금으로 전체 지원
Sonnet 4, Sonnet 4.5	구 beta 방식 (header + 프리미엄 요금)	구 beta 방식	구 beta 방식

주의: 구 모델 사용자

Sonnet 4, Sonnet 4.5는 여전히 구 beta 방식을 사용한다. context-1m-2025-08-07 beta header가 필요하고 200K 초과 시 프리미엄 요금이 부과된다. 표준 요금 정책은 Opus 4.6과 Sonnet 4.6에만 적용된다.

 

클라우드 플랫폼별 지원 현황

1M context는 Anthropic 직접 API 외에 주요 클라우드 플랫폼에서도 지원된다. 단, 플랫폼별로 처리량(throughput) 제약이 다르다:

플랫폼	모델 ID	1M 처리량	비고
Anthropic API	claude-opus-4-6	표준 계정 처리량 (Rate Limit 통합)	beta header 불필요. GA 표준 요금
AWS Bedrock	us.anthropic.claude-opus-4-6-v1 eu.anthropic.claude-opus-4-6-v1	~5 req/min 수준 (1M context preview 클래스, 추정) 표준 클래스: ~500 req/min. 계정·리전별 상이	1M은 Preview 티어. AWS Bedrock Quotas에서 계정별 실제 한도 확인 필요하다.
Google Vertex AI	claude-opus-4-6	200 QPM, 2M input TPM (리전당)	us-east5, europe-west1, asia-southeast1 지원

Bedrock 사용자 주의

AWS Bedrock에서 Opus 4.6의 1M context는 현재 "preview" 클래스로 제공되며, 처리량이 표준 클래스 대비 크게 낮은 것으로 알려져 있다(계정·리전별 상이, 위 표 참고). 프로덕션에서 대규모 1M context 요청이 필요하다면 Google Vertex AI를 우선 검토하거나 Anthropic 직접 API 사용을 권장한다.

 

3. 핵심 변경사항 상세 분석

자동 활성화 — beta header 불필요

가장 실용적인 변화는 기존 코드를 전혀 수정하지 않아도 1M 컨텍스트가 동작한다는 점이다.

# 2026년 3월 13일 이후: 동일한 코드로 1M 컨텍스트 자동 동작
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --data '{
    "model": "claude-opus-4-6",
    "max_tokens": 8096,
    "messages": [
      {
        "role": "user",
        "content": "... 90만 토큰짜리 대용량 콘텐츠 ..."
      }
    ]
  }'
# beta header 없이 자동으로 1M 컨텍스트 처리
# AWS Bedrock: anthropic.claude-opus-4-6-v1
# Vertex AI: claude-opus-4-6

Claude Code 사용자는 이미 자동 적용

Claude Code를 사용 중이라면 별도 설정 없이 이미 1M 컨텍스트가 활성화되어 있다. Claude Code v2.1.75부터 Max, Team, Enterprise 사용자에게는 Opus 4.6의 1M 컨텍스트가 기본 적용된다. 직접 확인하려면 세션 중 상태 표시줄에서 사용 중인 토큰 수를 확인하면 된다.

 

요금 정책 — 900K도 9K와 같은 단가

가장 큰 실용적 변화 중 하나가 요금이다. Anthropic의 공식 문서에 따르면:

공식 요금 정책 (2026년 3월 13일 기준)

900K 토큰 요청과 9K 토큰 요청은 동일한 토큰당 단가로 청구된다. 더 이상 대용량 컨텍스트에 대한 프리미엄 배율이 없다.

• Opus 4.6 API: 입력 $5/MTok, 출력 $25/MTok (전체 컨텍스트 범위 동일)
• Sonnet 4.6 API: 입력 $3/MTok, 출력 $15/MTok (전체 컨텍스트 범위 동일)

출처: Anthropic 공식 가격 문서 (platform.claude.com/docs/en/about-claude/pricing). 요금은 변경될 수 있으므로 최신 공식 문서를 확인하세요.

 

Claude Code 구독자에게는?

Max, Team, Enterprise 플랜의 Claude Code 구독자에게는 추가 토큰 비용이 발생하지 않는다. 구독 플랜의 사용량 한도 내에서 1M 컨텍스트를 자유롭게 사용할 수 있다. Pro 플랜은 1M 컨텍스트 사용 시 추가 사용량이 필요할 수 있다.

 

Rate Limit 정책 변화

이전에는 1M 컨텍스트 사용 시 별도의 Rate Limit이 적용되어, 대용량 요청 시 처리량이 감소하는 문제가 있었다. 2026년 3월 13일 이후:

• 전용 1M Rate Limit 제거: 더 이상 별도의 대용량 컨텍스트 Rate Limit이 없다
• 표준 계정 처리량 적용: 모든 컨텍스트 길이에 동일한 Rate Limit이 적용된다
• 실질적 의미: 900K 토큰 요청과 9K 토큰 요청이 같은 Rate Limit 풀을 공유한다

Rate Limit이 '같아진' 것의 의미

Rate Limit이 "처리량 감소 없이 동일하게 적용된다"는 것은, 대용량 컨텍스트 요청이 기존 처리량에서 불이익을 받지 않는다는 의미다. 단, 900K 토큰 요청 하나가 토큰 기준 Rate Limit을 많이 소모한다는 물리적 사실은 변하지 않는다. RPM(분당 요청 수) 기준으로는 동일하게 카운트된다.

 

성능 벤치마크 — "Context Rot" 해결

단순히 컨텍스트 크기만 늘어난 것이 아니다. Anthropic은 Opus 4.6이 대용량 컨텍스트에서도 실제로 높은 정확도를 보임을 벤치마크로 입증했다.

https://pbs.twimg.com/media/HDTovvJaMAI8jWP?format=png&name=medium

벤치마크	Opus 4.6	주요 비교 모델
1M 8-needle MRCR v2 (1M 컨텍스트 내 8개 항목 검색)	78.3% 프론티어 모델 중 최고 (출처: 1M Context GA 블로그)	Claude Sonnet 4.5: 18.5% Gemini 3 Pro: 26.3% (출처: Anthropic Opus 4.6 공식 발표)
Terminal-Bench 2.0 (터미널 기반 코딩 작업)	65.4% (max effort, Anthropic 공식) 공개 리더보드 최고: 81.8% (ForgeCode + Opus 4.6)	GPT-5.2-Codex: 57.5% Opus 4.5: 59.8%

특히 1M 8-needle MRCR v2 벤치마크는 중요하다. 100만 토큰짜리 텍스트 속에 숨겨진 8개의 정보를 찾아내는 테스트인데, Opus 4.6이 78.3%를 기록한 반면 Claude Sonnet 4.5는 18.5%, Gemini 3 Pro는 26.3%에 그쳤다. 이는 "Context Rot"(컨텍스트가 길어질수록 정확도가 떨어지는 현상)이 Opus 4.6에서 크게 개선되었음을 보여준다. (출처: Anthropic 공식 Opus 4.6 발표 및 1M Context GA 블로그)

벤치마크 vs 실전 주의사항

MRCR v2 벤치마크는 단일 API 호출로 전체 1M 토큰을 한 번에 주입하는 방식이다. Claude Code는 파일을 도구(Tool)로 순차적으로 읽는 방식이라 실제 동작이 다를 수 있다. 커뮤니티 보고에 따르면 툴 기반 읽기 방식에서는 200K+ 구간 이후 정확도가 낮아지는 경우가 있으므로, 중요한 정보는 세션 초반에 로드하는 것이 좋다.

 

4. Claude Code에서의 실제 활용

 - 진행전 내 클로드 코드 버전 체크 

> claude --version

2.1.76 (Claude Code)

 

 - 현재 모델 및 컨텍스트 윈도우 크기 확인

ex) 200k

ex) model : opusplan

 

 - /model : 변경 가능한 모델 확인

 - 선택 후 Opus 4.6 (1M context) 가 선택되었다고 표현된다.

 - Opus 4.6에서 defaultfh 백만 context 윈도우로 변경된것을 볼 수 있다.

 

모델 선택 방법

Claude Code에서 1M 컨텍스트 모델을 명시적으로 선택하려면.

# 세션 내에서 1M 모델로 전환
/model opus[1m]

# 또는 전체 모델 ID 사용 (공식 모델 ID: claude-opus-4-6)
/model claude-opus-4-6[1m]

# Sonnet 4.6 1M 모델 (추가 사용량 필요)
/model sonnet[1m]

# 특정 모델 ID 고정 시 (안정적 동작 보장)
# opus/sonnet 별칭은 최신 버전으로 자동 업데이트됨
# claude-opus-4-6 고정 사용을 원한다면 env var 활용:
# ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6

# 현재 사용 중인 모델 확인
/model

Max/Team/Enterprise 사용자는 자동 적용

Claude Code v2.1.75 이상을 사용 중이고 Max, Team, Enterprise 플랜이라면 별도 선택 없이 Opus 4.6의 1M 컨텍스트가 기본 활성화된다. /model 명령어로 현재 설정을 확인할 수 있다.

 

Opus 4.6 vs Sonnet 4.6 — 어떤 모델을 써야 할까?

두 모델 모두 1M context를 지원하지만 특성이 다르다. Anthropic 공식 권장 가이드라인에 따르면:

상황	Opus 4.6 권장	Sonnet 4.6 권장
대규모 코드베이스 리팩터링	O	-
다중 에이전트 워크플로우 코디네이션	O	-
과학·수학적 추론, 전문가급 분석	O	-
Max output 128K 필요	O (Opus만 128K)	X (최대 64K)
일반 코딩, 버그 수정, 기능 구현	-	O
인터랙티브 UX, 빠른 응답 필요	-	O
지식 커트오프 (참고용)	훈련 데이터: 2025년 8월	훈련 데이터: 2026년 1월 (공식 Transparency Hub 확인 권장)
API 단가 (입력/출력)	$5 / $25 MTok	$3 / $15 MTok

권장 전략: Sonnet 기본, Opus로 에스컬레이션

Anthropic 공식 권장은 Sonnet 4.6으로 시작해서 복잡한 아키텍처 판단, 다중 에이전트 코디네이션, 고위험 작업 시에만 Opus 4.6으로 전환하는 전략이다. Claude Code에서는 /model sonnet, /model opus[1m]으로 손쉽게 전환할 수 있다. (출처: Anthropic 공식 모델 선택 가이드)

 

Compaction 동작 변화

1M 컨텍스트 도입 후 가장 체감되는 변화 중 하나가 Compaction 빈도다:

• 200K 모델: 기본적으로 ~190K 토큰 사용 시 Compaction 발생 (95% 임계값)
• 1M 모델: 기본적으로 ~950K 토큰 사용 시 Compaction 발생
• 실질 효과: 대부분의 코딩 세션에서 Compaction 없이 작업을 완료할 수 있다

Claude Code의 상태 표시줄에서 현재 컨텍스트 사용량을 확인할 수 있다. context_window.used_percentage는 모델의 전체 윈도우 대비 입력 토큰 비율을 보여준다.

 

대규모 코드베이스 작업

1M 컨텍스트의 가장 강력한 활용처는 대규모 코드베이스 작업이다:

 

전체 프로젝트 파악

# 대규모 레포 전체를 한 번에 분석
"이 프로젝트의 모든 소스 파일을 읽고 아키텍처를 파악해줘.
특히 데이터 흐름과 의존성 관계를 중점적으로 분석해줘."

# 이전에는 파일 수가 많으면 중간에 컨텍스트가 부족해졌다.
# 1M 컨텍스트로 수백 개 파일을 한 번에 처리할 수 있다.

 

장기 리팩터링 세션

# 여러 파일에 걸친 일관된 리팩터링
"src/ 디렉토리 전체의 클래스명을 새 네이밍 컨벤션으로 바꿔줘.
변경 전후의 일관성을 확인하면서 진행해줘."

# 수십 개 파일을 동시에 염두에 두고 일관성 있게 작업 가능

 

Agent Teams와의 시너지

Opus 4.6 출시와 함께 Claude Code에 Agent Teams(에이전트 팀)가 리서치 프리뷰로 추가되었다. 1M 컨텍스트와 Agent Teams의 조합은 특히 강력하다:

• 병렬 코드베이스 리뷰: 여러 서브에이전트가 동시에 코드를 분석하고, 결과를 1M 컨텍스트로 통합
• 읽기 중심 작업의 병렬화: 문서 분석, 테스트 결과 수집 등 읽기 작업을 병렬로 처리
• 서브에이전트도 1M 적용: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE가 메인 세션과 모든 서브에이전트에 동일하게 적용된다

 

Prompt Caching으로 비용·속도 최적화

1M 컨텍스트의 실질적인 단점인 응답 지연(TTFT)과 반복 비용을 해결하는 핵심 기법이 Prompt Caching이다. Opus 4.6에서 완전 지원되며, 대용량 컨텍스트 환경에서 효과가 극대화된다:

캐시 유형	요금 (Opus 4.6 기준)	효과
캐시 쓰기 (5분 TTL)	$6.25/MTok (기본의 1.25배)	최초 1회 캐싱 비용
캐시 쓰기 (1시간 TTL)	$10/MTok (기본의 2배)	장기 세션에서 유리
캐시 읽기	$0.50/MTok (기본의 10%)	90% 비용 절감, 85% 레이턴시 절감

Prompt Caching의 핵심 장점 — Rate Limit 면제

cache_read_input_tokens는 ITPM(분당 입력 토큰 수) Rate Limit에 산입되지 않는다. 80% 캐시 히트율 기준으로 실질 처리량이 최대 5배 증가한다. 대규모 코드베이스를 반복 참조하는 세션에서는 Rate Limit 걱정 없이 여러 요청을 보낼 수 있다.

# Prompt Caching 설계 권장 순서 (안정 → 가변)
# 1. tools 정의 (가장 안정적 — 캐시 히트율 최고)
# 2. system 프롬프트 (CLAUDE.md 내용 등)
# 3. 대용량 정적 문서 (코드베이스, 레퍼런스)
# 4. 동적 사용자 입력 (가장 마지막)

# cache_control 마킹 예시 (API 직접 사용 시)
{
  "system": [
    {
      "type": "text",
      "text": "... 대용량 시스템 프롬프트 ...",
      "cache_control": {"type": "ephemeral", "ttl": 3600}
    }
  ]
}
# Claude Code에서는 자동으로 캐싱 적용됨 (별도 설정 불필요)

실전 활용 시나리오

시나리오 1: 레거시 시스템 현대화

10년 된 레거시 PHP 코드베이스를 현대적인 Python으로 전환하는 작업. 전체 소스 파일(약 300개, 50만 토큰)을 컨텍스트에 올려두고 일관성 있는 마이그레이션 계획을 수립할 수 있다.

시나리오 2: 대규모 버그 추적

수만 줄의 에러 로그, 관련 소스 파일, 이전 수정 히스토리를 모두 컨텍스트에 올려두고 근본 원인을 분석. 이전에는 로그를 일부만 잘라서 제공해야 했다면, 이제는 전체 로그를 제공할 수 있다.

시나리오 3: 장기 기능 개발

새로운 기능을 여러 파일에 걸쳐 개발할 때, Compaction 없이 수 시간의 세션을 유지할 수 있다. Claude가 초반에 논의한 설계 결정을 끝까지 기억하며 일관성을 유지한다.

 

5. 환경변수 설정 완전 가이드

Claude Code는 1M 컨텍스트와 관련된 여러 환경변수를 제공한다.

(출처: Claude Code 공식 환경변수 문서)

 

CLAUDE_CODE_DISABLE_1M_CONTEXT

1M 컨텍스트를 비활성화하는 opt-out 환경변수다.

항목	내용
변수명	CLAUDE_CODE_DISABLE_1M_CONTEXT
값	1 (비활성화), 미설정 (활성화)
효과	1M 컨텍스트 지원 비활성화. 모델 선택기에서 [1m] 모델 변형 제거
주요 용도	기업 컴플라이언스 요구사항, 비용 예측 가능성 확보, 규제 환경에서의 대용량 컨텍스트 제한

# 방법 1: 쉘 환경변수로 설정 (해당 세션에만 적용)
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1
claude

# 방법 2: settings.json에 영구 설정 (모든 세션에 적용)
# ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1"
  }
}

# 방법 3: 프로젝트별 설정 (해당 프로젝트에만 적용)
# .claude/settings.local.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1"
  }
}

 

Compaction 관련 환경변수

1M 컨텍스트를 완전히 끄지 않고 Compaction 동작만 조정하려면 다음 변수들을 활용한다.

 

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE

자동 Compaction 트리거 임계값을 백분율로 설정한다.

# 기본값: 95% (950K/1M 토큰에서 Compaction 발생)
# 더 일찍 Compaction하려면 낮은 값 설정

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70
# 1M 모델에서 700K 토큰(70%) 도달 시 Compaction

# settings.json에 영구 설정
{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "70"
  }
}

 

CLAUDE_CODE_AUTO_COMPACT_WINDOW

Compaction 계산에 사용할 토큰 윈도우 크기를 직접 지정한다. 기본값은 모델의 실제 컨텍스트 윈도우 크기다.

# 1M 모델을 사용하지만 Compaction은 500K 기준으로 트리거
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=500000

# 95% 임계값 기준: 475K 토큰에서 Compaction 발생
# 단: 상태 표시줄은 여전히 1M 대비 % 표시 (약 47.5%에서 compaction)

# settings.json에 영구 설정
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "500000"
  }
}

두 변수의 조합 공식

Compaction 트리거 토큰 수 = CLAUDE_CODE_AUTO_COMPACT_WINDOW × CLAUDE_AUTOCOMPACT_PCT_OVERRIDE / 100

• 기본 (1M 모델): 1,000,000 × 0.95 = 950,000 토큰에서 Compaction
• 보수적 설정 (window=500K, pct=70): 500,000 × 0.70 = 350,000 토큰에서 Compaction

 

CLAUDE_CODE_MAX_OUTPUT_TOKENS

최대 출력 토큰 수를 설정한다. 이 값을 높이면 응답이 길어지지만, 동시에 Compaction이 더 빨리 발생할 수 있다.

# settings.json 전체 설정 예시 (보수적 long-session 프로파일)
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "700000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75"
  }
}
# 결과: 525K 토큰에서 Compaction 발생 (안전한 여유 확보)

 

settings.json 설정 방법

환경변수는 여러 범위(scope)에서 설정할 수 있다:

파일 위치	적용 범위	용도
~/.claude/settings.json	모든 프로젝트, 모든 세션	사용자 전역 설정
.claude/settings.json	해당 프로젝트의 모든 사용자	팀 공유 설정 (git 커밋 가능)
.claude/settings.local.json	해당 프로젝트의 본인만	로컬 개인 설정 (.gitignore 권장)

 

6. 성능 최적화 팁

최적 컨텍스트 크기 — 700~800K 권장

GeekNews 등 개발자 커뮤니티에서는 1M 풀로 사용하는 것보다 700~800K 수준에서 끊어 쓰는 것이 좋다는 경험적 의견이 있다. 이유는 다음과 같다:

• 안전 마진 확보: 900K 이상에서는 예상치 못한 컨텍스트 한계 도달 위험이 있다
• 응답 속도: 컨텍스트가 클수록 응답 생성 시간이 늘어날 수 있다
• Compaction 품질: 극단적으로 큰 컨텍스트의 Compaction은 더 많은 정보 손실을 초래할 수 있다

커뮤니티 팁: 700~800K 실전 설정

이 설정은 커뮤니티의 경험적 조언이며, Anthropic 공식 권장사항은 아니다. 개인의 워크플로우에 따라 최적값이 다를 수 있다.

# 700~800K에서 Compaction 발생하도록 설정
# settings.json
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "800000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "88"
  }
}
# 결과: 800K × 0.88 = 704K 토큰에서 Compaction 발생

# 대안: 직접 700K로 설정
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "700000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "100"
  }
}

 

Compaction 임계값 튜닝

워크로드 특성에 따라 다른 설정이 적합하다:

시나리오	권장 설정	이유
빠른 단기 작업	기본값 (95%)	Compaction 최소화, 대부분 완료 전에 한도 도달 안 함
장기 코딩 세션	70~80%	안전 마진 확보, Compaction 품질 향상
기업/컴플라이언스 환경	DISABLE_1M=1 또는 낮은 COMPACT_WINDOW	대용량 컨텍스트 사용 제한
Agent Teams 운영	80~85%	서브에이전트에도 동일 적용, 안정적 운영

 

메모리 관리 전략

1M 컨텍스트를 효율적으로 사용하기 위한 실전 팁:

• CLAUDE.md 활용: 프로젝트 구조, 핵심 컨벤션을 CLAUDE.md에 기록하여 매번 컨텍스트를 낭비하지 않는다
• 점진적 파일 로딩: 관련 파일만 필요할 때 읽도록 요청한다. 처음부터 모든 파일을 로드하면 컨텍스트를 낭비한다
• 세션 분리: 논리적으로 독립적인 작업은 별도 세션에서 진행한다
• 컨텍스트 확인: 상태 표시줄에서 정기적으로 컨텍스트 사용량을 확인한다

 

7. 주의사항 및 제한

중요: 문서 불일치 주의

2026년 3월 16일 현재, Anthropic의 일부 문서(특히 Help Center FAQ)가 최신 상태를 반영하지 않고 있다. FAQ는 아직 일부 Max 20x 사용자에게만 제한적으로 제공된다고 표시하지만, 플랫폼 릴리스 노트와 실제 서비스는 이미 GA 상태다. 최신 정보는 릴리스 노트를 기준으로 확인하자.

 

현재 알려진 제한사항

• 플랜 제한: Max, Team, Enterprise 플랜에서 Opus 4.6 1M이 기본 포함. Pro는 추가 사용량 필요
• 모델 제한: 표준 요금 1M 컨텍스트는 Opus 4.6과 Sonnet 4.6만 해당. 구 모델(Sonnet 4, 4.5)은 여전히 beta 방식
• 응답 속도: 컨텍스트가 클수록 첫 응답 토큰까지의 지연(TTFT)이 증가할 수 있다
• 미디어 제한: 1M 컨텍스트 사용 시 요청당 최대 600개의 이미지 또는 PDF 페이지를 포함할 수 있다
• Compaction 주의: 950K 이상에서 발생하는 Compaction은 더 많은 정보 손실을 초래할 수 있으므로, 미리 적절한 임계값을 설정하는 것이 좋다
• 출력 토큰과의 관계: CLAUDE_CODE_MAX_OUTPUT_TOKENS를 높이면 Compaction이 더 빨리 발생한다 (입력 공간이 줄어들기 때문)

Compaction Loop 주의

200K 컨텍스트 예산을 초과한 후 긴 세션에서 잘못된 Compaction Loop가 발생한다는 커뮤니티 보고가 있었다. 임계값을 극단적으로 조정하는 경우 테스트 환경에서 먼저 검증하는 것을 권장한다.

 

8. 트러블슈팅 Q&A

Q1. 1M 컨텍스트가 활성화되어 있는지 어떻게 확인하나요?

방법 1: 세션 내에서 /model 명령어를 실행하면 현재 사용 중인 모델과 컨텍스트 윈도우 크기를 확인할 수 있다. [1m] 모델이 표시되면 1M 컨텍스트가 활성화된 것이다.

방법 2: 상태 표시줄에서 컨텍스트 사용량을 확인한다. 200K 이상을 사용해도 Compaction이 발생하지 않으면 1M 모델이 활성화된 것이다.

# 세션 내에서 현재 모델 확인
/model

# 환경변수 확인
cat ~/.claude/settings.json | jq '.env'

Q2. Pro 플랜인데 1M 컨텍스트를 사용할 수 없습니다

원인: Pro 플랜에서 Opus 4.6 1M 컨텍스트는 추가 사용량이 필요하다. Max, Team, Enterprise 플랜에서만 기본 포함이다.

해결:

• Max 플랜으로 업그레이드 검토
• API를 직접 사용하는 경우 표준 요금으로 1M 컨텍스트 사용 가능
• Pro에서 사용 가능한 범위 내에서 Sonnet 4.6 활용 검토

Q3. 200K도 안 됐는데 Compaction이 발생합니다

원인 1: CLAUDE_CODE_AUTO_COMPACT_WINDOW가 낮게 설정되어 있을 수 있다.

원인 2: CLAUDE_AUTOCOMPACT_PCT_OVERRIDE가 매우 낮게 설정되어 있을 수 있다.

원인 3: 상태 표시줄의 %는 모델의 전체 윈도우 대비 비율이다. CLAUDE_CODE_AUTO_COMPACT_WINDOW를 낮게 설정한 경우, 표시줄이 낮은 %를 보여줘도 Compaction이 발생할 수 있다.

# 현재 compaction 관련 설정 확인
cat ~/.claude/settings.json | jq '.env | {
  CLAUDE_AUTOCOMPACT_PCT_OVERRIDE,
  CLAUDE_CODE_AUTO_COMPACT_WINDOW
}'

Q4. 기업 환경에서 1M 컨텍스트를 제한하고 싶습니다

방법 1: 완전 비활성화

# 관리형 설정을 통해 모든 사용자에게 1M 비활성화
# managed settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1"
  }
}

방법 2: 특정 임계값으로 제한 (1M 모델은 유지하되 조기 Compaction)

{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "90"
  }
}
# 효과: 180K 토큰에서 Compaction 발생 (실질적 200K 제한)

Anthropic은 CLAUDE_CODE_DISABLE_1M_CONTEXT가 "기업 컴플라이언스 요구사항에 유용하다"고 공식 문서에 명시하고 있다.

Q5. Sonnet 4.5에서 1M 컨텍스트를 표준 요금으로 사용할 수 있나요?

아니다. 표준 요금 1M 컨텍스트는 Opus 4.6과 Sonnet 4.6에만 해당한다. Sonnet 4와 Sonnet 4.5는 여전히 구 beta 방식을 사용하며, context-1m-2025-08-07 beta header가 필요하고 200K 초과 시 프리미엄 요금이 부과된다.

Q6. 1M 컨텍스트를 사용하면 응답이 느려지나요?

대용량 컨텍스트를 처리할 때 첫 응답 토큰까지의 지연(TTFT, Time To First Token)이 증가할 수 있다. 이는 모델이 더 많은 텍스트를 처리해야 하기 때문이다.

실제 응답 속도는 컨텍스트 크기, 서버 부하, 요청의 복잡도에 따라 달라진다. 컨텍스트가 크더라도 이전에 캐시된 부분은 빠르게 처리된다 (Anthropic의 Prompt Caching 활용).

설정 변경 시 주의사항

• settings.json 수정 전에 반드시 백업을 생성한다 (cp ~/.claude/settings.json ~/.claude/settings.json.backup)
• 환경변수 변경 후에는 Claude Code를 재시작해야 적용된다
• 극단적인 임계값 설정은 테스트 환경에서 먼저 검증한다

 

9. 결론

Claude Code의 1M 컨텍스트 정식 지원은 단순한 숫자의 증가가 아니다. 이는 개발자가 AI와 협업하는 방식을 근본적으로 바꾸는 변화다.

이전에는 "컨텍스트가 금방 찰 것 같으니 파일 몇 개만 보여줄게"라고 신중하게 제약을 걸었다면, 이제는 "레포 전체를 보면서 파악해줘"라고 자연스럽게 요청할 수 있다.

핵심 요약

• 자동 활성화: Max, Team, Enterprise 사용자는 별도 설정 없이 Opus 4.6 1M 컨텍스트 자동 적용
• 추가 요금 없음: 900K 토큰 요청도 9K 요청과 동일한 토큰당 단가
• Rate Limit 동일: 대용량 컨텍스트 사용 시 처리량 불이익 없음
• 기존 코드 그대로: beta header 없이도 자동으로 1M 컨텍스트 동작
• Opt-out 가능: CLAUDE_CODE_DISABLE_1M_CONTEXT=1로 비활성화
• 최적 활용: 700~800K 수준에서 사용하면 안전 마진과 성능 균형

Opus 4.6의 78.3% MRCR v2 벤치마크 성능이 보여주듯, 1M 컨텍스트는 단순히 더 많이 넣는 것이 아니라 더 깊이 이해하는 것을 가능하게 한다. 대규모 코드베이스를 다루는 개발자라면 지금 바로 활용해 보자.

시작하기

Max, Team, Enterprise 플랜이라면 Claude Code v2.1.75 이상을 설치하면 바로 1M 컨텍스트가 활성화된다. /model로 현재 모델을 확인하고, 상태 표시줄에서 컨텍스트 사용량을 모니터링하면서 활용해 보자.

공식 문서: 환경변수 레퍼런스 | 모델 설정 | 릴리스 노트