클로드 API 컨텍스트 창 정리, 모델별 100만 토큰과 사고·도구 사용 시 계산 방식 (2026년 10월 기준)

클로드 API에서 컨텍스트 창은 모델이 한 번의 응답을 만들 때 참조할 수 있는 전체 텍스트의 한도입니다. 이 글은 2026년 10월 25일 공식 컨텍스트 창 문서를 기준으로, 무엇이 컨텍스트 창에 들어가는지, 모델별 크기, 사고와 도구 사용이 있을 때 계산 방식, 한도를 넘을 때 동작, 긴 대화를 관리하는 방법을 정리했습니다.

이 글은 공식 문서를 읽고 정리한 글이고, 직접 호출해 본 결과는 아닙니다. 모델 목록과 한도는 바뀔 수 있으므로 쓰기 전에 공식 문서의 모델 비교표를 다시 확인해야 합니다.

컨텍스트 창이란

문서는 컨텍스트 창을 모델이 응답을 만들 때 참조할 수 있는 모든 텍스트로 설명하며, 응답 자체도 포함됩니다. 모델이 학습한 방대한 자료와는 다른 개념이고, 모델의 작업 기억에 가깝다는 설명입니다.

창이 크다고 항상 좋은 것은 아닙니다. 문서는 토큰이 늘어날수록 정확도와 회상 능력이 떨어질 수 있다고 하며, 이를 컨텍스트 부패라고 부릅니다. 그래서 얼마나 많이 넣을 수 있는지만큼 무엇을 넣을지 고르는 것도 중요하다고 안내합니다.

대화가 길어질수록 이전 턴의 사용자 메시지와 응답이 모두 쌓여 다음 요청의 입력이 됩니다. 한 번의 요청은 입력 단계와 출력 단계로 나뉘고, 출력은 다음 턴의 입력에 들어갑니다.

컨텍스트 창에 들어가는 것

문서에 따르면 요청의 모든 요소가 컨텍스트 창에 들어갑니다.

• 시스템 프롬프트
• messages의 모든 메시지(도구 결과, 이미지, 문서 포함)
• 도구 정의
• Claude가 만든 출력(확장 사고 포함)

응답의 usage 항목에서 이번 요청이 얼마나 썼는지 알 수 있습니다. 프롬프트 캐싱을 쓰면 입력 토큰이 input_tokens, cache_read_input_tokens, cache_creation_input_tokens 세 가지로 나뉘는데, 세 가지 모두 컨텍스트 창에 들어갑니다. 캐싱은 토큰의 비용을 바꿀 뿐 컨텍스트 창을 차지하는지는 바꾸지 않습니다. 캐싱 구조는 프롬프트 캐싱 글에 있습니다. 보내기 전에 토큰 수를 어림하는 방법은 API 토큰 수 미리 세기 글에서 다룹니다.

모델별 크기

문서가 100만 토큰 컨텍스트 창을 가진 모델로 드는 목록은 다음과 같습니다.

• 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.5, Claude Sonnet 5, Claude Sonnet 4.6
• Claude Haiku 5.5, Claude Mythos Preview

이 모델들은 한 번의 요청에서 최대 12만 8천 출력 토큰까지 만들 수 있습니다. 그 밖의 모델은 Claude Sonnet 4.5(지원 중단 예정)를 포함해 20만 토큰 컨텍스트 창입니다.

100만 토큰 모델은 100만이 기본값이라 별도의 베타 헤더가 필요 없습니다. 긴 컨텍스트 요청도 표준 요금으로 청구되지만, Claude Haiku 5.5는 프롬프트가 10만 토큰을 넘으면 요금이 더 높습니다. 한 요청에는 이미지나 PDF 쪽수를 최대 600개까지 넣을 수 있고, 20만 토큰 모델은 100개입니다. 이미지와 문서가 많으면 토큰 한도보다 요청 크기 한도에 먼저 닿을 수 있습니다.

사고가 있을 때의 계산

확장 사고를 쓰면 사고 토큰도 입력과 출력에 모두 포함되어 컨텍스트 창에 들어갑니다. 문서는 사고 토큰이 max_tokens의 일부이고, 출력 토큰으로 청구되며, 호출 한도에도 포함된다고 설명합니다. 적응형 사고에서는 Claude가 사고 양을 요청마다 다르게 정하므로 사용량이 달라집니다. 한도 계산은 API 속도 제한 글에서 다룹니다.

이전 턴의 사고 블록을 컨텍스트에 남기는지는 모델에 따라 다릅니다.

• Claude Opus 4.5 이후 Opus 모델, Claude Sonnet 4.6 이후 Sonnet 모델, Claude Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview는 이전 사고 블록을 기본으로 유지하며, 다른 입력과 똑같이 컨텍스트 창에 들어갑니다.
• 이전 Opus와 Sonnet 모델, Claude Haiku 4.5까지의 Haiku 모델은 이전 사고 블록을 API가 자동으로 제거합니다.

사고 토큰은 만들어질 때 출력 토큰으로 한 번 청구되고, 이전 사고 블록을 유지하는 모델에서는 이후 요청의 입력으로 다시 청구됩니다. 이 기본값은 사고 블록 지우기 기능으로 바꿀 수 있습니다.

사고와 도구 사용을 함께 쓸 때

