클로드 코드(Claude Code) 모델 변경·effort 설정 완전 정리 - Opus 5 / Sonnet 5 / Fable 5.1 골라 쓰는 법 🎛️

안녕하세요! Mojangcam입니다 😎

지난 7월에 Claude Opus 5 출시 소식을 전하면서 /model·/effort 명령어를 잠깐 소개해 드렸는데요. 그 뒤로 블로그 유입 검색어를 보니 '클로드 코드 모델 변경', 'claude effort 차이' 같은 검색어로 찾아오시는 분이 꾸준히 있더라고요. 그런데 딱 그것만 정리한 글이 없어서, 오늘은 아예 이 두 가지만 파는 전용 정리 글을 준비했어요.

이번 글에서 배울 것은 이렇습니다.

• 모델과 effort가 각각 뭘 바꾸는지 (헷갈리기 쉬운 두 개의 다이얼)
• 2026년 9월 기준 라인업(Fable 5.1 / Opus 5 / Sonnet 5 / Haiku 4.5)과 플랜별 기본 모델
• /model로 바꾸기 → /effort로 조절하기 → settings.json에 고정하기
• 내 작업엔 뭘 골라야 하는지 — 선택 기준과 플랜별 추천 조합
• 자주 하는 실수 (바꿨는데 다음 세션에서 원래대로 돌아오는 이유 등)

왜 이게 중요하냐면요. Pro 플랜은 기본이 Sonnet 5, Max 플랜은 Opus 5라서 같은 Claude Code를 쓰는데도 사람마다 다른 모델이 돌아가고 있어요. 게다가 effort 하나로 토큰 소모가 몇 배씩 달라지기도 하고요. 사용량 한도에 자꾸 걸리는 분도, 반대로 "답이 너무 성의 없다"고 느끼는 분도 결국 이 두 설정에서 답을 찾게 됩니다 🙌

📌 준비물

• Claude Code v2.1.278 (2026-09-21 기준 npm 최신) — 최소 요구 버전: Opus 5 → v2.1.219+, Sonnet 5 → v2.1.197+, Fable 5.1 → v2.1.257+
• Claude 구독(Pro·Max·Team) 또는 Anthropic API 키
• API 키를 쓰신다면 ANTHROPIC_API_KEY 환경변수로만 넣으세요. 설정 파일이나 코드에 키를 하드코딩하면 안 돼요!

버전부터 맞추고 시작할게요.

claude update
claude --version

💬 이 글은 Anthropic API / claude.ai 구독으로 직접 연결한 환경 기준이에요. Amazon Bedrock·Google Cloud·Microsoft Foundry는 별칭이 가리키는 버전이 달라서 아래 표에 따로 적어둘게요.

🧠 모델 vs effort — 뭐가 다른가요?

Claude Code에는 "답을 더 좋게 만드는 것 같은" 설정이 두 개 있어요. 그런데 둘이 하는 일이 완전히 달라요. Anthropic 공식 블로그의 설명을 한 표로 정리하면 이렇습니다.

핵심은 effort가 단순히 "생각 시간"이 아니라는 거예요. effort를 올리면 Claude는 파일을 더 읽고, 테스트를 더 돌리고, 저한테 되묻기 전에 더 멀리까지 스스로 갑니다. 반대로 낮추면 토큰을 아끼는 대신 "이거 어떻게 할까요?" 하고 더 자주 물어봐요.

그래서 뭔가 틀렸을 때 어느 다이얼을 돌릴지 판단하는 공식 기준이 이거예요 💡

• 몰라서 틀렸다 (컨텍스트 다 줬는데 자신 있게 엉뚱한 답, 미묘한 버그, 낯선 도메인) → 모델을 올리세요
• 덜 열심히 해서 틀렸다 (파일을 건너뜀, 테스트를 안 돌림, 리팩터링을 중간에 멈춤) → effort를 올리세요
• 그 전에 먼저: 프롬프트가 모호하지 않은지, CLAUDE.md와 도구가 제대로 잡혀 있는지부터 확인. 다이얼보다 컨텍스트 문제인 경우가 훨씬 많아요.

