Claude Code에서 기본 모델을 변경하는 방법(및 2.1.251의 새로운 모델 전환 훅)

/model로 Claude Code 기본 모델 설정하기

핵심은 기본 설정을 저장하는 것과 모델을 일시적으로 전환하는 것을 구분하는 데 있습니다. 2026년 8월 29일 당시, /model 에서는 이미 두 작업 방식을 모두 지원했습니다.

버전 2.1.153에서는 다음 동작이 변경되었습니다. /model 선택한 모델이 새 세션의 기본값으로 저장되도록 바뀌었습니다. 이 동작은 2.1.251 이전부터 제공되었습니다. 8월 릴리스에서 도입된 것은 모델 전환 훅이지, 대화형으로 선택한 모델을 기억하는 기능이 아닙니다.

이 버전이 명시된 변경 로그 는 이 차이를 확인할 수 있는 과거 기록입니다. 여기에는 선택한 모델을 지속적으로 유지하는 동작과 일시적으로 전환하는 선택기의 동작이 모두 기록되어 있습니다.

향후 세션에 사용할 기본 설정 저장하기

모델 선택기를 사용하세요.

/model

기본값으로 사용할 모델을 선택하세요. 2.1.153에서 도입된 설정 유지 동작에 따라 이 선택은 새 세션에 사용할 기본값으로 저장됩니다.

이는 “선호하는 모델을 계속 유지하려면 어떻게 해야 하나요?”라는 질문에 대해 과거 기록으로 가장 명확하게 뒷받침되는 답입니다. 이전 릴리스에서 도입된 기능을 2.1.251의 새로운 기능으로 취급할 필요가 없습니다.

현재 세션에서만 전환하기

누르세요: s 모델 선택기에서 이 키를 누르면 현재 세션에서만 모델을 전환합니다. 선택을 일시적으로 적용하려면 이 동작을 사용하세요.

이 차이는 이전 지침을 따르거나 사용자 지정 키보드 단축키를 관리할 때 중요합니다. 선택기의 기존 d 동작은 다음으로 변경되었습니다. s그리고 관련 사용자 지정 키 바인딩은 다음에서 modelPicker:setAsDefault 다음으로 변경되었습니다. modelPicker:thisSessionOnly.

모델 선택에 관한 더 폭넓은 맥락은 다음을 참조하세요. Claude Code 모델 가이드. 이 릴리스와 관련된 핵심은 간단합니다. 일반적인 선택은 기본값을 저장하고, 현재 세션에만 적용하는 동작은 모델을 일시적으로 전환합니다.

구성 파일, ANTHROPIC_MODEL, 시작 시 재정의

모델 구성에는 설정 파일, 환경 변수, 시작 플래그를 사용하는 방법도 있습니다. 다만 제공된 조사 자료에는 과거 기록상의 한계가 있습니다. 2026년 8월 29일까지 확인할 수 있었던 스냅샷에서 이 방법들의 정확한 문서 내용과 우선순위가 독립적으로 검증되지 않았습니다.

이 모델 구성 문서 및 설정 문서 에서는 이러한 방법을 설명하지만, 해당 페이지에는 이후 업데이트가 포함되어 있습니다. 따라서 이 문서들만으로는 이 글의 기준 시점 당시 동작의 모든 세부 사항을 확정할 수 없습니다.

다음 표는 문서에 설명된 옵션과 날짜가 확인되는 근거로 뒷받침되는 내용을 구분합니다.

어떤 설정이 우선하나요?

제공된 조사 자료에 따르면 문서에서는 시작 플래그가 다음보다 우선한다고 설명합니다. ANTHROPIC_MODEL그리고 환경 변수는 설정 파일의 다음 항목보다 우선합니다. model 값. 또한 이 우선순위가 발행 기준 시점에 대해서는 검증되지 않았다고 명시합니다.

따라서 이 글에서는 해당 우선순위 체계를 8월 29 당시의 확정된 사실로 제시하지 않습니다. /model 설정 유지 동작의 변경은 날짜가 명시된 변경 로그로 뒷받침되지만, 정확한 구성 우선순위 체계에는 그러한 근거가 없습니다.

특정 프로젝트의 기본값은 어떻게 설정하나요?

조사 자료는 문서에 사용자 설정 파일, 프로젝트 설정 파일, 개인용 프로젝트 설정 파일이 있음을 확인합니다. 하지만 기준 시점 이전의 스냅샷을 통해 당시의 정확한 문구나 모델 설정 동작을 확정하지는 못합니다.

따라서 프로젝트 구성 튜토리얼보다 제한적인 답만 제시할 수 있습니다. /model 설정 유지 동작은 확인되었지만, 프로젝트별 파일 설정 지침은 과거 기록 검증이 필요합니다. CLI 참조 는 명령줄 구성을 위한 유용한 참고 자료이지만, 이 글에서 제시할 수 있는 근거의 한계를 해소하지는 못합니다.

2.1.251에서 모델 전환 훅으로 추가된 기능

Claude Code 2.1.251는 2026년 8월 28일에 출시되었습니다. 해당 버전의 공식 릴리스 노트 에서는 다음과 같은 정확한 이름의 훅을 소개합니다.

