Claude Code 공식문서 리뷰-Configuration[3] : 모델 구성(Model configuration)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> [설정] 섹션의 내용 중 [모델 구성(Model configuration)]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/en/model-config

Model configuration - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

Claude Code 모델 설정

왜 모델 설정을 알아야 할까?

Claude Code는 여러 AI 모델을 지원한다. 작업 유형에 따라 적절한 모델을 선택하면 비용을 절감하면서도 더 나은 결과를 얻을 수 있다.

이 문서에서 다루는 내용

• 모델 별칭: sonnet, opus, haiku 등 간편한 이름으로 모델 선택
• 설정 방법: CLI 명령, 환경 변수, 설정 파일 3가지 방법
• 특수 모델: opusplan (계획+실행 하이브리드), sonnet[1m] (100만 토큰)
• 프롬프트 캐싱: 성능 최적화 및 비용 절감

처음 사용자라면?

일단 기본 설정(sonnet)으로 시작하자. 모델 설정을 바꾸지 않아도 Claude Code는 잘 작동한다. 작업하다가 "더 빠른 응답이 필요해" 또는 "더 복잡한 분석이 필요해"라고 느낄 때 이 문서를 다시 참고하면 된다.

 

사용 가능한 모델

model 설정에는 다음 두 가지를 사용할 수 있다:

• 모델 별칭 - 간편한 이름 (예: sonnet, opus)
• 모델 이름 - 전체 모델 식별자
  • Anthropic API: 전체 모델 이름
  • Bedrock: 추론 프로필 ARN
  • Foundry: 배포 이름
  • Vertex: 버전 이름

 

모델 별칭

모델 이름을 전부 외울 필요 없다. 별칭(alias)만 기억하면 된다.

별칭	설명	이런 상황에 사용
default	계정 유형에 따른 권장 모델	아무 설정 없이 그냥 사용할 때
sonnet	최신 Sonnet 모델 (현재 Sonnet 4.5) 가장 많이 사용	"함수 작성해줘", "이 버그 고쳐줘"
opus	Opus 모델 (현재 Opus 4.5) 가장 강력	"아키텍처 설계해줘", "복잡한 알고리즘 분석"
haiku	빠르고 효율적인 Haiku 모델 가장 빠름/저렴	"이 파일 찾아줘", "간단한 수정"
sonnet[1m]	100만 토큰 컨텍스트 윈도우의 Sonnet	대화가 길어져서 컨텍스트가 필요할 때
opusplan	플랜 모드에서 opus, 실행 시 sonnet 자동 전환	큰 기능 구현, 대규모 리팩토링

어떤 모델을 선택해야 할지 모르겠다면?

sonnet으로 시작하자. 대부분의 코딩 작업에 적합하다. 정말 어려운 문제(복잡한 아키텍처 설계, 알고리즘 분석)에서만 opus로 전환하면 된다.

실제 사용 예시

sonnet

• "이 함수 리팩토링해줘"
• "테스트 코드 작성해줘"
• "이 에러 원인이 뭐야?"

opus

• "마이크로서비스 아키텍처 설계"
• "복잡한 동시성 버그 분석"
• "레거시 시스템 현대화 계획"

haiku

• "프로젝트 구조 보여줘"
• "이 파일 어디있어?"
• "간단한 오타 수정"

 

모델 설정 방법

모델은 다음 방법으로 설정할 수 있다 (우선순위 순):

1. 세션 중 - /model <별칭|이름> 명령으로 전환
2. 시작 시 - claude --model <별칭|이름> 옵션 사용
3. 환경 변수 - ANTHROPIC_MODEL=<별칭|이름> 설정
4. 설정 파일 - settings.json의 model 필드

명령줄 예시

# Opus로 시작
claude --model opus

# 세션 중 Sonnet으로 전환
/model sonnet

# 100만 토큰 컨텍스트로 시작
claude --model sonnet[1m]

설정 파일 예시

{
  "permissions": {
    "allow": ["Bash(npm run:*)"]
  },
  "model": "opus"
}

실전 팁: 팀 프로젝트에서는 .claude/settings.json에 모델을 지정해 모든 팀원이 동일한 모델을 사용하도록 할 수 있다.

 

