Claude Code 모델 변경: 5가지 방법과 우선순위

프로젝트 설정 파일에 {"model":"haiku"}만 적어 두고 Claude Code를 띄우면 Haiku가 답합니다. 여기에 ANTHROPIC_MODEL=sonnet을 얹으면 Sonnet 5.5가 답하고, 다시 --model haiku를 더하면 Haiku로 돌아오더라고요. 모델을 정하는 자리가 여러 곳이고, 그중 위에 있는 쪽이 이기기 때문입니다.

그래서 지금 세션만 바꾸려면 /model 피커에서 모델을 고르고 s를 누르고, 앞으로 계속 쓸 모델은 Enter로 고르면 됩니다. Enter로 고른 모델은 기본값으로 저장돼요. 바꿨는데 다음 세션이 다른 모델로 시작한다면, 셸의 ANTHROPIC_MODEL 환경 변수나 프로젝트 설정 파일의 model이 덮어쓰고 있지 않은지부터 보세요.

2026년 10월 1일 공식 문서 기준이고, 우선순위 2~4위는 Ubuntu 24.04 · Claude Code 2.1.286 테스트 환경에서 직접 겹쳐 확인했습니다.

10월 12일에는 Windows 11 · PowerShell 5.1 · Claude Code 2.1.296에서 같은 실험을 다시 했고, 별칭 표와 오류 문구를 그날 문서와 출력에 맞췄습니다.

다섯 자리와 이기는 순서

모델을 정하는 자리는 다섯 곳입니다. 둘 이상에 값이 있으면 표에서 위에 있는 쪽이 이깁니다.

순위	방법	적는 법	어디까지 적용되나
1	세션 중 전환	/model <별칭 또는 이름>, 인자 없이 /model이면 피커	지금 세션. 피커에서 Enter로 고르면 새 세션 기본값으로도 저장
2	시작할 때 플래그	claude --model <별칭 또는 이름>	그 플래그로 띄운 세션만
3	환경 변수	ANTHROPIC_MODEL=<별칭 또는 이름>	그 변수가 살아 있는 셸에서 띄운 세션
4	설정 파일	settings.json의 "model": "<별칭 또는 이름>"	그 설정 파일이 읽히는 모든 세션
5	새 세션 기본값	ANTHROPIC_DEFAULT_MODEL=<별칭 또는 이름>	위 네 곳과 조직 기본 모델이 모두 비었을 때만

표만 봐서는 놓치기 쉬운 부분이 있습니다.

• 5번은 거의 쓰이지 않을 수 있습니다. /model로 기본값을 한 번이라도 저장했다면 그 값이 설정 파일에 들어가서, ANTHROPIC_DEFAULT_MODEL은 그 뒤로 쓰이지 않거든요. 이 변수는 Claude Code v2.1.236 이상에서 동작합니다.
• 4번은 “처음 켤 모델”일 뿐 강제가 아닙니다. 설정 파일에 model을 적어도 사용자가 /model에서 Default를 골라 계정 기본값으로 돌아가는 것은 막지 못해요. 사용자가 고를 수 있는 모델 자체를 막는 것은 관리 설정의 availableModels(조직 관리자 영역)입니다.
• ANTHROPIC_BASE_URL은 이 다섯 자리에 들지 않습니다. 바꾸면 요청을 보내는 곳만 바뀌고, 어느 모델이 답하는지는 그대로입니다.

직접 겹쳐 본 결과

도입에서 말한 실험을 표로 옮기면 이렇습니다. 프로젝트 설정 파일(.claude/settings.json)에 {"model":"haiku"}만 적어 두고, 같은 폴더에서 환경 변수와 플래그를 하나씩 얹어 어느 모델이 답하는지 봤습니다.

