컨텍스트 윈도우

대화가 길어지면 결국 컨텍스트 윈도우 한도에 가까워지게 됩니다. 장기 실행 대화와 에이전트 워크플로의 경우, 서버 측 압축이 컨텍스트 관리를 위한 주요 전략입니다.

컨텍스트 윈도우의 작동 방식

"context window"(컨텍스트 윈도우)는 언어 모델이 응답을 생성할 때 참조할 수 있는 모든 텍스트를 의미하며, 응답 자체도 포함됩니다. 이는 언어 모델이 학습한 대규모 데이터 코퍼스와는 다르며, 대신 모델의 "작업 메모리"를 나타냅니다. 더 큰 컨텍스트 윈도우는 모델이 더 복잡하고 긴 프롬프트를 처리할 수 있게 하지만, 컨텍스트가 많다고 해서 자동으로 더 좋은 것은 아닙니다. 토큰 수가 늘어날수록 정확도와 재현율이 저하되는데, 이 현상을 context rot(컨텍스트 부패)이라고 합니다. 따라서 컨텍스트에 무엇을 담을지 선별하는 것이 사용 가능한 공간의 크기만큼이나 중요합니다.

다음 다이어그램은 API 요청에 대한 표준 컨텍스트 윈도우 동작을 보여줍니다¹:

¹ claude.ai와 같은 채팅 인터페이스는 "선입선출" 방식의 롤링 기반으로 컨텍스트 윈도우를 관리할 수도 있습니다.

• 점진적 토큰 누적: 대화가 턴을 거치며 진행됨에 따라 각 사용자 메시지와 어시스턴트 응답이 컨텍스트 윈도우 내에 누적되며, 이전 턴은 완전히 보존됩니다.
• 컨텍스트 윈도우 용량: 컨텍스트 윈도우(모델에 따라 최대 1M 토큰)는 대화 기록과 Claude가 생성하는 새로운 출력을 담습니다.
• 입력-출력 흐름: 각 턴은 다음으로 구성됩니다:
  • 입력 단계: 이전의 모든 대화 기록과 현재 사용자 메시지를 포함합니다
  • 출력 단계: 다음 턴의 입력 일부가 되는 텍스트 응답을 생성합니다

요청에 포함된 모든 것이 컨텍스트 윈도우에 계산됩니다. 시스템 프롬프트, messages의 모든 메시지(도구 결과, 이미지, 문서 포함), 그리고 도구 정의가 여기에 해당합니다. 해당 턴에서 Claude가 생성하는 출력도 확장 사고를 포함하여 계산됩니다. 모든 응답은 usage 필드에 해당 요청이 소비한 양을 보고합니다. 프롬프트 캐싱을 사용하는 경우, 입력 수는 input_tokens, cache_read_input_tokens, cache_creation_input_tokens로 나뉘며, 세 가지 모두 윈도우에 계산됩니다. 요청을 보내기 전에 추정하려면 토큰 카운팅 API를 사용하세요.

모델별 컨텍스트 윈도우 크기

Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6 및 Claude Mythos Preview는 1M 토큰 컨텍스트 윈도우를 갖습니다. 이들 모델 중 어느 모델이든 단일 요청으로 최대 128k 출력 토큰(max_tokens)을 생성할 수 있습니다. Claude Sonnet 4.5를 포함한 다른 Claude 모델은 200k 토큰 컨텍스트 윈도우를 갖습니다.

1M 토큰 컨텍스트 윈도우를 가진 모든 모델에서 1M이 기본값입니다. 베타 헤더가 필요하지 않으며, 긴 컨텍스트 요청은 표준 가격으로 청구됩니다.

단일 요청에는 최대 600개의 이미지 또는 PDF 페이지(200k 토큰 컨텍스트 윈도우를 가진 모델의 경우 100개)를 포함할 수 있습니다. 많은 이미지나 대용량 문서를 보내는 경우, 토큰 한도에 도달하기 전에 요청 크기 한도에 먼저 도달할 수 있습니다.

모델별 컨텍스트 윈도우 크기 목록은 모델 비교 표를 참조하세요.

사고를 사용할 때의 컨텍스트 윈도우

사고를 사용하면 사고 토큰을 포함한 모든 입력 및 출력 토큰이 컨텍스트 윈도우 한도에 계산되며, 멀티턴 상황에서는 몇 가지 미묘한 차이가 있습니다.

