사고 문제 해결

이 페이지는 사고(thinking)를 구성하거나 thinking 블록을 왕복(round-tripping, 반환된 thinking 블록을 이후 요청에서 다시 전송하는 것)할 때 가장 흔히 발생하는 실패를 다룹니다. 첫 번째 섹션은 각 모델을 지원되는 사고 구성 및 거부되는 구성에 매핑하며, 그 이후의 섹션들은 각각 관찰되는 증상에서 시작하므로 오류 메시지나 예상치 못한 응답을 원인 및 해결 방법에 직접 대응시킬 수 있습니다. 사고가 어떻게 작동하는지 알아보려면 사고 개요를 참조하세요.

모델별 사고 지원, 기본값 및 거부되는 구성

대부분의 사고 구성 오류는 요청의 thinking.type 값과 모델이 지원하는 값 사이의 불일치입니다. 대부분의 모델에서 사고는 thinking: {type: "adaptive"}로 실행되며, 많은 모델에서 기본적으로 켜져 있습니다. 일부 이전 모델은 대신 thinking: {type: "enabled", budget_tokens: N}으로 구성되는 레거시 수동 모드인 extended thinking(확장 사고)을 사용합니다.

"Extended thinking"(확장 사고)(thinking.type: "enabled"와 budget_tokens 사용)는 Claude 4.6 모델에서 지원 중단되었습니다(이를 사용하는 요청은 여전히 성공합니다). Claude 4.7 및 이후 모델은 이를 지원하지 않으며, 이를 사용하는 요청을 거부하고 400 오류를 반환합니다. 사고를 지원하는 Claude 4.5 및 이전 모델에서는 확장 사고가 사용 가능한 유일한 사고 모드입니다. Claude Mythos Preview는 두 모드를 모두 지원합니다. 두 모드를 모두 사용할 수 있는 경우에는 대신 adaptive thinking(적응형 사고)을 사용하세요.

아래 표는 각 모델이 지원하는 항목, 기본값, 그리고 400 오류로 거부하는 thinking.type 값을 나열합니다. 거부 항목으로 나열되지 않은 값은 모두 허용됩니다.

¹ enabled와 budget_tokens는 이 모델들에서 여전히 작동하지만 지원 중단되었습니다. 대신 적응형 사고를 사용하세요.
² Claude Opus 5는 effort가 high 이하일 때 "disabled"를 허용합니다. effort xhigh 또는 max와 함께 사용하면 400 오류가 반환됩니다. 이 제한은 Claude Opus 5 및 이후 모델에 적용되며 각 요청마다 적용됩니다.

항상 켜짐으로 표시된 모델은 사고를 끌 수 없습니다. 켜짐으로 표시된 모델은 기본적으로 사고를 수행하지만 thinking: {type: "disabled"}를 허용합니다.

이전 Claude 4 모델(Claude Opus 4.1, Claude Sonnet 4, Claude Opus 4)은 확장 사고만 지원합니다. 이들의 가용성은 모델 지원 중단을 참조하세요. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5는 Anthropic이 명시적으로 승인하지 않는 한 제로 데이터 보존 하에서 사용할 수 없습니다.

400 오류에서 "thinking.type.enabled"가 지원되지 않는다고 표시됨

요청이 다음과 같은 메시지의 400 오류로 실패합니다:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

이는 요청한 모델에서 확장 사고가 제거되었기 때문에 발생합니다(모델별 구성 표 참조).

요청을 thinking: {type: "adaptive"}로 전환하고 budget_tokens 대신 effort로 사고 깊이를 조정하세요. 적응형 사고로 마이그레이션에서 변환 과정을 안내합니다.

400 오류에서 "thinking.type.disabled"가 지원되지 않는다고 표시됨

요청이 다음과 같은 메시지의 400 오류로 실패합니다:

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

이는 사고가 항상 켜져 있는 모델에서 발생합니다. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview는 "disabled"를 거부합니다. Claude Mythos Preview를 제외한 이 모델들은 모두 오류 텍스트에서 제안하는 "thinking.type.enabled"도 거부합니다.

thinking 매개변수를 생략하세요. 이 모델들은 아무 구성 없이도 사고를 수행합니다. 응답에서 사고 텍스트를 제외하는 것이 목적이었다면 사고를 비활성화하는 대신 display: "omitted"를 사용하세요. 사고 표시 제어를 참조하세요.

