이 기사의 요점

• Claude Opus 5는 Opus 4.8과 동일한 가격 및 동일한 기능 세트를 가진 드롭인 업그레이드(drop-in upgrade)이지만, 주의가 필요합니다. 파라미터를 아무것도 변경하지 않고 모델 ID만 교체하면, thinking의 기본값이 ON으로 반전됩니다. 또한 max_tokens가 사고(thinking) + 응답의 합산 상한이 되기 때문에 응답이 중간에 끊길 수 있습니다.
• thinking: {"type": "disabled"}와 effort: xhigh / max의 조합은 400 에러를 발생시킵니다. 이는 요청 단위의 검증이므로, 대화 도중에 effort를 높이는 경로도 대상이 됩니다.
• 마이그레이션 시 정말 효과적인 것은 API 수정보다 프롬프트 측면의 튜닝입니다. 특히 "검증을 지시하기", "더 많이 위임하라고 지시하기"와 같은 Opus 4.8용 정석적인 지시는 Opus 5에서는 삭제하는 것이 정답이 되었습니다.

Claude Opus 5는 Claude Opus 4.8의 후속 모델로, 복잡한 에이전틱 코딩(agentic coding)이나 엔터프라이즈 업무를 위한 모델입니다. 가격과 기능 세트 모두 4.8과 동일하므로 "모델 ID만 바꾸면" 마이그레이션할 수 있을 것처럼 보이지만, 실제로는 코드를 망가뜨리는 두 가지 파괴적 변경(breaking changes)이 있으며, 프롬프트의 효과가 달라지는 항목이 10개 가까이 있습니다.

이 기사에서는 Opus 5의 스펙과 포지셔닝, 두 가지 파괴적 변경, effort 파라미터의 실전적인 사용법, 새롭게 도입된 API 기능, 그리고 "조용히 망가지는" 타입의 함정과 그 대처법까지, 실제로 수정해야 할 코드 단위로 정리합니다.

컨텍스트 윈도우의 1M 토큰은 베타 헤더 등으로 활성화하는 옵션이 아니라 기본값이자 최대값입니다.

가격은 $/1M 토큰 기준이며, 입력 / 출력으로 나뉩니다.

최고 성능 티어는 Fable 5입니다. Opus 5는 그 절반 가격으로, 깊은 추론(reasoning) · 에이전틱(agentic) / 장기 태스크 · 테스트 시간 연산(test-time compute) 스케일링에 가장 강력하다는 포지션을 가집니다.

그리고 Opus 4.8과는 가격과 기능 세트가 동일합니다. 즉, "Opus 4.8을 사용 중이라면 비용 증가 없이 갈아탈 수 있다"는 것이 Opus 5의 기본적인 포지셔닝입니다. 다만 후술하는 바와 같이, 수정 없이 갈아탈 수 있는 것은 아닙니다.

인프라 측면에서 먼저 파악해 두어야 할 점이 두 가지 있습니다.

레이트 리미트(Rate Limit)는 Opus 4.x 계열과는 별도의 버킷(bucket)입니다

Opus 4.8 / 4.7 / 4.6 / 4.5는 공유 풀(pool)이지만, Opus 5는 거기서 독립되어 있습니다. Opus 4.8에서 마이그레이션하더라도 기존 버킷의 할당량은 비워지지 않으며, 기존 할당량을 승계하지도 않습니다. 운영 트래픽을 옮기기 전에, 본인의 티어에서 Opus 5에 할당된 할당량이 얼마나 되는지 반드시 확인하십시오.

Priority Tier는 Opus 5를 지원하지 않습니다

Fable 5나 Opus 4.8 등은 지원하지만, Opus 5 / Sonnet 5 / Mythos 5는 제외되어 있으며, Priority Tier를 지정한 요청은 유효성 검사 오류(Validation Error)가 발생합니다. Priority Tier를 전제로 설계된 루트는 모델 ID(Model ID)만 교체해서는 작동하지 않습니다.

