DEV Community

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

Posted on • Originally published at apidog.com

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

claude-opus-4-8를 claude-opus-5로 바꾸는 일은 모델 ID 한 줄을 수정하는 것처럼 보입니다. 대부분의 요청은 실제로 그렇게 동작합니다. 하지만 기본 사고 기능, max_tokens 예산, 노력(effort) 수준 조합, 우선순위 티어 지원 여부가 달라졌습니다. 특히 기존에 유효했던 일부 요청은 Opus 5에서 HTTP 400 오류를 반환할 수 있습니다. Anthropic은 2026년 7월 24일 Opus 5를 Opus 4.8과 동일한 가격(입력 토큰 100만 개당 5달러, 출력 토큰 100만 개당 25달러)으로 출시했으므로, 핵심은 가격 변경이 아니라 안전한 마이그레이션입니다. Anthropic의 Opus 4.8에서 Opus 5로의 마이그레이션 가이드를 기준으로, 아래 항목을 프로덕션 배포 전에 검증하십시오. 각 요청 변형은 Apidog에 저장해 비교하면 빠르게 확인할 수 있습니다.

지금 Apidog 사용해 보기

요약

변경 사항 영향 조치
기본 사고 기능 활성화 응답이 조용히 잘릴 수 있음 max_tokens 증가 및 stop_reason 검사
thinking: disabled + xhigh/max HTTP 400 사고 기능을 켜거나 effort를 낮춤
노력 수준 재조정 기존 비용/품질 기준이 달라짐 설정값을 복사하지 말고 재평가
1M 컨텍스트 베타 헤더 불필요 오래된 헤더가 중복됨 확장 컨텍스트 베타 값 제거
캐시 최소값 512 토큰 더 작은 공통 프롬프트도 캐싱 가능 cache_control 후보 재검토
대화 중간 시스템 메시지 허용 기존 우회 로직 단순화 가능 선택적으로 시스템 메시지 인라인 처리
우선순위 티어 미지원 지연 시간 보장 경로 영향 해당 워크로드는 Opus 4.8 유지 검토
고속 모드 지원 더 높은 비용으로 빠른 응답 대화형 경로에서만 선택 적용
fallbacks: "default" 사이버 거부 시 Opus 4.8 폴백 필요 시 베타 헤더와 함께 사용
샘플링 매개변수, 토큰 개수 큰 변경 없음 기존 검증 로직 유지

1. 기본 사고 기능이 활성화됩니다: 먼저 max_tokens를 점검하세요

Opus 4.8에서는 thinking 필드를 생략하면 사고 기능 없이 요청이 실행되었습니다. Opus 5에서는 같은 요청이 적응형 사고 기능을 사용합니다.

중요한 점은 max_tokens가 사고 토큰과 표시되는 응답 토큰을 합친 전체 예산이라는 것입니다. 따라서 Opus 4.8에서 max_tokens: 1024로 충분했던 요청이 Opus 5에서는 사고 과정에 예산을 사용한 뒤 응답이 잘릴 수 있습니다.

기존 요청 예시:

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

모델 이름만 바꾸지 말고, 먼저 출력 예산을 늘려 테스트하십시오.

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

마이그레이션 테스트에서는 다음 두 값을 반드시 수집하십시오.

  1. stop_reason
    • end_turn: 모델이 정상 완료했습니다.
    • max_tokens: 출력이 예산 한도에 도달해 잘렸습니다.
  2. usage
    • 실제 입력, 출력 및 사고 관련 토큰 사용량을 확인합니다.
    • 충분한 품질이 나오는 최소 max_tokens 값을 측정으로 결정합니다.

예를 들어 Node.js 테스트 코드에서는 응답을 받은 직후 잘림을 실패로 처리할 수 있습니다.

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 8192,
  messages: [
    {
      role: "user",
      content: "이 사고 보고서를 세 가지 요점으로 요약해 주세요."
    }
  ]
});

if (response.stop_reason === "max_tokens") {
  throw new Error("응답이 max_tokens 한도에서 잘렸습니다.");
}

console.log(response.usage);
Enter fullscreen mode Exit fullscreen mode

이전처럼 사고 기능을 명시적으로 끄려면 아래를 보낼 수 있습니다.

{
  "thinking": {
    "type": "disabled"
  }
}
Enter fullscreen mode Exit fullscreen mode

단, 다음 섹션의 effort 조합 제한을 먼저 확인해야 합니다.

2. HTTP 400 원인: thinking: disabled와 xhigh 또는 max를 함께 사용한 경우

Opus 5에서는 아래 조합이 HTTP 400 오류를 반환합니다.

  • thinking: {"type": "disabled"}
  • output_config.effort: "xhigh" 또는 "max"

실패하는 요청 예시:

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

수정 A: 높은 effort를 유지하려면 사고 기능을 켜세요

