Claude Opus 4.8에서 Opus 5로 마이그레이션: 모든 주요 변경사항

claude-opus-4-8를 claude-opus-5로 바꾸는 것은 한 줄 변경처럼 보입니다. 대체로 그렇습니다. 하지만 몇 가지 기본 설정이 변경되었고, 이전에 유효했던 요청 조합 중 하나는 이제 400 오류를 반환하며, 기업 팀에서 비용을 지불하던 한 가지 기능은 새 모델에서 사라졌습니다.

Anthropic은 2026년 7월 24일 Claude Opus 5를 Opus 4.8과 동일한 가격(입력 토큰 백만 개당 5달러, 출력 토큰 백만 개당 25달러)으로 출시했으므로, 이는 예산 문제가 아닌 정확성 문제입니다. 아래는 작동 중인 통합을 손상시킬 수 있는 모든 차이점이며, 첫날에 문제가 발생할 가능성이 높은 순서대로 정렬되어 있으며, 클라이언트에 붙여넣을 수 있는 변경 전후 코드 조각이 포함되어 있습니다. Anthropic 자체의 Opus 4.8에서 Opus 5로의 마이그레이션 가이드는 API 표면의 주요 소스입니다. 각 변경 사항을 라이브 엔드포인트에 대해 먼저 테스트하려면, Apidog에 요청 하나를 저장하고 각 변형별로 복제하십시오.

요약

1. 사고 기능이 기본적으로 활성화되며, max_tokens는 여전히 모든 것을 제한합니다.

이것은 조용히 작동하던 코드를 망가뜨리는 변경 사항입니다.

Opus 4.8에서는 thinking 필드가 없는 요청이 사고 기능 없이 실행되었습니다. Opus 5에서는 동일한 요청이 적응형 사고 기능을 실행합니다. JSON은 변경되지 않았지만, 모델은 이제 보이는 답변을 작성하기 전에 추론하는 데 토큰을 소비합니다. 그리고 max_tokens는 사고 토큰과 응답 토큰을 합한 총량에 대한 엄격한 상한선으로 남아 있으므로, 4.8에서 1,024 토큰 예산에 여유롭게 맞았던 요청도 이제 그 예산의 대부분을 사고 기능에 소모하고 잘린 답변을 반환할 수 있습니다.

다음은 예전에는 안전했던 요청의 형태입니다.

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "이 사고 보고서를 세 가지 요점으로 요약해 주세요."}
  ]
}

모델 ID만 변경하고 다른 것은 변경하지 않으면 잘림 위험이 있습니다. 해결책은 예산에 여유를 주는 것입니다.

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "messages": [
    {"role": "user", "content": "이 사고 보고서를 세 가지 요점으로 요약해 주세요."}
  ]
}

상한을 올린 후 두 가지를 확인하십시오. 응답의 stop_reason을 확인하세요: max_tokens는 잘렸음을 의미하고, end_turn은 모델이 완료되었음을 의미합니다. 그런 다음 usage 블록을 읽어 실제 프롬프트에서 사고 기능이 얼마나 많은 예산을 소비했는지 확인하고, 추측이 아닌 측정값을 기반으로 숫자를 조정하십시오.

정말로 이전의 사고 기능 없는 동작을 원한다면 thinking: {"type": "disabled"}를 명시적으로 보내십시오. 하지만 다음 섹션을 먼저 읽으십시오. 왜냐하면 해당 필드가 이제 오류를 반환하는 방식으로 노력(effort)과 상호 작용하기 때문입니다.

2. 400 오류: 사고 기능 비활성화와 xhigh 또는 max 노력 수준 병합

이것은 오류 로그에 가장 자주 나타날 함정입니다. 왜냐하면 Opus 4.8에서는 이 둘 각각이 개별적으로 유효했기 때문입니다.

Opus 5에서는 thinking: {"type": "disabled"}와 output_config.effort가 xhigh 또는 max로 설정된 조합은 HTTP 400 오류를 반환합니다. Anthropic은 요청별로 이를 강제하므로, 성능 저하 없이 즉시 그리고 일관되게 실패합니다. 논리는 간단합니다. 상위 두 노력 수준은 더 많은 사고 기능을 얻기 위해 존재하므로, 사고 기능을 끈 상태에서 최대 노력을 요구하는 것은 모순입니다.