얹은 것	Ubuntu · 2.1.286	Windows · 2.1.296
없음(설정 파일 haiku만)	claude-haiku-4-5-20251001	claude-haiku-5-5
ANTHROPIC_MODEL=sonnet	claude-sonnet-5-5	claude-sonnet-5-5
ANTHROPIC_MODEL=sonnet + --model haiku	claude-haiku-4-5-20251001	claude-haiku-5-5

두 환경 모두 환경 변수가 설정 파일을 이기고, 플래그가 환경 변수를 이겼습니다. 표의 순서 그대로예요. PowerShell에서는 환경 변수를 $env:ANTHROPIC_MODEL = "sonnet"으로 얹었습니다.

그런데 같은 haiku가 2.1.286에서는 Haiku 4.5로, 2.1.296에서는 Haiku 5.5로 풀렸습니다. 설정 파일에 적은 값은 같은데, 버전이 다른 두 환경에서 서로 다른 모델로 풀린 거예요. 아래 절의 “별칭은 버전이 고정되지 않는다”가 바로 이 얘기입니다.

대화형 세션에서 지금 어느 모델로 돌고 있는지는 /status나 상태 표시줄에서 확인할 수 있습니다.

별칭은 버전이 고정되지 않는다

모델 전체 이름 대신 별칭을 쓸 수 있습니다.

별칭	쓰임
haiku	빠르고 가벼운 모델. 간단한 작업
sonnet	최신 Sonnet. 일상적인 코딩
opus	최신 Opus. 복잡한 추론
fable	그 제공자의 Fable 모델. 가장 어렵고 오래 걸리는 작업
best	Fable을 쓸 수 있으면 fable, 아니면 opus와 같은 모델
opusplan	plan 모드에서는 opus, 실행할 때는 sonnet으로 자동 전환
sonnet[1m], opus[1m]	100만 토큰 컨텍스트 창을 고르는 변형. sonnet이 이미 100만 창이 기본인 모델(Sonnet 5.5·Sonnet 5)로 풀리면 효과 없음
default	별칭이 아니라, 모델 지정을 지우고 계정 기본값으로 되돌리는 특수 값

default를 고르면 어느 모델이 되는지는 계정 종류마다 다릅니다(2026년 10월 1일 기준). Pro·Max·Team·Enterprise와 Anthropic API, Claude Platform on AWS·Amazon Bedrock·Google Cloud’s Agent Platform은 Opus 5.5, Microsoft Foundry는 Sonnet 4.5예요. 관리자가 조직 기본 모델을 정해 두었다면 그 모델입니다.

여기서 꼭 알아 둘 건 별칭은 버전이 고정돼 있지 않다는 점입니다. 그 제공자의 권장 버전을 가리키고 시간이 지나면 바뀌어요. 같은 별칭도 제공자마다 다른 버전으로 풀립니다(2026년 10월 12일 기준).

제공자	opus	sonnet	haiku
Anthropic API	Opus 5.5	Sonnet 5.5	Haiku 5.5
Claude Platform on AWS	Opus 5.5	Sonnet 4.6	Haiku 4.5
Amazon Bedrock, Google Cloud’s Agent Platform	Opus 5.5	Sonnet 4.5	Haiku 4.5
Microsoft Foundry	Opus 4.6	Sonnet 4.5	Haiku 4.5

버전을 묶어 두려면 claude-opus-5-5처럼 전체 이름을 쓰거나 ANTHROPIC_DEFAULT_OPUS_MODEL 같은 환경 변수로 별칭이 가리킬 모델을 정하면 됩니다.

Sonnet 5.5는 Claude Code v2.1.284 이상, Opus 5.5는 v2.1.280 이상, Haiku 5.5는 v2.1.293 이상이 필요하니, 별칭이 예상보다 옛 모델로 풀리면 제공자와 CLI 버전부터 확인하세요. 업데이트가 안 될 때는 설치 방식별 업데이트 명령과 버전이 안 바뀔 때 볼 것을 보시면 됩니다.

평소엔 Sonnet, 어려운 설계엔 Opus

모델을 어떻게 나눌지는 저도 공식 권장과 같은 쪽을 권합니다.