• PreModelSwitch
• PostModelSwitch

릴리스에서는 이 훅의 기능을 모델 전환 차단, 확인 요청, 주석 추가로 설명합니다. 이 훅은 전환 과정에 제어 기능을 추가하여 모델 선택 워크플로를 확장합니다.

기본 설정 유지와 구분해야 할 새로운 기능은 바로 이것입니다. 모델 기본 설정을 저장하는 기능은 이미 제공되고 있었으며, 새로운 훅 이벤트는 모델 변경에 관여할 수 있는 방법을 추가합니다.

훅으로 전환을 차단하거나 확인을 요청할 수 있나요?

네, 차단과 확인 요청은 릴리스 발표에 명시된 기능입니다. 주석 추가도 포함되어 있습니다.

발표에는 전체 입력 및 출력 스키마, 매처 규칙, 결정 JSON가 제공되지 않습니다. 따라서 이러한 기능을 설명할 근거는 되지만, 발표만으로 실행 가능한 구성을 제시할 근거는 되지 못합니다.

이전 모델과 새 모델을 식별하는 페이로드 필드나 확인 응답의 구성 방식 같은 세부 사항에도 같은 한계가 적용됩니다. 이러한 세부 사항은 제공된 기준 시점 이전의 근거에 포함되어 있지 않습니다.

구현하기 전에 무엇이 필요한가요?

실제로 작동하는 구현에는 이벤트 이름만으로는 부족합니다. 적용할 구성 형식과 지원되는 응답 규약이 필요합니다. 릴리스 노트에는 이러한 정보가 제공되지 않습니다.

다음을 참조하세요. Claude Code 훅 가이드 에서 훅에 관한 더 폭넓은 맥락을 확인할 수 있습니다. 이 릴리스에서 확인된 범위는 다음과 같이 정확히 한정하세요. PreModelSwitch 및 PostModelSwitch 이 훅들이 존재하며, 발표에서는 차단, 확인 요청, 주석 추가 기능을 설명합니다.

프롬프트 캐시 동작과 재개 비용 살펴보기

버전 2.1.251에는 프롬프트 캐시 동작을 이해하는 데 도움이 되는 진단 기능도 추가되었습니다. 이 기능은 캐시 활동과 예상 재구축 비용을 보여줍니다. 이 릴리스에서는 새로운 토큰 가격이나 수치로 표시되는 캐시 한도를 발표하지 않았습니다.

/cost의 새로운 캐시 항목 확인하기

기존 명령에 세션별 프롬프트 캐시 항목이 추가됩니다.

/cost

이 항목은 다음 정보를 보여줍니다.

• 적중률
• 미스
• 다시 캐시된 토큰
• 웜 또는 콜드 상태

이 정보들을 함께 보면 비용 수치만 볼 때보다 캐시 상태를 더 자세히 파악할 수 있습니다. 캐시 적중과 미스를 구분하고, 다시 캐시된 토큰 수를 보여줍니다.

상태 표시줄 스크립트에도 이에 대응하는 prompt_cache 객체가 추가됩니다. 이에 따라 다음 명령뿐 아니라 상태 표시줄 인터페이스에서도 캐시 진단 정보를 확인할 수 있습니다. /cost.

발표에서는 이 객체의 전체 스키마를 제공하지 않습니다. 다음을 prompt_cache 확인된 객체 이름으로만 취급하고, 릴리스에 설명된 진단 정보 외에 추가 필드가 있다고 가정하지 마세요.

SessionStart를 통해 재개 정보 확인

세션을 재개하면, SessionStart 훅이 이제 세션의 오래된 정도와 프롬프트 캐시를 재구축하는 데 드는 예상 비용을 받습니다.

이는 다음 표시와는 다릅니다: /cost 표시: 재개 기능에 추가된 정보는 훅에 전달되는 반면, 이 명령은 세션별 캐시 진단 정보를 보고합니다. 두 추가 기능 모두 캐시 상태를 파악하는 데 관련되지만, 서로 다른 인터페이스를 통해 정보를 제공합니다.

릴리스 노트에는 세션의 오래된 정도나 예상 재구축 비용에 대한 정확한 페이로드 키 이름이 나와 있지 않습니다. 해당 이름을 가정하는 훅 예제는 확인 가능한 근거의 범위를 넘어섭니다.

다른 모델 기본값과 진단 기능도 변경되었습니다

2.1.251의 몇 가지 관련 변경 사항은 “기본 모델”을 해석할 때 중요합니다. 이러한 변경 사항은 하위 에이전트, 계정 기본값, 추론 노력 설정, 게이트웨이 지출 현황과 관련됩니다.

하위 에이전트 모델 우선순위

CLAUDE_CODE_SUBAGENT_MODEL 이제 기본값을 제공합니다. 에이전트 정의의 model: 값과 에이전트를 생성할 때 명시적으로 선택한 모델이 해당 변수보다 우선합니다.

