Thinking 문제 해결
Thinking 문제 해결 (Troubleshooting thinking)
이 페이지는 thinking을 구성하거나 thinking 블록을 왕복(반환된 thinking 블록을 이후 요청에 다시 보내기)할 때 가장 흔한 실패를 다뤄요. 첫 섹션은 각 모델을 지원하는 thinking 구성과 거부하는 구성에 매핑하고, 이후 섹션들은 각각 관찰한 증상에서 시작해서 오류 메시지나 예상 밖의 응답을 원인과 해결책에 직접 연결해요. thinking이 어떻게 동작하는지 배우려면 Thinking 개요를 보세요.
출처: 문서
본문
이 페이지는 thinking을 구성하거나 thinking 블록을 왕복(반환된 thinking 블록을 이후 요청에 다시 보내기)할 때 가장 흔한 실패를 다뤄요. 첫 섹션은 각 모델을 지원하는 thinking 구성과 거부하는 구성에 매핑하고, 이후 섹션들은 각각 관찰한 증상에서 시작해서 오류 메시지나 예상 밖의 응답을 원인과 해결책에 직접 연결해요. thinking이 어떻게 동작하는지 배우려면 Thinking 개요를 보세요.
모델별 thinking 지원, 기본값, 거부되는 구성
대부분의 thinking 구성 오류는 요청의 thinking.type 값과 모델이 지원하는 것의 불일치예요. 대부분의 모델에서 thinking은 thinking: {type: "adaptive"}로 실행되고, 많이는 기본으로 켜져 있어요. 일부 이전 모델은 대신 확장 thinking을 쓰는데, thinking: {type: "enabled", budget_tokens: N}으로 구성되는 레거시 수동 모드예요.
확장 thinking(thinking.type: "enabled" + budget_tokens)은 Claude 4.6 모델에서 더 이상 사용되지 않아요(그것을 사용하는 요청은 여전히 성공해요). Claude 4.7 이상 모델은 그것을 지원하지 않고, 그것을 쓰는 요청을 400 오류로 거부해요. thinking을 지원하는 Claude 4.5 이하 모델에서는 확장 thinking이 유일한 thinking 모드예요. Claude Mythos Preview는 두 모드를 모두 지원해요. 두 모드가 모두 가능한 곳에서는 적응형 thinking을 쓰세요.
표는 각 모델이 무엇을 지원하고, 무엇이 기본이며, 어떤 thinking.type 값을 400 오류로 거부하는지 나열해요. 거부로 나열되지 않은 값은 허용돼요.
| Model | Thinking types | Default | Rejected with 400 |
|---|---|---|---|
| Claude Fable 5.1 | Adaptive only | Always on | "enabled", "disabled" |
| Claude Mythos 5.1 | Adaptive only | Always on | "enabled", "disabled" |
| Claude Fable 5 | Adaptive only | Always on | "enabled", "disabled" |
| Claude Mythos 5 | Adaptive only | Always on | "enabled", "disabled" |
| Claude Mythos Preview | Adaptive, extended | Always on | "disabled" |
| Claude Opus 5.5 | Adaptive only | Always on | "enabled", "disabled" |
| Claude Opus 5 | Adaptive only | On | "enabled", "disabled"2 |
| Claude Opus 4.8 | Adaptive only | Off | "enabled" |
| Claude Opus 4.7 | Adaptive only | Off | "enabled" |
| Claude Sonnet 5 | Adaptive only | On | "enabled" |
| Claude Opus 4.6 | Adaptive, extended (deprecated)1 | Off | None |
| Claude Sonnet 4.6 | Adaptive, extended (deprecated)1 | Off | None |
| Claude Opus 4.5 | Extended only | Off | "adaptive" |
| Claude Haiku 4.5 | Extended only | Off | "adaptive" |
| Claude Sonnet 4.5 | Extended only | Off | "adaptive" |
1 enabled와 budget_tokens는 이 모델들에서 여전히 작동하지만 더 이상 사용되지 않아요. 적응형 thinking을 쓰세요.
2 Claude Opus 5는 effort high 이하에서 "disabled"를 받아요. effort xhigh나 max와 결합하면 400 오류를 반환해요. 이 제한은 요청마다 시행돼요.
Always on으로 표시된 모델은 thinking을 끌 수 없어요. On으로 표시된 모델은 기본으로 thinking이지만 thinking: {type: "disabled"}를 받아요.
이전 Claude 4 모델(Claude Opus 4.1, Claude Sonnet 4, Claude Opus 4)은 확장 thinking만 지원해요. 가용성은 모델 폐기를 보세요. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5는 zero data retention 하에서 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을 제거했기 때문이에요(모델별 구성 표 참고).
요청을 thinking: {type: "adaptive"}로 바꾸고, budget_tokens 대신 effort로 thinking 깊이를 스티어링하세요. 적응형 thinking으로 마이그레이션이 변환 과정을 안내해요.
400 오류가 "thinking.type.disabled"를 지원하지 않는다고 말해요
요청이 400 오류로 실패해요. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Opus 5.5, Claude Mythos 5에서 메시지는 이렇게 읽혀요:
"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
Claude Mythos Preview(이 모델들 중 확장 thinking을 받는 유일한 모델)에서 메시지는 이렇게 읽혀요:
"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.
이 모든 모델에서 thinking이 항상 켜져 있기 때문이에요(모델별 구성 표 참고).
thinking 파라미터를 생략하세요. 이 모델들은 구성 없이 생각해요. 목표가 thinking 텍스트를 응답에서 빼는 것이었다면 thinking을 비활성화하는 대신 display: "omitted"를 쓰세요. Thinking 표시 제어를 보세요.
"disabled"에 대한 400 오류는 Claude Opus 5에서도 일어날 수 있는데, 이 모델은 effort high 이하에서만 thinking: {type: "disabled"}를 받아요. effort xhigh나 max와 결합하면 거부돼요. effort 수준을 낮추거나 thinking을 켜 두세요.
400 오류가 적응형 thinking을 지원하지 않는다고 말해요
요청이 400 오류로 실패하고 메시지는 이렇게 읽혀요:
adaptive thinking is not supported on this model
모델이 확장 thinking만 지원하기 때문이에요(모델별 구성 표 참고).
대신 thinking: {type: "enabled", budget_tokens: N}을 쓰세요. 구성은 확장 thinking을 보세요.
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의 올바른 코드는 도구 및 멀티턴 워크플로에서의 thinking의 실제 왕복 예시를 보세요.
400 오류가 thinking 블록 서명이 유효하지 않다고 말해요
Claude Fable 5.1이나 Claude Opus 5.5로 이전 thinking 블록을 재생하는 요청이 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.를 더해요.
메시지는 보통 무엇이 바뀌었는지 말하는 문장으로 끝나요: system 프롬프트, tools 목록, 달라진 첫 메시지나 블록, 빠지거나 새로 생긴 콘텐츠, 빠졌거나 순서가 뒤바뀐 이전 thinking 블록 같은 것들이요. 그 문장은 사람과 로그를 위한 것이에요. 표현이 바뀔 수 있으므로 코드에서 그것을 매칭하지 마세요.
메시지가 Invalid `signature` in `thinking` block 다음에서 멈추면 서명 자체가 검증되지 않은 거예요: 잘렸거나, 바뀌었거나, 빈 채로 보내졌고, prefix_mismatch_behavior는 적용되지 않아요. 편집된 thinking 텍스트는 다른 오류를 반환해요. 400 오류가 thinking 블록을 수정할 수 없다고 말해요를 보세요.
Claude Fable 5.1과 Claude Opus 5.5에서 API는 재생된 thinking 블록을, 그것보다 앞선 system 프롬프트, tools, 메시지가 바뀌지 않은 동안만 받아요. 접두사 변경 없이 유지하기를 보세요. 이 오류는 대화에서 이전의 어떤 것이 요청 사이에 바뀌었음을 의미해요: 편집·재정렬·제거된 턴, 주입됐다가 나중에 제거된 턴별 알림, 다시 만들어진 system 프롬프트나 tools 배열, 혹은 최근 턴과 그 thinking을 그대로 유지한 클라이언트 측 compaction. 검사는 2026년 8월 31일 이후 생성된 새 계정과, thinking.block_binding.prefix_mismatch_behavior를 설정한 모든 요청에 시행돼요. 서버 측 compaction과 컨텍스트 편집은 절대 이것을 촉발하지 않아요.
고치려면 기록을 append-only로 유지하세요: 이전 턴을 보내고 받은 그대로 정확히 전달하고, system이나 tools를 편집하는 대신 대화 중간 시스템 메시지로 지시를 추가하며, 다듬기는 서버 측 컨텍스트 편집이나 compaction에 맡기세요. 같은 요청 본문을 재시도해도 오류가 사라지지 않아요. 무효화된 추론 없이 이 요청을 계속하려면 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 블록을 텍스트 없이 반환해요.
thinking 구성에서 display: "summarized"를 설정하면 요약된 thinking 텍스트를 받아요. 모델별 기본값은 Thinking 표시 제어를 보세요. 추론이 아니라 일부 모델이 도구 호출 사이에 쓰는 짧은 상태 줄만 원한다면 대신 display: "updates"(베타)를 설정하세요. 도구 호출 사이의 진행 업데이트를 보세요.
thinking 필드가 빈 블록도 여전히 완전해요: signature가 추론을 담아요. 다른 블록처럼 턴과 함께 다시 보내세요. 어시스턴트 턴을 반환된 그대로 다시 보내기를 보세요.
어떤 턴에는 thinking 블록이 나타나지 않아요
일부 응답은 thinking이 구성되어 있어도 thinking 블록을 전혀 담지 않아요.
적응형 모드에서 정상이에요: Claude는 직접 답하기에 충분히 단순하다고 판단한 요청에서는 생각을 건너뛰어요.
thinking을 더 자주, 더 깊게 원한다면 effort를 올리거나 프롬프팅으로 스티어링하세요. Claude가 생각하는 빈도 스티어링하기를 보세요.
텍스트 출력에 도구 호출이나 XML 태그가 나타나요
응답이 가끔 tool_use 블록을 내보내는 대신 도구 호출을 텍스트에 쓰거나, 눈에 보이는 텍스트에 <thinking>이나 다른 내부 XML 태그를 포함해요. 누출된 도구 호출은 절대 실행되지 않고, 에이전트 루프에서 누출된 텍스트는 대화 기록에 남아 후속 턴에도 영향을 줘요.
이것은 thinking이 꺼진 Claude Opus 5에서 일어나는데, 검색 같은 도구가 많은 워크로드에서 가장 흔해요. 모델이 생각하지 말거나 추론하지 말라고 지시하는 시스템 프롬프트 규칙이 태그 누출을 늘려요.
thinking(기본값)을 다시 켜고, 토큰 비용을 제어하려면 더 낮은 effort 수준을 쓰세요. 통합이 thinking을 꺼 둬야 한다면 Thinking 비활성화로 실행하기의 프롬프팅 완화책을 적용하세요.
응답이 stop_reason: "max_tokens"로 멈춰요
응답이 stop_reason: "max_tokens"으로 끝나는데, 보통 잘렸거나 빠진 텍스트 블록과 함께요.
thinking 토큰이 max_tokens에 포함되므로, 긴 thinking 통과가 텍스트 응답이 끝나기 전에 예산을 소비할 수 있기 때문이에요.
thinking과 텍스트 둘 다 담을 공간을 남기려면 max_tokens을 올리거나, Claude가 thinking에 덜 쓰도록 effort를 낮추세요. 비용 제어와 Thinking과 컨텍스트 창을 보세요.
thinking 설정을 바꾼 뒤 캐시 적중이 떨어져요
이전에 캐시에 적중했던 요청에서 cache_read_input_tokens가 0으로 떨어져요.
thinking 구성과 effort 수준(혹은 그 기본값)이 캐시된 프롬프트 접두사의 일부이기 때문인데, 그중 하나를 바꾸면 새 접두사가 시작돼요: thinking 모드를 바꾸고, effort 값을 바꾸고, budget_tokens를 바꾸는 것 모두 메시지 캐시 중단점을 무효화하고, 모델이 구성을 렌더링하는 위치에 따라 도구·시스템 프롬프트 중단점도 무효화할 수 있어요.
대화를 공유하는 요청들에서 thinking 구성과 effort 수준을 일정하게 유지하세요. 파라미터를 명시적으로 기본값으로 설정하는 것은 생략과 동등하고 무효화하지 않아요. Thinking과 프롬프트 캐싱을 보세요.
effort를 설정해도 thinking이 바뀌지 않아요
effort를 바꾸는데 thinking 빈도나 깊이가 그대로예요.
effort는 적응형 모드에서만 주요 thinking 레버이기 때문이에요. 확장 thinking 전용 모델에서는 thinking 깊이를 budget_tokens가 결정해요.
그 모델들에서는 budget_tokens를 조정하거나, 모델이 어떤 모드로 실행되는지 확인하세요. Thinking과 effort를 보세요. effort를 지원하는 유일한 확장 thinking 전용 모델인 Claude Opus 4.5에서는 effort가 예산과 결합돼요. 예산 규칙과 튜닝을 보세요.