• 기본은 Sonnet. 대부분의 코딩 작업을 잘 처리하고 Opus보다 쌉니다.
• Opus는 아껴서, 복잡한 설계 판단이나 여러 단계를 거치는 추론에 씁니다.
• 서브에이전트의 단순 작업은 Haiku. 서브에이전트 정의에 model: haiku를 적어 둡니다.

Opus 5.5와 Fable 5.1 중 무엇을 고를지는 벤치마크와 그래도 Fable을 고르게 되는 경우에서 따로 다뤘습니다.

모델과 별도로 노력 수준(effort)도 고를 수 있습니다. /effort, --effort, CLAUDE_CODE_EFFORT_LEVEL로 정하고, 정하지 않으면 모델별 기본값을 씁니다.

수준	언제 쓰나	기본값인 모델
low	결과를 바로바로 확인하는 짧은 작업: 브레인스토밍, 이름 바꾸기
medium	범위가 분명한 일상 작업: 새 기능 구현	Opus 5.5, Sonnet 5.5
high	검증이 중요한 일: 기존 코드의 버그 수정	위 두 모델과 Opus 4.7을 뺀 나머지
xhigh	토큰을 더 써서 깊게 추론	Opus 4.7
max	사람이 붙어 있지 않아도 끝까지 파고들 어려운 문제

수준을 높인다고 항상 좋아지지는 않습니다. max는 효용이 줄고 과하게 생각하는 경향이 있어서, 넓게 쓰기 전에 시험해 보는 게 좋아요.

같은 과제를 low부터 max까지 30번 돌려 본 결과는 effort 단계별로 토큰·시간·결과를 잰 글에 있습니다.

그리고 같은 이름이라도 모델마다 실제 값이 다르니, 모델을 바꿀 때 쓰던 수준을 그대로 옮기면 같은 결과가 나오지 않을 수 있습니다. 모델이 지원하지 않는 수준을 고르면 그 아래에서 지원하는 가장 높은 수준으로 내려갑니다.

세션 도중에 바꿀 때의 대가

/model sonnet 한 줄이면 바뀌지만 공짜는 아닙니다.

가장 큰 건 캐시가 새로 시작한다는 점이에요. 캐시는 모델마다 따로라서, 바꾼 직후 요청은 내용이 같아도 대화 전체를 캐시 없이 다시 읽습니다. 긴 대화일수록 비싸죠.

그래서 캐시가 아직 살아 있을 때 다른 모델로 바꾸면 Claude Code가 한 번 확인을 묻습니다. opusplan도 plan 모드를 켜고 끌 때마다 모델이 바뀌니 같은 일이 생깁니다.

캐시가 비용에 미치는 영향은 캐싱이 실제로 비용을 줄이는 조건에 있습니다.

서브에이전트에도 번집니다. 모델을 따로 적지 않은 서브에이전트는 메인 대화의 모델을 물려받거든요.

작은 모델에 묶어 두려면 서브에이전트 정의에 model을 적으세요. 정의를 만드는 법은 조사와 검토를 나누는 커스텀 에이전트 만들기에 있습니다.

터미널마다 다른 모델을 동시에 쓰고 싶다면 /model로 바꾸지 말고 각 터미널을 --model로 띄우세요. /model은 기본값을 저장하니 이후 새로 여는 세션 모두에 영향을 줍니다.

바꾼 모델이 안 남을 때

/model 피커에서 Enter로 고르면 사용자 설정(~/.claude/settings.json)에 저장되고, s로 고르면 이번 세션에만 적용됩니다. /model sonnet처럼 이름을 붙이면 Enter와 같고요. Windows에서 띄운 피커 맨 아래에도 이 두 키가 그대로 적혀 있습니다.

그런데도 새 세션이 다른 모델로 시작한다면 흔한 원인은 이렇습니다.