사고 토큰은 max_tokens 매개변수의 일부이며, 출력 토큰으로 청구되고, 속도 제한에 계산됩니다. 적응형 사고를 사용하면 Claude가 사고 할당량을 동적으로 결정하므로 사고 토큰 사용량은 요청마다 달라집니다.

이전 어시스턴트 턴의 사고 블록이 컨텍스트 윈도우에 남아 있는지 여부는 모델에 따라 다릅니다. Claude Opus 4.5 및 이후 Opus 모델, Claude Sonnet 4.6 및 이후 Sonnet 모델, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, 그리고 Claude Mythos Preview에서는 API가 기본적으로 이전 사고 블록을 유지하며, 이는 다른 입력 토큰과 마찬가지로 컨텍스트 윈도우에 계산됩니다. 이전 Opus 및 Sonnet 모델과 모든 Haiku 모델에서는 사고 블록을 다시 전달하면 API가 대화 기록에서 이전 사고 블록을 자동으로 제거하여 대화 콘텐츠를 위한 토큰 용량을 보존합니다. 모델별 기본값은 모델별 사고 블록 보존을 참조하세요. 어느 방향으로든 기본값을 재정의하려면 사고 블록 지우기를 사용하세요.

다음 다이어그램은 이전 사고 블록을 제거하는 모델에서 사고가 활성화되었을 때 토큰이 어떻게 관리되는지 보여줍니다:

• 사고 블록 제거: 이전 사고 블록을 제거하는 모델에서는 사고 블록(진한 회색으로 표시)이 각 턴의 출력 단계에서 생성되지만 후속 턴의 입력 토큰으로 이어지지 않습니다. 사고 블록을 직접 제거할 필요는 없습니다. 다시 전달하면 Claude API가 자동으로 제거합니다.
• 청구: 사고 토큰은 생성될 때 한 번 출력 토큰으로 청구됩니다. 이전 사고 블록을 유지하는 모델에서는 유지된 블록이 이후 요청의 입력 일부가 되어 나머지 대화 기록과 마찬가지로 입력 토큰으로 청구됩니다.

사고와 도구 사용을 함께 사용할 때의 컨텍스트 윈도우

다음 다이어그램은 이전 사고 블록을 제거하는 모델에서 사고와 도구 사용을 결합할 때 토큰이 어떻게 관리되는지 보여줍니다:

1. 1

   첫 번째 턴 아키텍처

   • 입력 구성 요소: 도구 구성 및 사용자 메시지
   • 출력 구성 요소: 사고 + 텍스트 응답 + 도구 사용 요청
   • 토큰 계산: 모든 입력 및 출력 구성 요소가 컨텍스트 윈도우에 계산되며, 모든 출력 구성 요소는 출력 토큰으로 청구됩니다.
2. 2

   도구 결과 처리 (턴 2)

   • 입력 구성 요소: 첫 번째 턴의 모든 블록과 tool_result. 해당 도구 결과와 함께 사고 블록을 반드시 반환해야 합니다. 이것이 사고 블록을 반환해야 하는 유일한 경우입니다.
   • 출력 구성 요소: 도구 결과가 Claude에 다시 전달된 후, Claude는 텍스트로만 응답합니다(인터리브 사고가 활성화되지 않은 한, 다음 user 메시지까지 추가 사고 없음).
   • 토큰 계산: 모든 입력 및 출력 구성 요소가 컨텍스트 윈도우에 계산되며, 모든 출력 구성 요소는 출력 토큰으로 청구됩니다.
3. 3

   새로운 사용자 턴 (턴 3)

   • 입력 구성 요소: 이전 턴의 모든 입력과 출력이 이어집니다. 완료된 도구 사용 사이클의 사고 블록은 더 이상 컨텍스트에 남아 있을 필요가 없습니다. 이전 사고 블록을 제거하는 모델에서는 다시 전달하면 API가 자동으로 삭제하고, 이전 사고 블록을 유지하는 모델에서는 사고 블록 지우기로 지우지 않는 한 남아 있습니다. 여기서 다음 user 턴도 추가합니다.
   • 출력 구성 요소: 도구 사용 사이클 외부에 새로운 user 턴이 있으므로, Claude는 새로운 사고 블록을 생성하고 거기서부터 계속합니다.
   • 토큰 계산: 이전 사고 블록을 제거하는 모델에서는 이전 사고 토큰이 더 이상 컨텍스트 윈도우에 계산되지 않습니다. 다른 모든 이전 블록은 여전히 컨텍스트 윈도우에 계산되며, 현재 assistant 턴의 사고 블록도 마찬가지입니다.