이제 실패하는 요청:

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "xhigh"},
  "messages": [
    {"role": "user", "content": "이 모듈을 리팩토링하고 장단점을 설명해 주세요."}
  ]
}

수정 A, 기능 유지. thinking 필드를 제거하고 높은 노력 수준을 유지합니다. 이것은 Anthropic이 권장하는 방향이며, 코딩 및 에이전트 작업에 적합합니다.

{
  "model": "claude-opus-5",
  "max_tokens": 32000,
  "output_config": {"effort": "xhigh"},
  "messages": [
    {"role": "user", "content": "이 모듈을 리팩토링하고 장단점을 설명해 주세요."}
  ]
}

수정 B, 사고 기능 끄기 유지. 진정으로 사고 기능이 필요 없는 지연 시간에 민감한 경로의 경우, disabled를 유지하고 노력 수준을 high 이하로 낮춥니다.

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "high"},
  "messages": [
    {"role": "user", "content": "이 티켓을 다섯 가지 범주 중 하나로 분류해 주세요."}
  ]
}

수정 B에 대한 한 가지 주의사항입니다. Anthropic은 사고 기능이 비활성화되었을 때 가끔 나타나는 두 가지 아티팩트를 문서화합니다. 실행되지 않고 일반 텍스트로 작성되는 도구 호출과, <thinking>과 같은 내부 XML 태그가 보이는 출력으로 유출되는 것입니다. 에이전트 루프에서는 유출된 텍스트가 이후 턴을 오염시키기도 합니다. Anthropic의 자체 완화책은 사고 기능을 유지하고 더 낮은 노력 수준으로 비용을 제어하는 것입니다. 수정 B는 기본 옵션이 아닌, 제한적인 옵션으로 취급하십시오.

3. 노력 수준이 재조정되었으므로, 설정 복사 대신 다시 평가하십시오.

Opus 5는 high 노력 수준을 기본값으로 사용하며, 수준 자체가 재조정되었습니다. Opus 5의 low 및 medium은 이전 Opus 모델보다 의미 있게 더 강력하므로, 4.8에서 조정한 설정은 더 이상 동일한 비용 및 품질 지점에 도달하지 않습니다. Anthropic은 4.8 구성을 그대로 가져오는 대신 새로운 노력 수준 평가를 실행하라고 명확히 말하며, 이 조언은 양방향으로 적용됩니다.

• 품질을 위해 4.8에서 high 또는 xhigh로 고정된 작업 부하는 Opus 5에서 medium 수준으로 유지될 수 있으며, 이는 토큰당 가격이 동일하더라도 실제 비용 절감으로 이어집니다.
• 비용을 위해 low로 고정된 작업 부하는 토큰당 품질이 향상되었기 때문에 한 단계 높이는 것을 고려할 가치가 있을 수 있습니다.

코딩 및 장기 에이전트 작업의 경우, xhigh가 권장되는 시작점입니다. 충분한 max_tokens(최상위 수준에서는 64k가 합리적인 시작 예산)와 함께 사용하여 사고 기능이 발휘될 여지를 제공하십시오.

벤치마크가 아닌 자체 평가 세트에서 평가를 실행하십시오. 프롬프트를 고정하고 노력 값만 변경하여 각 수준별 출력 품질, 지연 시간 및 usage를 기록하십시오. 노력 매개변수 심층 분석은 각 수준의 메커니즘을 다룹니다. 동일한 결정의 비용 측면에 대해서는 Opus 5 가격 분석을 참조하십시오.

4. 긴 컨텍스트 베타 헤더 제거

Opus 5는 기본값이자 최댓값으로 1M 토큰 컨텍스트 창을 제공합니다. 이를 활성화하는 베타 헤더는 없으며, 긴 컨텍스트에 대한 가격 프리미엄도 없습니다.

클라이언트가 Opus 4.8 설정에서 anthropic-beta 헤더에 확장 컨텍스트 베타 값을 여전히 보내고 있다면, 이제 이는 불필요한 부분입니다. 제거하십시오. 공유 HTTP 클라이언트의 오래된 베타 값은 6개월 후에 관련 없는 요청을 디버깅하게 되는 원인이 됩니다.