1. 이번 세션에만 고른 것이었다. 피커에서 s를 눌렀거나, --model로 띄웠거나, 비대화형 모드(-p)에서 /model을 쓴 경우입니다.
2. 더 위의 자리가 매번 덮어쓴다. 셸에 남아 있는 ANTHROPIC_MODEL, 프로젝트나 관리 설정의 model, 관리자가 정한 조직 기본값입니다. 프로젝트나 관리 설정이 모델을 정했으면 시작 화면에 그 파일 이름이 나옵니다.
3. 저장이 실패했다. 다른 도구가 ~/.claude/settings.json을 만들어 두었거나 읽기 전용 링크로 걸어 두면 /model이 쓰지 못하고, 고른 모델은 그 세션에서만 삽니다.
4. 세션을 재개했다. claude --resume·--continue·/resume으로 재개한 세션은 다른 세션에서 바꾼 기본값에 휩쓸리지 않도록, 대체로 그 세션이 쓰던 모델로 돌아옵니다. 이건 정상 동작이에요. 다른 모델로 재개하려면 --model이나 ANTHROPIC_MODEL을 함께 줍니다. 그 모델이 은퇴했거나 availableModels에서 빠졌으면 일반 우선순위를 따르고, Amazon Bedrock·Google Cloud’s Agent Platform·Microsoft Foundry에서는 이전 모델을 복원하지 않습니다.

확인은 이 순서가 빠릅니다.

# Windows PowerShell
$env:ANTHROPIC_MODEL
[Environment]::GetEnvironmentVariable("ANTHROPIC_MODEL", "User")
Get-Content "$env:USERPROFILE\.claude\settings.json"

Windows에서는 둘째 줄도 보세요. $env:는 지금 창의 값만 보여 주는데, setx나 시스템 속성에서 사용자 환경 변수로 걸어 둔 값은 새 창을 열 때마다 다시 들어옵니다.

# macOS·Linux
echo "$ANTHROPIC_MODEL"
cat ~/.claude/settings.json

첫 줄에 값이 나오면 그 환경 변수가 범인입니다. 다른 도구를 위해 셸에 전역으로 걸어 둔 ANTHROPIC_MODEL 때문에 Claude Code가 계속 Haiku로 시작했고, 전역 설정을 지우자 해결됐다는 공개 보고도 있어요(아래 사례).

환경 변수가 비어 있으면 사용자 설정 파일에 model이 실제로 들어 있는지, 그다음 프로젝트의 .claude/settings.json을 보세요. 어느 설정 파일이 읽혔는지 확인하는 일반 절차는 설정이 적용되지 않을 때 무엇이 읽혔는지부터 보는 순서에 있습니다.

자주 나는 오류

There's an issue with the selected model (<모델 이름>)

없는 모델 이름을 넣으면 시작은 조용하고, 첫 요청에서 이 메시지가 납니다. --model, ANTHROPIC_MODEL, 설정 파일의 model은 미리 검사하지 않기 때문이에요. 테스트 환경에서 일부러 없는 이름을 넣어 본 결과입니다.

claude -p "reply with just: ok" --model claude-sonnet-9-9

"claude-sonnet-9-9" isn't described by this version's model catalog; update Claude Code, or map it with behavesAs on a modelPicker row (or modelOverrides, if it is a provider id of a model this version knows). ...
There's an issue with the selected model (claude-sonnet-9-9). It may not exist or you may not have access to it. Run --model to pick a different model.

2.1.296에서 다시 넣어 보니 마지막에 Run --model to pick a different model.이 붙었습니다.

철자를 확인하거나 별칭으로 바꾸세요. 첫 줄처럼 “이 버전의 모델 목록에 없다”고 나오면 새 모델을 쓰려는데 Claude Code가 옛 버전인 것이니, 먼저 업데이트하면 됩니다.

Model "<이름>" is restricted by your organization's settings. Using <모델> instead.