• 사고와 함께 도구를 사용할 때의 고려 사항:
  • 도구 결과를 게시할 때는 해당 도구 요청에 수반되는 수정되지 않은 전체 사고 블록을 서명과 함께 포함해야 합니다.
  • API는 암호화 서명을 사용하여 사고 블록의 진위를 검증합니다. 사고 블록을 수정하면 API가 오류를 반환합니다.

도구 정의 자체가 소비하는 컨텍스트를 줄이려면 도구 컨텍스트 관리를 참조하거나, 도구 검색 도구로 도구 정의를 지연 로드하세요.

컨텍스트 인식

Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Haiku 4.5는 context awareness(컨텍스트 인식) 기능을 가지고 있습니다. 이 모델들은 대화 전반에 걸쳐 남은 컨텍스트 윈도우("토큰 예산")를 추적합니다. 이를 통해 모델은 남은 토큰 수를 추측하는 대신 남은 공간에 맞춰 장기 실행 작업을 관리할 수 있습니다. 컨텍스트 인식은 자동입니다. 활성화할 것이 없으며, 이 섹션에 표시된 태그를 직접 보낼 일도 없습니다. API가 이를 주입합니다.

작동 방식

모든 요청의 시스템 프롬프트에서 API는 Claude에게 전체 컨텍스트 윈도우를 알려줍니다:

<budget:token_budget>200000</budget:token_budget>

예산은 요청에 사용 가능한 컨텍스트 윈도우와 일치합니다. Claude Sonnet 5와 Claude Sonnet 4.6의 경우 1M 토큰, Claude Sonnet 4.5와 Claude Haiku 4.5의 경우 200k 토큰입니다. 이 섹션의 예시는 200k 토큰 컨텍스트 윈도우를 가진 모델을 보여줍니다.

각 도구 호출 후, API는 Claude에게 남은 용량에 대한 업데이트를 제공합니다:

<system_warning>Token usage: 35000/200000; 165000 remaining</system_warning>

이미지 토큰도 이 예산에 포함됩니다.

Claude Opus 4.7 및 이후 Opus 모델, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5는 이러한 주입된 태그를 받지 않습니다. 이 모델들에서는 베타 단계인 작업 예산을 사용하여 모델에 명시적인 예산을 제공할 수 있습니다.

컨텍스트 인식 활용에 대한 프롬프트 작성 지침은 프롬프트 작성 모범 사례를 참조하세요.

압축으로 컨텍스트 관리

대화가 정기적으로 컨텍스트 윈도우 한도에 가까워진다면 서버 측 압축을 사용하세요. 압축은 서버에서 대화의 이전 부분을 자동으로 요약하므로, 대화가 컨텍스트 윈도우 한도를 넘어서도 계속될 수 있습니다. Claude 4.6 및 이후 모델과 Claude Mythos Preview에서 베타로 제공됩니다.

보다 특수한 요구 사항의 경우, 컨텍스트 편집이 추가 전략을 제공합니다:

• 도구 결과 지우기: 에이전트 워크플로에서 오래된 도구 결과를 지웁니다
• 사고 블록 지우기: 확장 사고를 사용할 때 사고 블록을 관리합니다

캐시된 프롬프트 접두사도 여전히 컨텍스트 윈도우를 차지합니다. 프롬프트 캐싱은 해당 토큰에 대해 지불하는 비용을 바꿀 뿐, 계산 여부를 바꾸지는 않습니다.

컨텍스트 윈도우 초과 동작

입력만으로 이미 모델의 컨텍스트 윈도우를 초과하는 경우, API는 모든 모델에서 400 invalid_request_error("prompt is too long")를 반환합니다.

Claude 4.5 모델 및 이후 모델에서는 입력 토큰과 max_tokens의 합이 컨텍스트 윈도우 크기를 초과하더라도 API가 요청을 수락합니다. 이후 생성이 컨텍스트 윈도우 한도에 도달하면 stop_reason: "model_context_window_exceeded"로 중지됩니다. 이전 모델에서는 API가 대신 유효성 검사 오류를 반환합니다. 해당 모델에서 model_context_window_exceeded 동작을 선택하려면 model-context-window-exceeded-2025-08-26 베타 헤더를 사용하세요. 자세한 내용은 중지 이유 및 폴백을 참조하세요.

컨텍스트 윈도우 한도 내에 머무르려면 Claude에 메시지를 보내기 전에 토큰 카운팅 API를 사용하여 토큰 사용량을 추정하세요.

다음 단계