특수 모델 동작

default 모델

default의 동작은 계정 유형에 따라 다르다. 특정 Max 사용자의 경우, Opus 사용량 임계치에 도달하면 Claude Code가 자동으로 Sonnet으로 폴백한다.

opusplan 모델

opusplan이 뭔가요?

"계획은 똑똑하게, 실행은 빠르게"를 자동으로 해주는 하이브리드 모델이다. 복잡한 작업을 요청하면 먼저 Opus가 계획을 세우고, 실제 코드 작성은 Sonnet이 담당한다.

모드	사용 모델	용도
플랜 모드	opus	복잡한 추론, 아키텍처 결정, 전략 수립
실행 모드	sonnet	코드 생성, 파일 수정, 테스트 작성

opusplan 실제 사용 예시

요청: "이 모놀리식 앱을 마이크로서비스로 분리해줘"

1단계: Opus가 계획

• 서비스 경계 분석
• 의존성 그래프 파악
• 마이그레이션 순서 결정
• 위험 요소 식별

2단계: Sonnet이 실행

• 코드 분리 작업
• API 인터페이스 생성
• 테스트 코드 작성
• 설정 파일 수정

언제 opusplan을 쓸까?

• 대규모 리팩토링 - 여러 파일에 걸친 구조 변경
• 새 기능 설계 - 처음부터 아키텍처를 고민해야 할 때
• 레거시 코드 현대화 - 복잡한 마이그레이션 작업
• 성능 최적화 - 병목 분석 후 개선 작업

확장 컨텍스트 [1m]

Console/API 사용자는 전체 모델 이름에 [1m] 접미사를 추가하여 100만 토큰 컨텍스트 윈도우를 활성화할 수 있다.

# 100만 토큰 컨텍스트 사용
/model anthropic.claude-sonnet-4-5-20250929-v1:0[1m]

주의: 확장 컨텍스트 모델은 가격이 다르다. 사용 전 요금을 확인하자.

 

현재 모델 확인

현재 사용 중인 모델을 확인하는 방법:

1. 상태 줄 (설정된 경우)
2. /status 명령 - 계정 정보와 함께 표시

/status

 

환경 변수

언제 환경 변수가 필요할까?

대부분의 경우 환경 변수 설정은 필요 없다. 다음 상황에서만 고려하자:

• 특정 모델 버전 고정 - 팀 전체가 동일한 버전을 사용해야 할 때
• 비용 최적화 - 서브에이전트에 저렴한 Haiku를 고정하고 싶을 때
• Bedrock/Vertex AI 사용 - 클라우드 프로바이더별 모델 이름 지정

별칭이 매핑되는 모델 이름을 환경 변수로 제어할 수 있다. 값은 전체 모델 이름이어야 한다.

모델 매핑

환경 변수	설명
ANTHROPIC_DEFAULT_OPUS_MODEL	opus 또는 플랜 모드의 opusplan에 사용할 모델
ANTHROPIC_DEFAULT_SONNET_MODEL	sonnet 또는 실행 모드의 opusplan에 사용할 모델
ANTHROPIC_DEFAULT_HAIKU_MODEL	haiku 또는 백그라운드 기능에 사용할 모델
CLAUDE_CODE_SUBAGENT_MODEL	서브에이전트에 사용할 모델

사용 예시

# 특정 Sonnet 버전 사용
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5-20250929"

# 서브에이전트에 Haiku 사용
export CLAUDE_CODE_SUBAGENT_MODEL="claude-3-5-haiku-20250929"

claude

 

프롬프트 캐싱 설정

Claude Code는 성능 최적화와 비용 절감을 위해 자동으로 프롬프트 캐싱을 사용한다. 필요시 비활성화할 수 있다.

환경 변수	설명
DISABLE_PROMPT_CACHING	1로 설정하면 모든 모델의 캐싱 비활성화
DISABLE_PROMPT_CACHING_HAIKU	Haiku 모델만 캐싱 비활성화
DISABLE_PROMPT_CACHING_SONNET	Sonnet 모델만 캐싱 비활성화
DISABLE_PROMPT_CACHING_OPUS	Opus 모델만 캐싱 비활성화