Claude Enterprise 관리자가 관리 콘솔에서 그 모델을 꺼 둔 것입니다. 세션은 허용된 모델로 시작하고, /model 피커에서는 막힌 모델이 아예 보이지 않아요. 풀려면 관리자에게 요청해야 합니다.

Haiku 계열은 항상 쓸 수 있고 끌 수 없습니다. 이 제한은 Claude Code v2.1.187 이상에서 로그인하거나 자기 API 키를 쓸 때 적용되고, 조직 서비스 키 같은 조직 범위 자격 증명에는 적용되지 않습니다.

메시지 없이 모델이 바뀌어 있다

아무 메시지 없이 모델이 바뀌었다면 자동 전환이 일어난 경우입니다.

• 대체 모델 설정(--fallback-model, fallbackModel)은 주 모델이 과부하이거나 쓸 수 없을 때만 넘어갑니다. 인증·결제·요금 한도 오류로는 넘어가지 않아요. 이 설정은 시작할 때 확인되지 않고 /status에도 나오지 않으니, 설정 파일의 fallbackModel과 실행 스크립트의 --fallback-model을 직접 확인해야 합니다.
• 안전 분류기도 있습니다. Fable 계열과 Opus 5.5·Sonnet 5.5·Opus 5는 안전 분류기와 함께 돌고, 사이버 보안·생물학 내용이 걸리면 다른 모델로 넘어갈 수 있습니다. 사용자 설정이 원인인지 가리려면 claude --safe-mode로 CLAUDE.md·스킬·MCP 서버·훅을 끄고 띄워 보세요.

다른 사람들이 겪은 문제

“고른 모델이 유지되지 않는다”는 보고가 GitHub 이슈에 여러 번 올라와 있습니다. 증상은 같은데 원인으로 지목된 곳이 서로 달라요.

• tddpirate(2026-01-19, #19241): ~/.claude/settings.json에 "model": "opus"가 있는데 Claude Code 2.1.12가 Sonnet 4.5로 시작했고, /model opus로 바꿔도 재시작하면 다시 Sonnet이었다고 보고했습니다. 중복으로 닫혔습니다.
• dannytb-coding-projects(2026-07-21, #79805): 다른 CLI 도구를 위해 셸에 export한 ANTHROPIC_MODEL=claude-haiku-4-5-20251001 때문에 2.1.216부터 설정 파일의 opus 대신 Haiku로 시작했고, 전역 export를 없애자 해결됐다고 보고했습니다. 같은 보고는 /model로도 바꾸지 못했다고 적었는데, /model이 1순위라는 문서와 어긋납니다. not planned로 닫혔습니다.
• meckert75(2026-07-23, #80614): 2.1.218에서 /model이 기본값으로 저장했다고 표시했는데 재시작하면 다른 모델이었고, ~/.claude/settings.json에 model 키가 없었다고 보고했습니다. not planned로 닫혔습니다.

두 번째 사례처럼 다른 도구 때문에 걸어 둔 환경 변수는 정작 Claude Code를 쓸 때는 잊고 있기 쉽습니다. 그래서 저는 모델이 이상하면 설정 파일보다 셸의 ANTHROPIC_MODEL부터 보길 권해요.

마치며

모델 설정이 헷갈리는 건 자리가 다섯 곳이나 되고, 그중 일부는 한 세션에만, 일부는 다음 세션까지 남기 때문입니다. 겹쳐 보니 순서는 문서 그대로였어요. 그러니 “왜 내 기본값이 안 먹지” 싶을 때는 순서를 의심하기보다 더 위의 자리에 무언가 남아 있지 않은지를 찾는 게 빠릅니다.

셸에 ANTHROPIC_MODEL이 남아 있지 않은지 한 번 확인해 두시고, 팀과 같이 쓰는 저장소라면 프로젝트 설정 파일에 model을 넣을지도 정해 두세요. 모델을 올렸을 때 토큰이 얼마나 더 드는지는 직접 재 본 여덟 가지 절약 방법에 같은 작업을 놓고 잰 수치가 있습니다.