도구 사용 중에는 도구 결과를 돌려보낼 때 해당 요청에 딸린 사고 블록을 서명까지 포함해 수정 없이 함께 보내야 한다고 문서가 안내합니다. 사고 블록을 수정하면 API가 오류를 반환합니다. 사고 블록을 돌려보내야 하는 경우는 이때뿐입니다.

새 사용자 턴이 시작되면 지난 도구 사용 사이클의 사고 블록은 더 이상 컨텍스트에 남아 있을 필요가 없습니다. 이전 사고 블록을 제거하는 모델에서는 API가 자동으로 빼고, 유지하는 모델에서는 사고 블록 지우기를 하지 않는 한 남습니다.

도구 정의 자체가 컨텍스트를 많이 차지하면 도구 컨텍스트 관리 문서나 도구 검색 도구로 정의를 뒤로 미루는 방법이 있다고 안내합니다.

컨텍스트 인식

Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5(지원 중단 예정), Claude Haiku 4.5는 남은 컨텍스트 창을 스스로 추적하는 컨텍스트 인식 기능이 있습니다. 켤 필요 없이 자동이고, API가 시스템 프롬프트에 전체 토큰 예산을 넣고 도구 호출 뒤마다 남은 용량을 알려 줍니다. 사용자가 이 태그를 직접 보내는 것은 아닙니다.

Claude Opus 4.7 이후 Opus 모델, Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Haiku 5.5는 이 태그를 받지 않습니다. 이 모델들에는 베타 상태인 작업 예산 기능으로 명시적인 예산을 줄 수 있다고 문서가 안내합니다.

긴 대화를 관리하는 방법

대화가 컨텍스트 창 한도에 자주 가까워진다면 서버 측 압축을 쓰라고 문서가 권합니다. 이전 대화를 서버에서 자동으로 요약해 한도를 넘어서도 대화를 이어 갈 수 있게 하는 기능이고, Claude 4.6 이후 모델과 Claude Mythos Preview에서 베타로 제공됩니다.

세부적인 관리는 컨텍스트 편집에서 합니다. 오래된 도구 결과를 지우는 도구 결과 지우기와 이전 턴의 사고 블록을 관리하는 사고 블록 지우기가 있습니다. 다시 말하지만 캐시된 프롬프트 앞부분도 컨텍스트 창을 차지합니다.

한도를 넘으면

입력만으로 이미 모델의 컨텍스트 창을 넘으면 모든 모델에서 API가 400 invalid_request_error를 반환하며 메시지는 프롬프트가 너무 길다는 내용입니다. 오류 코드 전반은 API 오류 코드 글에 정리했습니다.

입력 토큰과 max_tokens를 더한 값이 컨텍스트 창을 넘는 경우는 모델에 따라 다릅니다.

• Claude 4.5 모델과 그 이후 모델은 요청을 받아들이고, 생성이 한도에 닿으면 stop_reason이 model_context_window_exceeded로 끝납니다.
• 이전 모델은 검증 오류를 반환합니다. 이전 모델에서 위 동작을 쓰려면 model-context-window-exceeded-2025-08-26 베타 헤더를 지정해야 합니다.

한도 안에 머물려면 보내기 전에 토큰 수를 세어 보라고 문서가 권합니다. 응답을 조각으로 받는 방식은 API 스트리밍 글에서 다룹니다.

정리자의 판단: 점검 순서

아래는 공식 문서의 내용을 바탕으로 정리한 해석이며, 문서에 그대로 적힌 문장은 아닙니다.

• 100만 토큰 창이 기본값인 모델에서도 문서는 토큰이 늘수록 정확도와 회상이 떨어질 수 있다고 설명합니다. 창을 가득 채우기보다 필요한 내용만 넣는 쪽이 낫다고 볼 수 있습니다.
• 긴 대화나 도구를 많이 쓰는 작업에서 한도에 가까워지는 일이 반복된다면, 서버 측 압축과 컨텍스트 편집을 먼저 검토하고 요청마다 토큰 카운팅으로 점검하는 순서가 합리적입니다.
• 사고를 쓰는 모델은 이전 사고 블록을 유지하는지에 따라 같은 대화의 토큰 수가 달라질 수 있으므로, 모델을 바꿀 때는 다시 세어 보는 것이 안전합니다.
• 입력과 최대 출력의 합이 한도를 넘는 경우의 동작이 모델마다 다르므로, max_tokens는 필요한 만큼만 지정하는 편이 결과를 예측하기 쉽습니다.

자주 묻는 질문

100만 토큰을 쓰려면 별도 설정이 필요한가요?

문서는 100만 토큰 컨텍스트 창을 가진 모델에서는 100만이 기본값이라 베타 헤더가 필요 없다고 안내합니다.

컨텍스트 창이 크면 응답 품질도 좋아지나요?

문서는 토큰이 많아질수록 정확도와 회상이 떨어질 수 있다고 설명합니다. 무엇을 넣을지 고르는 것도 중요합니다.

사고 토큰은 컨텍스트 창에 들어가나요?

들어갑니다. 이전 턴의 사고 블록은 모델에 따라 유지되기도 하고 제거되기도 합니다.

입력이 한도를 넘으면 어떻게 되나요?

모든 모델에서 400 오류가 납니다. 입력은 한도 안인데 입력과 최대 출력의 합이 넘는 경우는 모델에 따라 동작이 다릅니다.

내용은 지금도 같은가요?

2026년 10월 25일 문서 기준입니다. 모델 목록과 한도는 바뀔 수 있으므로 쓰기 전에 공식 문서를 다시 확인해야 합니다.