코딩, 리팩토링, 에이전트 작업처럼 품질이 중요한 경우에는 thinking 필드를 제거하고 높은 effort를 유지하십시오.

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

수정 B: 사고 기능을 끄려면 effort를 high 이하로 낮추세요

지연 시간이 매우 중요한 단순 분류 경로라면 사고 기능을 끈 채로 effort를 낮출 수 있습니다.

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

다만 Anthropic은 사고 기능이 비활성화된 경우 다음 아티팩트가 나타날 수 있다고 문서화했습니다.

  • 실행되지 않는 도구 호출이 일반 텍스트로 출력됨
  • <thinking> 같은 내부 XML 태그가 응답에 노출됨
  • 에이전트 루프에서 노출 텍스트가 다음 턴 컨텍스트를 오염시킴

따라서 thinking: disabled는 기본값이 아니라 제한적인 최적화로 취급하는 편이 안전합니다.

3. effort 값을 그대로 이월하지 말고 다시 평가하세요

Opus 5의 기본 effort는 high이며, 각 effort 수준 자체도 이전 Opus 모델과 다르게 조정되었습니다.

특히 Opus 5의 low와 medium은 이전 Opus 모델보다 의미 있게 강력할 수 있습니다. 따라서 Opus 4.8에서 사용하던 effort 값을 그대로 복사하면 동일한 비용/품질 지점이 보장되지 않습니다.

권장 시작점은 다음과 같습니다.

워크로드 시작 effort 초기 max_tokens
단순 분류, 짧은 추출 low 또는 medium 4k~8k
일반 분석, 문서 작성 medium 또는 high 8k~16k
리팩토링, 복잡한 코드 작업 xhigh 32k 이상
장기 에이전트 작업 xhigh 64k부터 검증

평가할 때는 벤치마크 하나만 보지 말고 실제 서비스 평가 세트를 사용하십시오.

  1. 프롬프트와 입력 데이터를 고정합니다.
  2. low, medium, high, xhigh를 각각 실행합니다.
  3. 출력 품질, 지연 시간, usage, stop_reason을 저장합니다.
  4. 품질 기준을 통과하는 가장 낮은 effort를 선택합니다.

노력 매개변수 심층 분석에서 각 수준의 동작을 확인할 수 있으며, 비용 비교는 Opus 5 가격 분석을 참고하십시오.

4. 긴 컨텍스트 베타 헤더를 제거하세요

Opus 5는 기본적으로 최대 1M 토큰 컨텍스트 창을 제공합니다. 확장 컨텍스트를 활성화하기 위한 별도 베타 헤더가 필요하지 않으며, 긴 컨텍스트에 대한 가격 프리미엄도 없습니다.

기존 HTTP 클라이언트에 확장 컨텍스트용 anthropic-beta 헤더가 남아 있다면 제거하십시오.

 headers: {
-  "anthropic-beta": "context-1m-2025-08-07",
   "x-api-key": process.env.ANTHROPIC_API_KEY,
   "anthropic-version": "2023-06-01"
 }
Enter fullscreen mode Exit fullscreen mode

Messages API의 최대 출력은 128k 토큰입니다. 더 큰 출력이 필요하다면 Batch API에서 output-300k-2026-03-24 베타 헤더를 통해 최대 300k 출력 토큰을 사용할 수 있습니다. 이는 1M 컨텍스트 활성화와는 별도의 기능입니다.

5. 프롬프트 캐시 최소값이 512 토큰으로 낮아졌습니다

Opus 4.8에서는 캐싱하려는 프롬프트 세그먼트가 최소 1,024 토큰이어야 했습니다. Opus 5에서는 최소값이 512 토큰으로 낮아졌습니다.

기존 코드가 즉시 깨지지는 않습니다. 하지만 다음처럼 512~1,024 토큰 사이에 있는 반복 블록을 다시 찾아볼 가치가 있습니다.

  • 시스템 프롬프트
  • 도구 정의
  • few-shot 예시
  • 반복적으로 포함되는 정책 또는 도메인 문서

캐시 효과는 동일 요청을 두 번 실행한 뒤 두 번째 응답의 usage.cache_read_input_tokens로 확인하십시오.

const secondResponse = await client.messages.create(request);

console.log({
  cacheReadTokens: secondResponse.usage.cache_read_input_tokens,
  inputTokens: secondResponse.usage.input_tokens
});
Enter fullscreen mode Exit fullscreen mode

두 번째 호출에서 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": "더 간결하게 만드세요."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

이 기능은 Opus 5에만 적용됩니다. 같은 대화 기록을 claude-opus-4-8로 폴백하거나 라우팅할 수 있다면, 모델별 메시지 직렬화 로직을 유지해야 합니다.

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

Opus 4.8은 우선순위 티어를 지원하지만 Opus 5는 지원하지 않습니다.