이 부분이 Opus 5 마이그레이션의 가장 큰 고비입니다.

Opus 4.8 / 4.7에서는 thinking 파라미터를 생략한 요청은 사고(Thinking)하지 않았습니다. Opus 5에서는 이와 반대로, 생략한 요청은 사고를 합니다 ({"type": "adaptive"}를 지정한 것과 동일한 동작).

코드를 한 줄도 바꾸지 않아도 동작이 변하는, 이번 업데이트에서 가장 사고가 나기 쉬운 포인트입니다.

# Opus 4.8까지: thinking을 쓰지 않으면 사고하지 않음
response = client.messages.create(
model="claude-opus-4-8",
...

# Opus 5: 동일한 코드라도 사고함
response = client.messages.create(
model="claude-opus-5",
...

max_tokens는 사고(Thinking)와 응답 텍스트의 합계에 대한 상한선입니다. 즉, Opus 4.8에서 "사고하지 않음"을 전제로 max_tokens를 타이트하게 설정해 두었다면, Opus 5에서는 사고 과정이 먼저 예산을 소모하여 응답 텍스트가 중간에 끊기게 됩니다.

400 에러가 발생한다면 알아챌 수 있겠지만, 이것은 에러가 발생하지 않습니다. 요청은 200으로 반환되고 응답도 존재하지만, 단지 내용이 중간에 잘릴 뿐입니다. 유효성 검사가 느슨한 후속 처리 단계라면 그대로 흘러가 버리게 됩니다.

【Opus 4.8】thinking을 작성하지 않음 = 사고하지 않음
|<---------------- max_tokens ---------------->|
+----------------------------------------------+
...

모델 ID를 claude-opus-5로 교체한다면, 모든 루트에서 max_tokens를 재검토하십시오. "하나의 엔드포인트만 수정했다"로는 부족합니다. 배치 처리(Batch processing), 사내 도구, 원샷(One-shot) 요약 작업 등 thinking을 명시하지 않은 모든 코드가 대상입니다. Opus 5는 raw chain of thought(가공되지 않은 사고 과정)를 반환하지 않습니다. display의 기본값은 "omitted"입니다. 요약이 필요한 경우에는 display: "summarized"를 명시해야 합니다.

import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
...

대응 방법은 두 가지입니다.

단, 후자의 경우에는 다음 장과 후반부의 "두 가지 함정"에서 설명할 조건이 따라붙습니다. 기본적으로는 사고를 활성화한 상태에서 effort를 조정하는 방향을 최우선으로 검토하는 것을 권장합니다.

thinking: {"type": "disabled"}는 effort가 high 이하일 때만 사용할 수 있습니다.

400 에러가 발생하는 조건 자체는 단순하지만, disabled

및 effort가 서로 다른 파일에 설정되어 있으면 알아차리기 어렵습니다. 두 가지를 모두 한꺼번에 grep 하는 것이 빠릅니다.

이 부분이 실무에서 매우 중요한 포인트입니다. 이 검증은 **요청 단위 (request unit)**로 수행됩니다. 대화 도중에 effort를 높이는 하네스 (harness)를 구성해 두었다면, 그 이전의 턴들이 모두 통과했더라도 effort를 높인 바로 그 요청만 거부됩니다.

"작동하니까 괜찮다"는 논리가 통하지 않습니다. 동적으로 effort를 높이는 로직을 가진 코드는 특히 주의하십시오.

# "어려워지면 effort를 높인다" 타입의 하네스
effort = "high"
for turn in conversation:
...

thinking을 정적인 설정값(환경 변수나 설정 파일)으로 유지하면서, effort를 동적으로 변경하는 설계는 Opus 5에서 깨지기 쉽습니다. thinking과 effort는 세트로 결정되는 하나의 설정으로 취급하십시오.

Opus 4.7 이전 모델에서 마이그레이션하는 경우에는 다음 사항도 함께 대응해야 합니다. 이것들은 Opus 5에서 새로 도입된 제약이 아니라, 4.7 이후부터 계속 400 에러가 발생하던 항목들입니다.

effort는 최상위 레벨(top-level)이 아니라 output_config 내부에 있습니다. 이 부분을 실수하기 쉬우니 주의하십시오.

output_config={"effort": "xhigh"}

Opus 5에서 effort를 결정하는 방법에는 명확한 권장 사항이 있습니다.

• 코딩 / 에이전틱 (agentic) 작업은 xhigh부터 시작
• 그 외의 지능 중시 워크로드는 high부터 시작하여 그 아래 방향으로 스윕 (sweep) 할 것

max는 가장 깊은 추론을 위한 것이지만, 수확 체감의 법칙이 적용되어 간단한 태스크에서는 과하게 생각할 수 있습니다. 처음부터 max로 설정하는 것은 현명한 전략이 아닙니다.

"일단 높은 쪽으로 설정한다"가 아니라, 높은 곳에서 시작하여 점차 낮춰가는 것이 핵심입니다. Opus 5는 low / medium 설정이 기존 등급 이상으로 강력하여, 많은 워크로드에서 품질을 유지하면서도 토큰 양과 레이턴시(latency)를 훨씬 줄일 수 있습니다.

이전 모델에서 이어받은 effort 설정은 최적이 아닐 가능성이 높습니다.

Opus 4.8에서 튜닝한 effort 값을 그대로 가져오면, Opus 5에서는 과도한 비용을 지불하고 있을 가능성이 큽니다. 마이그레이션 시 한 번쯤 다시 스윕해 볼 가치가 있습니다.

xhigh / max를 사용할 때는 max_tokens를 크게 잡아야 합니다. 64K를 기점으로 조정하는 것이 기준입니다. 앞 장에서 언급했듯이 max_tokens는 사고(thinking) + 응답(response)의 합산 상한선이므로, 깊게 생각하게 할수록 응답 텍스트용으로 남는 토큰이 줄어듭니다.

장시간 작동하는 에이전틱 작업에서는 task_budget을 병용할 수 있습니다.

with client.beta.messages.stream(
model="claude-opus-5", max_tokens=128000,
output_config={"effort": "high", "task_budget": {"type": "tokens", "total": 64000}},
...

task_budget의 최소 total 값은 20,000입니다. max_tokens와 task_budget

이름은 비슷하지만 역할이 다릅니다.

Opus 5는 강화된 사이버 보안 세이프가드 (Cybersecurity Safeguards)를 갖추고 있어, 안전 분류기 (Safety Classifier)가 요청을 거부할 수 있습니다. fallbacks는 거부되었을 때 서버 측에서 다른 모델로 재실행시키는 메커니즘입니다.

기존에는 대체 모델을 직접 지정했습니다.

{
"model": "claude-opus-5",
"fallbacks": [{"model": "claude-opus-4-8"}],
...
}

이 배열 형식에는 beta 헤더 server-side-fallback-2026-06-01을 사용합니다.

새로운 "default" 모드에서는 Anthropic이 권장하는 대체 대상이 거부 카테고리별로 자동 라우팅됩니다. 예를 들어 cyber 카테고리의 거부는 Claude Opus 4.8로 전달됩니다.

POST /v1/messages
anthropic-beta: server-side-fallback-2026-07-01
{"model": "claude-opus-5", "fallbacks": "default", "max_tokens": 1024,
...

모델을 고정하는 것보다 "default"를 사용하는 것이 권장됩니다. 대체 모델이 향후 지원 중단(Deprecated)되더라도 별도의 마이그레이션 작업이 필요 없기 때문입니다.

헤더와 파라미터 형식은 반드시 세트로 사용해야 합니다.

배열 형식에 -2026-07-01을, "default"에 -2026-06-01을 조합하면 400 에러가 발생합니다. 베타 헤더만 최신으로 바꾸고 내용은 배열 그대로 두는 것이 흔히 발생하는 실수입니다.

기존에 tools는 대화 중에 고정되어 있었습니다. 변경하면 프롬프트 캐시 (Prompt Cache)가 모두 무효화됩니다 (tools는 프리픽스 (Prefix)의 맨 앞에 렌더링되기 때문).

Opus 5 이후부터는 캐시를 유지하면서 턴(Turn) 사이에 도구를 추가하거나 삭제할 수 있습니다.

방법은 {"role": "system", "content": [...]} 메시지에 tool_addition / tool_removal 블록을 포함하는 방식입니다. 도구는 tool_reference를 통해 이름으로 참조합니다.

tools = [
{"name": "get_weather", "description": "Get weather",
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}}},
...
]

포인트는 다음과 같습니다.

• 추가하고 싶은 도구는 미리 tools[]에 "defer_loading": True를 붙여 선언해 두어야 합니다. "선언은 되어 있지만 컨텍스트에는 로드되지 않은" 상태를 만들어 두는 개념입니다.
• tool_removal 블록은 assistant 메시지 직전이나 messages의 끝에 배치합니다.
• 도구 정의를 "변경"하고 싶다면, 첫 번째 요청에서 삭제 → 다음 요청에서 업데이트된 버전을 tools[]에 넣는 2단계 과정을 거쳐야 합니다.
• SDK의 타입 정의가 아직 따라오지 못했기 때문에, Python은 일반 dict를 사용하고, TypeScript는 @ts-expect-error를 붙여서 전달해야 합니다.

messages 배열 안에 {"role": "system", "content": "..."}를 삽입할 수 있게 되었습니다. 이 경우 beta 헤더는 필요하지 않습니다.

최상위(Top-level)의 system을 다시 쓰면 캐시된 프리픽스가 모두 무효화되지만, 이 방식을 사용하면 캐시가 유지됩니다.

messages = [
{"role": "user", "content": "이 설계를 리뷰해줘"},
{"role": "assistant", "content": "..."},
...
]

또 다른 장점은 프롬프트 인젝션 (Prompt Injection) 내성입니다. 기존처럼 user 턴의 텍스트에 운영자 지시사항을 삽입하는 방식은 사용자 입력에 의해 위조될 수 있습니다. system 역할의 메시지는 위조할 수 없는 '운영자 채널'로 사용할 수 있습니다.

Sonnet 5는 미지원입니다. 모델을 동적으로 전환하는 라우팅 계층을 가지고 있는 경우, Opus 5용으로 작성된 대화 중간 시스템 메시지가 Sonnet 5로 전달되면 400 에러가 발생합니다.

Opus 4.8의 1024에서 절반으로 줄었습니다. 즉, 지금까지 "너무 짧아서 캐시할 수 없다"며 포기했던 시스템 프롬프트가 코드 변경 없이 캐시될 수 있게 됩니다.

response = client.messages.create(
model="claude-opus-5",
max_tokens=16000,
...

주의할 점은, 이 최소값이 세대 순으로 단조 증가/감소하지 않는다는 것입니다.

최소 캐시 가능 접두사 길이
512 |#### Opus 5 / Fable 5 / Mythos 5
1024 |######## Opus 4.8 / Sonnet 5 / Sonnet 4.6 / 4.5
...

최신 모델인 Opus 5가 512인 반면, Opus 4.6이나 Haiku 4.5는 4096입니다. "새 모델일수록 작다"라고 단정 짓고 멀티 모델 대응 캐시 판정 로직을 작성하면 오류가 발생합니다.

가격 측면에서 캐시 읽기(Read)는 기본 입력 가격의 약 0.1배이며, 쓰기(Write)는 5분 TTL 기준 1.25배, 1시간 TTL 기준 2배입니다.

동일한 Opus 5를 더 빠르게 구동하는 모드입니다. 작은 모델로 전환하는 것이 아닙니다.

client.beta.messages.create(
model="claude-opus-5", max_tokens=4096,
speed="fast", betas=["fast-mode-2026-02-01"],
...

speed: "fast"와 beta 헤더를 추가하는 것 외에도, beta 엔드포인트(client.beta.messages.*)를 사용해야 합니다.

429 에러가 발생했을 때는 retry-after를 기다리거나, speed를 낮추어 일반 모드로 폴백(Fallback)합니다. 다만 속도 전환 시 프롬프트 캐시가 무효화된다는 점에 주의하십시오. 폴백이 일어날 때마다 캐시를 버리게 됩니다.

멀티 클라우드 구성에서 "Bedrock 경유로도 폴백한다"와 같은 라우팅을 가지고 있는 경우, Fast mode는 Claude API 경로로만 한정하십시오. Bedrock / Google Cloud / Microsoft Foundry에서는 사용할 수 없습니다.

Opus 5는 강화된 사이버 보안 세이프가드(Safeguard)를 갖추고 있어, 안전 분류기(Safety Classifier)가 요청을 거부할 수 있습니다. 여기서 중요한 점은 거부는 에러가 아니다라는 점입니다.

거부는 **HTTP 200 + stop_reason: "refusal"**로 반환됩니다.

stop_details에 category가 포함됩니다 ("cyber" / "bio" / "reasoning_extraction" / "frontier_llm" / null 등). 예외(Exception)가 발생하지 않습니다. 따라서 try / except로는 잡아낼 수 없습니다.

# Before: 흔히 사용하는 방식
response = client.messages.create(...)
text = response.content[0].text # refusal 발생 시 오류 발생

# After: stop_reason을 먼저 확인
response = client.messages.create(...)
if response.stop_reason == "refusal":
    ...

response.content[0]를 무조건적으로 읽는 코드는 Opus 5에서 작동하지 않습니다. 반드시 stop_reason을 먼저 확인하십시오.

선의의 보안 업무나 생명 과학(Life Science) 업무에서도 드물게 오탐(False Positive)이 발생할 수 있으므로, "우리 유스케이스는 관련이 없으니 발생하지 않을 것이다"라고 판단하는 것은 위험합니다.

앞서 언급한 fallbacks: "default"를 옵트인(Opt-in)해 두면, cyber 카테고리의 거부는 Opus 4.8로 라우팅됩니다. 즉, 거부 핸들링(Refusal Handling)과 fallbacks는 세트로 구성해야 실제로 복구(Recovery)가 가능합니다. 한쪽만 적용하면 거부를 감지하더라도 대체 결과를 얻지 못하거나, 대체 기능이 작동하더라도 호출 측에서 에러가 발생하게 됩니다.

이후 내용은 thinking: {"type": "disabled"}를 명시적으로 설정한 경우에만 해당합니다. Opus 5는 기본적으로 사고(Thinking) 기능이 ON 상태이므로, 일반적인 요청이 이 상황에 해당하지는 않습니다. Opus 4.8에서 "사고 없음" 설정을 그대로 이어받은 코드가 대상입니다.

결론부터 말씀드리면, 두 가지 함정 모두에 대한 최우선 권장 대처법은 동일합니다. 사고(Thinking) 기능을 다시 ON으로 돌리고 effort를 낮추는 것입니다.

다음은 가장 까다로운 문제입니다.

구조화된 tool_use 블록이 아니라, 사용자용 텍스트 안에 도구 호출(Tool Call)을 작성해 버리는 경우가 있습니다.

이 경우 다음과 같은 현상이 발생합니다:

• 턴(Turn)은 정상적으로 종료됩니다 (stop_reason은 이상 없음)
• 도구 호출은 실행되지 않습니다
• 에러도 발생하지 않습니다
• tool_use 블록도 나타나지 않습니다

즉, 하네스(Harness) 측면에서는 "성공했지만 아무것도 하지 않은 턴"으로 보이게 됩니다. 로그에도 예외가 남지 않습니다. 모니터링 중에도 알아채기 어려운 전형적인 **사일런트 페일러(Silent Failure)**입니다.

에이전틱 루프(Agentic Loop)에서는 상황이 더 악화됩니다. 해당 가짜 텍스트가 대화 기록에 남아 후속 턴을 왜곡합니다. 모델 스스로가 "도구를 호출했다"고 착각한 상태로 대화가 진행되기 때문입니다.

검색 등 도구를 많이 사용하는 워크로드에서 발생하기 쉬운 경향이 있습니다.

대처 방법은 다음과 같습니다.

완화책이 효과가 있는 이유는, 서론(Preamble)을 억제하려는 시도가 원인인 것처럼 보이기 때문입니다. "불필요한 말은 하지 말고 도구를 호출하라"는 지시가 오히려 이 실패 모드를 유발하고 있을 가능성이 있습니다.

사고(Thinking) 기능을 비활성화하면, <thinking> 태그가 가시적인 응답에 유출될 수 있습니다.

사고 기능을 ON으로 돌릴 수 없는 경우의 대처법은 두 가지 모두 직관에 반합니다.

# Before (흔히 하지만 역효과를 낳는 방식)
생각하지 마세요. 추론하지 말고 직접 답하세요.
<thinking> 태그를 출력하지 마세요.

# After
내부 또는 시스템의 XML 태그를 응답에 포함하지 마세요.

핵심 포인트는 두 가지입니다.

• "생각하지 마라 / 추론하지 마라"라는 지시는 삭제하십시오. 이는 태그 유출을 오히려 늘립니다.
• 지시는 범용적으로 작성하고, 사고 태그를 직접 지칭하지 마십시오. "내부 또는 시스템의 XML 태그를 응답에 포함하지 마세요"라고 하는 것이 더 효과적입니다.

"<thinking>

「태그를 출력하지 마라」고 명시적으로 적을수록 오히려 누출되기 쉽다는 점은 많은 사람의 직관과 반대되는 부분입니다. 프롬프트에 "출력해서는 안 되는 것"을 구체적인 명칭으로 나열하는 습관이 있다면, 이 항목만큼은 예외로 처리하십시오.

파괴적인 변경 사항에 대해 계속 이야기했지만, 마이그레이션의 동기가 될 수 있는 부분들도 정리해 두겠습니다.

어려운 태스크일수록 강력하다는 것이 특징입니다. 여러 파일에 걸친 기능 구현, 대규모 리팩토링 (Refactoring), 엔드 투 엔드 (End-to-End) 기능 개발 등에서 차이가 나타납니다. 스텁 (Stub)이나 플레이스홀더 (Placeholder)를 남기지 않고 완수합니다.

반대로, 간단한 단발성 편집에서는 이전 모델과의 차이가 작아집니다.

Opus 5를 평가할 때는 어려운 쪽의 태스크로 평가하십시오. "가벼운 수정을 던져서 비교하는" 타입의 평가는 차이가 보이지 않아 도입 판단을 그르칠 수 있습니다.

또한, 태스크 사양을 처음에 한꺼번에 전달하여 실행하는 것이 효과적입니다. 지시 사항을 조금씩 나누어 추가하는 것보다, 첫 번째 턴 (Turn)에 사양을 모두 전달하는 것이 더 잘 맞물립니다.

높은 정밀도 (Precision) 및 높은 재현율 (Recall)을 보입니다. 1패스 (Pass)당 실제 버그 검출률이 높으며, 추가로 제기되는 지적 사항들도 오검출이 아닌 실제 버그인 경우가 많아지고 있습니다.

실무적으로 유용한 점은 낮은 노력 (Low effort)으로도 정확도가 잘 떨어지지 않는다는 점입니다. "리뷰 시에는 우선 저비용 패스로 돌리고, 필요한 부분에만 나중에 정밀한 패스를 적용한다"는 운영 방식이 현실적이 됩니다.

차트, 문서, 도표의 이해, 그리고 UI / 프론트엔드 (Front-end)의 시각적 재현 능력이 향상되었습니다.