"disabled"에 대한 400 오류는 Claude Opus 5에서도 발생할 수 있습니다. Claude Opus 5는 effort가 high 이하일 때만 thinking: {type: "disabled"}를 허용하며, effort xhigh 또는 max와 함께 사용하면 거부됩니다. effort 수준을 낮추거나 사고를 켜 두세요.

400 오류에서 적응형 사고가 지원되지 않는다고 표시됨

요청이 다음과 같은 메시지의 400 오류로 실패합니다:

adaptive thinking is not supported on this model

이는 모델이 확장 사고만 지원하기 때문에 발생합니다(모델별 구성 표 참조).

대신 thinking: {type: "enabled", budget_tokens: N}을 사용하세요. 구성 방법은 확장 사고를 참조하세요.

400 오류에서 thinking 블록을 수정할 수 없다고 표시됨

도구 결과를 반환하는 요청이 다음 내용을 포함하는 메시지의 400 invalid_request_error로 실패합니다:

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified

멀티턴 및 도구 사용 대화에서는 thinking 및 redacted_thinking 블록을 포함한 이전 어시스턴트 메시지를 API로 다시 전송하며, API는 이들이 수정되지 않은 채로 도착했는지 검증합니다. 이 오류는 다시 전송한 어시스턴트 메시지가 API가 반환한 것과 다를 때 발생하며, 대부분 코드가 콘텐츠 블록을 유형별로 필터링하면서 redacted_thinking 블록을 누락하거나, 어시스턴트 메시지를 그대로 되돌려 보내는 대신 재구성하기 때문입니다.

thinking 블록을 포함하여 어시스턴트 턴을 그대로 되돌려 보내세요. 규칙은 thinking 블록 보존을 참조하고, 모든 SDK에서의 올바른 코드는 도구 및 멀티턴 워크플로에서의 사고의 왕복 예제를 참조하세요.

400 오류에서 thinking 블록 서명이 유효하지 않다고 표시됨

이전 thinking 블록을 재전송하는 Claude Fable 5.1 요청이 다음과 같은 메시지의 400 invalid_request_error로 실패합니다:

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

요청이 thinking-binding-controls-2026-08-01 베타 헤더를 보내지 않은 경우, 메시지에 That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.가 추가됩니다. 메시지는 변경된 첫 번째 메시지를 지목하는 문장으로 끝날 수도 있습니다. 메시지에 이유 절이 전혀 없다면 블록의 내용이 수정된 것입니다. 400 오류에서 thinking 블록을 수정할 수 없다고 표시됨을 참조하세요.

Claude Fable 5.1에서 API는 재전송된 thinking 블록을 그 앞에 있던 system 프롬프트, tools, 메시지가 변경되지 않은 동안에만 허용합니다. 이 오류는 요청 사이에 대화의 앞부분에서 무언가가 변경되었음을 의미합니다. 편집, 재정렬 또는 제거된 턴, 주입되었다가 나중에 제거된 턴별 리마인더, 재구성된 system 프롬프트 또는 tools 배열, 또는 최근 턴과 그 사고를 그대로 유지한 클라이언트 측 압축 등이 해당됩니다. 이 검사는 2026년 8월 31일 이후에 생성된 신규 계정과 thinking.block_binding.prefix_mismatch_behavior를 설정한 모든 요청에 적용됩니다. 서버 측 압축 및 컨텍스트 편집은 이 오류를 절대 유발하지 않습니다.

해결하려면 기록을 추가 전용(append-only)으로 유지하세요. 이전 턴을 보내고 받은 그대로 정확히 다시 전달하고, system이나 tools를 편집하는 대신 대화 중 시스템 메시지로 지시를 추가하며, 잘라내기는 서버 측 컨텍스트 편집 또는 압축에 맡기세요. 동일한 요청 본문을 재시도해도 오류는 해소되지 않습니다. 무효화된 추론 없이 이 요청을 계속하려면 thinking-binding-controls-2026-08-01 베타 헤더를 보내고 thinking.block_binding.prefix_mismatch_behavior를 "drop_block"으로 설정하세요. 또는 기록에서 모든 thinking 및 redacted_thinking 블록을 제거하고(최소한 지목된 블록과 그 이후의 모든 블록, 해당 턴과 이후 모든 턴에서), 각 턴의 다른 블록은 그대로 둔 채 한 번 재시도하세요.

대상 모델이 읽을 수 없는 모델의 블록은 이 오류를 절대 발생시키지 않습니다. API가 이를 삭제하고, 베타 헤더 하에서는 input_transformations에 보고합니다.

응답에서 thinking 필드가 비어 있음

응답에 thinking 블록이 포함되어 있지만 thinking 필드는 빈 문자열이고 signature 필드만 채워져 있습니다.