프로덕션 지연 시간을 보장하기 위해 우선순위 티어 또는 약정 처리량에 의존하던 경로가 있다면, Opus 5로 옮기는 순간 표준 용량으로 돌아갈 수 있습니다.

실무적으로는 워크로드를 분리하는 방식이 안전합니다.

function selectModel(workload: {
  requiresPriorityTier: boolean;
}) {
  return workload.requiresPriorityTier
    ? "claude-opus-4-8"
    : "claude-opus-5";
}
Enter fullscreen mode Exit fullscreen mode

전체 트래픽을 한 번에 전환하지 말고 다음처럼 나누십시오.

  • 지연 시간 보장이 필요한 경로: Opus 4.8 유지
  • 일반 분석, 코딩, 에이전트 경로: Opus 5 평가 후 전환
  • 표준 용량에서 tail latency가 허용 범위인지 측정 가능한 경로: 점진 전환

8. 고속 모드와 서버 측 폴백을 선택적으로 사용하세요

고속 모드

고속 모드는 Opus 5에서 동작합니다. 입력 토큰 100만 개당 10달러, 출력 토큰 100만 개당 50달러로 약 2.5배의 출력 속도를 제공합니다.

다만 다음 제약이 있습니다.

  • 연구 미리 보기 기능입니다.
  • Anthropic 자체 API에서만 지원됩니다.
  • Amazon Bedrock, Google Cloud, Microsoft Foundry에서는 지원되지 않습니다.
  • Batch API와 함께 사용할 수 없습니다.

따라서 배치 작업보다 사용자 대화, IDE 보조, 즉시 응답이 필요한 인터랙티브 경로에 사용하는 편이 적합합니다.

사이버 거부에 대한 서버 측 폴백

server-side-fallback-2026-07-01 베타 헤더와 함께 fallbacks: "default"를 전송하면, Opus 5가 사이버 범주를 이유로 거부한 요청을 Opus 4.8로 자동 폴백할 수 있습니다.