Messages API의 최대 출력은 128k 토큰입니다. 더 많은 것이 필요하다면, Batch API는 output-300k-2026-03-24 베타 헤더와 함께 300k 출력 토큰까지 지원하며, 이는 컨텍스트 길이를 위해 수행했던 것과는 별개의 옵트인입니다.

5. 프롬프트 캐시 최소값이 512 토큰으로 하락합니다.

Opus 4.8에서는 프롬프트 세그먼트가 캐싱 대상이 되려면 1,024 토큰에 도달해야 했습니다. Opus 5에서는 최소값이 512입니다. 코드에서 변경할 필요는 없으며, 백만 개당 0.50달러의 캐시 읽기는 기본 입력 5달러에 비해 가격표에서 가장 저렴한 토큰입니다.

수행할 가치가 있는 것은 검토 과정입니다. 512에서 1,024 토큰 사이에 있었지만 이전에 cache_control 중단점을 둘 가치가 없었던 시스템 프롬프트, 도구 정의 및 few-shot 블록을 찾으십시오. 이제는 가치가 있습니다. 응답 usage 블록에서 cache_read_input_tokens를 읽어 효과를 확인하십시오. 두 번째 동일한 호출에서는 0이 아니어야 합니다. 저희의 Claude API 요금 절감 가이드는 더 넓은 캐싱 전략을 다룹니다.

6. 대화 중간 시스템 메시지가 이제 허용됩니다.

Opus 4.8은 messages 배열 내의 {"role": "system"} 항목을 400 오류와 함께 거부했습니다. Opus 5는 이를 허용합니다. 이는 추가적인 기능이므로 아무것도 손상시키지 않지만, 우회책을 제거할 수 있습니다. 만약 대화 중간의 지시 변경 사항을 가상 사용자 턴에 포함시키는 메커니즘을 구축했다면, 이제 지시 사항을 제자리에 인라인으로 넣을 수 있습니다.

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "messages": [
    {"role": "user", "content": "릴리스 노트를 초안하세요."},
    {"role": "assistant", "content": "여기에 초안이 있습니다..."},
    {"role": "system", "content": "여기부터는 응답을 150단어 이내로 유지하십시오."},
    {"role": "user", "content": "더 간결하게 만드세요."}
  ]
}

이것은 모델별 기능입니다. 동일한 대화 기록을 Opus 4.8로 대체 라우팅하는 경우, 이전 모델은 여전히 해당 메시지에서 400 오류를 반환합니다.

7. Opus 5에서는 우선순위 티어(Priority Tier)가 지원되지 않습니다.

이것은 기업 팀에게는 아픈 부분이며, grep으로 찾을 수 있는 오류가 아니라 단순히 없기 때문에 놓치기 쉽습니다. Opus 4.8은 우선순위 티어를 지원합니다. Opus 5는 그렇지 않습니다. 프로덕션 경로에서 지연 시간을 보장하기 위해 약정된 처리량을 구매했다면, 해당 경로를 마이그레이션하면 표준 용량으로 되돌아갑니다.

영리한 해결책은 없습니다. 지연 시간에 중요한 트래픽은 claude-opus-4-8에 유지하고 다른 모든 것은 Opus 5로 옮기거나, 표준 용량을 수용하고 꼬리 지연 시간이 실제로 저하되는지 측정해야 합니다. 전체 시스템을 한 번에 전환하기보다는 워크로드별로 마이그레이션을 분할하십시오.

8. 고속 모드(Fast mode)가 이제 작동하며, 새로운 사이버 거부 폴백 기능이 추가되었습니다.

고속 모드는 Opus 5에서 실행됩니다. Opus 4.7에서는 오류를 반환했고, Opus 4.6에서는 표준 속도로 조용히 실행되었습니다. Opus 5에서는 입력 백만 개당 10달러, 출력 백만 개당 50달러로 약 2.5배의 출력 속도를 제공합니다. 이는 연구 미리 보기 기능이며, Anthropic 자체 API에서만 지원됩니다(Amazon Bedrock, Google Cloud 또는 Microsoft Foundry에서는 지원되지 않음). 또한 Batch API와는 결합되지 않습니다. 백그라운드 작업이 아닌 대화형 경로에서 활용하십시오.

사이버 거부에 대한 서버 측 폴백. server-side-fallback-2026-07-01 베타 헤더와 함께 fallbacks: "default"를 보내면 Opus 5가 사이버 범주를 이유로 거부하는 요청이 자동으로 Opus 4.8로 폴백됩니다. 이 기능은 보안 도구에서 유용하게 사용될 수 있습니다.