이는 최신 모델에서 display의 기본값이 "omitted"이기 때문에 발생하며, 이 경우 텍스트 없이 thinking 블록이 반환됩니다.

요약된 사고 텍스트를 받으려면 사고 구성에서 display: "summarized"를 설정하세요. 모델별 기본값은 사고 표시 제어를 참조하세요. 추론이 아니라 일부 모델이 도구 호출 사이에 작성하는 짧은 상태 줄만 원한다면 대신 display: "updates"(베타)를 설정하세요. 도구 호출 사이의 진행 업데이트를 참조하세요.

일부 턴에서 thinking 블록이 나타나지 않음

사고가 구성되어 있는데도 일부 응답에 thinking 블록이 전혀 포함되지 않습니다.

이는 적응형 모드에서 정상입니다. Claude는 직접 답변할 수 있을 만큼 간단하다고 판단한 요청에서는 사고를 건너뜁니다.

사고를 더 자주 또는 더 깊게 수행하기를 원한다면 effort를 높이거나 프롬프팅으로 조정하세요. Claude의 사고 빈도 조정을 참조하세요.

텍스트 출력에 도구 호출이나 XML 태그가 나타남

응답이 간혹 tool_use 블록을 내보내는 대신 도구 호출을 텍스트에 작성하거나, 보이는 텍스트에 <thinking> 또는 기타 내부 XML 태그를 포함합니다. 유출된 도구 호출은 절대 실행되지 않으며, 에이전트 루프에서는 유출된 텍스트가 대화 기록에 남아 이후 턴에도 영향을 미칩니다.

이는 Claude Opus 5에서 사고가 비활성화되었을 때 발생하며, 검색과 같이 도구 사용이 많은 워크로드에서 가장 흔합니다. 모델에게 사고하지 말거나 추론하지 말라고 지시하는 시스템 프롬프트 규칙은 태그 유출을 증가시킵니다.

사고를 다시 활성화하고(기본값) 대신 낮은 effort 수준으로 토큰 비용을 제어하세요. 통합에서 사고를 반드시 비활성화 상태로 유지해야 한다면 사고 비활성화 상태로 실행의 프롬프팅 완화 방법을 적용하세요.

응답이 stop_reason: "max_tokens"로 중단됨

응답이 stop_reason: "max_tokens"로 끝나며, 종종 텍스트 블록이 잘리거나 누락됩니다.

이는 사고 토큰이 max_tokens에 포함되어 계산되기 때문에 발생하며, 긴 사고 과정이 텍스트 응답이 완료되기 전에 예산을 소진할 수 있습니다.

사고와 텍스트 모두를 위한 여유를 두도록 max_tokens를 높이거나, Claude가 사고에 덜 소비하도록 effort를 낮추세요. 비용 제어 및 사고와 컨텍스트 윈도우를 참조하세요.

사고 설정 변경 후 캐시 적중이 감소함

이전에 캐시에 적중했던 요청에서 cache_read_input_tokens가 0으로 떨어집니다.

이는 사고 구성과 effort 수준(또는 그 기본값)이 캐시된 프롬프트 접두사의 일부이기 때문에 발생하며, 이 중 하나라도 변경하면 새 접두사가 시작됩니다. 사고 모드 전환, effort 값 변경, budget_tokens 변경은 모두 메시지 캐시 중단점을 무효화하며, 모델이 구성을 렌더링하는 위치에 따라 도구 및 시스템 프롬프트 중단점도 무효화할 수 있습니다.

대화를 공유하는 요청 전반에서 사고 구성과 effort 수준을 일정하게 유지하세요. 매개변수를 명시적으로 기본값으로 설정하는 것은 생략하는 것과 동일하며 무효화하지 않습니다. 사고와 프롬프트 캐싱을 참조하세요.

effort를 설정해도 사고가 변하지 않음

effort를 변경했지만 사고 빈도나 깊이가 그대로입니다.

이는 effort가 적응형 모드에서만 주요 사고 조절 수단이기 때문에 발생합니다. 확장 사고 전용 모델에서는 사고 깊이가 대신 budget_tokens로 설정됩니다.

해당 모델에서는 budget_tokens를 조정하거나, 모델이 어떤 모드로 실행되는지 확인하세요. 사고와 effort를 참조하세요. effort를 지원하는 유일한 확장 사고 전용 모델인 Claude Opus 4.5에서는 effort가 예산과 결합됩니다. 예산 규칙 및 튜닝을 참조하세요.

다음 단계