Claude Opus 5.5 API 전환 가이드: 400 오류 나는 설정 4가지와 수정 코드

Claude Opus 5.5로 모델 이름만 바꿨는데 400 오류가 난다면, 이전 모델에서 쓰던 설정 네 가지 중 하나가 원인일 가능성이 큽니다. 생각 끄기, 강제 도구 호출, 이전 컴퓨터 사용 도구, 대화 중간 수정이 그 네 가지입니다. 이 글은 Anthropic 개발자 문서의 Opus 5.5 안내와 마이그레이션 가이드를 기준으로 오류 문구, 원인, 고치는 코드를 정리했습니다. 코드 예시는 문서를 기준으로 구성했으며 이 블로그에서 실행한 결과가 아닙니다.

먼저 바꿀 것: 모델 이름과 effort

API 모델 이름은 claude-opus-5-5입니다. Amazon Bedrock에서는 anthropic.claude-opus-5-5를 씁니다. 모델 이름을 바꾼 다음 가장 먼저 확인할 항목은 effort입니다. Opus 5.5에서는 생각(thinking)이 항상 켜져 있고, 생각의 깊이를 조절하는 요청 설정은 effort 하나뿐입니다. 단계는 low, medium, high, xhigh, max 다섯 가지입니다.

기본값이 달라졌다는 점이 중요합니다. Opus 5는 effort를 적지 않으면 high로 동작했지만 Opus 5.5는 medium으로 동작합니다. 또 같은 단계에서도 Opus 5보다 한 번에 더 많이 생각하는 경향이 있다고 문서에 적혀 있습니다. 그래서 이전 설정을 그대로 옮기기보다 내 평가 자료로 단계별 결과를 다시 확인하라고 안내합니다. 가격과 성능 변화는 출시 정리 글에서 따로 다뤘으니, 이 글은 코드 변경에 집중합니다.

400 오류가 나는 설정 4가지

이전 설정	Opus 5.5에서	고치는 방법
thinking: {"type": "disabled"} 또는 budget_tokens 지정	400 invalid_request_error	thinking을 빼거나 {"type": "adaptive"}로 두고 effort로 조절
tool_choice의 any, tool	400 오류(토큰 계산 요청도 동일)	auto로 바꾸고 도구 정의에 strict: true, 또는 구조화 출력 사용
이전 컴퓨터 사용 도구 computer_20251124	Claude API와 Google Cloud에서 400 오류	{"type": "computer_toolset_20260801"}로 교체, 베타 헤더 제거
대화 앞부분(시스템 지침, 도구, 이전 메시지)을 고친 뒤 생각 블록 재전송	2026년 8월 31일 이후 생성 계정은 400 오류	대화를 덧붙이기만 하고, 지침 변경은 대화 중간 시스템 메시지로 전달

오류 문구를 검색해 이 글에 오신 분을 위해 문서에 실린 문구를 그대로 옮깁니다.

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
tool_choice: type "tool" and "any" are not supported for this model.
'claude-opus-5-5' does not support tool types: computer_20251124.

Amazon Bedrock에서는 computer_20251124 도구가 Opus 5.5에서도 계속 동작한다고 안내됐습니다. 같은 코드라도 어느 플랫폼에서 호출하느냐에 따라 결과가 다를 수 있으니 배포 경로별로 확인하세요.

코드 수정 전후 비교

아래는 생각을 끄고 특정 도구 호출을 강제하던 요청을 Opus 5.5에 맞게 바꾼 예시입니다. Python SDK 형식이며 문서 기준으로 구성했습니다.

# 이전 (Opus 5)
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    tool_choice={"type": "tool", "name": "save_record"},
    tools=tools,
    messages=messages,
)

# 이후 (Opus 5.5)
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,                 # 생각과 답변을 합한 상한
    output_config={"effort": "low"},  # 생각을 끄던 자리는 낮은 effort로
    tool_choice={"type": "auto"},     # 도구 정의에는 "strict": True
    tools=tools,
    messages=messages,
)

강제 호출이 없어도 모델이 도구를 쓰게 하려면 프롬프트에 언제 그 도구를 써야 하는지 적어 두라고 문서는 안내합니다. 결과를 정해진 JSON 형식으로 받아야 한다면 구조화 출력으로 옮기는 방법도 있습니다.

max_tokens도 다시 봐야 합니다. 이 값은 생각과 답변을 합한 전체 출력의 상한입니다. 생각 토큰은 화면에 보이지 않아도 출력 토큰으로 청구됩니다. 문서는 xhigh나 max를 쓸 때 64k 토큰에서 시작해 조정하라고 권합니다.

오류 없이 달라지는 동작 3가지

변화	생길 수 있는 증상	대응
모든 응답이 thinking 블록으로 시작할 수 있음	content[0].text처럼 순서로 읽는 코드가 빈 값을 받음	블록의 type으로 골라 읽기
도구 호출 사이의 짧은 안내 문장이 thinking 블록으로 옴	진행 상황을 보여 주던 화면이 도구 호출 사이에 조용해짐	thinking.display를 "summarized" 또는 "updates"(베타)로 설정
안전 분류기 범위 확대(사이버 보안에 생물학 추가)	HTTP 200인데 stop_reason이 "refusal"	거절 처리 코드와 대체 모델 재시도 준비