초보자 팁: 일반적으로 프롬프트 캐싱을 활성화한 상태로 두는 것이 좋다. 비용과 응답 시간 모두 개선된다.

캐싱 비활성화가 유용한 경우

• 특정 모델 디버깅 시
• 클라우드 제공자의 캐싱 구현이 다른 경우
• 캐싱 동작 테스트 시

# 모든 캐싱 비활성화
export DISABLE_PROMPT_CACHING=1

# Sonnet만 캐싱 비활성화
export DISABLE_PROMPT_CACHING_SONNET=1

 

모델 선택 가이드

작업 유형	권장 모델	이유
일반 코딩	sonnet	균형 잡힌 성능과 속도
복잡한 아키텍처	opus	우수한 추론 능력
빠른 편집	haiku	빠른 응답
대규모 리팩토링	opusplan	계획은 깊게, 실행은 빠르게
긴 대화	sonnet[1m]	100만 토큰 컨텍스트

 

자주 묻는 질문 (FAQ)

Q. 모델을 바꾸면 비용이 많이 차이나나요?

네, 상당히 차이납니다. 대략적인 비용 순서: opus > sonnet > haiku.
간단한 작업에 opus를 쓰면 불필요한 비용이 발생하니, 작업에 맞는 모델을 선택하자. 비용 최적화를 원하면 opusplan이 좋은 선택이다.

Q. 세션 중에 모델을 바꿔도 되나요?

물론이다. /model sonnet 명령으로 언제든 바꿀 수 있다. 예를 들어, 처음에 sonnet으로 작업하다가 복잡한 문제가 생기면 /model opus로 전환하고, 다시 간단한 작업으로 돌아오면 /model sonnet으로 돌아오면 된다.

Q. sonnet[1m]은 언제 쓰나요?

대화가 길어지거나, 많은 파일을 동시에 참조해야 할 때 유용하다. 일반적인 코딩 작업에서는 기본 컨텍스트로 충분하지만, 대규모 코드베이스 전체 분석이나 복잡한 디버깅 세션에서는 sonnet[1m]이 도움된다. 단, 비용이 더 발생할 수 있다.

Q. 프롬프트 캐싱은 끄면 안 되나요?

특별한 이유가 없다면 켜두는 것이 좋다. 캐싱은 반복되는 시스템 프롬프트 등을 재사용해서 비용과 응답 시간을 모두 줄여준다. 끄는 경우는 디버깅이나 특수한 테스트 상황 정도다.

Q. 팀 전체가 같은 모델을 쓰게 하려면?

프로젝트 루트의 .claude/settings.json에 모델을 지정하자. 이 파일을 Git에 커밋하면 팀 전체가 동일한 설정을 공유할 수 있다.

{
  "model": "sonnet"
}

 

관련 문서

문서	설명
Settings	전체 설정 가이드
서브에이전트	서브에이전트 모델 설정
비용	모델별 비용 정보

 

핵심 요약 - 빠르게 확인하기

3분 만에 이해하는 모델 선택

이런 작업에는	이 모델을	이렇게 설정
일반적인 코딩 작업 (함수 작성, 버그 수정, 리팩토링)	sonnet	기본값 (설정 불필요)
복잡한 문제 해결 (아키텍처 설계, 알고리즘 분석)	opus	/model opus
빠른 응답 필요 (파일 탐색, 간단한 질문)	haiku	/model haiku
대규모 기능 구현 (계획 + 실행이 필요한 작업)	opusplan	/model opusplan

자주 쓰는 명령어

모델 전환

/model sonnet
/model opus
/model haiku

현재 모델 확인

/status

시작할 때 지정

claude --model opus

처음이라면 기억할 것 딱 하나

그냥 claude로 시작하면 된다. 기본 모델(sonnet)이 대부분의 작업에 적합하다. 복잡한 문제가 생기면 그때 /model opus로 전환하면 된다.

Claude Code 한국어 문서
번역 기준일: 2025-12-23 | 원본: code.claude.com/docs