🧩 2026년 9월 기준 모델 라인업

공식 Models overview 기준으로 지금 고를 수 있는 모델은 4개예요.

표의 가격은 API 종량제 기준이에요. Pro·Max 구독은 정액이지만, 비싼 모델일수록 사용량 한도를 빨리 소모하는 건 똑같으니 감각은 그대로 가져가시면 됩니다. 참고로 Sonnet 5는 API에서 항상 1M 컨텍스트로 돌고, 20만 토큰을 넘어도 추가 요금은 없어요.

그리고 아무것도 안 건드렸을 때(default) 어떤 모델이 뜨는지는 플랜에 따라 달라요. 여기서 많이들 헷갈리세요.

즉 Max는 켜자마자 Opus 5, Pro는 켜자마자 Sonnet 5예요. Pro인데 "왜 내 Claude Code는 Opus가 아니지?" 하셨다면 정상입니다 😅

📌 1단계 - /model로 모델 바꾸기

세션 도중에 바로 바꿀 수 있어요. 인자 없이 치면 피커(선택 화면)가 열립니다.

/model

피커에서 키 하나가 중요해요 💡

• Enter : 모델을 바꾸고, 앞으로의 기본값으로 저장 (사용자 설정 파일의 model 값을 씀)
• s : 이번 세션에서만 바꾸고 저장된 기본값은 그대로 둠
• ←/→ 방향키 : 같은 화면에서 effort 슬라이더 조절

이름을 직접 쳐도 됩니다. 이 경우엔 Enter를 누른 것과 같아서 기본값까지 저장돼요.

/model opus
/model sonnet
/model fable
/model claude-opus-5

자주 쓰는 별칭(alias)을 정리해 둘게요.

opusplan은 은근 알짜예요. 설계(플랜)는 똑똑한 모델이 하고, 코드 찍어내기는 빠른 모델이 하니까 비용이 확 줄거든요.

시작할 때부터 지정하고 싶으면 플래그로 넘기면 되는데, 이건 그 세션에만 적용되고 기본값은 안 건드려요. 터미널 두 개를 서로 다른 모델로 굴리고 싶을 때 딱입니다.

claude --model sonnet

그리고 여러 방법이 겹치면 우선순위가 있어요. 위에 있을수록 셉니다.

1. 세션 중 /model
2. 시작 시 claude --model
3. 환경변수 ANTHROPIC_MODEL
4. 설정 파일의 model 키 (/model로 저장한 값이 여기 들어감)
5. 환경변수 ANTHROPIC_DEFAULT_MODEL (아무것도 지정 안 했을 때만 쓰는 시작 기본값, v2.1.236+)

지금 뭐가 돌고 있는지는 /status로 확인할 수 있고, 세션 시작 헤더에도 모델명이 찍혀요. 프로젝트 설정이나 관리(managed) 설정이 모델을 정한 경우엔 어느 파일이 정했는지까지 헤더에 나오니 참고하세요.

📌 2단계 - 어떤 모델을 언제 쓸까? (선택 기준)

공식 가이드를 작업 유형별로 옮기면 이렇게 돼요.

공식 블로그의 비유가 재밌어서 그대로 옮겨볼게요. Opus를 low effort로 쓰는 것은 내 문제를 잘 아는 전문가와 5분 면담하는 것이고, Sonnet을 high effort로 쓰는 것은 똑똑한 제너럴리스트에게 오후 내내 시간을 주는 거예요. 전자는 경험치는 많지만 내 코드를 대충 훑고, 후자는 내 코드를 샅샅이 읽지만 "이거 전에 봤어"가 적죠. 그리고 Fable은 남들이 다 막힌 문제를 슬쩍 보고도 짚어내는 스페셜리스트라서, 진짜 필요한 작업에만 아껴 쓰라는 게 공식 입장이에요.

