Claude Sonnet 5.5 전환 가이드 — Sonnet 5 코드가 오류를 내는 다섯 가지와, Opus를 앞섰다는 벤치마크의 조건
가격은 그대로, 요청 형식과 응답 모양은 달라졌습니다
목차
Anthropic이 9월 28일 Claude Sonnet 5.5를 공개했습니다. 토큰 단가는 Sonnet 5와 같고, 개발사는 작업당 비용이 최대 30% 줄고 출력이 30% 이상 빨라졌다고 밝혔습니다. 그런데 모델 ID만 바꾸면 되는 교체는 아닙니다. 공식 문서는 Sonnet 5에서 쓰던 코드가 오류를 내는 변경 다섯 가지와, 오류는 나지 않지만 응답 구조가 바뀌어 화면에 표시되던 진행 안내가 사라지는 변경 하나를 따로 적어 두었습니다. 공지 표의 Terminal-Bench 점수(70.6% 대 66.4%)는 Sonnet 5.5가 상위 모델인 Opus 5.5를 앞선 것처럼 보입니다. 그러나 모델의 평가와 안전성 정보를 담은 시스템 카드를 보면 두 모델은 서로 다른 추론 강도로 측정됐고, Opus 5.5의 점수는 안전장치에 걸린 요청이 대체 모델로 재실행되어 평가 시행의 10%가 영향을 받은 상태의 값입니다. 마이그레이션 문서, 모델 페이지, 가격표, 148쪽 시스템 카드를 대조해 정리했습니다.
핵심 요약
Sonnet 5와 같음 · 가격표 2026-09-29 확인
모델 페이지·새 기능 문서의 목록
Opus 5.5 대 Sonnet 5.5 · 시스템 카드 8.5절
먼저 알아 둘 용어
| 용어 | 뜻 |
|---|---|
| effort(추론 강도) | 모델이 답하기 전에 얼마나 오래 생각할지 정하는 API 값입니다(output_config.effort). low·medium·high·xhigh·max 다섯 단계이고, 높을수록 느리고 토큰을 더 쓰는 대신 결과가 좋아지는 경향이 있습니다 |
| adaptive thinking | 모델이 문제의 난이도에 따라 생각할 양을 스스로 정하는 방식입니다. Sonnet 5.5에서는 thinking 필드를 보내지 않으면 이 방식으로 실행됩니다 |
| thinking 블록 | 응답에 포함되는 모델의 추론 정보 블록입니다. 기본값에서는 내용이 비어 있고 서명(signature)만 붙어 옵니다. 도구 호출을 반복할 때는 받은 그대로 다시 보내야 합니다 |
| 강제 도구 호출 | tool_choice를 any나 특정 도구(tool)로 지정해 모델이 반드시 도구를 부르게 하는 설정입니다. 분류나 JSON 추출에 흔히 써 왔습니다 |
| strict 도구 | 도구 정의에 strict: true를 붙이면 모델이 만든 도구 입력이 스키마와 정확히 맞도록 보장됩니다 |
| 서버 측 대체(fallback) | 안전장치가 요청을 거절하면 API가 같은 요청을 다른 모델로 다시 실행해 한 번의 응답으로 결과를 반환하는 베타 기능입니다. Sonnet 5.5에서는 cyber와 frontier_llm 범주의 거절만 Sonnet 5로 재실행합니다 |
| 400 오류 | API가 요청 형식이 잘못됐다고 거부하는 HTTP 오류입니다. 이 글의 “오류를 낸다”는 모두 이 경우입니다 |
그대로인 것과 기본값
| 항목 | Sonnet 5.5 | Sonnet 5 | Opus 5.5 |
|---|---|---|---|
| 입력 / 출력 (100만 토큰당) | $2 / $10 | $2 / $10 | $4 / $20 |
| 캐시 읽기 | $0.20 | $0.20 | $0.20 |
| 5분 캐시 쓰기 | $2.50 | $2.50 | $5 |
| 컨텍스트 윈도우 / 최대 출력 | 100만 / 12만 8천 토큰 | — | 100만 / 12만 8천 토큰 |
| API 기본 effort | high | — | medium |
| 최소 캐시 가능 길이 | 512토큰 | 1,024토큰 | — |
Anthropic 모델 페이지·가격표·새 기능 문서, 2026-09-29 확인. “—”는 이 글에서 확인하지 않은 칸입니다. Batch API는 입출력 50% 할인이고, 베타 헤더를 쓰면 Batch에서 최대 출력 30만 토큰까지 받을 수 있습니다.
- 모델 ID는
claude-sonnet-5-5입니다. 날짜 접미사가 없습니다. Amazon Bedrock에서는anthropic.claude-sonnet-5-5입니다. - Sonnet 5의 $2/$10은 원래 한시 도입가였습니다. 가격표 각주는 “8월 31일까지의 도입가로 발표된 Sonnet 5 가격이 이제 표준가이며, 9월 1일로 예정됐던 $3/$15 인상은 없던 일이 됐다”고 적고 있습니다.
- effort 기본값은 쓰는 곳마다 다릅니다. 공지에 따르면 Claude Code와 Claude 앱은
medium, Claude Platform(API)은high가 기본입니다. 같은 모델이라도 앱에서 받은 인상과 API 결과가 다를 수 있는 이유입니다. - 토크나이저는 Sonnet 5와 같습니다. 같은 글이면 토큰 수도 같습니다. 이 블로그의 토크나이저 측정에서는 Sonnet 4.6에서 Sonnet 5로 넘어갈 때 순수 한국어 테스트 텍스트 네 종의 토큰 수가 1.000배로 그대로였고, JSON 로그는 1.42배로 늘었습니다.
Sonnet 5 코드가 오류를 내는 다섯 가지
Sonnet 5.5 모델 페이지와 “What's new” 문서는 “Sonnet 5에서 이미 실행 중인 코드에 영향을 주는 호환성 변경 다섯 가지”를 이렇게 나열합니다.
| 변경 | Sonnet 5.5에서 생기는 일 | 대응 |
|---|---|---|
| 1. thinking 끄기 | thinking: {"type": "disabled"}가 400 오류 | {"type": "between_tools"}로 바꿉니다. 단 low·medium·high effort에서만 받고 xhigh·max에서는 400 오류입니다. 대화 도중 effort를 바꾸거나 display 같은 다른 필드를 함께 보내도 400 오류입니다 |
| 2. 강제 도구 호출 | tool_choice의 any·tool이 400 오류. 토큰 계산 엔드포인트도 같음 | auto에 strict: true를 붙이고, 언제 도구를 써야 하는지 프롬프트에 적습니다. strict 도구는 요청당 20개까지이고, Amazon Bedrock에서는 strict를 쓸 수 없어 코드에서 입력을 검증해야 합니다 |
| 3. thinking 블록의 모델·대화 종속 | 2026-08-31 00:00 UTC 이후 만든 계정에서는(Claude API·Amazon Bedrock·Google Cloud), 앞선 대화 기록(system·tools·이전 메시지)을 고친 뒤 Sonnet 5.5의 thinking 블록을 다시 보내면 400 오류 | 대화를 덧붙이기만 하고 고치지 않습니다. 지시나 도구를 바꿀 때는 대화 중간 시스템 메시지를 씁니다 |
| 4. computer use 도구 버전 | Claude API와 Google Cloud에서 computer_20251124가 400 오류. 더 오래된 computer_20250124는 모든 플랫폼에서 400 오류 | Claude API·Google Cloud는 computer_toolset_20260801로, Amazon Bedrock은 computer_20251124로 옮깁니다 |
| 5. advisor 도구 조합 | Opus 4.8·Opus 4.7·Opus 4.6·Sonnet 5·Sonnet 4.6을 advisor로 지정하면 400 오류 | Opus 5·Opus 5.5·Fable 5·Fable 5.1·Mythos 5·Mythos 5.1 또는 Sonnet 5.5 자신을 지정합니다. 이 경우 조언은 암호화된 advisor_redacted_result 블록으로 와서 내용을 읽을 수 없습니다 |
3번은 설명이 조금 더 필요합니다. Sonnet 5.5가 만든 thinking 블록은 다른 어떤 모델도 읽지 못합니다. 대화 도중 다른 모델로 바꾸면 API가 오류 없이 그 블록을 요청에서 제외하고 요청은 성공하며, 제외된 블록은 과금하지 않습니다. 반대 방향으로 Sonnet 5.5는 Sonnet 5, Opus 4.8, Haiku 4.5와 그 이전 모델의 블록은 읽지만 Opus 5, Opus 5.5, Fable·Mythos 계열의 블록은 읽지 못합니다. 또 Sonnet 5.5의 thinking 블록은 그 블록을 만든 계정(또는 연결된 계정)에서만 유효합니다. 다른 계정에서 보내면 별도 오류 없이 요청에서 제외됩니다. 여러 조직 계정을 오가며 대화를 이어 붙이는 서비스라면 추론이 끊기는 지점이 생길 수 있습니다.
disabled를 보내면 “between_tools를 쓰거나 adaptive와 effort로 조절하라”는 문구가 돌아옵니다. 공식 문서는 Claude Code에서 /claude-api migrate를 실행하면 모델 ID 교체와 이런 파라미터 변경을 코드 전체에 적용하고 수동 확인 목록을 만들어 준다고 안내합니다(이 글에서는 실행해 보지 않았습니다).
오류 없이 달라지는 것
도구 호출 사이의 텍스트가 사라진 것처럼 보입니다
Sonnet 5까지는 모델이 도구 호출 사이에 쓰는 설명(“이제 테스트를 실행하겠습니다” 같은 진행 안내)이 모두 text 블록으로 왔습니다. Sonnet 5.5에서는 한두 문장보다 긴 안내가 진행 상황 thinking 블록으로 옵니다. 기본 설정(display: "omitted")에서는 이 블록의 내용이 비어 있으므로, 진행 안내를 사용자에게 스트리밍하던 화면에서는 오류 없이 해당 안내가 사라집니다. 받으려면 adaptive thinking에서 display를 "updates"(베타 헤더 thinking-display-updates-2026-08-18 필요)나 "summarized"로 바꾸거나, between_tools로 사전 사고를 끄면 됩니다.
거절 범주가 늘었고, 일부 거절은 과금됩니다
Sonnet 5.5는 Sonnet 5보다 많은 범주에서 요청을 거절합니다. 거절은 HTTP 200에 stop_reason: "refusal"로 오고, stop_details.category에 범주가 적힙니다.
| 범주 | 뜻 | 출력 전 거절도 과금 | 서버 측 대체 시 Sonnet 5로 재실행 |
|---|---|---|---|
cyber | 악성코드·익스플로잇 개발처럼 사이버 피해로 이어질 수 있는 요청 | 아니오 | 예 |
bio | 생물학적 피해로 이어질 수 있는 요청 | 예 | 아니오 |
frontier_llm | 경쟁 AI 모델 개발을 도울 수 있는 요청 | 예 | 예 |
reasoning_extraction | 모델의 내부 추론을 응답 본문에 그대로 옮겨 달라는 요청 | 예 | 아니오 |
general_harms | 그 밖의 이용 정책 영역. 문서는 무해한 작업도 걸릴 수 있다고 적었습니다 | 아니오 | 아니오 |
마이그레이션 가이드와 “Refusals and fallback” 문서, 2026-09-29 확인. 과금 범주는 “2026년 9월 기준 오탐이 적게 측정된 범주”이며 바뀔 수 있다고 문서가 밝혔습니다. 중간에 거절되면 입력과 이미 스트리밍된 출력이 과금되고, 거절된 요청도 사용량 한도에는 포함됩니다.
서버 측 대체는 Claude API에서만 쓸 수 있는 베타 기능이고(fallbacks: "default"와 베타 헤더 server-side-fallback-2026-07-01), Message Batches API·Amazon Bedrock·Google Cloud·Microsoft Foundry에서는 쓸 수 없습니다. 그곳에서는 SDK 미들웨어로 클라이언트에서 재시도해야 합니다. 공지는 “일상적인 버그 찾기와 수정은 영향을 받지 않고, 위험도가 높은 사이버보안 작업은 눈에 보이게 Sonnet 5로 대체된다”고 적었습니다.
effort 단계가 다시 보정됐습니다
같은 high 설정이라도 Sonnet 5와 같은 양의 추론을 하지 않습니다. 문서는 설정을 그대로 옮기지 말고 다시 측정하라고 권하면서 출발점을 이렇게 제시합니다. 일반 작업은 high, 잘 정의된 에이전트 코딩과 여러 단계 도구 사용은 medium(어렵거나 긴 작업은 high), 채팅처럼 지연에 민감한 작업은 medium이나 low입니다.
Sonnet 4.6 이하에서 옮길 때 더 볼 것
Sonnet 5를 건너뛰고 Sonnet 4.6이나 그 이전에서 바로 옮기면 4절의 다섯 가지에 더해 아래가 바뀝니다(마이그레이션 가이드의 모델별 목록).
| 변경 | 내용 |
|---|---|
| thinking이 기본으로 켜짐 | thinking 필드가 없는 요청에서도 추론이 실행됩니다. 응답이 thinking 블록으로 시작할 수 있으므로 content[0].text를 읽는 코드는 깨집니다. 사고 토큰은 출력 토큰으로 과금되고 max_tokens에 포함됩니다 |
| 사고 예산 지정이 400 오류 | thinking: {"type": "enabled", "budget_tokens": N}를 effort로 바꿔야 합니다. 문서는 예산과 effort 사이에 정해진 대응 관계가 없으므로 두세 단계에서 평가하라고 설명합니다 |
| 샘플링 값이 400 오류 | 기본값이 아닌 temperature·top_p·top_k를 보내면 거부됩니다 |
| 토큰 약 30% 증가 | 문서는 같은 글도 Sonnet 4.6보다 약 30% 더 많은 토큰으로 계산된다고 설명합니다. 다만 이 블로그 측정에서 순수 한국어 텍스트는 늘지 않았고 JSON 로그는 42% 늘었습니다. 내 입력으로 다시 세어야 합니다 |
| 이미지 토큰 약 2.5배 | 긴 변 2,576픽셀·이미지당 최대 4,784토큰의 고해상도 단계를 씁니다. 문서 예시로 2000×1500 이미지는 약 2.5배의 토큰이 듭니다 |
| assistant 미리 채우기(prefill) 400 오류 | Sonnet 4.5 이하에서 옮기는 경우입니다. 출력 형식을 강제하려는 용도라면 구조화 출력을 쓰고, 앞선 답변을 이어 쓰게 하려는 용도라면 사용자 메시지로 요청합니다 |
Haiku 4.5에서 올라가는 경우는 토큰 단가 자체가 오르므로(Haiku 4.5 입력 $1, 출력 $5) 비용을 새로 산정해야 합니다.
벤치마크와 비용 수치의 조건
Terminal-Bench에서 Opus 5.5를 앞섰다는 값
공지 표에서 가장 많이 인용된 수치는 에이전트 코딩 벤치마크 Terminal-Bench 4.0의 Sonnet 5.5 70.6%와 Opus 5.5 66.4%입니다. 하위 모델이 상위 모델을 앞선 것처럼 보이지만, 시스템 카드 8.5절에 조건이 적혀 있습니다.
| 조건 | Sonnet 5.5 | Opus 5.5 |
|---|---|---|
| 점수 | 70.6% | 66.4% |
| effort | max | xhigh(max에서는 64.8%) |
| 안전장치에 걸려 대체 모델이 답한 요청 | 1.2% | 2.5% |
| 그 영향을 받은 시행 | 1.5% | 10% |
| 표준오차 | ±2.5점 | ±2.6점 |
두 점수 차이는 4.2점입니다. 두 표준오차를 합치면 약 3.6점이므로 차이는 그 1.2배 정도이고, 우연이 아니라고 볼 때 흔히 쓰는 기준(약 2배)에 못 미칩니다(제가 계산한 값입니다). 이 표만으로 Sonnet 5.5가 Opus 5.5보다 낫다고 말하기는 어렵습니다. 게다가 Opus 5.5는 안전장치에 걸린 요청이 대체 모델로 넘어가면서 시행의 10%가 영향을 받았습니다. Hacker News에서도 이 차이를 지적한 댓글이 나왔고, 시스템 카드 원문과 일치했습니다.
같은 벤치마크 안에서도 effort에 따라 순서가 바뀝니다
코드 변경이 사람 수정 없이 병합될 수 있는지 채점하는 FrontierCode에서 Sonnet 5.5는 max에서 46.2%, xhigh에서 52.1%였습니다. 더 높은 effort 설정의 점수가 낮았습니다. 공지 각주는 max에서 Claude Code의 코드 리뷰 스킬을 더 자주 실행해 시간 초과나 과제 범위를 벗어난 수정이 생긴 사례를 이유로 들었습니다. effort를 올리면 항상 좋아진다고 가정하면 안 된다는 점이 개발사 자료 안에서 확인됩니다.
“작업당 최대 30% 절감”과 고객 인용
- 단가가 같으므로 절감은 전부 토큰 수에서 나옵니다. 공지는 “같은 일을 하는 데 훨씬 적은 토큰이 들어 자체 시험에서 작업당 최대 30% 저렴했다”고 적었고, 조건은 공개하지 않았습니다.
- 고객 인용은 회사가 고른 사례입니다. Balyasny는 금융 과제 2,441개에서 답변당 토큰이 Sonnet 5의 49만 7천 개에서 12만 1천 개로 줄었다고 했고, Slack은 출력 토큰이 약 14%, Box는 전체 토큰이 12% 줄었다고 했습니다. 폭이 크게 다르다는 것 자체가 “작업마다 다르다”는 뜻입니다.
- 지식 업무 점수(GDPval-AA·AA-Briefcase)는 외부 기관 Artificial Analysis가 출시 전 배포판에서 측정했는데, 그 배포판에 구조화 출력을 쓰는 요청의 응답 품질을 저하시킬 수 있는 버그가 있었다고 공지 각주가 밝혔습니다. 개발사는 영향이 작고 점수를 낮추는 방향일 것이라고 봤습니다.
개발자 토론에서 나온 문제
Hacker News의 공지 스레드는 759점, 댓글 500개가 넘었습니다(2026-09-29 확인). 원문으로 확인할 수 있었던 것과 없었던 것을 나눕니다.
| 토론에서 나온 주장 | 확인 결과 |
|---|---|
| Terminal-Bench에서 Opus 5.5는 시행 10%가 대체 모델의 영향을 받았다 | 시스템 카드 8.5절과 일치합니다. 원문은 “요청의 2.5%가 안전장치에 걸려 시행의 10%에 영향”입니다(7절 표) |
max effort에서 사고 토큰 12만 8천 개를 15분 동안 쓰고 최종 결과물을 내기 전에 멈췄다 | 한 사용자의 사례라 재현하지 않았습니다. 다만 사고 토큰이 max_tokens에 포함되고 최대 출력이 12만 8천 토큰이라는 점은 문서와 맞습니다 |
Cyber Verification Program에 가입했는데도 승인된 버그 바운티 작업이 cyber로 걸린다 | 개인의 경험담이라 확인하지 못했습니다. 문서는 cyber 범주에 무해한 보안 작업도 걸릴 수 있다고 적고 있습니다 |
비용 대비 성능 그래프에서 높은 effort의 Sonnet 5.5보다 high의 Opus 5.5가 낫다 | 공지 스스로 “높은 설정에서는 비슷한 비용으로 비슷한 성능”이며 “낮은 effort에서 Opus를 가장 잘 보완한다”고 적었습니다. 판단은 작업별 측정이 필요합니다 |
전환 체크리스트
- 코드에서 다섯 가지를 검색하세요.
"disabled"(thinking),tool_choice의any·tool, 대화 기록을 고쳐 다시 보내는 부분,computer_20251124·computer_20250124, advisor 모델 지정. 하나라도 있으면 모델 ID보다 이것을 먼저 고칩니다. - 응답을 블록 종류(
type)로 읽으세요.content[0].text처럼 첫 블록을 텍스트로 가정한 코드는 thinking 블록 때문에 깨집니다. - 진행 안내를 화면에 보여 준다면
display를 정하세요. 기본값에서는 오류 없이 안내가 사라집니다. - 거절 처리를 넣으세요.
stop_reason: "refusal"과stop_details.category를 기록하고, Claude API라면 서버 측 대체를, 다른 플랫폼이라면 클라이언트 측 재시도를 검토합니다. 출력 전 거절 가운데 과금되는 범주가 있다는 점도 비용 모니터링에 반영합니다. - effort를 두세 단계에서 다시 측정하세요. Sonnet 5의 설정을 그대로 옮기지 말고, 같은 테스트 과제 집합으로 품질·지연·토큰 수를 함께 평가합니다.
max가 항상 가장 좋지는 않았습니다. - 비용은 단가가 아니라 작업당 토큰으로 비교하세요. 개발사의 30%는 자체 시험 값입니다. 같은 요청 수십 건을 두 모델에 보내
usage의 입력·출력 토큰을 비교하면 됩니다. - 여러 계정·여러 모델을 오가는 대화라면 thinking 블록이 빠지는지 확인하세요.
thinking-binding-controls-2026-08-01베타 헤더를 보내면 빠진 블록이 응답의input_transformations에 표시됩니다. - Haiku 4.5를 쓰고 있다면 기다려 보는 것도 방법입니다. 공지는 대량·저비용용 Haiku 5.5가 몇 주 안에 나온다고 적었습니다.
아직 결론이 아닌 것
- API로 직접 측정하지 않았습니다. 이 글은 공식 문서와 시스템 카드를 대조한 정리입니다. 오류 동작은 문서에 적힌 대로 옮겼고 호출해서 확인하지는 않았습니다.
- 벤치마크는 개발사와 개발사가 인용한 외부 기관의 값입니다. 독립 측정은 아직 확인하지 못했습니다.
- “작업당 최대 30%”와 “30% 이상 빠름”의 측정 조건은 공개되지 않았습니다.
- 베타 기능이 많습니다. 서버 측 대체, 진행 안내 표시, thinking 바인딩 제어, 대화 중간 도구 변경은 모두 베타이고 헤더 이름이나 동작이 바뀔 수 있습니다. 과금되는 거절 범주도 바뀔 수 있다고 문서가 밝혔습니다.
- 토크나이저 측정은 이전 글의 값입니다. Sonnet 5.5가 Sonnet 5와 같은 토크나이저를 쓴다는 것은 문서의 설명이고, Sonnet 5.5로 직접 세어 보지는 않았습니다.
- 문서는 출시 직후라 갱신될 수 있습니다. 이 글은 2026-09-29에 받은 문서 기준입니다.
참고자료
모든 1차 출처는 2026-09-29에 열어 확인했습니다. 문서는 Markdown 원본(URL 끝에 .md)으로 받아 대조했습니다.
| 출처 | 이 글이 가져온 것 | 구분 |
|---|---|---|
| Anthropic, “Claude Sonnet 5.5” 공지 (2026-09-28) | 가격, 30% 주장, 벤치마크 표와 각주, effort 기본값, 안전장치, 고객 인용, Haiku 5.5 예고 | 1차(개발사) |
| Claude Sonnet 5.5 System Card (148쪽) | 표 8.1.A 표준 설정(max effort, 5회 평균), 8.4절 FrontierCode, 8.5절 Terminal-Bench 대체 비율·표준오차·effort 조건 | 1차(개발사) |
| Claude 문서, “Migrating to Claude Sonnet 5.5” | 400 오류 설정, between_tools, 강제 도구 호출, thinking 블록 종속, computer use, advisor, 거절 범주, 모델별 체크리스트, 토큰·이미지 변화 | 1차 |
| Claude 문서, Sonnet 5.5 모델 페이지와 “What's new in Claude Sonnet 5.5” | 호환성 변경 다섯 가지 목록, 모델 ID, 컨텍스트·출력 한도, 기본 effort, 계정 귀속 thinking, 동작 차이 | 1차 |
| Claude 문서, Pricing | 모델별 단가, Sonnet 5 도입가 각주 | 1차 |
| Claude 문서, “Refusals and fallback”, “Effort” | 거절 과금 규칙, 서버 측 대체 제약, effort 단계 설명 | 1차 |
| Hacker News, “Sonnet 5.5” 스레드 (2026-09-28) | 개발자들이 제기한 문제(8절) | 2차 |
| 이 블로그, 토크나이저 교체 후 비용 측정 (2026-09-21) | 순수 한국어 1.000배, JSON 로그 1.42배 | 이전 측정 |
Anthropic이 문서나 가격을 갱신하면 이 글을 고치고 개정 날짜를 적겠습니다.