Claude Opus 5.5로 마이그레이션하기
이전 Claude 모델에서 Claude Opus 5.5로 마이그레이션하는 방법을 안내합니다: 모델 ID, 호환성이 깨지는 변경 사항, 권장 변경 사항 및 마이그레이션 체크리스트.
동작상의 차이점과 모델별 프롬프팅 패턴은 Claude Opus 5.5 프롬프팅을 참조하세요.
Claude Opus 5.5는 Claude Opus 5보다 비용이 저렴하며(입력/출력 토큰 100만 개당 $4 / $20 USD로, Claude Opus 5의 $5 / $25와 비교됩니다. Claude 가격 참조), Claude Opus 5의 1M 토큰 "context window"(컨텍스트 윈도우)와 128k 최대 출력 토큰을 그대로 유지합니다. 이미 Claude Opus 5에서 실행 중인 코드에는 네 가지 "breaking change"(호환성이 깨지는 변경 사항)가 있으며, 이는 호환성이 깨지는 변경 사항에서 다룹니다. 기능 지원에 대해서는 Claude Opus 5.5의 새로운 기능을 참조하세요.
Claude Opus 5에서 Claude Opus 5.5로 마이그레이션하기
모델 이름 업데이트
model = "claude-opus-5" # Before
model = "claude-opus-5-5" # Afterclaude-opus-5-5는 날짜 접미사가 없는 고정 모델 ID로, claude-opus-5와 동일한 체계입니다. Amazon Bedrock, Claude Platform on AWS, Google Cloud 및 Microsoft Foundry에서는 해당 플랫폼의 모델 ID를 사용하세요. 가용성을 참조하세요.
호환성이 깨지는 변경 사항
각 변경 사항은 Claude Opus 5.5의 새로운 기능에서 설명하며, 이 섹션에서는 각 변경 사항에 대한 코드 변경을 제공합니다.
사고를 비활성화할 수 없음
thinking: {"type": "disabled"}와 thinking: {"type": "enabled", "budget_tokens": N}는 모두 400 오류("thinking.type.disabled" is not supported for this model. 또는 "thinking.type.enabled" is not supported for this model.)를 반환합니다. thinking 필드를 제거하고 effort 수준을 선택하세요. 토큰을 절약하기 위해 사고를 비활성화했던 경우에는 더 낮은 수준을 사용하세요. 그러면 응답이 thinking 블록으로 시작하므로, type으로 콘텐츠 블록을 선택하고 도구 결과와 함께 thinking 블록을 수정하지 않은 채로 다시 전달하세요. 사고를 비활성화할 수 없음을 참조하세요.
변경 전(Claude Opus 5에서는 허용되고, Claude Opus 5.5에서는 거부됨):
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "disabled"},
messages=[{"role": "user", "content": "..."}],
)변경 후:
client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
output_config={"effort": "low"}, # thinking is always on; effort is the control
messages=[{"role": "user", "content": "..."}],
)강제 도구 사용은 지원되지 않음
tool_choice 유형 any와 tool은 토큰 카운팅 엔드포인트를 포함하여 400 오류(tool_choice: type "tool" and "any" are not supported for this model.)를 반환합니다. 엄격한 도구 사용 또는 구조화된 출력과 함께 auto를 사용하고, 도구가 적용되는 경우를 프롬프트에 명시하세요. 강제 도구 사용은 지원되지 않음을 참조하세요.
변경 전:
client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)변경 후:
client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
# strict tool use(엄격한 도구 사용): 모든 호출이 도구의 input_schema와 일치합니다
tools=[{**tool, "strict": True} for tool in tools],
tool_choice={"type": "auto"},
messages=[
{
"role": "user",
"content": "What's the weather in Paris? Use the get_weather tool.",
}
],
)사고 블록은 모델 및 대화에 연결됨
Claude API에서는 Claude Fable 5.1과 Claude Mythos 5.1이 Claude Opus 5.5의 사고 블록을 읽을 수 있으며, 다른 모델은 읽을 수 없습니다. 대화를 Claude Opus 5.5에서 다른 모델로 옮기는 라우터나 폴백은 해당 턴을 사고 블록 없이 실행합니다. 반대 방향으로, Claude Opus 5.5는 Claude Opus 5 및 이전 Opus, Sonnet, Haiku 모델의 사고 블록은 읽지만, Claude Fable 또는 Claude Mythos 모델의 사고 블록은 읽지 않습니다. 블록이 유효하게 유지되도록 대화를 추가 전용(append-only)으로 유지하세요(대화 도중 system 프롬프트, tools 또는 이전 메시지를 편집하지 않음). Claude Code, claude.ai, Claude Managed Agents 및 Claude Agent SDK는 이미 이렇게 하고 있습니다. 적용 방식은 모든 플랫폼에서 Claude Fable 5.1과 동일합니다: 2026년 8월 31일 00:00 UTC 이후에 생성된 계정의 경우, 이러한 편집 후 사고 블록을 재전송하면 기본적으로 400 오류가 반환됩니다. 추가 전용 통합에는 코드 변경이 필요하지 않습니다. 사고 블록은 모델 및 대화에 연결됨 및 보존된 사고를 참조하세요.
computer_20251124 컴퓨터 사용 도구는 Claude API 및 Google Cloud에서 지원되지 않음
Claude API 및 Google Cloud에서 유형이 computer_20251124인 tools 항목은 400 오류('claude-opus-5-5' does not support tool types: computer_20251124.와 그 뒤에 모델이 허용하는 도구 유형)를 반환합니다. 대신 computer_toolset_20260801 도구 세트를 선언하세요: 베타 헤더를 제거하고 name이나 디스플레이 크기 없이 항목을 전송하세요. 에이전트 루프에서는 멤버 tool_use 블록(액션은 input.action이 아니라 블록의 name입니다)을 턴당 여러 개 처리하고, 모든 결과에 toolset_name을 그대로 반환하세요. 요청 변경 사항은 아래에 나와 있으며, 에이전트 루프 변경 사항은 computer_20251124에서 마이그레이션에 나열되어 있습니다. Amazon Bedrock에서는 이전 computer_20251124 도구가 Claude Opus 5에서와 마찬가지로 Claude Opus 5.5에서도 계속 작동하므로 변경이 필요하지 않습니다. 다른 플랫폼의 경우 컴퓨터 사용 도구의 호환성 섹션을 참조하세요. Claude API 및 Google Cloud에서 computer_20251124 컴퓨터 사용 도구는 지원되지 않음을 참조하세요.
변경 전:
client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["computer-use-2025-11-24"],
tools=[
{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768,
}
],
messages=[{"role": "user", "content": "Open the display settings."}],
)변경 후:
client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
# 베타 헤더가 필요 없으며, toolset 항목에는 이름이나 디스플레이 크기를 지정하지 않습니다
tools=[{"type": "computer_toolset_20260801"}],
messages=[{"role": "user", "content": "Open the display settings."}],
)도구 호출 사이의 텍스트가 사고 블록으로 반환됨
Claude Opus 5에서는 모델이 도구 호출 사이에 작성하는 텍스트가 text 블록으로 반환됩니다. Claude Opus 5.5에서는 Claude Fable 5.1과 마찬가지로 이러한 설명이 진행 상황 업데이트 thinking 블록으로 반환되며, 각 도구 호출 앞에 최대 하나씩 반환됩니다. 기본 thinking.display 값인 "omitted"에서는 해당 블록의 thinking 필드가 비어 있습니다. 요청이 실패하지는 않지만, 해당 텍스트를 진행 상황 업데이트로 사용자에게 스트리밍하는 애플리케이션은 도구 호출 사이에 아무것도 표시하지 않게 됩니다. 업데이트를 복원하려면 thinking 블록에서 업데이트를 읽고, 해당 텍스트를 반환하는 display 값을 설정하세요: "updates"(베타, thinking-display-updates-2026-08-18 헤더)는 추론은 숨긴 채 진행 상황 업데이트를 반환하고, "summarized"는 둘 다 섞어서 반환합니다. 그런 다음 비어 있지 않은 각 thinking 블록을 그 뒤에 오는 tool_use 블록보다 먼저 렌더링하고, 어시스턴트 턴의 나머지 부분과 함께 블록을 변경하지 않은 채로 다시 전달하세요. 사용자 대상 진행 상황 업데이트를 참조하세요.
안전 분류기 및 폴백
Claude Opus 5.5는 stop_details 카테고리와 함께 stop_reason: "refusal"을 반환할 수 있습니다. 이 모델의 분류기는 Claude Opus 5보다 더 넓은 범위의 카테고리를 다루므로, "cyber" 외에도 "bio" 및 "reasoning_extraction"과 같은 stop_details.category 값을 예상하세요. 거부 카테고리 표를 참조하세요. 거부를 처리하고 서버 측 폴백 또는 자체 재시도를 구성하세요(서버 측 폴백은 "reasoning_extraction"으로 거부된 요청을 재시도하지 않으며, 해당 거부는 그대로 반환됩니다). 거부 및 폴백 및 안전장치 거부를 참조하세요.
권장 변경 사항
- effort 스윕을 다시 실행하세요. Effort는 Claude Opus 5.5에서 유일한 사고 제어 수단이며, 기본값이 Claude Opus 5의
high와 달리medium이므로effort를 생략한 요청은 이제medium으로 실행됩니다. 품질이 유지되는 경우에는 수준을 낮추고, 가장 까다로운 작업에는 수준을 높이세요. Effort를 참조하세요. - 모델별 프롬프트 지침을 재평가하세요. Claude Opus 5의 동작에 맞춰 조정된 지침은 더 이상 필요하지 않을 수 있습니다. Claude Opus 5.5 프롬프팅을 참조하세요. 사고를 비활성화한 상태로 실행했다면 사고 비활성화를 전제로 작성된 프롬프트도 참조하세요.
- 프로덕션 트래픽을 전환하기 전에 개발 환경에서 테스트하세요.
마이그레이션 체크리스트
- 모델 ID를
claude-opus-5-5로 업데이트하세요. thinking: {"type": "disabled"}및thinking: {"type": "enabled", ...}를 제거하고, 대신 effort 수준을 선택하세요.effort를 명시적으로 설정하세요: 기본값은medium이며, Claude Opus 5의 기본값은high입니다.tool_choice유형any및tool을auto와 엄격한 도구 사용 또는 구조화된 출력의 조합으로 대체하세요.- Claude API 또는 Google Cloud에서 컴퓨터 사용을 사용하는 경우,
computer_20251124대신computer_toolset_20260801(베타 헤더 없음)을 선언하고 도구 세트에 맞게 에이전트 루프를 업데이트하세요. Amazon Bedrock에서는computer_20251124를 유지하세요. 다른 플랫폼의 경우 컴퓨터 사용 도구의 호환성 섹션을 확인하세요. - 라우터나 폴백이 대화를 Claude Opus 5.5에서 다른 모델로 옮길 수 있는 경우, 해당 모델이 Claude Opus 5.5의 사고 블록 없이 실행될 것으로 예상하세요(Claude API의 Claude Fable 5.1과 Claude Mythos 5.1은 예외로, 블록을 유지합니다). Claude Opus 5.5 자체는 Claude Opus 5 및 이전 Opus, Sonnet, Haiku 모델의 사고는 읽지만, Claude Fable 또는 Claude Mythos 모델의 사고는 읽지 않습니다.
type으로 콘텐츠 블록을 읽고, 도구 사용 루프에서thinking블록을 수정하지 않은 채로 다시 전달하세요.- 인터페이스에서 도구 호출 사이의 텍스트를 렌더링하는 경우,
display: "updates"(베타) 또는"summarized"를 설정하고 비어 있지 않은thinking블록을 렌더링하세요. - 코드가 대화 도중 이전 턴,
system프롬프트 또는tools를 편집하는 경우, 보존된 사고를 따르세요. stop_reason: "refusal"을 처리하고 폴백을 구성하세요.- 선택한 effort 수준에서 비용과 "latency"(지연 시간)의 기준선을 다시 설정하세요.
Claude Opus 4.8에서 Claude Opus 5.5로 마이그레이션하기
먼저 Claude Opus 4.8에서 Claude Opus 5로 마이그레이션하기를 진행하세요: 이 가이드는 기본적으로 활성화된 사고와 그에 따른 응답 형태 변경 사항을 다룹니다. 그런 다음 Claude Opus 5에서 마이그레이션하기를 적용하세요. 해당 가이드의 두 번째 Claude Opus 5 호환성이 깨지는 변경 사항(사고는 high effort 이하에서만 비활성화할 수 있음)은 적용되지 않습니다: Claude Opus 5.5에서는 사고를 전혀 비활성화할 수 없습니다.
마이그레이션 체크리스트
- Claude Opus 4.8 → Claude Opus 5 체크리스트의 모든 항목. 단,
thinking: {"type": "disabled"}는 사용할 수 없습니다. - Claude Opus 5 → Claude Opus 5.5 체크리스트의 모든 항목.
Claude Opus 4.7 및 이전 Opus 모델에서 Claude Opus 5.5로 마이그레이션하기
Claude Opus 5 마이그레이션 가이드는 현재 모델과 Claude Opus 5 사이의 호환성이 깨지는 변경 사항을 다룹니다: 샘플링 매개변수 거부, 수동 확장 사고 거부, 프리필 제거, 그리고 새로운 토크나이저입니다. 해당 가이드에서 사용 중인 모델에 해당하는 섹션을 claude-opus-5 대신 claude-opus-5-5를 대상으로 진행한 다음, Claude Opus 5에서 마이그레이션하기를 적용하세요. 해당 가이드에서 사고를 high effort 이하에서 비활성화할 수 있다고 안내하는 부분은 Claude Opus 5.5에서는 해당되지 않습니다. 또한 기존 computer_20251124 통합이 계속 작동한다고 안내하는 부분은, Claude API 및 Google Cloud의 Claude Opus 5.5에서는 작동하지 않습니다. 이 플랫폼에서 Claude Opus 5.5는 컴퓨터 사용을 computer_toolset_20260801 도구 세트로만 허용합니다(호환성이 깨지는 변경 사항 참조). Amazon Bedrock에서는 계속 작동합니다.
Claude Sonnet 5에서 Claude Opus 5.5로 마이그레이션하기
상위 모델 클래스로 이동할 때 달라지는 사항은 Claude Sonnet 5에서 Claude Opus 5로 마이그레이션를 참조한 다음, Claude Opus 5에서 마이그레이션하기를 적용하세요.
Was this page helpful?