💡 비용 팁 하나. 큰 모델은 토큰 단가가 비싸지만, 어려운 작업에선 반복 횟수가 줄어서 작업당 총비용이 오히려 낮아질 수 있어요. 작은 모델이 한계까지 갈고닦으며 토큰을 태우는 동안 큰 모델은 몇 스텝 만에 끝내거든요. 반대로 루틴 작업 구간에서는 작은 모델로 내리는 게 순이득입니다.

Fable 5.1을 쓸 때 공식 문서가 권하는 요령도 짧게요.

• 단계가 아니라 결과를 설명하세요. 경로는 알아서 짭니다
• 모호한 문제를 통째로 맡기세요. 근본 원인 조사, 장애 디버깅, 아키텍처 결정에서 값어치를 함
• "테스트 꼭 돌려", "검증해" 같은 리마인더는 빼세요. 시키지 않아도 스스로 검증해서, 넣으면 오히려 과잉 검증이 됨
• 작업을 잘게 쪼개지 마세요. 평소 나눠서 시키던 일을 한 덩어리로 줘도 됩니다

서브에이전트(탐색·검색 담당)는 굳이 비싼 모델일 필요가 없어요. CLAUDE_CODE_SUBAGENT_MODEL=haiku처럼 환경변수로 따로 지정할 수 있습니다. 4단계에서 예제로 보여드릴게요.

📌 3단계 - /effort로 사고 깊이 조절하기

/effort
/effort medium
/effort auto

하나씩 뜯어볼게요 💡

• /effort : 인자 없이 치면 슬라이더가 뜸. /model 피커 안에서도 방향키로 같은 슬라이더를 조절할 수 있음
• /effort medium : 레벨 직접 지정. 작업 중에도 칠 수 있고, 다음 요청부터 적용됨
• /effort auto : 현재 모델에 저장해 둔 레벨을 지움 (모델 기본값으로 리셋)

레벨은 이렇게 골라요.

모델마다 지원 범위가 달라요. Fable 5.1·Fable 5·Opus 5·Sonnet 5·Opus 4.8·4.7은 low~max 전부, Opus 4.6·Sonnet 4.6은 xhigh가 없고, Haiku 4.5는 effort 자체를 지원하지 않아요. 지원 안 하는 레벨을 지정하면 그 아래 최고 레벨로 자동 하향됩니다(예: Opus 4.6에서 xhigh → high). 그리고 같은 high라도 모델마다 보정된 값이라 모델이 바뀌면 같은 레벨 이름이 같은 강도를 뜻하진 않아요.

저장 방식도 알아두면 좋아요.

• 슬라이더에서 Enter 또는 /effort 레벨 직접 입력 → 기본값으로 저장, 다음 세션에도 유지
• 슬라이더에서 s → 이번 세션만 (v2.1.257+)
• 저장은 모델별로 돼요. Opus 5에서 medium을 저장해도 Sonnet 5로 바꾸면 Sonnet 5의 저장값(없으면 기본 high)을 씁니다. 설정 파일의 modelSettings 키에 기록돼요
• max는 환경변수로 넣지 않는 한 현재 세션 전용

한 턴만 깊게 생각시키고 싶을 땐 세션 설정을 건드릴 필요 없이 프롬프트 아무 데나 ultrathink를 넣으면 돼요. Claude Code가 이 키워드를 인식해서 그 턴에만 더 깊이 추론하라는 지시를 붙입니다(API로 가는 effort 값은 그대로). 반면 "think hard", "think more" 같은 말은 그냥 평범한 문장으로 처리되니 참고하세요 😉

그럼 얼마나 차이가 날까요? 공식 블로그의 예시 그림에서는 같은 프롬프트를 high로 돌렸을 때 low보다 대략 7배 많은 토큰을 써서 더 확신 있는 답에 도달했어요(설명용 예시 수치예요). 다만 effort는 "얼마나 멀리 갈 의향이 있는가"지 "무조건 그만큼 쓴다"가 아니라서, 간단한 작업은 high여도 알아서 짧게 끝냅니다. 그래서 공식 가이드는 대부분의 작업은 기본값(high) 그대로, 조절은 작업마다가 아니라 내 업무 성향(꼼꼼함 vs 속도)에 맞춰 한 번 정하라고 권해요.