# 순서가 아니라 type으로 답변 텍스트 모으기
answer = "".join(b.text for b in response.content if b.type == "text")

if response.stop_reason == "refusal":
    # 사용자에게 안내하거나 다른 모델로 다시 요청
    handle_refusal(response)

thinking.display의 기본값은 "omitted"라서 생각 블록의 텍스트가 비어 있습니다. "updates"는 진행 안내만 돌려주고, "summarized"는 생각 요약까지 함께 돌려줍니다. 도구를 쓰는 반복 흐름에서는 생각 블록을 고치지 말고 그대로 다시 보내야 합니다. 거절 외에 요청 한도 오류까지 같이 다루고 싶다면 HTTP 429와 Retry-After 처리 글의 재시도 순서를 함께 적용해 보세요.

대화 도중 모델을 바꿀 때 주의할 점

Opus 5.5의 생각 블록에는 그 블록을 만든 모델과 대화 내용이 묶여 있습니다. Opus 5.5는 Opus 5 이하의 Opus, Sonnet, Haiku가 만든 블록은 읽지만 Fable이나 Mythos 모델의 블록은 읽지 않습니다. 반대로 Claude API에서 Fable 5.1과 Mythos 5.1은 Opus 5.5의 블록을 읽습니다. 읽을 수 없는 블록은 API가 오류 없이 빼고 처리하며 그 부분은 청구되지 않습니다. 대신 이전 모델의 추론 흐름은 이어지지 않습니다. Fable 5.1 쪽 변화는 Fable 5.1과 Mythos 5.1 정리 글에 있습니다.

대화 앞부분을 고치는 경우는 더 엄격합니다. 2026년 8월 31일 0시(UTC) 이후 만든 계정에서는 시스템 지침이나 도구 목록을 바꾼 뒤 예전 생각 블록을 다시 보내면 400 오류가 납니다. 문서가 권하는 방법은 대화를 덧붙이기만 하는 것입니다. 지침이나 도구가 바뀌면 대화 중간 시스템 메시지로 알리면 됩니다. 꼭 필요하면 thinking-binding-controls-2026-08-01 베타 헤더와 prefix_mismatch_behavior: "drop_block" 설정으로 오류 대신 해당 블록을 빼도록 바꿀 수 있습니다.

함께 쓸 수 있는 새 기능과 전환 체크리스트

Opus 5.5에서 쓸 수 있는 기능 가운데 전환과 함께 검토할 만한 항목입니다. 프롬프트 캐시는 최소 512토큰부터 적용되고, 메시지별 effort 변경(베타), 작업 예산, 배치 처리, 파일 API, PDF와 이미지 입력을 지원합니다. inline-tools-2026-09-15 헤더로 대화 중간에 도구 정의를 추가할 수 있고, compact-2026-09-04 헤더로 원하는 시점에 대화를 요약 블록으로 줄일 수 있습니다. 빠른 모드는 Claude API에서만 speed: "fast"와 fast-mode-2026-02-01 헤더로 씁니다.

Claude Code를 쓰고 있다면 문서에 안내된 명령으로 전환 작업을 맡길 수 있습니다. 적용 범위를 먼저 묻고, 모델 이름 교체와 설정 변경을 한 뒤 사람이 확인할 목록을 만들어 준다고 설명돼 있습니다.

/claude-api migrate this project to claude-opus-5-5

1. 모델 이름을 claude-opus-5-5로 바꾸고 effort를 명시했다
2. thinking의 disabled, enabled, budget_tokens 설정을 모두 지웠다
3. tool_choice의 any, tool을 auto와 strict 도구 정의로 바꿨다
4. Claude API와 Google Cloud의 컴퓨터 사용 도구를 toolset으로 옮겼다
5. 응답 블록을 type으로 읽고, stop_reason: "refusal"을 처리한다
6. max_tokens를 생각까지 고려해 다시 정했다

자주 묻는 질문

Opus 5.5에서 생각 기능을 끌 수 있나요?

끌 수 없습니다. thinking: {"type": "disabled"}를 보내면 400 오류가 납니다. 생각을 줄이고 싶다면 effort를 low로 낮추는 것이 문서가 안내하는 방법입니다.

특정 도구를 반드시 호출하게 하려면 어떻게 하나요?

tool_choice의 강제 옵션은 지원되지 않습니다. auto를 유지하고 도구 정의에 strict: true를 두거나, 프롬프트에 그 도구를 써야 하는 상황을 분명히 적어 주세요. 형식이 정해진 결과만 필요하다면 구조화 출력이 더 단순합니다.

Opus 5에서 thinking을 켜고 쓰던 코드도 고쳐야 하나요?

문서에 따르면 생각을 켠 상태로 Opus 5에서 동작하던 코드는 모델 이름 외에 바꿀 필요가 없습니다. 다만 effort 기본값이 medium으로 바뀌었으므로 품질과 비용을 다시 확인하고, 도구 호출 사이의 안내 문장을 화면에 보여 주던 서비스라면 display 설정을 확인하세요.