또한 mid-conversation-tool-changes-2026-07-01 베타 헤더도 있는데, 이는 프롬프트 캐시를 무효화하지 않고 턴 사이에 도구 정의를 추가하거나 제거할 수 있게 해줍니다. 변화하는 도구 세트를 사용하는 장기 에이전트 세션의 비용 절감 수단이 될 수 있습니다.

9. 변경되지 않은 사항

어떤 것을 그대로 둘 수 있는지 아는 것이 시간을 절약해 줍니다.

• 샘플링 매개변수는 여전히 400 오류를 반환합니다. temperature, top_p, top_k의 기본값 이외의 값은 Opus 4.8과 동일하게 거부됩니다. 시스템 프롬프트를 통해 동작을 유도하십시오.
• 토큰 개수는 거의 동일합니다. Opus 5는 4.8과 동일한 토크나이저 계열을 사용하므로, 기존 토큰 예산과 비용 모델은 재계산 없이 그대로 유지됩니다. 이는 약 30%의 토큰 개수 변화가 있었던 Sonnet 4.6에서 Sonnet 5로의 전환과는 다릅니다.
• 기본 가격은 동일합니다. Opus 4.8, 4.7, 4.6, 4.5와 동일하게 입력 5달러, 출력 25달러입니다. Opus 4.8 가격 페이지를 참조하십시오.
• 요청 및 응답 형태. 스트리밍, 도구 사용, 비전, 구조화된 출력, 배치 처리 모두 이전과 동일하게 작동합니다.

API가 변경되지 않은 부분에서도 한 가지 변경된 점이 있습니다. Opus 5는 프롬프트 없이도 자체 작업을 확인하므로, 기존의 "답변을 다시 확인해 보세요" 지침은 과도한 확인을 유발하고 토큰을 낭비하게 됩니다. 기본 응답 또한 4.8보다 길며, 노력 수준을 낮추는 것은 보이는 길이보다 사고 기능을 줄이므로, 명시적으로 간결함을 요청하십시오. 이러한 것들은 프롬프트 수준의 수정 사항이며, Claude Opus 5 프롬프트 작성에서 다룹니다.

배포하기 전에 마이그레이션을 확인하세요.

위의 모든 항목은 HTTP 수준의 차이점이므로, 애플리케이션 외부에서 테스트할 수 있습니다. Apidog에서 실행 가능한 루프:

1. 환경 변수로 저장된 키를 사용하여 Messages 엔드포인트에 요청 하나를 저장하십시오. 절대 본문에 인라인으로 넣지 마십시오.
2. 이를 변형으로 복제하십시오: claude-opus-4-8 기준선, 기본값이 적용된 claude-opus-5, 그리고 노력 수준별로 하나씩 복제본을 만드십시오.
3. 의도적으로 사고 기능 비활성화와 xhigh 조합을 실행하고 400 오류 본문을 기록하여 프로덕션 로그에서 이를 인식할 수 있도록 하십시오.
4. 잘린 max_tokens 응답이 조용히 배포되지 않고 테스트를 실패하도록 stop_reason에 대해 어설션하십시오.
5. 동일한 캐시된 요청을 두 번 보내고 두 번째 호출에서 usage.cache_read_input_tokens를 확인하십시오.
6. 스트리밍 요청 하나를 실행하고 SSE 파서가 이제 기본적으로 도착하는 사고 블록을 처리하는지 확인하십시오.

향후 모든 모델 교체를 위한 재사용 가능한 컬렉션으로 유지하려면 Apidog를 다운로드하십시오.

모든 것을 마이그레이션하기 전의 솔직한 주의사항

Opus 5는 Claude 스택의 정점이 아닙니다. Fable 5는 Anthropic에서 가장 유능한 널리 출시된 모델로 남아 있으며, Opus 5는 사이버 보안 익스플로잇 및 자율 생물학 연구 분야에서 여전히 Mythos 5에 뒤처집니다. Anthropic은 출시 게시물에서 직접 이를 언급했습니다. 출시 벤치마크 주장(Frontier-Bench, ARC-AGI 3, OSWorld 2.0, CursorBench 3.2)은 2026년 7월 25일 현재 공급업체 자체 테스트이며 독립적으로 재현되지 않았습니다. 이를 Anthropic이 보고한 수치로 간주하고 프로덕션 워크로드를 확정하기 전에 자체 평가를 실행하십시오. 정확한 요약은 다음과 같습니다. 선두급 성능을 선두급 가격의 절반으로 제공하지만, 그 위에 더 높은 수준의 모델이 존재한다는 것입니다.