지금 적용된 레벨은 세션 헤더에 "with low effort"처럼 표시되고, 시작할 때와 바꿀 때 하단에 잠깐 떠요. 헷갈리면 헤더부터 보세요.

📌 4단계 - settings.json에 고정하기

매번 치기 귀찮으면 설정 파일에 박아두면 됩니다. 설정 파일은 세 군데예요.

~/.claude/settings.json              ← 사용자 설정 (내 PC 전체)
                                       윈도우는 C:\Users\<계정>\.claude\settings.json
<프로젝트>/.claude/settings.json        ← 프로젝트 공유 설정 (git에 커밋해서 팀 전체 적용)
<프로젝트>/.claude/settings.local.json  ← 프로젝트 로컬 설정 (나만, .gitignore 권장)

우선순위는 관리(managed) 설정 > 명령줄(--settings) > 프로젝트 로컬 > 프로젝트 공유 > 사용자 설정 순이에요. /model·/effort로 저장한 값은 사용자 설정에 들어가기 때문에, 프로젝트 설정에 model이 박혀 있으면 다음 실행 때 프로젝트 설정이 다시 이깁니다. 이게 "바꿨는데 왜 돌아오지?"의 단골 원인이에요.

사용자 설정 예제입니다. 복붙 OK 👇

{
  "model": "opus",
  "effortLevel": "high",
  "modelSettings": {
    "claude-opus-5": { "effortLevel": "medium" }
  },
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

하나씩 뜯어볼게요 💡

• model : 기본 모델. 별칭(opus·sonnet·fable·opusplan)이나 정식 ID(claude-opus-5) 모두 가능. /model에서 Enter로 저장하면 이 값이 바뀜
• effortLevel : 따로 저장된 레벨이 없는 모델에 적용할 기본 effort. low·medium·high·xhigh만 가능 — max와 ultracode는 설정 파일에 못 넣어요 (ultracode는 별도의 ultracode 키를 씁니다)
• modelSettings : 모델별 저장 레벨. /effort로 저장하면 여기에 정식 ID 이름으로 기록됨. 위 예제는 "Opus 5만 medium, 나머지는 각자 기본값"이라는 뜻. 같은 파일 안에서는 이 값이 effortLevel보다 우선. 한 모델의 상한만 두고 싶으면 그 항목에 maxEffortLevel을 추가
• fallbackModel : 주 모델이 과부하·장애일 때 대신 시도할 모델 목록(최대 3개). 그 턴만 대체하고 다음 메시지는 다시 주 모델부터 시도. 인증·요금·한도 오류는 해당 없음

프로젝트에 강제하고 싶다면 <프로젝트>/.claude/settings.json에 넣으세요. 예를 들어 "이 레포는 가벼운 스크립트 모음이니 Sonnet만"이라면:

{
  "model": "sonnet"
}

환경변수로도 됩니다. 그 터미널 세션에만 적용되니 "오늘만 이렇게" 쓸 때 편해요.

# Windows PowerShell — 이 터미널 창에서만 유효
$env:ANTHROPIC_MODEL = "sonnet"
$env:CLAUDE_CODE_EFFORT_LEVEL = "medium"
$env:CLAUDE_CODE_SUBAGENT_MODEL = "haiku"
claude

# macOS / Linux
export ANTHROPIC_MODEL=sonnet
export CLAUDE_CODE_EFFORT_LEVEL=medium
export CLAUDE_CODE_SUBAGENT_MODEL=haiku
claude

• ANTHROPIC_MODEL : 이 세션의 모델. /model로 저장한 값보다 우선
• CLAUDE_CODE_EFFORT_LEVEL : effort. --effort·/effort와 같은 최우선 그룹이라 설정 파일·모델 기본값을 전부 이깁니다. 스킬·서브에이전트 frontmatter의 effort보다도 세고요. 값은 레벨 이름 또는 auto이며 ultracode는 못 넣어요
• CLAUDE_CODE_SUBAGENT_MODEL : 서브에이전트·에이전트 팀 기본 모델. 탐색 작업은 haiku로 내리면 한도가 확 절약됨
• ANTHROPIC_DEFAULT_MODEL : 아무 데도 모델을 지정 안 했을 때만 쓰는 "새 세션 시작 모델" (v2.1.236+)
• ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL : opus·sonnet 별칭이 가리킬 정확한 버전을 고정(pin). 별칭이 새 버전으로 바뀌는 게 싫을 때

💡 플랜별 추천 조합

제가 정리한 레시피예요. 정답은 아니고 출발점으로 쓰세요.

• Pro : 기본 Sonnet 5 · high 그대로. 막히는 문제만 /model 피커에서 s로 Opus 5를 세션 한정으로 켜기. 설계 비중이 크면 opusplan. Opus 1M 컨텍스트는 사용량 크레딧이 필요하니 opus[1m]은 신중하게
• Max : 기본 Opus 5 · high. 오타 수정·단순 반복 구간엔 /model 피커에서 s로 Sonnet 5로 내려서(세션 한정) 한도 절약. 하루짜리 큰 작업은 /model fable — 크레딧 과금 동의 프롬프트가 뜨면 내용 확인 후 진행
• API 종량제 : 비용이 그대로 보이니 메인은 opus, 서브에이전트는 CLAUDE_CODE_SUBAGENT_MODEL=haiku, fallbackModel로 과부하 대비
• 공통 : effort는 손대지 말고 시작 → "파일을 건너뛰었다", "테스트를 안 돌렸다"가 반복되면 한 단계 ↑. 반대로 간단한 작업만 하는 프로젝트면 그 프로젝트 설정에 "effortLevel": "medium"

📌 자주 나는 에러·실수

1. /model로 바꿨는데 새 세션에서 다른 모델이 뜬다

• 원인 : ① 피커에서 s를 눌렀거나 --model로 켰음 (세션 한정) ② 프로젝트·관리 설정의 model, 셸의 ANTHROPIC_MODEL, 조직 기본 모델이 더 우선 ③ 사용자 settings.json이 읽기 전용이라 저장 실패 ④ claude --resume/--continue는 그 세션이 쓰던 모델을 그대로 복원
• 해결 : 시작 헤더에 찍힌 "어느 설정 파일이 정했는지" 확인 → 해당 파일의 model 키 수정, 또는 /model에서 Enter로 다시 저장

2. Model "xxx" is not a recognized model id.

• 원인 : 별칭도 아니고 claude-로 시작하는 정식 ID도 아닌 문자열 (오타가 대부분)
• 해결 : opus·sonnet·fable 같은 별칭이나 claude-opus-5 같은 정식 ID로 다시 입력. 세션은 기존 모델을 유지하니 그냥 재입력하면 됨

3. Fable 5.1을 고르니 "Claude Code does not support this model"

• 원인 : Claude Code가 v2.1.257 미만
• 해결 : claude update 후 재시작

4. /effort xhigh를 했는데 헤더엔 "with high effort"

• 원인 : 지금 모델이 xhigh를 지원하지 않거나(Opus 4.6·Sonnet 4.6), maxEffortLevel·조직 effort 상한이 걸려 있음
• 해결 : /status로 모델 확인 → Opus 5/Sonnet 5로 변경, 설정 파일의 maxEffortLevel 확인

5. /effort로 올려도 적용이 안 된다 (ultracode를 고르면 "환경변수가 우선" 경고까지 뜬다)

• 원인 : CLAUDE_CODE_EFFORT_LEVEL이 xhigh 말고 다른 레벨로 걸려 있으면 요청은 그 레벨로 나가고 ultracode의 워크플로 조율이 꺼진 채로 돌아요. 이때 ultracode를 고르면 "환경변수가 세션 effort를 덮어쓴다"는 경고가 뜹니다. maxEffortLevel이나 조직 effort 상한에 걸린 경우도 있고요
• 해결 : 환경변수를 지우고($env:CLAUDE_CODE_EFFORT_LEVEL = $null / unset CLAUDE_CODE_EFFORT_LEVEL) 재시작

6. Fable 행에 "Requires usage credits"가 뜨고 결제 동의를 물어본다

• 원인 : 내 플랜·시트에선 Fable 사용량이 구독 한도가 아니라 사용량 크레딧으로 과금됨
• 해결 : 원치 않으면 프롬프트를 닫으면 현재 모델 그대로 유지. 쓰기로 했다면 한 번만 동의하면 이후엔 안 물어봄. 조직 결제를 쓰는 Enterprise 플랜은 이 프롬프트가 아예 안 떠요

7. 보안·생물학 관련 코드베이스에서 갑자기 모델이 바뀐다

• 원인 : Fable·Opus 5는 안전 분류기가 있어서, 주로 사이버보안·생물학으로 판정된 요청을 다른 모델에서 재실행하고 세션이 그 모델에 남아요. 어디로 가는지는 카테고리마다 달라요 — Fable 5.1·5: 생물학 → Opus 5, 사이버보안 → Opus 4.8 / Opus 5: 사이버보안 → Opus 4.8, 생물학은 폴백 모델이 없어서 거부로 끝남. 첫 요청부터 걸릴 수도 있어요(CLAUDE.md·git 상태도 같이 보내니까). 카테고리별 폴백은 v2.1.219+
• 해결 : /model로 원래 모델 복귀. 내 커스터마이징이 원인인지 보려면 claude --safe-mode로 한 번 켜보기(CLAUDE.md·스킬·MCP·훅을 끄고 시작). 매번 물어보게 하려면 /config에서 Switch models when a message is flagged를 끄기(설정 파일은 switchModelsOnFlag: false)

🙌 마무리

오늘 내용을 정리하면 이래요.

• 모델 = 얼마나 유능한지(어떤 두뇌), effort = 얼마나 열심히(파일·검증·단계 수). 몰라서 틀리면 모델 ↑, 덜 열심히 해서 틀리면 effort ↑
• 2026년 9월 라인업은 Fable 5.1($10/$50) · Opus 5($5/$25) · Sonnet 5($2/$10) · Haiku 4.5($1/$5). Max는 기본 Opus 5, Pro는 기본 Sonnet 5, Fable은 항상 직접 선택
• /model은 Enter(저장) vs s(세션만), /effort도 같은 규칙. 저장값은 사용자 settings.json의 model·modelSettings에 들어감
• 프로젝트 설정·환경변수가 사용자 설정보다 세다. "바꿨는데 돌아온다"면 시작 헤더부터 확인
• 대부분은 기본값(high) 유지, 조절은 작업별이 아니라 내 업무 성향에 맞춰 한 번

다음 편은 디스코드 봇 만들기 시리즈 #31로 돌아올 예정이고, 10월 1일 파이썬 3.15 정식 출시일에 맞춰 정식판 신기능 총정리도 준비하고 있어요. 기대해주세요 🙌

혹시 여러분은 어떤 모델·effort 조합으로 쓰고 계신가요? 댓글로 알려주시면 다음 글에 반영할게요!

📚 함께 보면 좋은 글

• Claude Opus 5 출시! Claude Code 기본 모델 교체 - /model·/effort 활용법 총정리
• Claude Code 입문 - 설치부터 첫 실행까지! 터미널 AI 코딩 에이전트 완벽 가이드
• AI 코딩 프롬프트 잘 쓰는 법 - 바이브코딩 실전 가이드
• 개발자 노트북 추천 2026 하반기 - AI·바이브코딩 시대엔 기준이 달라졌어요
• Claude Sonnet 5 출시 - Claude Code 기본 모델 교체, 달라진 점과 활용법