{
  "model": "claude-opus-5",
  "max_tokens": 8192,
  "fallbacks": "default",
  "messages": [
    {
      "role": "user",
      "content": "보안 검토 결과를 구조화해 주세요."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

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

9. 변경되지 않은 사항

다음은 기존 구현을 그대로 유지할 수 있는 부분입니다.

  • 샘플링 매개변수 제약: temperature, top_p, top_k에 기본값 이외의 값을 전달하면 Opus 4.8과 마찬가지로 400 오류가 발생합니다.
  • 토큰 개수: Opus 5는 Opus 4.8과 같은 토크나이저 계열을 사용하므로 기존 토큰 예산과 비용 모델을 대체로 그대로 사용할 수 있습니다.
  • 기본 가격: 입력 토큰 100만 개당 5달러, 출력 토큰 100만 개당 25달러로 동일합니다. 자세한 내용은 Opus 4.8 가격 페이지를 참고하십시오.
  • API 요청 및 응답 형태: 스트리밍, 도구 사용, 비전, 구조화된 출력, 배치 처리는 기존과 같은 방식으로 동작합니다.

다만 프롬프트는 다시 검토하십시오. Opus 5는 별도 지시가 없어도 작업을 자체 검증할 수 있으므로, 기존의 “답변을 다시 확인해 보세요” 같은 지시가 불필요한 토큰 사용을 유발할 수 있습니다.

또한 기본 응답이 Opus 4.8보다 길 수 있습니다. 더 짧은 출력을 원한다면 effort를 낮추기보다 명시적인 길이 지시를 추가하십시오.

결론만 3개의 불릿으로 작성하세요.
각 불릿은 25단어 이하로 제한하세요.
추론 과정은 출력하지 마세요.
Enter fullscreen mode Exit fullscreen mode

프롬프트 작성 전략은 Claude Opus 5 프롬프트 작성에서 확인할 수 있습니다.

배포 전에 마이그레이션을 검증하세요

이 변경 사항은 대부분 HTTP 요청 수준에서 확인할 수 있습니다. Apidog 같은 API 클라이언트로 아래 테스트 컬렉션을 구성하면 애플리케이션 배포 전에 문제를 찾을 수 있습니다.

  1. 환경 변수에 API 키를 저장하고 Messages 엔드포인트 요청을 하나 만듭니다.
  2. 기준 요청을 claude-opus-4-8로 저장합니다.
  3. 같은 요청을 복제해 claude-opus-5 기본 설정 버전을 만듭니다.
  4. low, medium, high, xhigh effort별 요청을 각각 만듭니다.
  5. thinking: disabled와 xhigh 조합을 의도적으로 실행해 400 응답 본문을 기록합니다.
  6. stop_reason !== "max_tokens"를 테스트 조건으로 추가합니다.
  7. 캐시된 동일 요청을 두 번 실행하고 두 번째 응답의 usage.cache_read_input_tokens를 확인합니다.
  8. 스트리밍 요청을 실행해 SSE 파서가 기본 사고 블록을 처리하는지 확인합니다.
  9. 우선순위 티어가 필요한 경로와 일반 용량으로 전환 가능한 경로를 분류합니다.

테스트 스크립트에는 다음 같은 검증을 추가할 수 있습니다.

function assertClaudeResponse(response) {
  if (response.stop_reason === "max_tokens") {
    throw new Error("Claude 응답이 토큰 한도에서 잘렸습니다.");
  }

  if (!response.usage) {
    throw new Error("usage 정보가 없습니다.");
  }

  return {
    stopReason: response.stop_reason,
    usage: response.usage
  };
}
Enter fullscreen mode Exit fullscreen mode

재사용 가능한 모델 마이그레이션 컬렉션을 만들려면 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일 기준 공급업체 자체 테스트입니다. 이를 프로덕션 성능 보장으로 간주하지 말고, 반드시 자체 평가 세트로 검증하십시오.

실무적인 결론은 간단합니다.

  • 일반적인 Opus 4.8 워크로드는 Opus 5로 이전할 수 있습니다.
  • 사고 기능과 effort에 따른 토큰 예산을 다시 측정해야 합니다.
  • 우선순위 티어가 필요한 트래픽은 별도 결정이 필요합니다.
  • 벤치마크보다 실제 서비스 입력과 품질 기준으로 전환 여부를 판단해야 합니다.

마이그레이션 체크리스트

다음 순서로 적용하십시오.

  1. 모델 문자열을 정확히 claude-opus-5로 변경합니다. 날짜 접미사는 사용하지 않습니다.
  2. 이전에 thinking을 생략하던 요청의 max_tokens를 높입니다.
  3. 코드베이스에서 "disabled"를 검색합니다.
  4. thinking: {"type": "disabled"}와 xhigh 또는 max가 함께 사용되는 요청을 제거합니다.
  5. anthropic-beta에서 긴 컨텍스트용 베타 값을 제거합니다.
  6. 실제 평가 세트로 low부터 xhigh까지 effort를 다시 비교합니다.
  7. 512~1,024 토큰 길이의 공통 프롬프트 블록에 cache_control 적용을 검토합니다.
  8. 우선순위 티어를 사용하는 트래픽을 식별하고 Opus 4.8 유지 여부를 결정합니다.
  9. “다시 확인하세요”처럼 중복된 프롬프트 지시를 제거합니다.
  10. 응답 길이가 중요한 경로에는 명시적인 간결성 요구를 추가합니다.
  11. 필요한 경우 fallbacks: "default"를 활성화합니다.
  12. 테스트 스위트에서 stop_reason을 검증해 잘린 응답을 실패로 처리합니다.

전체 요청 구조는 Claude Opus 5 API 가이드를 참고하십시오. 모델 사양과 가용성은 Claude Opus 5란 무엇인가 및 Anthropic의 모델 개요에서 확인할 수 있습니다.

이전 모델도 함께 운영한다면 Opus 4.8 설명과 Opus 4.8 API 워크스루를 함께 참고하십시오.

자주 묻는 질문

Opus 4.8에서 Opus 5로의 마이그레이션은 드롭인 방식인가요?

거의 그렇지만 완전히 동일하지는 않습니다. 대부분의 요청은 모델 문자열 변경만으로 동작합니다. 다만 기본 사고 기능이 활성화되어 max_tokens 예산을 공유하고, thinking: {"type": "disabled"}와 xhigh 또는 max effort를 함께 사용하면 400 오류가 발생합니다. 우선순위 티어도 Opus 5에서는 지원되지 않습니다.

claude-opus-5로 바꾼 뒤 400 오류가 발생하는 이유는 무엇인가요?

가장 흔한 원인은 사고 기능을 끈 상태에서 xhigh 또는 max effort를 요청한 경우입니다. thinking 필드를 제거하거나, 사고 기능을 끈 채로 effort를 high 이하로 낮추십시오.

또한 temperature, top_p, top_k에 기본값 이외의 값을 전달해도 Opus 4.8과 마찬가지로 400 오류가 발생합니다.

마이그레이션 후 토큰을 다시 계산해야 하나요?

전체 토큰 개수를 처음부터 다시 계산할 필요는 없습니다. Opus 5는 Opus 4.8과 같은 토크나이저 계열을 사용하므로 토큰 개수는 거의 동일합니다.

다만 기본 사고 기능이 활성화되므로, 실제 요청의 출력 및 사고 관련 토큰 사용량은 달라질 수 있습니다. 기존 비용 모델은 유지하되, usage 데이터를 수집해 max_tokens와 effort 설정을 다시 조정하십시오.

Top comments (0)