마이그레이션 체크리스트

다음 순서대로 진행하십시오.

1. 모델 문자열을 정확히 claude-opus-5로 변경하십시오. 날짜 접미사는 없습니다.
2. 이전에 thinking을 생략했던 모든 요청에 대해 max_tokens를 높이십시오. 사고 기능이 이제 기본적으로 실행되며 해당 예산을 공유합니다.
3. 코드베이스에서 "disabled"를 검색하고 어떤 요청도 이를 xhigh 또는 max 노력 수준과 함께 사용하지 않는지 확인하십시오. 해당 조합은 하드 400 오류를 발생시킵니다.
4. anthropic-beta에서 긴 컨텍스트 베타 값을 제거하십시오. 이제 1M 창이 기본값입니다.
5. 자체 평가를 통해 노력 수준 평가를 처음부터 다시 실행하십시오. 4.8 설정을 그대로 가져오지 마십시오.
6. 512에서 1,024 토큰 사이의 프롬프트 세그먼트에 cache_control 중단점을 추가하십시오。
7. 우선순위 티어를 사용하는 트래픽을 식별하고, 워크로드별로 claude-opus-4-8을 유지할지 결정하십시오.
8. 프롬프트에서 이월된 확인 지침을 삭제하고, 출력 길이가 중요한 곳에는 명시적인 간결성 지침을 추가하십시오.
9. 워크로드가 사이버 범주 거부를 트리거하는 경우 선택적으로 fallbacks: "default"를 활성화하십시오.
10. 테스트 스위트에서 stop_reason에 대해 어설션하여 잘림이 미묘하게 나쁜 답변이 아닌 실패로 나타나도록 하십시오.

전체 요청 워크스루는 Claude Opus 5 API 가이드를 참조하거나, 사양 및 가용성에 대한 Claude Opus 5란 무엇인가로 시작하십시오. 여전히 일부에서 이전 모델을 실행하는 경우, Opus 4.8 설명과 API 워크스루는 여전히 정확합니다. Anthropic의 모델 개요는 ID, 컨텍스트 창 및 마감일에 대한 공식 자료입니다。

자주 묻는 질문

Opus 4.8에서 Opus 5로의 마이그레이션은 드롭인(drop-in) 방식인가요? 거의 그렇지만, 완전히 같지는 않습니다. 대부분의 요청에서 모델 문자열을 변경하는 것은 작동합니다. 두 가지 문제가 발생할 수 있습니다. 사고 기능이 이제 기본적으로 실행되고 max_tokens 예산을 공유하며, thinking: {"type": "disabled"}와 xhigh 또는 max 노력 수준을 함께 사용하면 400 오류를 반환합니다. Opus 5는 우선순위 티어를 지원하지 않으므로, 우선순위 티어 트래픽에 대한 결정도 필요합니다.

claude-opus-5로 전환한 후 400 오류가 발생하는 이유는 무엇인가요? 가장 흔한 원인은 xhigh 또는 max 노력 수준을 요청하면서 사고 기능을 비활성화하는 경우입니다. thinking 필드를 제거하고 높은 노력 수준을 유지하거나, 사고 기능을 비활성화한 상태로 노력 수준을 high 이하로 낮추십시오. 기본값이 아닌 temperature, top_p 또는 top_k 값도 Opus 4.8과 마찬가지로 여전히 400 오류를 반환합니다.

마이그레이션 후 토큰을 다시 계산해야 하나요? 아니요. Opus 5는 Opus 4.8과 동일한 토크나이저 계열을 사용하므로, 토큰 개수는 거의 변경되지 않으며 기존 예산이 그대로 이월됩니다. 도구 사용 시스템 프롬프트 오버헤드는 290 토큰에서 286 토큰으로 약간 낮아졌습니다. 기본 가격도 입력 5달러, 출력 25달러로 동일하지만, 기본적으로 사고 기능이 출력 토큰을 증가시키는 경우 요금이 변경될 수 있습니다.