이는 태그가 지정된 변경 로그에서 확인된 우선순위 변경입니다. 기본 모델의 시작 플래그, 환경 변수, 설정 파일 값 사이의 검증되지 않은 과거 우선순위와는 구분해야 합니다.

하위 에이전트의 모델 선택을 검토할 때는 환경 변수를 결정적인 요소로 보기 전에 이러한 명시적 선택을 고려하세요. 다음 자료는 하위 에이전트 가이드 에이전트 구성에 대한 더 폭넓은 맥락을 제공합니다.

계정 기본값과 추론 노력 설정

좌석 기반 Enterprise 구독은 이제 다른 프리미엄 요금제와 마찬가지로 Opus 5을 기본값으로 사용합니다.

이 계정 수준의 변경은 다음을 통해 저장한 모델 설정과는 별개입니다: /model. 이번 릴리스에서는 다음 항목의 저장 방식도 변경됩니다: /effort 저장 방식: 이제 모델마다 별도의 기본 추론 노력 수준을 저장합니다.

실질적인 차이는 모델 선택과 추론 노력 설정의 저장이 별개의 설정이라는 점입니다. 새로운 추론 노력 설정 동작은 하나의 공통 기본값을 사용하는 것이 아니라 모델별 기본값을 기억합니다.

게이트웨이 지출 현황

이 /usage 명령에 다음 표시가 추가됩니다: 지출 한도 막대 표시가 지출 한도가 설정된 Claude 앱 게이트웨이를 사용하는 개발자에게 제공됩니다:

/usage

상태 표시줄 스크립트에는 이에 대응하는 rate_limits.spend_limit 필드가 추가됩니다. 이는 해당 게이트웨이 환경을 위한 진단 기능 추가입니다.

변경 로그는 모든 사용자에게 적용되는 달러 기준 한도를 발표하지 않습니다. 따라서 지출 한도 표시가 있다는 사실을 모든 Claude Code 사용자에게 고정된 한도가 적용된다는 뜻으로 해석해서는 안 됩니다.

핵심 요점

• /model 은 2.1.251 이전에도 새 세션의 기본값을 저장했으며, 이 동작은 2.1.153부터 제공되었습니다.
• 누르세요: s 을 모델 선택기에서 누르면 현재 세션에만 적용되는 전환을 할 수 있습니다. 사용자 지정 키 바인딩에는 다음을 사용합니다: modelPicker:thisSessionOnly.
• Claude Code 2.1.251에는 다음이 추가됩니다: PreModelSwitch 및 PostModelSwitch, 릴리스에는 차단, 확인, 주석 추가 기능이 설명되어 있습니다.
• /cost, 상태 표시줄 캐시 데이터, 재개 시 제공되는 SessionStart 정보를 통해 프롬프트 캐시 활동과 예상 재구축 비용을 파악할 수 있습니다.
• CLAUDE_CODE_SUBAGENT_MODEL 은 명시적인 에이전트 모델 선택으로 재정의할 수 있는 기본값을 제공합니다. 제공된 조사 자료에서는 과거 기본 모델 구성의 정확한 우선순위가 여전히 검증되지 않았습니다.

자주 묻는 질문

/model은 Claude Code에서 기본 모델을 저장하나요?

네. 버전 2.1.153에서 다음 항목이 변경되었습니다: /model 선택한 모델이 새 세션의 기본값으로 저장되도록 변경되었으며, 이 동작은 2.1.251 이전에도 제공되었습니다. 다음 키를 누르세요: s 현재 세션에만 적용되는 전환을 원할 때는 선택기에서 해당 키를 누르세요.

settings.json, ANTHROPIC_MODEL, --model 중 무엇이 우선하나요?

제공된 조사 자료에 따르면 문서에서는 시작 플래그가 다음 항목보다 우선한다고 설명합니다: ANTHROPIC_MODEL, 그리고 해당 변수는 설정 파일의 모델 값보다 우선합니다. 다만 29년 2026의 8월 이전 스냅샷에서는 정확한 순서가 독립적으로 검증되지 않았으므로, 이 글에서는 이를 기준 시점에 확정된 동작으로 제시하지 않습니다.

Claude Code 모델 전환 훅이 변경을 차단할 수 있나요?

2.1.251 릴리스에서는 다음 항목을 설명합니다: PreModelSwitch 및 PostModelSwitch 모델 전환의 차단, 확인, 주석 추가를 지원한다고 설명합니다. 완전한 스키마나 결정 JSON은 제공하지 않으므로, 발표 내용만으로는 실행 가능한 훅을 구현하기에 충분하지 않습니다.

캐시 미스와 예상 재구축 비용은 어디에서 확인할 수 있나요?

2.1.251에서는, /cost 세션별 캐시 적중률, 캐시 미스, 다시 캐시된 토큰, 웜 또는 콜드 상태를 보고하며, 상태 표시줄 스크립트에는 이에 대응하는 prompt_cache 객체가 추가됩니다. 별도로, SessionStart 훅은 세션 재개 시 세션의 오래된 정도와 예상 프롬프트 캐시 재구축 비용을 받지만, 릴리스 노트에는 해당 페이로드 키 이름이 명시되어 있지 않습니다.