Claude Code에서 Sonnet 5.5 사용하기: 모델·effort·권한 확인

Claude Code에서 Sonnet 5.5를 명시적으로 선택하려면 해당 ID를 지원하는 공급사에서 새 세션은 claude --model claude-sonnet-5-5, 기존 세션은 /model claude-sonnet-5-5를 사용하세요. 먼저 클라이언트 버전과 계정의 모델 권한을 확인해야 합니다. Anthropic의 현재 문서는 Claude Code v2.1.284 이상을 요구합니다.

클라이언트가 모델을 인식하는 것, 공급사가 모델을 제공하는 것, 계정이 사용 권한을 갖는 것은 별개입니다. 이 안내는 2026년 9월 29일 Claude Code 모델 설정 문서와 대조했습니다. 모든 구독이나 타사 엔드포인트에서 접근할 수 있다고 확인한 것은 아닙니다.

모델 확인과 선택

터미널에서 다음 명령을 사용합니다.

claude --version
claude update
claude --model claude-sonnet-5-5 --effort medium

claude update는 설치된 클라이언트를 변경합니다. 조직이 설치를 관리한다면 해당 소프트웨어 관리 절차를 따르세요. 기존 대화형 세션에서는 다음을 입력합니다.

/model claude-sonnet-5-5
/status

명령이 성공했다고 가정하지 말고 표시된 모델과 공급사를 확인하세요. 생성 답변의 자기소개를 실제 응답 모델의 증거로 쓰지 마세요. 클라이언트 상태와 응답 메타데이터가 더 유용합니다.

짧은 별칭 sonnet은 편리하지만 공급사와 클라이언트 버전에 따라 의미가 달라집니다. 현재 문서는 Anthropic API에서 Sonnet 5.5로 매핑하지만 일부 클라우드 공급사의 별칭은 이전 Sonnet 모델을 가리킵니다. 전체 모델 이름은 의도를 분명히 하지만 해당 공급사가 지원하는 ID와 접근 경로를 써야 한다는 조건은 그대로입니다.

기본값만 바꾸면 충분하지 않은 이유

Claude Code 기본 모델이 반드시 최신 Sonnet인 것은 아닙니다. 현재 문서는 여러 계정·공급사 범주에서 Opus 5.5를 기본값으로 안내합니다. Sonnet은 직접 선택해야 합니다. 조직이 모델을 제한하면 공개 가이드와 선택 목록이 다를 수 있습니다.

ANTHROPIC_DEFAULT_SONNET_MODEL 같은 환경 변수도 별칭의 대상 모델을 바꿀 수 있습니다. 설정을 수정하기 전에 사용자, 프로젝트, 관리 설정을 확인하세요. 실험을 되돌릴 수 있도록 기존 값을 남기고, 한 세션을 고치려고 팀 전체의 공급사 설정을 덮어쓰지 마세요.

재현 가능한 테스트에는 명시적 선택을 사용한 뒤 영구 기본값으로 둘지 결정합니다. 한 번 시험하기 위해 모든 저장소나 에이전트 정의를 변경할 필요는 없습니다.

작업에 맞는 effort 선택

Sonnet 5.5 API의 기본 effort는 high입니다. 반면 Claude Code 모델 설정 문서는 그 클라이언트에서 Sonnet 5.5의 기본값을 medium으로 설명합니다. 서로 다른 진입점에 관한 설명이므로 혼용하면 안 됩니다.

요구사항이 명확한 코드 변경이라면 medium이 문서에 따른 합리적인 출발점입니다. 작업과 결과가 뒷받침할 때만 높이세요. 계정 제한 안에서 대화형 /effort 또는 실행 시 --effort를 사용합니다. 관리되는 effort 상한 때문에 요청보다 낮은 값이 실제로 적용될 수 있으니 확인 가능한 적용 설정을 기록하세요.

Effort 가이드는 높은 이름이 더 나은 결과를 보장하지 않는 이유를 설명합니다. 분리된 브랜치, 명확한 합격 기준, 검토 가능한 diff부터 준비하세요. 모델은 도구 실행 권한이 필요하고, 병합 전에는 변경 내용을 검토해야 합니다.

구독 접근과 API 과금 구분

Claude 구독 로그인과 API 키는 다른 접근 경로입니다. 조직이 Claude Code 구독 접근을 비활성화했다는 메시지는 계정 정책에 따른 차단이며 Sonnet 장애의 증거가 아닙니다. 관리자에게 승인된 접근 경로를 확인하고 관리 제한을 우회하지 마세요.

이 글을 준비하면서 실행한 로컬 Claude Code v2.1.281은 해당 조직 접근 메시지를 반환했고 Sonnet 작업을 실행하지 못했습니다. 문서의 최소 버전보다도 낮았습니다. 따라서 이 시도로 성공적인 모델 테스트, 속도 결과, 비용 측정을 주장하지 않습니다. 위 명령은 문서로 확인한 사용 절차입니다.

승인된 API 경로가 있다면 요청에는 API 요금이 적용됩니다. 구독을 가지고 있다는 이유로 무료가 되지는 않습니다. 시험 전 정확한 엔드포인트, 모델, 계정, 현재 요금을 확인하세요. 공급사 요금표 계산은 Sonnet API 비용 가이드에 정리했습니다.

실제 실패 증상부터 확인하기

404를 전체 장애의 증거로, 429를 구독 취소의 증거로 보지 마세요. 민감한 정보를 지운 오류 본문, 시각, 클라이언트 버전을 저장합니다. 지원 요청에 토큰, 전체 환경 변수 덤프, 비공개 저장소 문맥을 게시하지 마세요.

네이티브 요청 변경은 Sonnet 5.5 API 마이그레이션 체크리스트, 이전 모델에서 바꿀지에 대한 판단은 Sonnet 5와 5.5 비교를 참고하세요.