65별칭은 공급자의 권장 버전을 가리키며 시간이 지남에 따라 업데이트됩니다. 특정 버전으로 고정하려면 전체 모델 이름(예: `claude-opus-5-5`)을 사용하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL`과 같은 해당 환경 변수를 설정합니다.65별칭은 공급자의 권장 버전을 가리키며 시간이 지남에 따라 업데이트됩니다. 특정 버전으로 고정하려면 전체 모델 이름(예: `claude-opus-5-5`)을 사용하거나 `ANTHROPIC_DEFAULT_OPUS_MODEL`과 같은 해당 환경 변수를 설정합니다.
66 66
67<Note>67<Note>
68 Sonnet 5.5는 Claude Code v2.1.284 이상이 필요하고, Opus 5.5는 v2.1.280 이상이 필요합니다. `claude update`를 실행하여 업그레이드합니다.68 Sonnet 5.5는 Claude Code v2.1.284 이상이 필요하고, Opus 5.5는 v2.1.280 이상이 필요합니다. 이전 버전의 요청이 실패하면 [Claude Code는 이 모델을 지원하지 않습니다](/docs/ko/errors#claude-code-does-not-support-this-model)를 참조하십시오. `claude update`를 실행하여 업그레이드합니다.
69</Note>69</Note>
70 70
71<h3 id="work-with-fable">71<h3 id="work-with-fable">
138 138
139`/model <name>`을 직접 입력하는 것은 `Enter`처럼 동작합니다. 이 세션에만 전환하려면 `/model`로 선택기를 열고 모델의 행에서 `s`를 누릅니다.139`/model <name>`을 직접 입력하는 것은 `Enter`처럼 동작합니다. 이 세션에만 전환하려면 `/model`로 선택기를 열고 모델의 행에서 `s`를 누릅니다.
140 140
141`/model`로 설정된 모델은 [주 대화의 모델을 상속하는 서브에이전트](/docs/ko/sub-agents#choose-a-model)에도 도달합니다. Claude Code는 Claude가 시작할 때 세션이 사용 중인 모델에서 해당 모델을 확인하기 때문입니다. 연구 또는 테스트 실행을 하나에 위임하기 전에 Opus로 전환하면 해당 작업도 Opus에서 실행됩니다. 사용자 정의 서브에이전트를 더 작은 모델에 유지하려면 해당 정의에서 `model`을 설정합니다.141Enterprise 플랜에서 claude.ai 계정으로 로그인하고 `/model`로 기본값을 저장하면 Claude Code는 해당 계정에도 선택을 기록합니다. Claude Code v2.1.280 이상이 필요합니다.
142
143* 관리자가 [조직 기본 모델](#organization-default-model)을 설정하지 않았을 때 [Default 옵션](#default-model-setting)은 기록된 모델로 확인될 수 있으며, 그렇게 되면 선택기의 Default 행은 해당 모델의 이름을 표시합니다.
144* [모델 제한](#restrict-model-selection)이 기록된 모델을 제외하거나 계정에서 사용할 수 없으며, 관리자가 조직 기본 모델을 설정하지 않았으면 Default 옵션은 아무것도 기록되지 않은 것처럼 확인됩니다.
145* Default 또는 `opusplan`을 `/model`에서 선택하면 기록된 선택은 변경되지 않습니다.
146
147`/model`로 모델을 전환하면 전환은 [주 대화의 모델을 상속하는 서브에이전트](/docs/ko/sub-agents#choose-a-model)에도 도달합니다. Claude Code는 Claude가 시작할 때 세션이 사용 중인 모델에서 해당 모델을 확인하기 때문입니다. 연구 또는 테스트 실행을 하나에 위임하기 전에 Opus로 전환하면 해당 작업도 Opus에서 실행됩니다. 사용자 정의 서브에이전트를 더 작은 모델에 유지하려면 해당 정의에서 `model`을 설정합니다.
142 148
143[비대화형 모드](/docs/ko/headless)에서 `-p` 플래그를 사용하여 `/model`로 모델을 설정하면 현재 세션에만 적용되며 기본값으로 저장되지 않습니다. `/model`은 해당 모드에서 Claude Code v2.1.205 이상이 필요합니다. 프로젝트 및 관리 설정은 여전히 우선순위를 가지며 다음 시작 시 다시 적용됩니다. [조직 기본 모델](#organization-default-model)이 관리자에 의해 사용자 선택을 재정의하도록 구성된 경우 다음 시작 시 다시 적용됩니다.149[비대화형 모드](/docs/ko/headless)에서 `-p` 플래그를 사용하여 `/model`로 모델을 설정하면 현재 세션에만 적용되며 기본값으로 저장되지 않습니다. `/model`은 해당 모드에서 Claude Code v2.1.205 이상이 필요합니다. 프로젝트 및 관리 설정은 여전히 우선순위를 가지며 다음 시작 시 다시 적용됩니다. [조직 기본 모델](#organization-default-model)이 관리자에 의해 사용자 선택을 재정의하도록 구성된 경우 다음 시작 시 다시 적용됩니다.
144 150
158 164
159Claude Code가 조직의 [관리 플러그인](/docs/ko/settings-reference#enabledplugins)이 제공하는 PreModelSwitch 훅을 알 수 없는 경우(예: 관리 플러그인이 로드되지 않음), 확인되지 않은 상태로 적용하는 대신 전환을 거부하며, 각 새 시도에서 다시 확인합니다. [PreModelSwitch 훅에 의해 모델 전환이 차단되었습니다](/docs/ko/errors#model-switch-was-blocked-by-a-premodelswitch-hook)를 참조하여 메시지 및 복구를 확인합니다.165Claude Code가 조직의 [관리 플러그인](/docs/ko/settings-reference#enabledplugins)이 제공하는 PreModelSwitch 훅을 알 수 없는 경우(예: 관리 플러그인이 로드되지 않음), 확인되지 않은 상태로 적용하는 대신 전환을 거부하며, 각 새 시도에서 다시 확인합니다. [PreModelSwitch 훅에 의해 모델 전환이 차단되었습니다](/docs/ko/errors#model-switch-was-blocked-by-a-premodelswitch-hook)를 참조하여 메시지 및 복구를 확인합니다.
160 166
161[Agent SDK](/docs/ko/agent-sdk/overview) `setModel()` 메서드를 통해 모델을 전환하거나 [Remote Control](/docs/ko/remote-control)을 통해 연결된 장치에서, 또는 Claude Code CLI를 전환하는 [Desktop 앱](/docs/ko/desktop)과 같은 앱에서 Claude Code는 문자열이 인식하는 것인지 확인한 후 저장합니다. 이 확인에는 Claude Code v2.1.200 이상이 필요합니다. Remote Control 선택을 확인하려면 머신에 Claude Code v2.1.260 이상이 필요합니다. Anthropic API에서 Claude Code는 다음을 인식합니다:167[Agent SDK](/docs/ko/agent-sdk/overview) `setModel()` 메서드를 통해 모델을 전환하거나 [Desktop 앱](/docs/ko/desktop)과 같은 앱에서, 또는 [Remote Control](/docs/ko/remote-control)을 통해 연결된 장치에서 Claude Code는 값을 전환할 때 확인합니다:
162 168
163* 모델 별칭169* **Agent SDK 또는 앱**: Claude Code v2.1.268 이상에서 Claude Code가 로컬에서 모델 ID를 수락하지 않으면(예: [사용자 정의 모델 옵션](#add-a-custom-model-option)의 경우), 세션이 처음 전환할 때 공급자와 ID를 확인합니다. 확인은 모든 공급자에서 실행되며, 공급자가 제공하지 않는 ID는 다음 요청에서 실패하는 대신 전환 시 거부됩니다.
164* `/model` 선택기의 항목170* **Remote Control**: Anthropic API에서 Claude Code는 값을 로컬에서 확인하고 요청을 보내지 않습니다.
165* `claude-`로 시작하는 모든 이름
166* [사용자 정의 모델 옵션](#add-a-custom-model-option)으로 또는 [`modelOverrides`](#override-model-ids-per-version)에서 자신이 구성한 값
167 171
168Claude Code는 인식되지 않은 문자열을 `Model "<name>" is not a recognized model id.`로 거부하며 세션은 현재 모델을 유지하고, 문자열을 저장하고 다음 요청에서 실패하는 대신입니다. 복구 단계는 [오류 참조](/docs/ko/errors#model-is-not-a-recognized-model-id)를 참조하십시오.172[모델은 인식된 모델 ID가 아닙니다](/docs/ko/errors#model-is-not-a-recognized-model-id) 및 [모델을 찾을 수 없습니다](/docs/ko/errors#model-not-found)를 참조하여 메시지를 확인합니다.
169 173
170확인은 Anthropic API에서만 실행됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), [LLM 게이트웨이](/docs/ko/llm-gateway) 뒤 또는 사용자 정의 `ANTHROPIC_BASE_URL`에서 공급자 또는 게이트웨이가 모델 이름을 정의하므로 Claude Code는 확인 없이 모든 문자열을 통과시킵니다. 확인은 또한 `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수 또는 `model` 설정을 다루지 않습니다. 잘못 입력된 값은 첫 번째 요청에서 [선택된 모델에 문제가 있습니다](/docs/ko/errors#theres-an-issue-with-the-selected-model)를 생성합니다. Claude Code는 여전히 모든 공급자에서 요청 시간에 [인식되지 않은 모델 진단 라인](/docs/ko/errors#unrecognized-model-id-on-a-request)을 작성할 수 있습니다.174`--model` 플래그, `ANTHROPIC_MODEL` 환경 변수 또는 `model` 설정으로 모델을 설정하면 Claude Code는 미리 확인하지 않으며, 잘못 입력된 값은 첫 번째 요청에서 [선택된 모델에 문제가 있습니다](/docs/ko/errors#theres-an-issue-with-the-selected-model)를 생성합니다.
171 175
172요청된 모델에 예정된 폐기 날짜가 있거나 자동으로 최신 버전으로 다시 매핑되면 Claude Code는 요청된 모델의 이름을 지정하는 경고를 표시합니다. 대화형 세션은 시작 알림으로 표시합니다. v2.1.182부터 기본 텍스트 출력 형식을 사용할 때 [비대화형 모드](/docs/ko/headless)에서 동일한 경고가 stderr에 작성됩니다. 확인은 또한 [서브에이전트 프론트매터](/docs/ko/sub-agents)에 설정된 `model`을 다룹니다. stderr 경고는 `--output-format json` 및 `stream-json`에 대해 억제됩니다. [결과 메시지](/docs/ko/headless#get-structured-output)의 `modelUsage` 필드에서 실제 모델을 읽습니다.176요청된 모델에 예정된 폐기 날짜가 있거나 자동으로 최신 버전으로 다시 매핑되면 Claude Code는 요청된 모델의 이름을 지정하는 경고를 표시합니다. 대화형 세션은 시작 알림으로 표시합니다. v2.1.182부터 기본 텍스트 출력 형식을 사용할 때 [비대화형 모드](/docs/ko/headless)에서 동일한 경고가 stderr에 작성됩니다. 확인은 또한 [서브에이전트 프론트매터](/docs/ko/sub-agents)에 설정된 `model`을 다룹니다. stderr 경고는 `--output-format json` 및 `stream-json`에 대해 억제됩니다. [결과 메시지](/docs/ko/headless#get-structured-output)의 `modelUsage` 필드에서 실제 모델을 읽습니다.
173 177
215 219
216* `default`, `inherit`, `opusplan` 또는 `haiku`로 설정합니다220* `default`, `inherit`, `opusplan` 또는 `haiku`로 설정합니다
217* [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)이 켜져 있습니다221* [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)이 켜져 있습니다
218* [`availableModels`](#restrict-model-selection) 또는 [조직 모델 제한](#organization-model-restrictions)이 모델을 제외합니다222* 조직의 [모델 제한](#restrict-model-selection)이 모델을 제외합니다
219* 모델을 계정에서 사용할 수 없습니다223* 모델을 계정에서 사용할 수 없습니다
220 224
221새 세션이 변수의 모델에서 시작될 때 `claude --resume`, `--continue` 또는 `/resume` 선택기로 재개한 세션도 시작됩니다. Claude Code는 해당 세션의 트랜스크립트에 저장된 모델을 복원하지 않습니다. 그렇지 않으면 Claude Code는 [세션을 재개할 때](#setting-your-model) 변수를 사용하지 않습니다.225새 세션이 변수의 모델에서 시작될 때 `claude --resume`, `--continue` 또는 `/resume` 선택기로 재개한 세션도 시작됩니다. Claude Code는 해당 세션의 트랜스크립트에 저장된 모델을 복원하지 않습니다. 그렇지 않으면 Claude Code는 [세션을 재개할 때](#setting-your-model) 변수를 사용하지 않습니다.
235 모델 선택 제한239 모델 선택 제한
236</h2>240</h2>
237 241
238엔터프라이즈 관리자는 [관리형 또는 정책 설정](/docs/ko/managed-settings)에서 `availableModels`를 사용하여 사용자가 선택할 수 있는 모델을 제한할 수 있습니다. 항목은 `sonnet`과 같은 모델 패밀리, `claude-sonnet-4-5`와 같은 버전 접두사, 또는 `claude-sonnet-4-5-20250929`와 같은 전체 모델 ID와 일치합니다. 버전 접두사는 또한 다른 세그먼트로 확장하는 이후 모델 ID와도 일치하므로, `claude-fable-5`는 Fable 5와 Fable 5.1을 모두 허용하고, `claude-fable-5-1`은 Fable 5.1만 허용합니다. 목록이 허용하는 모델을 차단하거나 각 모델 ID 항목이 이름을 지은 버전만 허용하도록 하려면 [특정 모델 또는 버전 차단](#block-specific-models-or-versions)을 참조하세요.242관리자는 [관리형 또는 정책 설정](/docs/ko/managed-settings)에서 `availableModels`를 사용하여 사용자가 선택할 수 있는 모델을 제한할 수 있습니다. 항목은 `sonnet`과 같은 모델 패밀리, `claude-sonnet-4-5`와 같은 버전 접두사, 또는 `claude-sonnet-4-5-20250929`와 같은 전체 모델 ID와 일치합니다. 버전 접두사는 또한 다른 세그먼트로 확장하는 이후 모델 ID와도 일치하므로, `claude-fable-5`는 Fable 5와 Fable 5.1을 모두 허용하고, `claude-fable-5-1`은 Fable 5.1만 허용합니다. 목록이 허용하는 모델을 차단하거나 각 모델 ID 항목이 이름을 지정하는 버전만 허용하도록 하려면 [특정 모델 또는 버전 차단](#block-specific-models-or-versions)을 참조하세요.
239 243
240Claude Code를 임베드하고 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정하는 플랫폼에서는 호스트의 모델 구성이 관리형 모델 설정보다 우선하며, 관리형 `availableModels` 허용 목록은 호스트가 자체 목록을 제공하지 않는 한 계속 적용됩니다. [관리형 설정 우선순위의 예외](/docs/ko/settings#exceptions-to-managed-settings-precedence)에서 호스트가 재정의하는 키와 변수를 설명합니다.244Claude Code를 포함하고 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정하는 플랫폼에서는 호스트의 모델 구성이 관리형 모델 설정보다 우선하며, 관리형 `availableModels` 허용 목록은 호스트가 자체 목록을 제공하지 않는 한 계속 적용됩니다. [관리형 설정 우선순위의 예외](/docs/ko/settings#exceptions-to-managed-settings-precedence)는 호스트가 재정의하는 키와 변수를 설명합니다.
241 245
242`availableModels`가 설정되면, 허용 목록은 사용자가 모델을 지정할 수 있는 모든 곳에 적용됩니다:246`availableModels`가 설정되면, 허용 목록은 사용자가 모델을 지정할 수 있는 모든 곳에 적용됩니다:
243 247
244* **메인 세션 모델**: `/model`, `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, `model` 설정, [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions), 그리고 [세션을 재개할 때](#setting-your-model) 복원되는 모델248* **메인 세션 모델**: `/model`, `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, `model` 설정, [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions), 그리고 [세션을 재개할 때](#setting-your-model) 복원되는 모델
245* **별칭 해석**: 환경 변수 `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL`은 허용된 별칭을 목록 외부의 모델로 리다이렉트할 수 없습니다249* **별칭 해석**: `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, 그리고 `ANTHROPIC_DEFAULT_FABLE_MODEL` 환경 변수는 허용된 별칭을 목록 외부의 모델로 리디렉션할 수 없습니다
246* **빠른 모드**: 목록 외부의 Opus 모델로 암묵적으로 전환될 경우 `/fast`는 토글을 거부하며, "is not in your organization's allowed models" 메시지를 표시합니다250* **빠른 모드**: `/fast`는 목록 외부의 Opus 모델로 암묵적으로 전환될 때 토글을 거부하며, "is not in your organization's allowed models" 메시지를 표시합니다
247* **서브에이전트 및 팀원 모델**: [서브에이전트](/docs/ko/sub-agents#choose-a-model) 프론트매터의 `model` 필드, Agent 도구의 `model` 파라미터, [에이전트 팀](/docs/ko/agent-teams#specify-teammates-and-models) 팀원 모델, `CLAUDE_CODE_SUBAGENT_MODEL`, 그리고 v2.1.197 이전 버전에서는 `/agents` 마법사의 모델 선택기 251* **서브에이전트 및 팀원 모델**: [서브에이전트](/docs/ko/sub-agents#choose-a-model) 프론트매터의 `model` 필드, Agent 도구의 `model` 매개변수, [에이전트 팀](/docs/ko/agent-teams#specify-teammates-and-models) 팀원 모델, `CLAUDE_CODE_SUBAGENT_MODEL`, 그리고 v2.1.197 이전에는 `/agents` 마법사의 모델 선택기 
248* **스킬 및 명령 모델**: [스킬 및 명령](/docs/ko/skills)의 `model` 프론트매터252* **스킬 및 명령 모델**: [스킬 및 명령](/docs/ko/skills)의 `model` 프론트매터
249* **어드바이저 모델**: 구성된 [`advisorModel`](/docs/ko/advisor) 설정 및 `--advisor` 플래그253* **어드바이저 모델**: 구성된 [`advisorModel`](/docs/ko/advisor) 설정 및 `--advisor` 플래그
250* **백그라운드 에이전트 모델**: [디스패치 선택기](/docs/ko/agent-view)에서 선택된 모델254* **백그라운드 에이전트 모델**: [디스패치 선택기](/docs/ko/agent-view)에서 선택된 모델
251 255
252Anthropic API 및 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)에서 모델 패밀리 별칭 `opus`, `sonnet`, `haiku`, 또는 `fable`은 허용 목록이 해당 모델을 허용할 때 일반적인 모델로 해석됩니다. 허용 목록이 해당 모델을 차단할 때, Claude Code는 허용 목록이 허용하는 패밀리의 최신 버전으로 대체하고 요청된 모델과 대체된 모델을 모두 이름 지어 공지합니다. 예를 들어 `["sonnet", "claude-opus-4-6"]`을 사용하면, `/model opus`와 `--model opus` 모두 허용된 최신 Opus인 Claude Opus 4.6을 선택합니다. v2.1.205 이전에는 최신 릴리스 버전이 목록 외부에 있는 별칭은 목록이 이전 버전을 허용하더라도 다른 차단된 선택처럼 거부되거나 대체되었습니다.256Anthropic API 및 [Claude Platform on AWS](/docs/ko/claude-platform-on-aws)에서, 모델 패밀리 별칭 `opus`, `sonnet`, `haiku`, 또는 `fable`은 허용 목록이 해당 모델을 허용할 때 일반적인 모델로 해석됩니다. 허용 목록이 해당 모델을 차단할 때, Claude Code는 허용 목록이 허용하는 패밀리의 최신 버전으로 대체하고 요청된 모델과 대체된 모델을 모두 이름 지정하는 알림을 표시합니다. 예를 들어 `["sonnet", "claude-opus-4-6"]`을 사용하면, `/model opus`와 `--model opus` 모두 허용된 최신 Opus인 Claude Opus 4.6을 선택합니다. v2.1.205 이전에는 최신 릴리스 버전이 목록 외부에 있는 별칭은 목록이 이전 버전을 허용했을 때도 다른 차단된 선택처럼 거부되거나 대체되었습니다.
253 257
254대체는 허용된 버전이 필요합니다: 허용 목록이 별칭의 패밀리 버전을 허용하지 않으면, 별칭은 다른 차단된 값처럼 아래의 거부 및 대체 동작을 따릅니다.258대체는 착지할 수 있는 허용된 버전이 필요합니다: 허용 목록이 별칭의 패밀리의 버전을 허용하지 않을 때, 별칭은 다른 차단된 값처럼 아래의 거부 및 대체 동작을 따릅니다.
255 259
256Claude Code는 모델이 설정된 위치에 따라 다른 차단된 선택을 처리합니다:260Claude Code는 모델이 설정된 위치에 따라 다른 차단된 선택을 처리합니다:
257 261
258* **`/model`**: Claude Code는 오류로 전환을 거부합니다262* **`/model`**: Claude Code는 스위치를 오류로 거부합니다
259* **`--model` 플래그, `ANTHROPIC_MODEL`, 또는 `model` 설정**: Claude Code는 시작 시 값을 경고와 함께 요청된 모델과 대체된 모델을 모두 이름 지어 대체하며, 세션은 기본 모델에서 시작됩니다263* **`--model` 플래그, `ANTHROPIC_MODEL`, 또는 `model` 설정**: Claude Code는 시작 시 값을 요청된 모델과 대체된 모델을 모두 이름 지정하는 경고와 함께 대체하고, 세션은 기본 모델에서 시작됩니다
260* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**: Claude Code는 변수를 무시합니다264* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**: Claude Code는 변수를 무시합니다
261* **서브에이전트 또는 팀원 재정의**: Claude Code는 요청을 실패하지 않고 서브에이전트 또는 팀원을 폴백 모델에서 실행합니다. 서브에이전트 폴백은 [모델 선택](/docs/ko/sub-agents#choose-a-model)을 참조하고 팀원 폴백은 [팀원 및 모델 지정](/docs/ko/agent-teams#specify-teammates-and-models)을 참조하세요.265* **서브에이전트 또는 팀원 재정의**: Claude Code는 요청을 실패하지 않고 서브에이전트 또는 팀원을 폴백 모델에서 실행합니다. 서브에이전트 폴백은 [모델 선택](/docs/ko/sub-agents#choose-a-model)을 참조하고 팀원 폴백은 [팀원 및 모델 지정](/docs/ko/agent-teams#specify-teammates-and-models)을 참조하세요.
262 266
263 대화형 세션에서, Claude Code는 요청된 모델과 대체된 모델을 이름 지어 이 폴백 또는 위의 최신 허용 버전 대체로 서브에이전트의 모델을 대체할 때 경고합니다. 팀원의 폴백은 보고하지 않습니다.267 대화형 세션에서, Claude Code는 이 폴백 또는 위의 최신 허용 버전 대체로 서브에이전트의 모델을 대체할 때 요청된 모델과 대체된 모델을 이름 지정하여 경고합니다. 팀원의 폴백은 보고하지 않습니다.
264 268
265 위의 최신 허용 버전 대체가 작동하는 경우, 차단된 패밀리 별칭이 대신 따릅니다. v2.1.222 이전에는 별칭이 모든 제공자에서 다른 차단된 값처럼 폴백했습니다269 위의 최신 허용 버전 대체가 작동하는 경우, 차단된 패밀리 별칭은 대신 이를 따릅니다. v2.1.222 이전에는 별칭이 모든 제공자에서 다른 차단된 값처럼 폴백했습니다
266* **스킬 또는 명령 재정의**: Claude Code는 차단된 패밀리 별칭을 포함한 재정의를 무시하고, 스킬 또는 명령은 세션 모델에서 실행됩니다. [서브에이전트에서 실행되는](/docs/ko/skills#run-skills-in-a-subagent) 스킬 또는 명령은 대신 위의 서브에이전트 동작을 따릅니다270* **스킬 또는 명령 재정의**: Claude Code는 차단된 패밀리 별칭을 포함한 재정의를 무시하고, 스킬 또는 명령은 세션 모델에서 실행됩니다. [서브에이전트에서 실행되는](/docs/ko/skills#run-skills-in-a-subagent) 스킬 또는 명령은 대신 위의 서브에이전트 동작을 따릅니다
267* **`advisorModel` 설정**: 어드바이저는 세션에 대해 비활성화됩니다271* **`advisorModel` 설정**: 어드바이저는 세션에 대해 비활성화됩니다
268* **`--advisor` 플래그**: Claude Code는 시작 시 오류로 종료됩니다. [백그라운드 세션](/docs/ko/agent-view)에서는 종료하지 않고 어드바이저 없이 세션을 시작합니다272* **`--advisor` 플래그**: Claude Code는 시작 시 오류로 종료됩니다. [백그라운드 세션](/docs/ko/agent-view)에서는 종료하지 않고 어드바이저 없이 세션을 시작합니다
291 295
292| 전달 메커니즘 | CLI 및 IDE | 데스크톱 로컬 세션 | 웹, 모바일 및 클라우드 세션 | Agent SDK 및 비대화형 | Cowork |296| 전달 메커니즘 | CLI 및 IDE | 데스크톱 로컬 세션 | 웹, 모바일 및 클라우드 세션 | Agent SDK 및 비대화형 | Cowork |
293| :- | :- | :- | :- | :- | :- |297| :- | :- | :- | :- | :- | :- |
294| 관리 콘솔의 [서버 관리 설정](/docs/ko/server-managed-settings) | 적용됨 | 적용됨 | 적용됨 | 적용됨 | 전달되지 않음 |298| 관리 콘솔의 [서버 관리 설정](/docs/ko/server-managed-settings) | 적용됨 | 적용됨 | [Claude Tag](https://claude.com/docs/claude-tag/overview) 세션을 제외하고 적용됨 | 적용됨 | 원격 Cowork 세션: 서버가 모델을 확인합니다. 사용자의 머신에서: 전달되지 않음. |
295| [MDM 또는 관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms) | 적용됨 | 적용됨 | Anthropic 호스팅 환경에서는 전달되지 않음. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서는 [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에 따라 러너 이미지에서 적용됨 | 적용됨 | 배포된 경우 적용됨 |299| [MDM 또는 관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms) | 적용됨 | 적용됨 | Anthropic 호스팅 환경에서는 전달되지 않음. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서는 [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에 따라 러너 이미지에서 적용됨 | 적용됨 | 배포된 경우 적용됨 |
296 300
297* 클라우드 세션은 [Claude Code on the web](/docs/ko/claude-code-on-the-web) 또는 Desktop 앱에서 기본적으로 Anthropic 관리 VM에서 실행됩니다: 장치에 배포된 설정은 이에 도달하지 않으므로, 서버 관리 설정을 통해 허용 목록을 전달하세요. 조직이 [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로 라우팅하는 세션은 자신의 컴퓨팅에서 실행되며 러너 이미지의 관리형 설정 파일도 읽습니다. [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에서 해당 파일이 적용되는 시기를 설명합니다. 클라우드 세션의 중간 세션 모델 전환은 요청된 모델이 허용 목록에 의해 제외될 때 거부됩니다. 서버 관리 설정의 `availableModels` 목록이 비어있지 않으면, 서버는 목록이 제외하는 모델에서 클라우드 세션을 시작하려는 사용자의 요청을 거부합니다.301* [클라우드 세션](/docs/ko/claude-code-on-the-web)(데스크톱 앱에서 시작하는 세션 포함)은 기본적으로 Anthropic 관리 VM에서 실행됩니다: 장치에 배포된 설정은 이에 도달하지 않으므로, 서버 관리 설정을 통해 허용 목록을 전달합니다. 조직이 [자체 호스팅 환경](/docs/ko/self-hosted-environments)으로 라우팅하는 세션은 자신의 컴퓨팅에서 실행되고 러너 이미지의 관리형 설정 파일도 읽습니다. [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 해당 파일이 언제 적용되는지 설명합니다. 클라우드 세션의 중간 세션 모델 전환은 요청된 모델이 허용 목록에 의해 제외될 때 거부됩니다. 서버 관리 설정의 `availableModels` 목록이 비어있지 않을 때, 서버는 목록이 제외하는 모델에서 claude.ai/code 또는 데스크톱 앱에서 클라우드 세션을 시작하도록 요청하는 것을 거부합니다.
298* Cowork는 Claude Desktop 앱의 에이전트 작업 탭이며, 설계상 claude.ai 관리 콘솔에서 서버 관리 설정을 수신하지 않습니다. 관리형 설정 파일은 세션이 실행되는 위치에 있을 때 Cowork 세션에 적용됩니다. 원격 Cowork 세션은 Anthropic 관리 VM에서 실행되며, 여기서 장치 배포 파일은 없습니다.302* [Claude Tag](https://claude.com/docs/claude-tag/overview) 세션은 클라우드 환경에서 실행되지만 서버 관리 설정을 수신하지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서는 여전히 러너 이미지의 관리형 설정 파일을 읽습니다. 이러한 세션의 모델을 설정하려면 Claude Tag 관리자 가이드의 [범위에 대한 모델 선택](https://claude.com/docs/claude-tag/admins/customize#choose-the-model-for-a-scope)을 참조하세요.
299* [Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 그리고 Claude Platform on AWS](/docs/ko/claude-platform-on-aws)와 같은 [제3자 제공자](/docs/ko/server-managed-settings#platform-availability)의 세션은 서버 관리 설정을 수신하지 않으므로, 거기서 MDM 또는 관리형 설정 파일을 통해 허용 목록을 전달하세요.303* Cowork(Claude 데스크톱 앱의 에이전트 작업 탭)는 Claude Code에서 세션을 실행하지만, 설계상 claude.ai 관리 콘솔에서 서버 관리 설정을 수신하지 않습니다. 서버 관리 설정의 `availableModels` 목록이 비어있지 않고 사용자가 목록 외부의 모델을 선택하면, 서버는 원격 Cowork 세션에 대해 해당 모델을 거부합니다. 관리형 설정 파일은 세션이 실행되는 위치에 있을 때 Cowork 세션에 적용됩니다. 원격 Cowork 세션은 Anthropic 관리 VM에서 실행되며, 여기서 장치 배포 파일은 없습니다.
304* [Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 그리고 Claude Platform on AWS](/docs/ko/claude-platform-on-aws)와 같은 [제3자 제공자](/docs/ko/server-managed-settings#platform-availability)의 세션은 서버 관리 설정을 수신하지 않으므로, 허용 목록을 MDM 또는 관리형 설정 파일을 통해 전달합니다.
300* 서버 관리 전달은 또한 세션이 [적격 로그인 또는 키](/docs/ko/server-managed-settings#platform-availability)로 인증하도록 요구합니다. [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트를 통해서만 키를 생성하는 플릿은 MDM 또는 관리형 설정 파일을 통해 허용 목록을 전달해야 합니다.305* 서버 관리 전달은 또한 세션이 [적격 로그인 또는 키](/docs/ko/server-managed-settings#platform-availability)로 인증하도록 요구합니다. [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper) 스크립트를 통해서만 키를 생성하는 플릿은 MDM 또는 관리형 설정 파일을 통해 허용 목록을 전달해야 합니다.
301* Desktop Code 탭은 또한 [SSH 세션](/docs/ko/desktop#ssh-sessions)을 호스팅하며, 이는 실행되는 원격 호스트에서 관리형 설정 파일을 읽습니다. [Desktop 관리형 설정](/docs/ko/desktop#managed-settings)을 참조하세요.306* 데스크톱 Code 탭은 또한 [SSH 세션](/docs/ko/desktop#ssh-sessions)을 호스팅하며, 이는 실행되는 원격 호스트에서 관리형 설정 파일을 읽습니다. [데스크톱 관리형 설정](/docs/ko/desktop#managed-settings)을 참조하세요.
302* claude.ai 및 Desktop 앱의 모델 선택기는 조직의 허용 목록에 의해 제외된 모델을 숨기거나 회색으로 표시합니다. 선택기 상태는 사용자를 위한 편의이며, 허용 목록을 적용하지 않습니다.307* claude.ai 및 데스크톱 앱의 모델 선택기는 조직의 허용 목록에 의해 제외된 모델을 숨기거나 회색으로 표시합니다. 선택기 상태는 사용자를 위한 편의입니다. 허용 목록을 적용하지 않습니다.
303 308
304<h3 id="default-model-behavior">309<h3 id="default-model-behavior">
305 기본 모델 동작310 기본 모델 동작
306</h3>311</h3>
307 312
308자체적으로, `availableModels`는 기본 옵션을 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)도 설정할 때까지 계정의 [런타임 기본값](#default-model-setting)에 남겨둡니다. 해당 기본값이 제한하려는 모델인 경우, `enforceAvailableModels`도 설정하거나 [해당 모델을 차단](#block-specific-models-or-versions)하세요.313기본 접두사 일치를 사용하면, `availableModels` 자체는 Default 옵션을 시스템의 [런타임 기본값](#default-model-setting)에 남겨두고, [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)도 설정할 때까지 계정에 대해 남겨둡니다. 해당 기본값이 제한하려는 모델인 경우, `enforceAvailableModels`도 설정하거나 [해당 모델을 차단](#block-specific-models-or-versions)하세요.
309 314
310`availableModels: []`을 사용하면, 명명된 모델 선택은 차단되지만 `enforceAvailableModels`는 효과가 없습니다.315`availableModels: []`를 사용하면, 명명된 모델 선택은 차단되고 `enforceAvailableModels`는 효과가 없습니다.
311 316
312<h3 id="enforce-the-allowlist-for-the-default-model">317<h3 id="enforce-the-allowlist-for-the-default-model">
313 기본 모델에 대한 허용 목록 적용318 Default 모델에 대한 허용 목록 적용
314</h3>319</h3>
315 320
316관리형 설정에서 비어있지 않은 `availableModels`와 함께 `enforceAvailableModels: true`를 설정하여 허용 목록을 기본 옵션으로 확장합니다. 이는 Claude Code v2.1.175 이상이 필요합니다.321관리형 설정에서 비어있지 않은 `availableModels`와 함께 `enforceAvailableModels: true`를 설정하여 허용 목록을 Default 옵션으로 확장합니다. 이는 Claude Code v2.1.175 이상이 필요합니다.
317 322
318```json theme={null}323```json theme={null}
319{324{
322}327}
323```328```
324 329
325기본 옵션은 계정 유형 기본값으로 해석되거나, 관리자가 설정한 경우 [조직 기본 모델](#organization-default-model)로 해석됩니다. 해당 모델이 허용 목록에 없으면, 기본 옵션은 대신 허용되고 사용 가능한 모델을 이름 지어 첫 번째 `availableModels` 항목으로 해석되며, `/model` 선택기의 기본 행은 해당 모델을 표시합니다. 이는 기본값에 도달하는 모든 곳에 적용됩니다: 세션 시작, `/model`에서 기본값 선택, [폴백 모델 체인](#fallback-model-chains)의 `"default"` 키워드, 그리고 제외된 선택이 삭제될 때 사용되는 폴백.330계정에 [기록된](#setting-your-model) 모델이 없는 멤버의 경우, Default 옵션은 계정 유형 기본값으로 해석되거나, 관리자가 설정한 경우 [조직 기본 모델](#organization-default-model)로 해석됩니다. 해당 모델이 허용 목록에 없을 때, Default 옵션은 대신 허용되고 사용 가능한 모델을 이름 지정하는 첫 번째 `availableModels` 항목으로 해석되고, `/model` 선택기의 Default 행은 해당 모델을 표시합니다. 이는 Default에 도달하는 모든 곳에 적용됩니다: 세션 시작, `/model`에서 Default 선택, [폴백 모델 체인](#fallback-model-chains)의 `"default"` 키워드, 그리고 제외된 선택이 삭제될 때 사용되는 폴백. 멤버의 계정에 기록된 모델도 `availableModels`에 대해 확인됩니다. [모델 설정](#setting-your-model)은 Default 옵션이 이를 처리하는 방식을 설명합니다.
326 331
327`enforceAvailableModels`는 `availableModels`가 비어있지 않을 때만 기본 옵션을 다시 매핑합니다. `availableModels`가 비어있지 않지만 허용되고 사용 가능한 모델을 이름 지어 항목이 없으면, 적용이 건너뛰어지고 `--debug` 아래에서만 표시되는 경고가 있습니다. 이를 피하려면 목록에 최소한 하나의 보장된 사용 가능 항목을 유지하세요.332`enforceAvailableModels`는 `availableModels`가 비어있지 않을 때만 Default 옵션을 다시 매핑합니다. `availableModels`가 비어있지 않지만 어떤 항목도 허용되고 사용 가능한 모델로 해석되지 않을 때, 적용은 `--debug` 아래에서만 볼 수 있는 경고와 함께 건너뜁니다. 이를 피하려면 목록에 최소한 하나의 보장된 사용 가능 항목을 유지하세요.
328 333
329전달하는 최상위 순위 관리형 소스에 두 키를 함께 배포하세요. 기본적으로 Claude Code는 해당 소스만 읽으므로, 관리형 설정 파일에 배치된 쌍은 관리 콘솔이 설정을 전달할 때 무시됩니다. [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)의 옵트인 병합에서, Claude Code는 여전히 `availableModels`를 설정하는 소스 아래에 순위가 지정된 소스의 `modelOverrides` 맵을 무시합니다.334전달하는 최상위 순위 관리형 소스에 두 키를 함께 배포합니다. 기본적으로 Claude Code는 해당 소스만 읽으므로, 관리형 설정 파일에 배치된 쌍은 관리 콘솔이 설정을 전달할 때 무시됩니다. [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)의 선택적 병합에서, Claude Code는 여전히 `availableModels`를 설정하는 소스 아래에 순위가 지정된 소스의 `modelOverrides` 맵을 무시합니다.
330 335
331<h3 id="control-the-model-users-run-on">336<h3 id="control-the-model-users-run-on">
332 사용자가 실행하는 모델 제어337 사용자가 실행하는 모델 제어
333</h3>338</h3>
334 339
335`model` 설정은 초기 선택이지, 적용이 아닙니다. 세션이 시작될 때 활성 모델을 설정하지만, 사용자는 여전히 `/model`을 열고 기본값을 선택할 수 있으며, 이는 `model`이 설정된 것에 관계없이 시스템의 [런타임 기본값](#default-model-setting)으로 해석됩니다. [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)가 이를 리다이렉트하지 않는 한.340`model` 설정은 초기 선택이지, 적용이 아닙니다. 세션이 시작될 때 활성 모델을 설정하지만, 사용자는 여전히 `/model`을 열고 Default를 선택할 수 있으며, 이는 `model`이 설정된 것과 관계없이 시스템의 [런타임 기본값](#default-model-setting)으로 해석됩니다. [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 또는 [특정 버전을 차단하는 키](#block-specific-models-or-versions)가 이에 적용되지 않는 한.
336 341
337모델 경험을 완전히 제어하려면 이러한 설정을 결합하세요:342모델 경험을 완전히 제어하려면 이러한 설정을 결합하세요:
338 343
339* **`availableModels`**: 사용자가 전환할 수 있는 명명된 모델을 제한합니다344* **`availableModels`**: 사용자가 전환할 수 있는 명명된 모델을 제한합니다
340* **`enforceAvailableModels`**: `availableModels` 허용 목록을 기본 옵션으로 확장하므로 기본값은 목록 외부의 모델로 해석될 수 없습니다345* **`enforceAvailableModels`**: `availableModels` 허용 목록을 Default 옵션으로 확장하므로 Default는 목록 외부의 모델로 해석될 수 없습니다
341* **`deniedModels`** 및 **`availableModelsMatch`**: [특정 버전을 차단](#block-specific-models-or-versions)하여 `availableModels` 항목이 허용할 수 있는 것을 차단합니다346* **`deniedModels`** 및 **`availableModelsMatch`**: [특정 버전을 차단](#block-specific-models-or-versions)하여 `availableModels` 항목이 허용할 수 있습니다
342* **`model`**: 세션이 시작될 때 초기 모델 선택을 설정합니다347* **`model`**: 세션이 시작될 때 초기 모델 선택을 설정합니다
343* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**: `sonnet`, `opus`, `haiku`, 그리고 `fable` 별칭이 해석되는 것을 제어하고, [계정 유형 기본값](#default-model-setting)이 사용하는 버전을 제어합니다348* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**: `sonnet`, `opus`, `haiku`, 그리고 `fable` 별칭이 해석되는 것을 제어하고, [계정 유형 기본값](#default-model-setting)이 사용하는 버전을 제어합니다
344 349
345이 예제는 사용자를 Sonnet 4.5에서 시작하고, 선택기를 Sonnet 및 Haiku로 제한하며, 기본값이 계층 기본값이 아닌 허용 목록의 모델로 해석되도록 합니다:350이 예제는 사용자를 Sonnet 4.5에서 시작하고, 선택기를 Sonnet 및 Haiku로 제한하고, Default가 계층 기본값이 아닌 허용 목록의 모델로 해석되도록 합니다:
346 351
347```json theme={null}352```json theme={null}
348{353{
355}360}
356```361```
357 362
358`enforceAvailableModels` 또는 `env` 블록이 없으면, 선택기에서 기본값을 선택하는 사용자는 `model`에 고정된 버전이 아닌 [런타임 기본값](#default-model-setting)을 얻습니다. 두 설정은 다른 범위를 다룹니다: `enforceAvailableModels`는 기본값이 허용 목록을 따르도록 하고, `env` 블록은 `sonnet`과 같은 허용된 별칭이 해석되는 버전을 고정합니다. 모델 패밀리 제한이 충분할 때 `enforceAvailableModels`만 사용하세요. 특정 버전을 고정해야 할 때도 `env` 블록을 추가하세요.363`enforceAvailableModels` 또는 `env` 블록이 없으면, 선택기에서 Default를 선택하는 사용자는 `model`에 고정된 버전이 아닌 [런타임 기본값](#default-model-setting)을 얻습니다. 두 설정은 다른 범위를 다룹니다: `enforceAvailableModels`는 Default가 허용 목록을 따르도록 하고, `env` 블록은 `sonnet`과 같은 허용된 별칭이 해석되는 버전을 고정합니다. 모델 패밀리 제한이 충분할 때 `enforceAvailableModels`만 사용하세요. 특정 버전을 고정해야 할 때도 `env` 블록을 추가하세요.
359 364
360<h3 id="merge-behavior">365<h3 id="merge-behavior">
361 병합 동작366 병합 동작
362</h3>367</h3>
363 368
364Claude Code가 적용하는 관리형 설정이 `availableModels`를 정의하면, [자체 목록을 제공하는 호스트 플랫폼](/docs/ko/settings#exceptions-to-managed-settings-precedence)을 제외하고 해당 목록만 적용됩니다: 사용자, 프로젝트 또는 로컬 설정의 항목은 이를 확장할 수 없으며, Claude Code는 관리형 소스 간에 `availableModels`를 병합하지 않습니다. [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에서 어느 소스의 목록이 적용되는지 설명합니다. 그렇지 않으면, 사용자, 프로젝트 및 로컬 설정의 목록은 다른 배열 설정처럼 [연결되고 중복 제거됩니다](/docs/ko/settings#settings-precedence). Claude Code v2.1.175 이전에는, 낮은 우선순위 범위의 항목이 관리형 목록으로 대체되지 않고 병합되었습니다.369Claude Code가 적용하는 관리형 설정이 `availableModels`를 정의할 때, 해당 목록만 적용됩니다. [자체 목록을 제공하는 호스트 플랫폼](/docs/ko/settings#exceptions-to-managed-settings-precedence) 제외: 사용자, 프로젝트 또는 로컬 설정의 항목은 이를 확장할 수 없고, Claude Code는 관리형 소스 전체에서 `availableModels`를 병합하지 않습니다. [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 어느 소스의 목록이 적용되는지 설명합니다. 그렇지 않으면, 사용자, 프로젝트 및 로컬 설정의 목록은 다른 배열 설정처럼 [연결되고 중복 제거됩니다](/docs/ko/settings#settings-precedence). Claude Code v2.1.175 이전에는 하위 우선순위 범위의 항목이 관리형 목록으로 병합되었습니다.
365 370
366유효한 목록 내에서, 패밀리의 특정 모델을 이름 지어 항목(버전 접두사 또는 전체 모델 ID 여부)은 해당 패밀리의 와일드카드 항목을 비활성화합니다: `["sonnet", "claude-sonnet-4-5"]`는 모든 Sonnet 모델이 아닌 Sonnet 4.5 버전만 허용합니다.371유효한 목록 내에서, 패밀리의 특정 모델을 이름 지정하는 항목(버전 접두사 또는 전체 모델 ID 여부)은 해당 패밀리의 와일드카드 항목을 비활성화합니다: `["sonnet", "claude-sonnet-4-5"]`는 모든 Sonnet 모델이 아닌 Sonnet 4.5 버전만 허용합니다.
367 372
368<h3 id="mantle-model-ids">373<h3 id="mantle-model-ids">
369 Mantle 모델 ID374 Mantle 모델 ID
370</h3>375</h3>
371 376
372[Amazon Bedrock Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)가 활성화되면, `availableModels`의 항목 중 `anthropic.`으로 시작하는 항목은 `/model` 선택기에 사용자 정의 옵션으로 추가되고 Mantle 엔드포인트로 라우팅됩니다. 이는 [제3자 배포를 위한 모델 고정](#pin-models-for-third-party-deployments)에서 설명한 별칭 일치의 예외입니다. 설정은 여전히 선택기를 나열된 항목으로 제한하며, Mantle ID는 패밀리 이름을 포함하므로, 특정 항목으로 계산되고 해당 패밀리의 와일드카드를 비활성화합니다: 모든 Mantle ID와 함께, 유지하려는 버전 접두사 또는 전체 ID를 나열하세요. [병합 동작](#merge-behavior)을 참조하세요.377[Amazon Bedrock Mantle 엔드포인트](/docs/ko/amazon-bedrock#use-the-mantle-endpoint)가 활성화되면, `availableModels`의 항목 중 `anthropic.`으로 시작하는 항목은 `/model` 선택기에 사용자 정의 옵션으로 추가되고 Mantle 엔드포인트로 라우팅됩니다. 이는 [제3자 배포를 위한 모델 고정](#pin-models-for-third-party-deployments)에 설명된 별칭 일치에 대한 예외입니다. 설정은 여전히 선택기를 나열된 항목으로 제한하고, Mantle ID는 패밀리 이름을 포함하므로, 특정 항목으로 계산되고 해당 패밀리의 와일드카드를 비활성화합니다: Mantle ID와 함께, 유지하려는 버전 접두사 또는 전체 ID를 나열하세요. [병합 동작](#merge-behavior)을 참조하세요.
373 378
374<h3 id="block-specific-models-or-versions">379<h3 id="block-specific-models-or-versions">
375 특정 모델 또는 버전 차단380 특정 모델 또는 버전 차단
376</h3>381</h3>
377 382
378`claude-opus-5`와 같은 `availableModels` 항목은 또한 Claude Code가 이를 지원하는 즉시 Opus 5.5와 같은 이를 확장하는 이후 릴리스도 허용합니다. 두 개의 관리형 설정을 사용하면 릴리스를 보류할 수 있으며, 둘 다 Claude Code v2.1.283 이상이 필요합니다:383`claude-opus-5`와 같은 `availableModels` 항목은 또한 Claude Code가 이를 지원하는 즉시 Opus 5.5와 같은 이를 확장하는 이후 릴리스를 허용합니다. 두 관리형 설정을 사용하면 릴리스를 보류할 수 있으며, 둘 다 Claude Code v2.1.283 이상이 필요합니다:
379 384
380* [`deniedModels`](/docs/ko/settings-reference#deniedmodels): 차단할 모델을 나열합니다. 나열된 모델은 `availableModels`가 이를 허용하더라도 차단되며, 키는 허용 목록이 없어도 작동합니다. 항목이 차단하지 않는 릴리스는 허용된 상태로 유지됩니다385* [`deniedModels`](/docs/ko/settings-reference#deniedmodels): 차단할 모델을 나열합니다. 나열된 모델은 `availableModels`가 이를 허용하더라도 차단되고, 키는 허용 목록이 없어도 작동합니다. 어떤 항목도 차단하지 않는 릴리스는 허용됩니다
381* [`availableModelsMatch`](/docs/ko/settings-reference#availablemodelsmatch): 이를 `"exact"`로 설정하여 `availableModels`의 각 모델 ID가 이름을 지은 버전만 허용하도록 합니다. 나열된 모델 ID의 최신 버전은 목록에 추가할 때까지 차단된 상태로 유지됩니다386* [`availableModelsMatch`](/docs/ko/settings-reference#availablemodelsmatch): 이를 `"exact"`로 설정하여 `availableModels`의 각 모델 ID가 이름을 지정하는 버전만 허용하도록 합니다. 나열된 모델 ID의 최신 버전은 목록에 추가할 때까지 차단된 상태로 유지됩니다
382 387
383이전 버전은 두 키를 모두 무시하므로, 이러한 버전이 시작되지 않도록 [`requiredMinimumVersion`](/docs/ko/settings-reference#requiredminimumversion)도 설정하세요.388이전 버전은 두 키를 모두 무시하므로, 이러한 버전이 시작되지 않도록 [`requiredMinimumVersion`](/docs/ko/settings-reference#requiredminimumversion)도 설정하세요.
384 389
385이 예제는 Opus 및 Sonnet 모델을 허용하고 날짜 지정 및 제공자별 ID를 포함한 모든 철자로 Opus 5.5를 차단합니다:390이 예제는 Opus 및 Sonnet 모델을 허용하고 날짜 및 제공자별 ID를 포함한 모든 철자로 Opus 5.5를 차단합니다:
386 391
387```json theme={null}392```json theme={null}
388{393{
391}396}
392```397```
393 398
394차단된 모델(whether `deniedModels`가 이름을 지었거나 `"exact"` 목록이 이를 생략했는지)은 [허용 목록이 적용되는](#restrict-model-selection) 모든 곳에서 차단된 선택으로 처리됩니다. 이는 `/model` 선택기에서 숨겨지며, `/model <name>`은 이를 거부합니다. `--model`, `ANTHROPIC_MODEL`, 또는 `model` 설정으로 차단된 모델 ID를 이름 지으면, Claude Code는 시작 시 이를 삭제하고 기본 옵션을 대신 해석합니다. [훅](/docs/ko/hooks) 또는 백그라운드 요청이 `deniedModels`가 차단하는 모델(예: 에이전트 훅의 `model` 필드)을 이름 지으면, 해당 요청은 세션의 모델에서 대신 실행됩니다.399차단된 모델(whether `deniedModels`가 이름을 지정하거나 `"exact"` 목록이 이를 생략)은 [허용 목록이 적용되는](#restrict-model-selection) 모든 곳에서 차단된 선택으로 처리됩니다. `/model` 선택기에서 숨겨지고, `/model <name>`은 이를 거부합니다. `--model`, `ANTHROPIC_MODEL`, 또는 `model` 설정으로 차단된 모델 ID를 이름 지정하면, Claude Code는 시작 시 이를 삭제하고 Default 옵션을 해석합니다. [훅](/docs/ko/hooks) 또는 백그라운드 요청이 `deniedModels`가 차단하는 모델(예: 에이전트 훅의 `model` 필드)을 이름 지정하면, 해당 요청은 세션의 모델에서 대신 실행됩니다.
395 400
396기본 옵션은 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)를 설정했는지 여부에 관계없이 두 키를 모두 따릅니다. 비어있지 않은 `availableModels`로 설정하면, 차단된 기본값은 허용 목록 외부의 모델로 계산됩니다. 그렇지 않으면, 차단된 모델로 해석될 기본 옵션은 이 순서로 단계적으로 내려갑니다:401Default 옵션은 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)를 설정했는지 여부와 관계없이 두 키를 모두 따릅니다. 비어있지 않은 `availableModels`로 설정하면, 차단된 기본값은 허용 목록 외부의 모델로 계산됩니다. 그렇지 않으면, 차단된 모델로 해석될 Default 옵션은 이 순서로 단계적으로 내려갑니다:
397 402
3981. 동일한 패밀리의 최신 허용 버전4031. 동일한 패밀리의 최신 허용 버전
3992. 각 낮은 비용 패밀리의 최신 허용 모델(순서대로): Sonnet, 그 다음 Haiku4042. 각 하위 비용 패밀리의 최신 허용 모델: Sonnet, 그 다음 Haiku
4003. 허용된 모델을 이름 지어 첫 번째 `availableModels` 항목4053. 허용된 모델을 이름 지정하는 첫 번째 `availableModels` 항목
401 406
402이 중 어느 것도 허용되지 않으면, 기본 옵션에서 시작하는 세션은 수정할 키를 이름 지어 [오류로 시작을 거부](/docs/ko/errors#managed-settings-block-the-default-model)합니다. `"exact"` 목록은 관리형 `availableModels` 목록이 최소한 하나의 모델 또는 패밀리를 이름 지을 때만 기본 옵션에 영향을 미칩니다.407이 중 어느 것도 허용되지 않으면, Default 옵션에서 시작하는 세션은 [시작을 거부](/docs/ko/errors#managed-settings-block-the-default-model)하고 수정할 키를 이름 지정하는 오류가 발생합니다. `"exact"` 목록은 관리형 `availableModels` 목록이 최소한 하나의 모델 또는 패밀리를 이름 지정할 때만 Default 옵션에 영향을 미칩니다.
403 408
404Claude Code는 관리형 설정에서만 두 키를 읽습니다. 사용자, 프로젝트, 로컬 설정 또는 `--settings`에서 이 중 하나를 설정하면, Claude Code는 경고와 함께 이를 무시합니다.409Claude Code는 관리형 설정에서만 두 키를 읽습니다. 사용자, 프로젝트 또는 로컬 설정이나 `--settings`로 둘 중 하나를 설정하면, Claude Code는 경고와 함께 이를 무시합니다.
405 410
406<h3 id="organization-model-restrictions">411<h3 id="organization-model-restrictions">
407 조직 모델 제한412 조직 모델 제한
408</h3>413</h3>
409 414
410Claude Enterprise 플랜의 조직 관리자는 claude.ai 관리 콘솔에서 개별 모델을 비활성화하여 멤버가 실행할 수 있는 모델을 제한합니다. 이 제한은 Claude Code가 인증할 때 계정의 자격과 함께 전달되며, 설정의 `availableModels` 목록과 별개이고, 서버는 세션이 생성될 때 동일한 제한을 독립적으로 적용합니다. Claude Code v2.1.187 이상이 필요합니다.415Claude Enterprise 플랜의 조직 관리자는 claude.ai 관리 콘솔에서 개별 모델을 비활성화하여 멤버가 실행할 수 있는 모델을 제한합니다. 이 제한은 설정의 `availableModels` 목록과 별도로 계정의 자격과 함께 전달되고, 서버는 세션이 생성될 때 동일한 제한을 독립적으로 적용합니다. Claude Code v2.1.187 이상 필요합니다.
411 416
412제한은 멤버가 로그인하거나 자신의 API 키를 사용할 때 적용됩니다. 조직 서비스 키와 같은 조직 범위 자격증명은 사용자와 연결되지 않으므로, 제한이 이에 적용되지 않습니다.417제한은 멤버가 로그인하거나 자신의 API 키를 사용할 때 적용됩니다. 조직 서비스 키와 같은 조직 범위 자격은 사용자와 연결되지 않으므로, 제한이 이에 적용되지 않습니다.
413 418
414Claude Console에는 모델 제한 제어가 없습니다. Claude Enterprise 플랜이 없는 조직(Anthropic API를 통해 인증하는 멤버를 포함한 조직)은 대신 [관리형 설정](/docs/ko/managed-settings)에서 [`availableModels`](#restrict-model-selection)로 모델을 제한하며, [기본 모델에 대한 허용 목록 적용](#enforce-the-allowlist-for-the-default-model)을 추가하여 기본 옵션을 다룹니다. [표면 범위](#surface-coverage)에서 각 표면이 이러한 설정을 수신하고 적용하는 방식을 설명합니다.419Claude Console에는 모델 제한 제어가 없습니다. Claude Enterprise 플랜이 없는 조직(Anthropic API를 통해 인증하는 멤버를 포함)은 [관리형 설정](/docs/ko/managed-settings)에서 [`availableModels`](#restrict-model-selection)로 모델을 제한하고, Default 옵션을 다루기 위해 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)를 추가합니다. [표면 범위](#surface-coverage)는 각 표면이 이러한 설정을 수신하고 적용하는 방식을 설명합니다.
415 420
416제한된 모델은 `/model` 선택기에서 숨겨집니다. `--model`, `ANTHROPIC_MODEL` 환경 변수, 또는 `model` 설정으로 이름으로 선택하면 공지 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`를 표시하고 세션은 허용된 모델에서 시작됩니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.421제한된 모델은 `/model` 선택기에서 숨겨집니다. `--model`, `ANTHROPIC_MODEL` 환경 변수, 또는 `model` 설정으로 이름으로 선택하면 `Model "<name>" is restricted by your organization's settings. Using <model> instead.` 알림을 표시하고 세션은 허용된 모델에서 시작됩니다. 제한된 모델에 대해 `/model <name>`을 입력하면 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`로 거부되고 세션은 현재 모델을 유지합니다.
417 422
418`opus`와 같은 [모델 패밀리 별칭](#restrict-model-selection)은 조직이 이를 허용할 때 일반적인 모델로 해석됩니다. 조직이 해당 모델을 제한할 때, Claude Code는 조직이 허용하는 패밀리의 최신 버전으로 대체하며, 동일한 대체 공지를 표시합니다. `/model <alias>`는 패밀리의 모든 버전이 제한될 때만 거부됩니다. `--model`, `ANTHROPIC_MODEL`, 또는 `model` 설정으로 설정된 별칭은 여전히 그 경우에 시작 시 대체됩니다. v2.1.205 이전에는, 패밀리 별칭이 최신 릴리스 버전만을 기반으로 대체되거나 거부되었으며, 이전 버전이 허용되었을 때도 그랬습니다.423`opus`, `sonnet`, `haiku`, 또는 `fable`과 같은 [모델 패밀리 별칭](#restrict-model-selection)은 조직이 이를 허용할 때 일반적인 모델로 해석됩니다. 조직이 해당 모델을 제한할 때, Claude Code는 조직이 허용하는 패밀리의 최신 버전으로 대체하고 동일한 대체 알림을 표시합니다. `/model <alias>`는 패밀리의 모든 버전이 제한될 때만 거부됩니다. `--model`, `ANTHROPIC_MODEL`, 또는 `model` 설정으로 설정된 별칭은 여전히 시작 시 해당 경우에 대체됩니다. v2.1.205 이전에는 패밀리 별칭이 최신 릴리스 버전만을 기반으로 대체되거나 거부되었으며, 이전 버전이 허용되었을 때도 마찬가지였습니다.
419 424
420제한은 조직 전체 또는 역할별로 적용됩니다:425제한은 조직 전체 또는 역할별로 적용됩니다:
421 426
422* 조직 수준에서 모델을 비활성화하면 모든 멤버에서 제거됩니다.427* 조직 수준에서 모델을 비활성화하면 모든 멤버에 대해 제거됩니다.
423* 역할 수준 액세스는 다양한 사용자 정의 역할에 다양한 모델을 부여하며, 여러 역할을 보유한 멤버는 해당 역할 중 하나가 부여하는 모든 모델을 사용할 수 있습니다.428* 역할 수준 액세스는 다양한 사용자 정의 역할에 다양한 모델을 부여하고, 여러 역할을 보유한 멤버는 자신의 역할 중 하나가 부여하는 모든 모델을 사용할 수 있습니다.
424* Haiku 모델은 항상 사용 가능하며 비활성화할 수 없으므로, 모든 멤버는 최소한 하나의 사용 가능한 모델을 유지합니다.429* Haiku 모델은 항상 사용 가능하며 비활성화할 수 없으므로, 모든 멤버는 최소한 하나의 사용 가능한 모델을 유지합니다.
425* 액세스 변경은 약 1분 내에 새 요청에 적용됩니다. `/model` 선택기는 다음 세션이 시작될 때 이를 반영합니다.430* 액세스 변경은 약 1분 내에 새 요청에 적용됩니다. `/model` 선택기는 다음 세션이 시작될 때 이를 반영합니다.
426 431
427두 제한이 함께 적용됩니다: 모델은 `availableModels`에 의해 허용되고 조직에 의해 제한되지 않을 때만 선택 가능합니다. 조직 제한은 Anthropic API 및 [LLM 게이트웨이](/docs/ko/llm-gateway) 배포의 세션에만 도달합니다. 다른 제공자에서는 대신 `availableModels`를 사용하세요.432두 제한이 함께 적용됩니다: 모델은 `availableModels`에 의해 허용되고 조직에 의해 제한되지 않을 때만 선택 가능합니다. 조직 제한은 Anthropic API 및 [LLM 게이트웨이](/docs/ko/llm-gateway) 배포의 세션에만 도달합니다. 다른 제공자에서는 `availableModels`를 대신 사용하세요.
428 433
429<h2 id="organization-default-model">434<h2 id="organization-default-model">
430 조직 기본 모델435 조직 기본 모델
479 484
480`default`의 동작은 계정 유형에 따라 달라집니다:485`default`의 동작은 계정 유형에 따라 달라집니다:
481 486
482* **Pro, Max, Team, Enterprise, Anthropic API**: Opus 5.5로 기본 설정됨487* **Pro, Max, Team, Enterprise 및 Anthropic API**: Opus 5.5로 기본 설정됨
483* **AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform**: Opus 5.5로 기본 설정됨488* **AWS의 Claude Platform, Amazon Bedrock 및 Google Cloud의 Agent Platform**: Opus 5.5로 기본 설정됨
484* **Microsoft Foundry**: Sonnet 4.5로 기본 설정됨489* **Microsoft Foundry**: Sonnet 4.5로 기본 설정됨
485 490
486v2.1.280 이전에는 `default`가 Pro 및 Team Standard에서 Sonnet 5로, Max, Team Premium, Enterprise, Anthropic API, AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform에서 v2.1.219부터 Opus 5로 확인되었습니다. v2.1.219 이전에는 `default`가 Anthropic API, Max, Team Premium, Enterprise 종량제에서 v2.1.154부터 Opus 4.8로, AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform에서 v2.1.207부터 Opus 4.8로 확인되었습니다. v2.1.207 이전에는 `default`가 AWS의 Claude Platform에서 Opus 4.7로, Amazon Bedrock 및 Google Cloud의 Agent Platform에서 Sonnet 4.5로 확인되었습니다.491v2.1.280 이전에는 `default`가 Pro 및 Team Standard에서 Sonnet 5로, Max, Team Premium, Enterprise, Anthropic API, AWS의 Claude Platform, Amazon Bedrock 및 Google Cloud의 Agent Platform에서 v2.1.219부터 Opus 5로 확인되었습니다. v2.1.219 이전에는 `default`가 Anthropic API, Max, Team Premium 및 Enterprise 종량제에서 v2.1.154부터 Opus 4.8로, AWS의 Claude Platform, Amazon Bedrock 및 Google Cloud의 Agent Platform에서 v2.1.207부터 Opus 4.8로 확인되었습니다. v2.1.207 이전에는 `default`가 AWS의 Claude Platform에서 Opus 4.7로, Amazon Bedrock 및 Google Cloud의 Agent Platform에서 Sonnet 4.5로 확인되었습니다.
487 492
488관리자가 [조직 기본 모델](#organization-default-model)을 설정한 경우, `default`는 위의 계정 유형 기본값 대신 해당 모델로 확인됩니다. Claude Code v2.1.196 이상이 필요합니다. `default`는 [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)로 설정한 모델로도 확인될 수 있으며, 해당 섹션에 나열된 조건 하에서 확인됩니다.493관리자가 [조직 기본 모델](#organization-default-model)을 설정한 경우, `default`는 위의 계정 유형 기본값 대신 해당 모델로 확인됩니다. Claude Code v2.1.196 이상이 필요합니다. `default`는 [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)로 설정한 모델로도 확인될 수 있으며, 해당 섹션에 나열된 조건 하에서 또는 [계정에 기록된](#setting-your-model) 모델로 확인될 수 있습니다.
489 494
490관리되는 설정이 [기본 모델에 대한 허용 목록 적용](#enforce-the-allowlist-for-the-default-model)을 강제하고 계정 유형 기본값이 `availableModels`에 없는 경우, `default`는 위의 계정 유형 기본값 대신 강제된 기본값으로 확인됩니다. 둘 다 적용되는 경우, 조직 기본값이 먼저 계정 유형 기본값을 대체하고 강제 적용이 이에 적용됩니다: 허용 목록에 있는 조직 기본값은 유지되고, 목록 외의 값은 강제된 기본값으로 확인됩니다.495계정에 아무것도 기록되지 않았을 때, 관리되는 설정이 [Default 모델에 대한 허용 목록을 적용](#enforce-the-allowlist-for-the-default-model)하고, 계정 유형 기본값이 `availableModels`에 없으면, `default`는 위의 계정 유형 기본값 대신 적용된 Default로 확인됩니다. 조직 기본값과 적용이 모두 적용될 때, 조직 기본값이 먼저 계정 유형 기본값을 대체하고 적용이 이에 적용됩니다: 허용 목록에 있는 조직 기본값은 유지되고, 목록 외의 값은 적용된 Default로 확인됩니다.
491 496
492Fable 모델은 어떤 플랜이나 제공자에서도 계정 유형 기본값이 아닙니다. `/model`로 선택하면 사용자 설정에서 선택된 모델로 저장되므로 이후 세션이 이 모델에서 시작됩니다. v2.1.257에서 Claude Code가 저장된 Fable 5 선택에 대해 수행하는 일회성 변경에 대해서는 [Fable 작업](#work-with-fable)을 참조하세요.497Fable 모델은 어떤 플랜이나 제공자에서도 계정 유형 기본값이 아닙니다. `/model`로 선택하면 사용자 설정에서 선택된 모델로 저장되므로, 이후 세션이 이 모델에서 시작됩니다. v2.1.257에서 Claude Code가 저장된 Fable 5 선택에 대해 수행하는 일회성 변경의 경우, [Fable 작업](#work-with-fable)을 참조하세요.
493 498
494<h3 id="opusplan-model-setting">499<h3 id="opusplan-model-setting">
495 `opusplan` 모델 설정500 `opusplan` 모델 설정
497 502
498`opusplan` 모델 별칭은 자동화된 하이브리드 접근 방식을 제공합니다:503`opusplan` 모델 별칭은 자동화된 하이브리드 접근 방식을 제공합니다:
499 504
500* **계획 모드에서**: 복잡한 추론 및 아키텍처 결정을 위해 `opus` 사용505* **계획 모드에서**: 복잡한 추론 및 아키텍처 결정을 위해 `opus`를 사용합니다
501* **실행 모드에서**: 코드 생성 및 구현을 위해 자동으로 `sonnet`으로 전환506* **실행 모드에서**: 코드 생성 및 구현을 위해 자동으로 `sonnet`으로 전환합니다
502 507
503이는 계획을 위한 Opus의 추론과 실행을 위한 Sonnet의 효율성을 결합합니다.508이는 계획을 위한 Opus의 추론과 실행을 위한 Sonnet의 효율성을 결합합니다.
504 509
505계획 모드 Opus 단계는 `opus` 모델 설정과 동일한 컨텍스트 윈도우를 사용하고, 실행 단계는 `sonnet`과 동일한 윈도우를 사용합니다. `opus`와 `sonnet`이 [1M 컨텍스트 윈도우](#extended-context)로 기본적으로 실행되는 모델로 확인될 때(현재 모델이 Anthropic API에서 그렇듯이), 두 단계 모두 이를 사용하여 실행됩니다. 그렇지 않은 경우 두 단계 모두에 1M 컨텍스트를 요청하려면 모델을 `opusplan[1m]`으로 [설정](#setting-your-model)하세요. 예를 들어 `/model opusplan[1m]`을 사용하세요. 이를 `/model`로 설정하려면 Claude Code v2.1.265 이상이 필요합니다. 이전 버전에서는 `--model` 플래그 또는 `model` 설정을 대신 사용하세요.510계획 모드 Opus 단계는 `opus` 모델 설정과 동일한 컨텍스트 윈도우를 사용하고, 실행 단계는 `sonnet`과 동일한 윈도우를 사용합니다. `opus`와 `sonnet`이 [1M 컨텍스트 윈도우](#extended-context)로 기본 실행되는 모델로 확인될 때, Anthropic API의 현재 모델처럼, 두 단계 모두 이를 사용하여 실행됩니다. 이들이 그렇지 않은 경우 두 단계 모두에 대해 1M 컨텍스트를 요청하려면, [모델을 설정](#setting-your-model)하여 `opusplan[1m]`으로 설정하세요. 예를 들어 `/model opusplan[1m]`을 사용합니다. 이를 `/model`로 설정하려면 Claude Code v2.1.265 이상이 필요합니다. 이전 버전에서는 `--model` 플래그 또는 `model` 설정을 대신 사용하세요.
506 511
507[`availableModels`](#restrict-model-selection)가 최신 Opus를 제외하지만 `["sonnet", "claude-opus-4-6"]`과 같은 이전 버전을 허용하는 경우, `opusplan`은 계획을 위해 허용된 최신 Opus를 사용하고 모든 Opus가 제외된 경우에만 Sonnet에만 유지됩니다. 계획 모드에서 일반적으로 Sonnet으로 업그레이드되는 Haiku 세션은 마찬가지로 허용된 최신 Sonnet을 사용하고, 모든 Sonnet이 제외된 경우에만 Haiku에만 유지됩니다. v2.1.205 이전에는 허용 목록이 이전 버전을 허용했더라도 업그레이드 제품군의 최신 버전이 제외되면 계획 모드가 세션의 모델에 유지되었습니다.512[`availableModels`](#restrict-model-selection)이 최신 Opus를 제외하지만 이전 버전(예: `["sonnet", "claude-opus-4-6"]`)을 허용할 때, `opusplan`은 계획을 위해 허용된 최신 Opus를 사용하고 모든 Opus가 제외될 때만 Sonnet에만 유지됩니다. 계획 모드에서 일반적으로 Sonnet으로 업그레이드할 Haiku 세션은 마찬가지로 허용된 최신 Sonnet을 사용하고, 모든 Sonnet이 제외될 때만 Haiku에만 유지됩니다. v2.1.205 이전에는 계획 모드가 허용 목록이 이전 버전을 허용했을 때에도 업그레이드 제품군의 최신 버전이 제외될 때마다 세션의 모델에 유지되었습니다.
508 513
509이전 허용 버전의 대체는 Anthropic API 및 [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws)에 적용됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Mantle에서는 배포가 제공자별 모델 ID를 사용하므로 업그레이드 모델이 제외되면 계획 모드가 세션의 모델에 유지됩니다.514이전 허용 버전의 대체는 Anthropic API 및 [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws)에 적용됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 Mantle에서는 제공자별 모델 ID를 사용하는 배포이므로, 계획 모드는 업그레이드 모델이 제외될 때마다 세션의 모델에 유지됩니다.
510 515
511Claude가 계획 경계에서 전환하는 대신 작업 중간에 두 번째 모델을 참조할 시기를 결정하는 하이브리드 접근 방식은 [advisor tool](/docs/ko/advisor)을 참조하세요.516Claude가 계획 경계에서 전환하는 대신 작업 중간에 두 번째 모델을 참조할 시기를 결정하는 하이브리드 접근 방식의 경우, [advisor 도구](/docs/ko/advisor)를 참조하세요.
512 517
513<h3 id="fallback-model-chains">518<h3 id="fallback-model-chains">
514 폴백 모델 체인519 폴백 모델 체인
515</h3>520</h3>
516 521
517주 모델이 과부하 상태이거나 사용 불가능하거나 다른 재시도 불가능한 서버 오류를 반환할 때, Claude Code는 요청이 실패하는 대신 폴백 모델로 전환할 수 있습니다. 인증, 청구, 속도 제한, 요청 크기, 전송 오류 및 [조직의 정책 확인에 의한 거부](/docs/ko/errors#automatic-retries)는 전환을 트리거하지 않습니다. 이들은 정상적인 재시도 및 오류 처리를 따릅니다.522기본 모델이 과부하 상태이거나 사용할 수 없거나 다른 재시도 불가능한 서버 오류를 반환할 때, Claude Code는 요청이 실패하는 대신 폴백 모델로 전환할 수 있습니다. 인증, 청구, 속도 제한, 요청 크기 및 전송 오류, 그리고 [조직의 정책 확인에 의한 거부](/docs/ko/errors#automatic-retries)는 전환을 트리거하지 않습니다. 이들은 정상적인 재시도 및 오류 처리를 따릅니다.
518 523
519하나 이상의 폴백 모델을 구성하고 Claude Code는 순서대로 시도하며, 전환할 때 알림을 표시합니다. 전환은 현재 턴에만 지속되므로 다음 메시지는 주 모델을 먼저 다시 시도합니다. Claude Code는 중복 제거 후 체인을 3개 모델로 제한하고 추가 항목을 무시합니다.524하나 이상의 폴백 모델을 구성하고 Claude Code는 순서대로 시도하며, 전환할 때 알림을 표시합니다. 전환은 현재 턴에만 지속되므로, 다음 메시지는 기본 모델을 다시 먼저 시도합니다. Claude Code는 체인을 중복 제거 후 3개 모델로 제한하고 추가 항목을 무시합니다.
520 525
521`--fallback-model` 플래그로 한 세션에 대한 체인을 설정하며, 이는 쉼표로 구분된 목록을 허용합니다:526`--fallback-model` 플래그로 한 세션에 대한 체인을 설정하며, 이는 쉼표로 구분된 목록을 허용합니다:
522 527
524claude --fallback-model sonnet,haiku529claude --fallback-model sonnet,haiku
525```530```
526 531
527세션 전체에 체인을 유지하려면 [설정](/docs/ko/settings)에서 `fallbackModel`을 배열로 설정하세요:532세션 전체에 체인을 유지하려면, [설정](/docs/ko/settings)에서 `fallbackModel`을 배열로 설정하세요:
528 533
529```json theme={null}534```json theme={null}
530{535{
532}537}
533```538```
534 539
535`--fallback-model` 플래그는 `fallbackModel` 설정보다 우선합니다. 각 항목은 모델 이름 또는 별칭을 허용하며, `"default"`는 기본 모델로 확장됩니다.540`--fallback-model` 플래그는 `fallbackModel` 설정보다 우선합니다. 각 항목은 모델 이름 또는 별칭을 허용하고, `"default"`는 기본 모델로 확장됩니다.
536 541
537Claude Code는 시작 시 체인을 확인하지 않으며 `/status`는 이를 표시하지 않습니다. 전환이 발생할 때 표시되는 알림이 폴백이 구성되었다는 첫 번째 눈에 띄는 신호입니다.542Claude Code는 시작 시 체인을 확인하지 않으며 `/status`는 이를 표시하지 않습니다. 전환이 발생할 때 표시되는 알림이 폴백이 구성되었다는 첫 번째 눈에 띄는 신호입니다.
538 543
539요청이 실패하면 Claude Code는 하나가 이를 수락할 때까지 순서대로 각 항목을 시도합니다. 설정에 고정된 폐기된 모델과 같이 도달할 수 없는 항목도 동일한 방식으로 다음 항목으로 폴백됩니다. Claude Code는 해당 이동을 시작하기 전에 두 가지 종류의 항목을 제거합니다:544요청이 폴백될 때, Claude Code는 하나가 이를 수락할 때까지 순서대로 각 항목을 시도합니다. 설정에 고정된 폐기된 모델과 같이 도달할 수 없는 항목도 동일한 방식으로 다음 항목으로 폴백됩니다. Claude Code는 해당 이동을 시작하기 전에 두 가지 종류의 항목을 제거합니다:
540 545
541* **허용 목록 외**: Claude Code는 체인을 읽을 때 [`availableModels`](#restrict-model-selection)에서 허용하지 않는 항목을 삭제합니다.546* **허용 목록 외**: Claude Code는 체인을 읽을 때 [`availableModels`](#restrict-model-selection)에 의해 허용되지 않는 항목을 삭제합니다.
542* **압축 중 더 작은 컨텍스트 윈도우**: 체인은 [압축](/docs/ko/context-window#what-survives-compaction)도 포함하지만, Claude Code는 주 모델보다 컨텍스트 윈도우가 작은 모델로 폴백하지 않습니다. 요약이 먼저 대화의 일부를 차단하기 때문입니다. 모든 폴백이 더 작으면 압축이 원래 오류를 표시하고 재시도할 수 있습니다.547* **압축 중 더 작은 컨텍스트 윈도우**: 체인은 [압축](/docs/ko/context-window#what-survives-compaction)도 포함하지만, Claude Code는 기본 모델보다 더 작은 컨텍스트 윈도우를 가진 모델로 폴백하지 않습니다. 요약이 먼저 대화의 일부를 차단하기 때문입니다. 모든 폴백이 더 작으면, 압축은 원래 오류를 표시하고 재시도할 수 있습니다.
543 548
544Claude Code는 [subagents](/docs/ko/sub-agents)에도 체인을 적용합니다. subagent의 요청이 실패하면 Claude Code는 순서대로 구성된 폴백 모델을 시도하고 subagent는 요청을 수락하는 모델에서 계속됩니다. 세션의 모델은 변경되지 않습니다. v2.1.247 이전에는 체인이 포함하는 실패가 subagent를 종료했습니다.549Claude Code는 [subagents](/docs/ko/sub-agents)에도 체인을 적용합니다. subagent의 요청이 폴백될 때, Claude Code는 순서대로 구성된 폴백 모델을 시도하고, subagent는 요청을 수락하는 모델에서 계속됩니다. 세션의 모델은 변경되지 않습니다. v2.1.247 이전에는 체인이 포함하는 실패가 subagent를 종료했습니다.
545 550
546<h3 id="automatic-model-fallback">551<h3 id="automatic-model-fallback">
547 자동 모델 폴백552 자동 모델 폴백
548</h3>553</h3>
549 554
550이 섹션은 Fable 모델, Opus 5.5, Sonnet 5.5, Opus 5의 콘텐츠 기반 폴백을 다룹니다. 모델이 과부하 상태이거나 사용 불가능할 때의 가용성 기반 폴백은 [폴백 모델 체인](#fallback-model-chains)을 참조하세요.555이 섹션은 Fable 모델, Opus 5.5, Sonnet 5.5 및 Opus 5의 콘텐츠 기반 폴백을 다룹니다. 모델이 과부하 상태이거나 사용할 수 없을 때의 가용성 기반 폴백의 경우, [폴백 모델 체인](#fallback-model-chains)을 참조하세요.
551 556
552Fable 모델, Opus 5.5, Sonnet 5.5, Opus 5는 안전 분류기로 실행되며, 대부분 사이버 보안 및 생물학 콘텐츠에 플래그를 지정합니다. 분류기가 요청에 플래그를 지정하고 플래그된 카테고리에 폴백 모델이 있는 경우, Claude Code는 해당 모델에서 요청을 다시 실행하고 기록에 알림을 표시합니다. 이 두 카테고리의 경우 폴백 모델은 거부한 모델에 따라 달라집니다:557Fable 모델, Opus 5.5, Sonnet 5.5 및 Opus 5는 안전 분류기로 실행되며, 이는 대부분 사이버 보안 및 생물학 콘텐츠에 플래그를 지정합니다. 분류기가 요청에 플래그를 지정하고 플래그된 카테고리에 폴백 모델이 있을 때, Claude Code는 해당 모델에서 요청을 다시 실행하고 트랜스크립트에 알림을 표시합니다. 이 두 카테고리의 경우, 폴백 모델은 어느 모델이 거부했는지에 따라 달라집니다:
553 558
554* **Fable 5.1, Fable 5, Opus 5.5**: 생물학 플래그 요청은 Opus 5에서 다시 실행되고, 사이버 보안 플래그 요청은 Opus 4.8에서 다시 실행됩니다.559* **Fable 5.1, Fable 5 및 Opus 5.5**: 생물학 플래그 요청은 Opus 5에서 다시 실행되고, 사이버 보안 플래그 요청은 Opus 4.8에서 다시 실행됩니다.
555* **Sonnet 5.5**: 사이버 보안 플래그 요청은 Sonnet 5에서 다시 실행됩니다. 생물학 플래그 요청은 거부로 끝나며, Sonnet 5.5는 생물학 폴백 모델이 없기 때문입니다.560* **Sonnet 5.5**: 사이버 보안 플래그 요청은 Sonnet 5에서 다시 실행됩니다. 생물학 플래그 요청은 Sonnet 5.5에 생물학 폴백 모델이 없기 때문에 거부로 종료됩니다.
556* **Opus 5**: 사이버 보안 플래그 요청은 Opus 4.8에서 다시 실행됩니다. 생물학 플래그 요청은 거부로 끝나며, Opus 5는 폴백 모델이 없는 자체 생물학 분류기를 실행하기 때문입니다.561* **Opus 5**: 사이버 보안 플래그 요청은 Opus 4.8에서 다시 실행됩니다. 생물학 플래그 요청은 Opus 5가 폴백 모델이 없는 자체 생물학 분류기를 실행하기 때문에 거부로 종료됩니다.
557 562
558Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 Claude Code는 배포를 통해 이러한 대상을 확인합니다. [Bedrock, Agent Platform, Foundry에서 폴백 활성화](#enable-fallback-on-bedrock-agent-platform-and-foundry)를 참조하세요.563Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서는 Claude Code가 배포의 모델 ID를 통해 이러한 대상을 확인합니다. [Bedrock, Agent Platform 및 Foundry에서 폴백 활성화](#enable-fallback-on-bedrock-agent-platform-and-foundry)를 참조하세요.
559 564
560폴백 후 세션은 폴백 모델에서 계속됩니다. 원래 모델로 돌아가려면 [`/model`](#setting-your-model)을 실행하세요.565폴백 후, 세션은 폴백 모델에서 계속됩니다. 원래 모델로 돌아가려면 [`/model`](#setting-your-model)을 실행하세요.
561 566
562카테고리 기반 폴백에는 Claude Code v2.1.219 이상이 필요합니다. v2.1.219 이전에는 모든 플래그된 Fable 5 요청이 제공자의 기본 Opus 모델에서 다시 실행되었고, Opus 5는 폴백 소스가 아니었습니다.567카테고리 기반 폴백에는 Claude Code v2.1.219 이상이 필요합니다. v2.1.219 이전에는 모든 플래그된 Fable 5 요청이 제공자의 기본 Opus 모델에서 다시 실행되었고, Opus 5는 폴백 소스가 아니었습니다.
563 568
567 폴백을 트리거한 것 확인572 폴백을 트리거한 것 확인
568</h4>573</h4>
569 574
570폴백은 세션의 첫 번째 요청에서 트리거될 수 있으며, 이는 비정상적인 것을 보내기 전입니다. 첫 번째 요청은 CLAUDE.md 콘텐츠 및 git 상태와 같은 작업 공간 컨텍스트를 전달하기 때문입니다. 보안 또는 생물학 자료를 포함하는 저장소는 해당 컨텍스트만으로 분류기를 트리거할 수 있습니다.575폴백은 CLAUDE.md 콘텐츠 및 git 상태와 같은 작업 공간 컨텍스트를 전달하는 첫 번째 요청 전에 세션의 첫 번째 요청에서 트리거될 수 있습니다. 보안 또는 생물학 자료를 포함하는 저장소는 해당 컨텍스트만으로 분류기를 트리거할 수 있습니다.
571 576
572사용자 정의가 트리거인지 확인하려면 `claude --safe-mode`로 세션을 시작하세요. 이는 CLAUDE.md, 스킬, MCP 서버, 훅과 같은 사용자 정의를 비활성화합니다. Git 상태 및 디렉토리 이름은 사용자 정의가 아니며 여전히 포함됩니다.577사용자 정의가 트리거인지 확인하려면, `claude --safe-mode`로 세션을 시작하세요. 이는 CLAUDE.md, 스킬, MCP 서버 및 훅과 같은 사용자 정의를 비활성화합니다. Git 상태 및 디렉토리 이름은 사용자 정의가 아니며 여전히 포함됩니다.
573 578
574<h4 id="ask-before-switching">579<h4 id="ask-before-switching">
575 전환 전에 요청580 전환하기 전에 요청
576</h4>581</h4>
577 582
578요청이 플래그될 때마다 자동으로 전환하는 대신 어떤 일이 발생할지 결정하려면 `/config`를 실행하고 **메시지가 플래그될 때 모델 전환**을 끄거나 설정 파일에서 [`switchModelsOnFlag`](/docs/ko/settings-reference#switchmodelsonflag)를 `false`로 설정하세요. 플래그된 요청은 세션을 일시 중지하고 두 가지 옵션을 제공합니다: 폴백 모델로 전환하거나 프롬프트를 편집하고 현재 모델에서 재시도합니다.583요청이 플래그될 때마다 자동으로 전환하는 대신 어떤 일이 발생할지 결정하려면, `/config`를 실행하고 **메시지가 플래그될 때 모델 전환**을 끄거나, 설정 파일에서 [`switchModelsOnFlag`](/docs/ko/settings-reference#switchmodelsonflag)를 `false`로 설정하세요. 플래그된 요청은 두 가지 옵션으로 세션을 일시 중지합니다: 폴백 모델로 전환하거나, 프롬프트를 편집하고 현재 모델에서 재시도합니다.
579 584
580일부 경우는 다르게 동작합니다:585일부 경우는 다르게 동작합니다:
581 586
582* 플래그된 카테고리에 폴백 모델이 없는 경우(예: Opus 5의 생물학 플래그 또는 Sonnet 5.5), Claude Code는 프롬프트를 표시하지 않으며 요청은 거부로 끝납니다.587* 플래그된 카테고리에 폴백 모델이 없을 때(예: Opus 5 또는 Sonnet 5.5의 생물학 플래그), Claude Code는 프롬프트를 표시하지 않으며 요청은 거부로 종료됩니다.
583* 두 모델이 동일한 요청에 플래그를 지정하면 프롬프트를 편집하고 재시도하거나 새 세션을 시작할 수 있습니다.588* 두 모델이 동일한 요청에 플래그를 지정하면, 프롬프트를 편집하고 재시도하거나 새 세션을 시작할 수 있습니다.
584* 모바일 앱의 [웹의 Claude Code](/docs/ko/claude-code-on-the-web) 세션에서는 편집 및 재시도가 지원되지 않습니다. 모델을 전환하거나 데스크톱 브라우저 또는 데스크톱 앱에서 세션을 계속하세요.589* 모바일 앱의 [클라우드 세션](/docs/ko/claude-code-on-the-web)에서는 편집 및 재시도가 지원되지 않습니다. 모델을 전환하거나 데스크톱 브라우저 또는 데스크톱 앱에서 세션을 계속하세요.
585* [비대화형 모드](/docs/ko/cli-reference#cli-flags) 및 프롬프트를 표시할 수 없는 SDK 통합에서 플래그된 요청은 거부로 턴을 종료합니다.590* [비대화형 모드](/docs/ko/cli-reference#cli-flags) 및 프롬프트를 표시할 수 없는 SDK 통합에서는 플래그된 요청이 거부로 턴을 종료합니다.
586* 폴백 대상이 [`availableModels`](#restrict-model-selection)에 의해 차단되면 Claude Code는 프롬프트를 표시하지 않습니다. 플래그된 요청은 거부로 끝나며, 대상이 차단될 때 자동 폴백과 동일합니다.591* 폴백 대상이 [`availableModels`](#restrict-model-selection)에 의해 차단될 때, Claude Code는 프롬프트를 표시하지 않습니다. 플래그된 요청은 거부로 종료되며, 대상이 차단될 때 자동 폴백과 동일합니다.
587 592
588<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">593<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">
589 Bedrock, Agent Platform, Foundry에서 폴백 활성화594 Bedrock, Agent Platform 및 Foundry에서 폴백 활성화
590</h4>595</h4>
591 596
592[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai), [Microsoft Foundry](/docs/ko/microsoft-foundry)에서 모델 ID는 제공자별이므로 자동 폴백은 Claude Code가 관련된 각 모델을 식별할 수 있을 때만 작동합니다:597[Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 및 [Microsoft Foundry](/docs/ko/microsoft-foundry)에서는 모델 ID가 제공자별이므로, 자동 폴백은 Claude Code가 관련된 각 모델을 식별할 수 있을 때만 작동합니다:
593 598
594* Claude Code는 현재 모델을 폴백 소스로 인식해야 합니다. Fable 5.1 및 Fable 5는 모델 ID에 `claude-fable-5`가 포함되거나, `ANTHROPIC_DEFAULT_FABLE_MODEL`의 값과 일치하거나, [`modelOverrides`](#override-model-ids-per-version)로 매핑될 때 인식됩니다. Opus 5.5, Sonnet 5.5, Opus 5는 제공자 모델 ID 또는 [`modelOverrides`](#override-model-ids-per-version) 매핑으로 인식됩니다.599* Claude Code는 현재 모델을 폴백 소스로 인식해야 합니다. Fable 5.1 및 Fable 5는 모델 ID가 `claude-fable-5`를 포함하거나, `ANTHROPIC_DEFAULT_FABLE_MODEL`의 값과 일치하거나, [`modelOverrides`](#override-model-ids-per-version)로 매핑될 때 인식됩니다. Opus 5.5, Sonnet 5.5 및 Opus 5는 제공자 모델 ID 또는 [`modelOverrides`](#override-model-ids-per-version) 매핑으로 인식됩니다.
595* Opus 대상은 배포에서 확인되어야 합니다. 어느 모델이 거부했든: `ANTHROPIC_DEFAULT_OPUS_MODEL`을 설정하거나 제공자의 모델 목록에 Opus 4.8 항목을 유지하세요. 없으면 모든 소스 모델에 대해 폴백이 꺼지고, Sonnet 5.5를 포함하여 플래그된 요청은 거부로 끝납니다.600* Opus 대상은 배포에서 확인되어야 합니다. 어느 모델이 거부했든: `ANTHROPIC_DEFAULT_OPUS_MODEL`을 설정하거나, 제공자의 모델 목록에 Opus 4.8 항목을 유지하세요. 없으면, 폴백은 Sonnet 5.5를 포함한 모든 소스 모델에 대해 꺼지고, 플래그된 요청은 거부로 종료됩니다.
596* 플래그된 카테고리의 폴백 모델은 배포에서 확인되어야 합니다. Fable 모델, Opus 5.5, Opus 5에서 `ANTHROPIC_DEFAULT_OPUS_MODEL`을 설정하면 폴백이 있는 모든 카테고리에 대해 플래그된 요청이 해당 모델에서 다시 실행됩니다. Opus 5의 생물학 플래그는 여전히 거부로 끝납니다. 설정하지 않으면 사이버 보안 플래그 요청이 Opus 4.8 항목에서 다시 실행되고, Fable 모델 또는 Opus 5.5의 생물학 플래그 요청이 Opus 5 항목에서 다시 실행됩니다. Sonnet 5.5에서 사이버 보안 플래그 요청은 `ANTHROPIC_DEFAULT_SONNET_MODEL`에서 설정한 모델에서 다시 실행되거나, 설정하지 않으면 제공자의 모델 목록에서 Sonnet 5 항목에서 다시 실행됩니다.601* 플래그된 카테고리의 폴백 모델은 배포에서 확인되어야 합니다. Fable 모델, Opus 5.5 또는 Opus 5에서, `ANTHROPIC_DEFAULT_OPUS_MODEL`을 설정하면, 플래그된 요청은 폴백이 있는 모든 카테고리에 대해 해당 모델에서 다시 실행됩니다. Opus 5의 생물학 플래그는 여전히 거부로 종료됩니다. 설정하지 않으면, 사이버 보안 플래그 요청은 Opus 4.8 항목에서 다시 실행되고, Fable 모델 또는 Opus 5.5의 생물학 플래그 요청은 Opus 5 항목에서 다시 실행됩니다. Sonnet 5.5에서는 사이버 보안 플래그 요청이 `ANTHROPIC_DEFAULT_SONNET_MODEL`에서 설정한 모델에서 다시 실행되거나, 설정하지 않으면 제공자의 모델 목록의 Sonnet 5 항목에서 다시 실행됩니다.
597 602
598모델을 식별할 수 없으면 Claude Code는 자동으로 전환하지 않습니다. 플래그된 요청은 거부 메시지로 끝나고 [`/model`](#setting-your-model)로 모델을 전환하고 재시도할 수 있습니다. 두 모델을 식별 가능하게 하려면 소스 모델에 대한 핀을 설정하세요:603두 모델 중 하나를 식별할 수 없으면, Claude Code는 전환하지 않습니다. 플래그된 요청은 거부 메시지로 종료되고, [`/model`](#setting-your-model)로 모델을 전환하고 재시도할 수 있습니다. 두 모델을 모두 식별 가능하게 하려면, 소스 모델에 대한 핀을 설정하세요:
599 604
600* **Fable 모델**: `ANTHROPIC_DEFAULT_FABLE_MODEL`을 Fable 모델 ID로 설정하여 Claude Code가 이를 폴백 소스로 인식하도록 합니다.605* **Fable 모델**: `ANTHROPIC_DEFAULT_FABLE_MODEL`을 Fable 모델 ID로 설정하여 Claude Code가 이를 폴백 소스로 인식하도록 합니다.
601* **모든 소스 모델**: `ANTHROPIC_DEFAULT_OPUS_MODEL`을 Opus 모델 ID로 설정하여 폴백을 켜고 플래그된 카테고리에 대상을 제공합니다. Opus 제품군 외의 모델 또는 거부한 모델을 지정하는 핀은 거부를 유지합니다.606* **모든 소스 모델**: `ANTHROPIC_DEFAULT_OPUS_MODEL`을 Opus 모델 ID로 설정하여 폴백을 켜고 플래그된 카테고리에 대상을 제공합니다. Opus 제품군 외의 모델 또는 거부한 모델을 이름 지정하는 핀은 거부를 유지합니다.
602* **Sonnet 5.5**: Opus 핀 외에도 `ANTHROPIC_DEFAULT_SONNET_MODEL`을 설정하거나 제공자의 모델 목록에 Sonnet 5 항목을 유지하여 요청이 다시 실행되는 모델을 제공합니다. Sonnet 제품군 외의 모델 또는 Sonnet 5.5 자체를 지정하는 Sonnet 핀은 거부를 유지합니다.607* **Sonnet 5.5**: Opus 핀 외에도, `ANTHROPIC_DEFAULT_SONNET_MODEL`을 설정하거나 제공자의 모델 목록에 Sonnet 5 항목을 유지하여 요청이 다시 실행되는 모델을 제공합니다. Sonnet 제품군 외의 모델 또는 Sonnet 5.5 자체를 이름 지정하는 Sonnet 핀은 거부를 유지합니다.
603 608
604<h4 id="security-research-and-biology-workloads">609<h4 id="security-research-and-biology-workloads">
605 보안 연구 및 생물학 워크로드610 보안 연구 및 생물학 워크로드
606</h4>611</h4>
607 612
608공격적인 보안 또는 생물학의 워크로드(침투 테스트, Capture the Flag(CTF) 연습, 생물학 인접 코드베이스 포함)는 자주 폴백을 트리거하며, 종종 첫 번째 요청에서 트리거됩니다. Fable 5.1, Fable 5, Opus 5.5의 실질적인 생물학 작업의 경우, Claude Code는 첫 번째 플래그된 요청에서 세션을 Opus 5로 이동하고, 이후 생물학 플래그 요청은 Opus 5에서 거부로 끝나며, Opus 5는 생물학 폴백이 없기 때문입니다. Opus 5 및 Sonnet 5.5에서는 첫 번째 플래그된 요청부터 이러한 거부를 받습니다.613공격적 보안 또는 생물학의 워크로드(침투 테스트, Capture the Flag(CTF) 연습 및 생물학 인접 코드베이스 포함)는 폴백을 자주 트리거하며, 종종 첫 번째 요청에서 트리거합니다. Fable 5.1, Fable 5 또는 Opus 5.5의 실질적인 생물학 작업의 경우, Claude Code는 첫 번째 플래그된 요청에서 세션을 Opus 5로 이동하고, 이후 생물학 플래그 요청은 Opus 5에서 거부로 종료됩니다. Opus 5에 생물학 폴백이 없기 때문입니다. Opus 5 및 Sonnet 5.5에서는 첫 번째 플래그된 요청부터 이러한 거부를 받습니다.
609 614
610이는 이러한 도메인에 대한 예상 라우팅이며 계정 플래그가 아닙니다. 조직이 이 작업을 위해 Fable 클래스 기능이 필요한 경우 Anthropic 계정 팀에 신뢰할 수 있는 액세스 프로그램에 대해 문의하세요.615이는 이러한 도메인에 대한 예상 라우팅이며, 계정 플래그가 아닙니다. 조직이 이 작업을 위해 Fable 클래스 기능이 필요한 경우, Anthropic 계정 팀에 신뢰할 수 있는 액세스 프로그램에 대해 문의하세요.
611 616
612<h3 id="adjust-effort-level">617<h3 id="adjust-effort-level">
613 노력 수준 조정618 노력 수준 조정
614</h3>619</h3>
615 620
616[노력 수준](https://platform.claude.com/docs/en/build-with-claude/effort)은 적응형 추론을 제어하며, 이를 통해 모델은 작업 복잡성에 따라 각 단계에서 생각할지 여부와 얼마나 생각할지 결정할 수 있습니다. 낮은 노력은 간단한 작업에 더 빠르고 저렴하지만, 높은 노력은 복잡한 문제에 더 깊은 추론을 제공합니다.621[노력 수준](https://platform.claude.com/docs/en/build-with-claude/effort)은 적응형 추론을 제어하며, 이는 모델이 각 단계에서 작업 복잡성에 따라 생각할지 여부와 얼마나 생각할지를 결정하도록 합니다. 낮은 노력은 간단한 작업에 더 빠르고 저렴하고, 높은 노력은 복잡한 문제에 더 깊은 추론을 제공합니다.
617 622
618사용 가능한 노력 수준은 모델에 따라 다릅니다. 여기에 나열되지 않은 모델은 노력을 지원하지 않습니다:623사용 가능한 노력 수준은 모델에 따라 다릅니다. 여기에 나열되지 않은 모델은 노력을 지원하지 않습니다:
619 624
620| 모델 | 수준 |625| 모델 | 수준 |
621| :- | :- |626| :- | :- |
622| Fable 5.1 및 Fable 5 | `low`, `medium`, `high`, `xhigh`, `max` |627| Fable 5.1 및 Fable 5 | `low`, `medium`, `high`, `xhigh`, `max` |
623| Opus 5.5, Sonnet 5.5, Opus 5, Sonnet 5, Opus 4.8, Opus 4.7 | `low`, `medium`, `high`, `xhigh`, `max` |628| Opus 5.5, Sonnet 5.5, Opus 5, Sonnet 5, Opus 4.8 및 Opus 4.7 | `low`, `medium`, `high`, `xhigh`, `max` |
624| Opus 4.6 및 Sonnet 4.6 | `low`, `medium`, `high`, `max` |629| Opus 4.6 및 Sonnet 4.6 | `low`, `medium`, `high`, `max` |
625 630
626활성 모델이 지원하지 않는 수준을 설정하면 Claude Code는 설정한 수준 이하의 지원되는 최고 수준으로 폴백합니다. 예를 들어 `xhigh`는 Opus 4.6에서 `high`로 실행됩니다. 조직은 모델에 사용 가능한 수준을 제한할 수도 있습니다. [조직 노력 제한](#organization-effort-limits)을 참조하세요.631활성 모델이 지원하지 않는 수준을 설정하면, Claude Code는 설정한 수준 이하의 지원되는 최고 수준으로 폴백합니다. 예를 들어, `xhigh`는 Opus 4.6에서 `high`로 실행됩니다. 조직 또는 자신의 설정도 모델이 제공하는 수준을 제한할 수 있습니다. [조직 노력 제한](#organization-effort-limits)을 참조하세요.
627 632
628[`ultracode`](/docs/ko/settings-reference#ultracode) 설정이 꺼져 있으면 Claude Code는 세션의 노력 수준을 이 순서로 확인하며, 적용되는 첫 번째를 사용합니다:633Claude Code는 세션의 노력 수준을 이 순서로 확인하며, 적용되는 첫 번째를 사용합니다:
629 634
6301. 명시적 선택: [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/ko/env-vars#variables) 환경 변수, `--effort`로 시작, 또는 세션의 `/effort` ([비대화형 `/effort`는 더 좁은 효과를 가짐](#non-interactive-effort))6351. 명시적 선택: [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/ko/env-vars#variables) 환경 변수, `--effort`로 시작하거나, 세션에서 `/effort` ([비대화형 `/effort`는 더 좁은 효과를 가짐](#non-interactive-effort))
6312. 설정: 모델에 대해 저장한 수준 또는 [`effortLevel`](/docs/ko/settings-reference#effortlevel) 키, 설정 파일 간 우선순위는 [`modelSettings`](/docs/ko/settings-reference#modelsettings)에 명시됨6362. 설정: 모델에 대해 저장한 수준 또는 [`effortLevel`](/docs/ko/settings-reference#effortlevel) 키, [`modelSettings`](/docs/ko/settings-reference#modelsettings)에 명시된 우선순위
6323. 모델의 기본 노력: 노력을 지원하는 모든 모델에서 `high`, Opus 5.5 및 Sonnet 5.5는 `medium`으로 기본값, Opus 4.7은 `xhigh`로 기본값, 조직이 [조직 기본 모델](#organization-default-model)에 대한 기본 노력 수준을 설정할 때 해당 모델을 실행할 때 해당 수준이 기본값6373. 모델의 기본 노력: 노력을 지원하는 모든 모델에서 `high`, Opus 5.5 및 Sonnet 5.5는 `medium`으로 기본값, Opus 4.7은 `xhigh`로 기본값, 그리고 조직이 [조직 기본 모델](#organization-default-model)에 대한 기본 노력 수준을 설정할 때, 해당 모델을 실행할 때 그 수준이 기본값입니다.
633 638
634Opus 5.5는 위의 소스 중 하나가 수준을 설정하지 않는 한 `medium`에서 시작하며, 사용자 설정 파일의 최상위 `effortLevel`은 Opus 5.5에 계산되지 않습니다. 해당 키는 Claude Code가 모델별로 수준을 저장하기 전에 `/effort`가 작성한 이전 형식입니다: 이전에 적용된 위치(Opus 5, Fable 5.1, 이전 모델)에서 계속 적용되는 반면, Opus 5.5 및 이후에 출시된 모델은 `/effort` 또는 `/model` 선택기로 수준을 선택할 때까지 자체 기본값에서 시작합니다. 프로젝트, 로컬, 관리되는 설정의 최상위 `effortLevel` 또는 `--settings`로 전달된 것은 모든 모델에 적용됩니다.639Opus 5.5는 위의 소스 중 하나가 수준을 설정하지 않으면 `medium`에서 시작하고, 사용자 설정 파일의 최상위 `effortLevel`은 Opus 5.5에 대해 계산되지 않습니다. 해당 키는 Claude Code가 모델별로 수준을 저장하기 전에 `/effort`가 작성한 이전 형식입니다: 이전에 적용된 곳에 계속 적용되며, Opus 5, Fable 5.1 및 이전 모델에서, Opus 5.5 및 이후 릴리스된 모델은 `/effort` 또는 `/model` 선택기로 수준을 선택할 때까지 자신의 기본값에서 시작합니다. 프로젝트, 로컬 또는 관리되는 설정의 최상위 `effortLevel` 또는 `--settings`로 전달된 것은 모든 모델에 적용됩니다.
635 640
636기계에서 대화형 세션에서 `low`, `medium`, `high`, `xhigh`를 설정할 때 확인 방법으로 지속 기간을 선택합니다:641기계에서 대화형 세션에서 `low`, `medium`, `high` 또는 `xhigh`를 설정할 때, 확인 방식으로 지속 기간을 선택합니다:
637 642
638* `/effort` 슬라이더 또는 `/model` 선택기에서 `Enter`, 또는 `/effort` 후에 입력한 수준: 수준을 기본값으로 저장하고 이후 세션에 적용643* `/effort` 슬라이더 또는 `/model` 선택기에서 `Enter`, 또는 `/effort` 후 입력한 수준: 수준을 기본값으로 저장하고 이후 세션에 적용합니다
639* `/effort` 슬라이더 또는 `/model` 선택기에서 `s`: 이 세션에만 수준을 적용합니다. Claude Code v2.1.257 이상이 필요합니다.644* `/effort` 슬라이더 또는 `/model` 선택기에서 `s`: 이 세션에만 수준을 적용합니다. Claude Code v2.1.257 이상이 필요합니다.
640 645
641Claude Code는 사용자 설정의 [`modelSettings`](/docs/ko/settings-reference#modelsettings) 키 아래 모델별로 수준을 저장하므로 각 모델은 자체 저장된 수준을 유지합니다.646Claude Code는 사용자 설정의 [`modelSettings`](/docs/ko/settings-reference#modelsettings) 키 아래에서 모델별로 수준을 저장하므로, 각 모델은 자신의 저장된 수준을 유지합니다.
642 647
643`max`는 가장 깊은 추론 수준입니다. `CLAUDE_CODE_EFFORT_LEVEL` 환경 변수를 통해 설정하지 않는 한 Claude Code는 `max`를 현재 세션에만 적용합니다.648`max`는 가장 깊은 추론 수준입니다. `CLAUDE_CODE_EFFORT_LEVEL` 환경 변수를 통해 설정하지 않으면, Claude Code는 `max`를 현재 세션에만 적용합니다.
644 649
645<Note>650<Note>
646 전화 또는 [원격 제어](/docs/ko/remote-control#what-connected-devices-see)를 통해 연결된 브라우저의 노력 제어에서 선택한 수준은 해당 세션에만 적용됩니다.651 [Remote Control](/docs/ko/remote-control#what-connected-devices-see)을 통해 연결된 휴대폰 또는 브라우저의 노력 제어에서 선택한 수준은 해당 세션에만 적용됩니다.
647</Note>652</Note>
648 653
649<span id="non-interactive-effort" />654<span id="non-interactive-effort" />
650 655
651[`-p` 실행](/docs/ko/headless)에서 `/effort`로 수준을 설정할 때 Claude Code는 이를 해당 세션에만 적용하고 기본값으로 저장하지 않습니다.656[`-p` 실행](/docs/ko/headless)에서 `/effort`로 수준을 설정할 때, Claude Code는 해당 세션에만 적용하고 기본값으로 저장하지 않습니다.
657
658`/effort` 슬라이더에는 **Ultracode** 토글도 있습니다. Ultracode는 모델 노력 수준이 아닌 Claude Code 설정입니다: 켜져 있으면, Claude는 세션이 실행되는 노력 수준에서 실질적인 작업에 대해 [동적 워크플로우](/docs/ko/workflows)를 조율합니다. 지속적으로 설정할 수 있는 위치는 [`ultracode`](/docs/ko/settings-reference#ultracode) 설정을 참조하세요.
652 659
653`/effort` 메뉴는 또한 `ultracode`를 제공합니다. Ultracode는 모델 노력 수준이 아닌 Claude Code 설정입니다: 모델에 `xhigh`를 보내고 추가로 Claude가 실질적인 작업에 대해 [동적 워크플로우](/docs/ko/workflows)를 조율하도록 합니다. 지속적으로 설정할 수 있는 위치는 [`ultracode`](/docs/ko/settings-reference#ultracode) 설정을 참조하세요.660`/effort` 또는 `ultracode` 설정으로 ultracode를 켜거나 끄면 노력 수준은 변경되지 않습니다. `--effort ultracode` 플래그 및 Agent SDK `effortLevel: "ultracode"` 값은 이를 켜고 수준을 `xhigh`로 설정합니다. `/effort` 슬라이더 또는 `/model` 선택기에서 수준을 선택하면 ultracode는 그대로 유지됩니다.
654 661
655다음 중 하나를 통해 ultracode를 켤 수 있습니다:662다음 중 하나를 통해 ultracode를 켤 수 있습니다:
656 663
657* **`/effort`**: `/effort ultracode`를 실행하거나 메뉴에서 선택664* **`/effort`**: 현재 세션에 대해 켜려면 `/effort ultracode`를 실행하거나 끄려면 `/effort ultracode off`를 실행하세요. `/effort` 슬라이더에서 `Tab`을 눌러 **Ultracode** 토글을 뒤집은 다음 `Enter`를 눌러 적용합니다.
658* **`--effort` 플래그**: `claude --effort ultracode`로 시작하여 `xhigh` 노력으로 세션을 시작하고 ultracode를 켭니다.665* **`--effort` 플래그**: `claude --effort ultracode`로 시작하여 `xhigh` 노력과 ultracode가 켜진 상태로 세션을 시작합니다.
659* **`ultracode` 설정**: 설정 파일에서 [`"ultracode": true`](/docs/ko/settings-reference#ultracode)를 설정하거나 `--settings`를 사용하거나 Agent SDK 제어 요청에서 설정합니다. [`applyFlagSettings()`](/docs/ko/agent-sdk/typescript#applyflagsettings) 요청도 `effortLevel: "ultracode"`를 허용합니다.666* **`ultracode` 설정**: 설정 파일, `--settings` 또는 Agent SDK 제어 요청에서 [`"ultracode": true`](/docs/ko/settings-reference#ultracode)를 설정합니다. [`applyFlagSettings()`](/docs/ko/agent-sdk/typescript#applyflagsettings) 요청도 `effortLevel: "ultracode"`를 허용하며, 이는 이를 켜고 노력 수준을 `xhigh`로 설정합니다.
660* **`/model` 선택기**: 모델을 선택하는 동안 화살표 키로 노력 슬라이더를 `ultracode`로 이동합니다. Claude Code는 해당 모델을 기본값으로 저장할 때도 현재 세션에 대해 켭니다.667
668`/effort ultracode off` 형식, 슬라이더 토글 및 `xhigh` 이외의 노력 수준에서 ultracode를 켜진 상태로 유지하려면 Claude Code v2.1.284 이상이 필요합니다. v2.1.284 이전에는 ultracode를 켜면 세션이 `xhigh` 노력으로 설정되고, 다른 수준을 선택하면 꺼지고, `xhigh` 아래의 노력 제한이 이를 사용할 수 없게 만들었습니다.
661 669
662`--effort` 플래그 또는 Agent SDK `effortLevel` 값에 `ultracode`를 전달하려면 Claude Code v2.1.203 이상이 필요합니다. v2.1.203 이전에는 `--effort ultracode`가 `Unknown --effort value 'ultracode'`를 인쇄했고 세션이 기본 노력으로 시작되었습니다.670`--effort` 플래그 또는 Agent SDK `effortLevel` 값에 `ultracode`를 전달하려면 Claude Code v2.1.203 이상이 필요합니다. v2.1.203 이전에는 `--effort ultracode`가 `Unknown --effort value 'ultracode'`를 인쇄했고 세션이 기본 노력으로 시작되었습니다.
663 671
664지속된 `effortLevel` 설정 및 `CLAUDE_CODE_EFFORT_LEVEL` 환경 변수는 `ultracode`를 허용하지 않습니다. `CLAUDE_CODE_EFFORT_LEVEL`이 `xhigh` 이외의 수준으로 설정되면 요청이 해당 수준에서 실행되고 ultracode의 워크플로우 조율은 비활성 상태로 유지됩니다. Ultracode를 선택하면 환경 변수가 세션의 노력을 재정의한다는 경고가 표시됩니다.672지속된 `effortLevel` 설정 및 `CLAUDE_CODE_EFFORT_LEVEL` 환경 변수는 `ultracode`를 허용하지 않습니다. `CLAUDE_CODE_EFFORT_LEVEL` 또는 [노력 제한](#organization-effort-limits)이 세션의 수준을 설정하면, ultracode는 해당 수준에서 켜진 상태로 유지됩니다.
665 673
666<span id="when-ultracode-is-available" />674<span id="when-ultracode-is-available" />
667 675
668Ultracode를 사용할 수 없을 때:676Ultracode는 다음과 같은 경우 사용할 수 없습니다:
669 677
670* [워크플로우가 꺼져 있을 때](/docs/ko/workflows#turn-workflows-off)678* [워크플로우가 꺼짐](/docs/ko/workflows#turn-workflows-off)
671* 모델이 `xhigh` 노력을 지원하지 않음679* 모델이 `xhigh` 노력을 지원하지 않음
672* [노력 제한](#organization-effort-limits)이 모델에 `xhigh` 아래로 적용됨
673 680
674이 경우 `--effort ultracode`는 ultracode를 끄고 모델 및 모든 제한이 허용하는 최고 노력 수준(최대 `xhigh`)에서 세션을 시작합니다.681이 경우 `--effort ultracode`는 모델 및 제한이 허용하는 최고 노력 수준(최대 `xhigh`)에서 ultracode가 꺼진 상태로 세션을 시작합니다.
675 682
676<h4 id="choose-an-effort-level">683<h4 id="choose-an-effort-level">
677 노력 수준 선택684 노력 수준 선택
678</h4>685</h4>
679 686
680각 수준은 토큰 지출을 기능에 대해 교환합니다. 기본값은 대부분의 코딩 작업에 적합합니다. 다른 균형을 원할 때 조정하세요.687각 수준은 토큰 지출을 기능에 대해 거래합니다. 기본값은 대부분의 코딩 작업에 적합합니다. 다른 균형을 원할 때 조정하세요.
681 688
682| 수준 | 사용 시기 |689| 수준 | 사용 시기 |
683| :- | :- |690| :- | :- |
684| `low` | 각 결과를 검토하는 짧은 교환(예: 브레인스토밍, 첫 번째 스케치, 이름 바꾸기와 같은 작은 변경) |691| `low` | 각 결과를 검토하는 빠른 교환(예: 브레인스토밍, 첫 번째 스케치 또는 이름 바꾸기와 같은 작은 변경) |
685| `medium` | 명확한 범위의 일상적인 엔지니어링 작업(예: 새 기능 구현)에 적합합니다. Opus 5.5 및 Sonnet 5.5의 기본값입니다. 다른 모델에서는 일부 지능을 교환할 수 있는 비용에 민감한 작업의 토큰 사용을 줄입니다. |692| `medium` | Opus 5.5 및 Sonnet 5.5의 기본값이며, 명확한 범위의 일상적인 엔지니어링 작업(예: 새 기능 구현)에 적합합니다. 다른 모델에서는 일부 지능을 거래할 수 있는 비용 민감한 작업의 토큰 사용을 줄입니다. |
686| `high` | 검증이 중요하거나 엣지 케이스가 가능한 작업(예: 기존 코드베이스의 버그 수정). Opus 5.5, Sonnet 5.5, Opus 4.7을 제외한 모든 모델의 기본값입니다. |693| `high` | 검증이 중요하거나 엣지 케이스가 가능한 작업(예: 기존 코드베이스의 버그 수정). Opus 5.5, Sonnet 5.5 및 Opus 4.7을 제외한 모든 모델의 기본값 |
687| `xhigh` | 더 높은 토큰 지출로 더 깊은 추론. Opus 4.7의 기본값입니다. |694| `xhigh` | 더 높은 토큰 지출로 더 깊은 추론. Opus 4.7의 기본값 |
688| `max` | 어려운 문제로 Claude가 당신 없이 작업하기를 원하는 경우(예: 보안 취약점 찾기). `max`는 수익 감소를 보일 수 있고 과도한 생각이 발생하기 쉬우므로 광범위하게 채택하기 전에 테스트하세요. |695| `max` | Claude가 당신 없이 작업하기를 원하는 어려운 문제(예: 보안 취약점 찾기). `max`는 수익 감소를 보일 수 있고 과도한 생각에 취약하므로, 광범위하게 채택하기 전에 테스트하세요. |
689| `ultracode` | 각 실질적인 작업에 대해 `xhigh` 메시지별 추론으로 [동적 워크플로우](/docs/ko/workflows)를 계획하는 Claude Code 설정 |696| `ultracode` | 수준이 아닌 Claude Code 설정: 모든 노력 수준에서 각 실질적인 작업에 대해 [동적 워크플로우](/docs/ko/workflows)를 계획합니다. |
690 697
691Opus 5.5 및 Fable 5.1의 테스트에서 Claude는 더 높은 수준에서 더 많은 엣지 케이스를 테스트했고 답변하기 전에 더 많은 작업을 검증했습니다. 또한 더 많은 선택을 독립적으로 했습니다. 더 낮은 수준에서 Claude는 시작점을 더 빨리 반환했으며, 이는 각 결과를 검토하고 다음 단계를 조율하는 작업에 적합합니다. 각 수준에서 실행되는 동일한 작업을 보려면 블로그의 [Claude Code 사용: 노력 지출](https://claude.dev/blog/spending-your-effort/)을 읽으세요.698Opus 5.5 및 Fable 5.1의 테스트에서, Claude는 더 높은 수준에서 더 많은 엣지 케이스를 테스트하고 답변하기 전에 더 많은 작업을 검증했습니다. 또한 더 많은 선택을 독립적으로 했습니다. 더 낮은 수준에서, Claude는 시작점을 더 빨리 반환했으며, 이는 각 결과를 검토하고 다음 단계를 조율하는 작업에 적합합니다. 각 수준에서 실행되는 동일한 작업을 보려면, 블로그의 [Using Claude Code: Spending your effort](https://claude.dev/blog/spending-your-effort/)를 읽으세요.
692 699
693노력 척도는 모델별로 보정되므로 동일한 수준 이름이 모델 전체에서 동일한 기본 값을 나타내지 않습니다.700노력 척도는 모델별로 보정되므로, 동일한 수준 이름이 모델 전체에서 동일한 기본 값을 나타내지 않습니다.
694 701
695Opus 5.5는 [기본적으로 `medium`](#adjust-effort-level)이며, Opus 5의 기본값인 `high`보다 한 수준 아래입니다. Anthropic의 테스트에서 Opus 5.5는 `medium`에서 코딩 및 지식 작업 평가에서 Opus 5를 `high`에서 일치하거나 초과합니다. 주어진 수준에서 Opus 5.5는 턴당 Opus 5보다 더 많이 생각하는 경향이 있습니다. Opus 5에서 Opus 5.5로 이동할 때 Opus 5에서 사용한 수준을 이월하는 대신 `medium`에서 시작하세요. 자신의 작업에 대해 수준을 테스트하려면 Opus 5.5 프롬프팅 가이드의 [노력 보정](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#calibrate-effort)을 참조하세요.702Opus 5.5는 [기본값 `medium`](#adjust-effort-level)으로 시작하며, Opus 5의 기본값 `high`보다 한 수준 아래입니다. Anthropic의 테스트에서, Opus 5.5는 `medium`에서 코딩 및 지식 작업 평가에서 Opus 5를 `high`에서 일치하거나 초과합니다. 주어진 수준에서, Opus 5.5는 Opus 5보다 턴당 더 많이 생각하는 경향이 있습니다. Opus 5에서 Opus 5.5로 이동할 때, Opus 5에서 사용한 수준을 이월하는 대신 `medium`에서 시작하세요. 자신의 작업에 대해 수준을 테스트하려면, Opus 5.5 프롬프팅 가이드의 [Calibrate effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#calibrate-effort)를 참조하세요.
696 703
697<h4 id="use-ultrathink-for-one-off-deep-reasoning">704<h4 id="use-ultrathink-for-one-off-deep-reasoning">
698 일회성 깊은 추론을 위해 ultrathink 사용705 일회성 깊은 추론을 위해 ultrathink 사용
699</h4>706</h4>
700 707
701프롬프트의 어디든 `ultrathink`를 포함하여 해당 턴에서 더 깊은 추론을 요청하세요. 세션 노력 설정을 변경하지 않습니다. Claude Code는 키워드를 인식하고 컨텍스트 내 지시를 추가합니다. API로 전송된 노력 수준은 변경되지 않습니다. Claude Code는 "think", "think hard", "think more"와 같은 다른 구문을 일반 프롬프트 텍스트로 전달하고 키워드로 인식하지 않습니다.708프롬프트의 어디든 `ultrathink`를 포함하여 세션 노력 설정을 변경하지 않고 해당 턴에서 더 깊은 추론을 요청합니다. Claude Code는 키워드를 인식하고 컨텍스트 내 지시를 추가합니다. API로 전송된 노력 수준은 변경되지 않습니다. Claude Code는 "think", "think hard" 및 "think more"와 같은 다른 구문을 일반 프롬프트 텍스트로 전달하고 키워드로 인식하지 않습니다.
702 709
703<h4 id="set-the-effort-level">710<h4 id="set-the-effort-level">
704 노력 수준 설정711 노력 수준 설정
706 713
707다음 중 하나를 통해 노력을 변경할 수 있습니다:714다음 중 하나를 통해 노력을 변경할 수 있습니다:
708 715
709* **`/effort`**: 인터랙티브 슬라이더를 열려면 인수 없이 `/effort`를 실행하거나, 직접 설정하려면 수준 이름 뒤에 `/effort`를 실행하거나, 활성 모델에 대해 저장된 수준을 지우려면 `/effort auto`를 실행하세요. Claude가 작업 중일 때 실행할 수 있으며, Claude Code가 [캐시 경고](/docs/ko/prompt-caching#changing-effort-level)를 표시하면 확인한 후 Claude Code는 새 수준을 턴의 다음 요청에 적용합니다.716* **`/effort`**: 인터랙티브 슬라이더를 열려면 인수 없이 `/effort`를 실행하고, 직접 설정하려면 수준 이름 뒤에 `/effort`를 실행하거나, 활성 모델에 대해 저장된 수준을 지우려면 `/effort auto`를 실행합니다. Claude가 작업 중일 때 실행할 수 있으며, Claude Code가 표시하는 경우 [캐시 경고](/docs/ko/prompt-caching#changing-effort-level)를 확인한 후, Claude Code는 새 수준을 턴의 다음 요청에 적용합니다.
710* **`/model`에서**: 모델을 선택할 때 좌우 화살표 키를 사용하여 노력 슬라이더를 조정합니다.717* **`/model`에서**: 모델을 선택할 때 왼쪽/오른쪽 화살표 키를 사용하여 노력 슬라이더를 조정합니다.
711* **`--effort` 플래그**: Claude Code를 시작할 때 단일 세션에 대해 설정하려면 수준 이름을 전달합니다.718* **`--effort` 플래그**: Claude Code를 시작할 때 단일 세션에 대해 설정하려면 수준 이름을 전달합니다.
712* **환경 변수**: `CLAUDE_CODE_EFFORT_LEVEL`을 수준 이름 또는 `auto`로 설정합니다.719* **환경 변수**: `CLAUDE_CODE_EFFORT_LEVEL`을 수준 이름 또는 `auto`로 설정합니다.
713* **설정**: [`modelSettings`](/docs/ko/settings-reference#modelsettings)에서 모델별 수준을 설정하거나, [`effortLevel`](/docs/ko/settings-reference#effortlevel)을 `low`, `medium`, `high`, `xhigh`로 설정하여 모델 없는 모델의 기본값으로 설정합니다. `max`는 두 키에서 허용되지 않으며, `ultracode`는 자체 [`ultracode`](/docs/ko/settings-reference#ultracode) 키를 가집니다.720* **설정**: [`modelSettings`](/docs/ko/settings-reference#modelsettings)에서 모델별 수준을 설정하거나, [`effortLevel`](/docs/ko/settings-reference#effortlevel)을 `low`, `medium`, `high` 또는 `xhigh`로 설정하여 수준이 없는 모델의 기본값으로 설정합니다. `max`는 두 키에서 수준으로 허용되지 않으며, `ultracode`는 자신의 [`ultracode`](/docs/ko/settings-reference#ultracode) 키를 가집니다.
714* **연결된 장치에서**: [원격 제어](/docs/ko/remote-control#what-connected-devices-see) 세션에서 전화 또는 브라우저의 노력 제어에서 수준을 선택합니다. 수준은 현재 세션에만 적용됩니다. Claude Code v2.1.234 이상이 필요합니다.721* **연결된 장치에서**: [Remote Control](/docs/ko/remote-control#what-connected-devices-see) 세션에서, 휴대폰 또는 브라우저의 노력 제어에서 수준을 선택합니다. 수준은 현재 세션에만 적용됩니다. Claude Code v2.1.234 이상이 필요합니다.
715* **스킬 및 subagent frontmatter**: [스킬](/docs/ko/skills#frontmatter-reference) 또는 [subagent](/docs/ko/sub-agents#supported-frontmatter-fields) markdown 파일에서 `effort`를 설정하여 해당 스킬 또는 subagent가 실행될 때 노력 수준을 재정의합니다.722* **스킬 및 subagent frontmatter**: [스킬](/docs/ko/skills#frontmatter-reference) 또는 [subagent](/docs/ko/sub-agents#supported-frontmatter-fields) markdown 파일에서 `effort`를 설정하여 해당 스킬 또는 subagent가 실행될 때 노력 수준을 재정의합니다.
716 723
717Frontmatter 노력은 해당 스킬 또는 subagent가 활성화될 때 적용되며, 세션 수준을 재정의하지만 환경 변수는 재정의하지 않습니다. [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) 또는 [조직 노력 제한](#organization-effort-limits)은 여전히 스킬 또는 subagent가 실행되는 수준을 제한합니다.724Frontmatter 노력은 해당 스킬 또는 subagent가 활성화될 때 적용되며, 세션 수준을 재정의하지만 환경 변수는 재정의하지 않습니다. [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) 또는 [조직 노력 제한](#organization-effort-limits)은 여전히 스킬 또는 subagent가 실행되는 수준을 제한합니다.
718 725
719[관리되는 설정](/docs/ko/managed-settings)에서 `effortLevel`을 설정하면 Claude Code는 [노력 확인 순서](#adjust-effort-level)의 설정 단계에서 이를 적용하고 사용자는 여전히 `/effort` 또는 `--effort`로 수준을 변경할 수 있습니다. 사용자를 수준 이하로 유지하려면 [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel)을 설정하세요.726[관리되는 설정](/docs/ko/managed-settings)에서 `effortLevel`을 설정하면, Claude Code는 [노력 해결 순서](#adjust-effort-level)의 설정 단계에서 적용하고, 사용자는 여전히 `/effort` 또는 `--effort`로 수준을 변경할 수 있습니다. 사용자를 수준 이하로 유지하려면, [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel)을 설정하세요.
720 727
721노력 슬라이더는 지원되는 모델이 선택되면 `/model`에 나타납니다. 현재 노력 수준은 또한 모델 이름 옆의 세션 헤더에 표시됩니다. 예를 들어 "with low effort"이므로 `/model`을 열지 않고 어떤 설정이 활성화되어 있는지 확인할 수 있습니다. 바닥글은 또한 시작 시 및 변경 시 노력 수준을 간단히 표시합니다.728노력 슬라이더는 지원되는 모델이 선택되었을 때 `/model`에 나타납니다. 현재 노력 수준은 모델 이름 옆의 세션 헤더에도 표시됩니다(예: "with low effort"). 따라서 `/model`을 열지 않고도 어느 설정이 활성화되었는지 확인할 수 있습니다. 바닥글은 시작 시 및 변경 시 노력 수준을 간단히 표시합니다.
722 729
723<h4 id="adaptive-reasoning-and-fixed-thinking-budgets">730<h4 id="adaptive-reasoning-and-fixed-thinking-budgets">
724 적응형 추론 및 고정 생각 예산731 적응형 추론 및 고정 생각 예산
725</h4>732</h4>
726 733
727적응형 추론은 각 단계에서 생각을 선택 사항으로 만들므로 Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻는 단계를 위해 더 깊은 생각을 예약할 수 있습니다. 현재 수준이 생성하는 것보다 Claude가 더 자주 또는 덜 자주 생각하기를 원하면 프롬프트 또는 `CLAUDE.md`에서 직접 말할 수 있습니다. 모델은 노력 설정 내에서 해당 지침에 응답합니다.734적응형 추론은 각 단계에서 생각을 선택 사항으로 만들므로, Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻는 단계를 위해 더 깊은 생각을 예약할 수 있습니다. 현재 수준이 생성하는 것보다 Claude가 더 자주 또는 덜 자주 생각하기를 원하면, 프롬프트 또는 `CLAUDE.md`에서 직접 말할 수 있습니다. 모델은 노력 설정 내에서 해당 지침에 응답합니다.
728 735
729Fable 모델, Sonnet 5 이상, Opus 4.7 이상은 항상 적응형 추론을 사용합니다. 고정 생각 예산 모드 및 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`은 이들에게 적용되지 않습니다.736Fable 모델, Sonnet 5 이상 및 Opus 4.7 이상은 항상 적응형 추론을 사용합니다. 고정 생각 예산 모드 및 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`은 이들에게 적용되지 않습니다.
730 737
731Opus 4.6 및 Sonnet 4.6에서 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`을 설정하여 `MAX_THINKING_TOKENS`로 제어되는 이전 고정 생각 예산으로 되돌릴 수 있습니다. [환경 변수](/docs/ko/env-vars)를 참조하세요.738Opus 4.6 및 Sonnet 4.6에서는 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`을 설정하여 `MAX_THINKING_TOKENS`로 제어되는 이전 고정 생각 예산으로 되돌릴 수 있습니다. [환경 변수](/docs/ko/env-vars)를 참조하세요.
732 739
733<h3 id="extended-thinking">740<h3 id="extended-thinking">
734 확장 생각741 확장 생각
735</h3>742</h3>
736 743
737확장 생각은 Claude가 응답하기 전에 내보내는 추론입니다. [적응형 추론](#adjust-effort-level)을 지원하는 모델에서 노력 수준은 얼마나 많은 생각이 발생하는지에 대한 주요 제어입니다. 아래 설정은 생각을 켜거나 끄고 표시 방법을 제어합니다. Anthropic API에서 생각이 꺼져 있으면 Claude Code는 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) Opus 5와 같은 모델에 더 높은 수준 대신 노력 `high`를 보냅니다.744확장 생각은 Claude가 응답하기 전에 내보내는 추론입니다. [적응형 추론](#adjust-effort-level)을 지원하는 모델에서, 노력 수준은 얼마나 많은 생각이 발생하는지에 대한 주요 제어이며, 아래 설정은 생각을 켜거나 끄고 표시 방식을 제어합니다. Anthropic API에서 생각이 꺼져 있으면, Claude Code는 Opus 5와 같이 [해당 조합을 허용하지 않는](/docs/ko/errors#effort-isnt-available-with-thinking-turned-off) 모델에 더 높은 수준 대신 노력 `high`를 보냅니다.
738 745
739| 제어 | 설정 방법 |746| 제어 | 설정 방법 |
740| :- | :- |747| :- | :- |
741| 현재 세션 토글 | macOS에서 `Option+T` 또는 Windows 및 Linux에서 `Alt+T` 누르기 |748| 현재 세션에 대한 토글 | macOS에서 `Option+T` 또는 Windows 및 Linux에서 `Alt+T`를 누릅니다. |
742| 전역 기본값 설정 | `/config`를 실행하고 생각 모드를 토글합니다. `~/.claude/settings.json`에 `alwaysThinkingEnabled`로 저장됨 |749| 전역 기본값 설정 | `/config`를 실행하고 생각 모드를 토글합니다. `~/.claude/settings.json`에서 `alwaysThinkingEnabled`로 저장됩니다. |
743| 환경 변수를 통해 비활성화 | [`MAX_THINKING_TOKENS=0`](/docs/ko/env-vars)을 설정하여 Anthropic API에서 Opus 5.5, Sonnet 5.5, Fable 모델을 제외한 생각을 끕니다. [타사 제공자](/docs/ko/third-party-integrations)에서 Claude Code는 `thinking` 매개변수를 생략하고 적응형 추론 모델은 여전히 생각할 수 있습니다. 다른 값은 [고정 생각 예산](#adaptive-reasoning-and-fixed-thinking-budgets)에만 적용됩니다. |750| 환경 변수를 통해 비활성화 | [`MAX_THINKING_TOKENS=0`](/docs/ko/env-vars)을 설정하여 Opus 5.5, Sonnet 5.5 및 Fable 모델을 제외한 Anthropic API에서 생각을 끕니다. [제3자 제공자](/docs/ko/third-party-integrations)에서, Claude Code는 `thinking` 매개변수를 생략하고, 적응형 추론 모델은 여전히 생각할 수 있습니다. 다른 값은 [고정 생각 예산](#adaptive-reasoning-and-fixed-thinking-budgets)에만 적용됩니다. |
751
752Opus 5.5, Sonnet 5.5 또는 Fable 모델에서 생각을 끌 수 없습니다. 세션 토글 및 `/config` 행은 스위치를 제공하는 대신 이 모델들에 대해 `Thinking can't be turned off`를 표시하고, 저장된 `alwaysThinkingEnabled: false` 또는 `MAX_THINKING_TOKENS=0`은 여기에 영향을 주지 않습니다. 이 모델들에서, 모델은 노력 수준에 따라 각 단계에서 얼마나 생각할지 결정합니다. 저장된 설정은 이를 허용하는 모델로 전환할 때 다시 적용됩니다.
744 753
745Opus 5.5, Sonnet 5.5, Fable 모델에서 생각을 끌 수 없습니다. 세션 토글, `alwaysThinkingEnabled`, `MAX_THINKING_TOKENS=0`은 효과가 없으며 모델은 노력 수준에 따라 단계별로 얼마나 생각할지 결정합니다.754Claude Code는 기본적으로 생각 출력을 축소합니다. `Ctrl+O`를 눌러 상세 모드를 토글하고 회색 기울임꼴 텍스트로 추론을 봅니다. Anthropic API의 대화형 세션은 기본적으로 편집된 생각 블록을 수신하므로, 확장할 때 전체 요약을 사용 가능하게 하려면 [설정](/docs/ko/settings)에서 `showThinkingSummaries: true`를 설정하세요. 축소되거나 편집된 경우에도 생성된 모든 생각 토큰에 대해 청구됩니다.
746 755
747Claude Code는 기본적으로 생각 출력을 축소합니다. 자세한 모드를 토글하고 회색 기울임꼴 텍스트로 추론을 보려면 `Ctrl+O`를 누르세요. Anthropic API의 대화형 세션은 기본적으로 수정된 생각 블록을 받으므로 확장할 때 전체 요약을 사용 가능하게 하려면 [설정](/docs/ko/settings)에서 `showThinkingSummaries: true`를 설정하세요. 축소되거나 수정되었을 때도 생성된 모든 생각 토큰에 대해 청구됩니다.756<a id="extended-context-with-1m" />
748 757
749<h3 id="extended-context">758<h3 id="extended-context">
750 확장 컨텍스트759 확장 컨텍스트
751</h3>760</h3>
752 761
753Fable 5.1, Fable 5, Sonnet 5 이상, Opus 4.6 이상, Sonnet 4.6은 큰 코드베이스가 있는 긴 세션을 위해 [1백만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 지원합니다.762Fable 5.1, Fable 5, Sonnet 5 이상, Opus 4.6 이상 및 Sonnet 4.6은 큰 코드베이스가 있는 긴 세션을 위해 [1백만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 지원합니다.
754 763
755Anthropic API에서 Fable 5.1, Fable 5, Sonnet 5 이상, Opus 4.7 이상은 모든 플랜(Pro 포함)에서 1M 윈도우로 실행됩니다. 이러한 모델에서 `[1m]` 변형을 선택하거나 1M 윈도우에 대해 사용 크레딧을 켤 필요가 없습니다. Fable 사용 자체는 일부 플랜에서 사용 크레딧으로 청구될 수 있습니다. [Fable 및 사용 크레딧](#fable-and-usage-credits)을 참조하세요.764Anthropic API에서, Fable 5.1, Fable 5, Sonnet 5 이상 및 Opus 4.7 이상은 Pro를 포함한 모든 플랜에서 1M 윈도우로 실행됩니다. 이 모델들에서 `[1m]` 변형을 선택하거나 1M 윈도우에 대해 사용 크레딧을 켤 필요가 없습니다. Fable 사용 자체는 일부 플랜에서 사용 크레딧으로 청구될 수 있습니다. [Fable 및 사용 크레딧](#fable-and-usage-credits)을 참조하세요.
756 765
757Opus 4.6 및 Sonnet 4.6은 `[1m]` 변형을 통해서만 1M에 도달하며, 해당 변형에 대한 액세스는 플랜에 따라 다릅니다. Max, Team, Enterprise 플랜(Team Standard 및 Team Premium 좌석 모두 포함)에서 1M 컨텍스트가 있는 Opus 4.6은 구독에 포함됩니다. 1M 컨텍스트가 있는 Sonnet 4.6은 Max를 포함한 모든 구독 플랜에서 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 필요합니다.766Opus 4.6 및 Sonnet 4.6은 `[1m]` 변형을 통해서만 1M에 도달하며, 해당 변형에 대한 액세스는 플랜에 따라 다릅니다. Max, Team 및 Enterprise 플랜(Team Standard 및 Team Premium 좌석 모두 포함)에서, 1M 컨텍스트가 있는 Opus 4.6은 구독에 포함됩니다. 1M 컨텍스트가 있는 Sonnet 4.6은 모든 구독 플랜(Max 포함)에서 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 필요합니다.
758 767
759| 플랜 | 1M 컨텍스트가 있는 Opus 4.6 | 1M 컨텍스트가 있는 Sonnet 4.6 |768| 플랜 | 1M 컨텍스트가 있는 Opus 4.6 | 1M 컨텍스트가 있는 Sonnet 4.6 |
760| - | - | - |769| - | - | - |
761| Max, Team, Enterprise | 구독에 포함됨 | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 |770| Max, Team 및 Enterprise | 구독에 포함됨 | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 |
762| Pro | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 |771| Pro | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 |
763| API 및 종량제 | 전체 액세스 | 전체 액세스 |772| API 및 종량제 | 전체 액세스 | 전체 액세스 |
764 773
765Claude Code는 Anthropic API에 직접 연결할 때만 이러한 플랜 요구 사항을 확인합니다. `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway#subscriptions-and-gateways)로 지정하고 저장된 claude.ai 로그인이 활성 자격증으로 유지되면 Claude Code는 계정의 사용 크레딧을 확인하지 않습니다. `/model`의 `[1m]` 옵션은 사용 가능하게 유지되고 게이트웨이가 요청 성공 여부를 결정합니다. v2.1.229 이전에는 Claude Code가 계정의 사용 크레딧을 확인할 수 없을 때 해당 구성에서 `/model sonnet[1m]`을 거부했습니다.774Claude Code는 Anthropic API에 직접 연결할 때만 이러한 플랜 요구 사항을 확인합니다. 저장된 claude.ai 로그인이 활성 자격증으로 유지되는 동안 `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이](/docs/ko/llm-gateway#subscriptions-and-gateways)로 지정하면, Claude Code는 계정의 사용 크레딧을 확인하지 않습니다. `[1m]` 옵션은 `/model`에서 사용 가능하게 유지되고, 게이트웨이는 요청이 성공하는지 결정합니다. v2.1.229 이전에는 Claude Code가 해당 구성에서 사용 크레딧을 확인할 수 없을 때 `/model sonnet[1m]`을 거부했습니다.
766 775
7671M 컨텍스트를 끄려면 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`을 설정하세요. Claude Code는 모델 선택기에서 1M 모델 변형을 제거합니다. Sonnet 5 및 Fable 모델과 같은 기본 1M 윈도우가 있는 모델에서 모델을 200K 컨텍스트 윈도우로 취급합니다:7761M 컨텍스트를 끄려면, `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`을 설정하세요. Claude Code는 모델 선택기에서 1M 모델 변형을 제거합니다. Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델에서, 모델을 200K 컨텍스트 윈도우로 취급합니다:
768 777
769* 자동 압축이 켜져 있으면 세션은 [자동 압축](#set-the-auto-compact-window)을 통해 200K 경계에서 압축합니다. 자동 압축 윈도우를 200K 위로 설정해도 유지가 해제되지 않습니다. Claude Code는 해당 윈도우를 모델의 컨텍스트 윈도우로 제한하기 때문입니다.778* 자동 압축이 켜져 있으면, 세션은 [자동 압축](#set-the-auto-compact-window)을 통해 200K 경계에서 압축됩니다. 자동 압축 윈도우를 200K 위로 설정해도 보류를 해제하지 않습니다. Claude Code는 해당 윈도우를 모델의 컨텍스트 윈도우로 제한하기 때문입니다.
770* 자동 압축이 꺼져 있으면 세션은 압축 대신 200K 경계에서 [컨텍스트 제한 오류](/docs/ko/errors#prompt-is-too-long)로 중지됩니다.779* 자동 압축이 꺼져 있으면, 세션은 압축하는 대신 200K 경계에서 [컨텍스트 제한 오류](/docs/ko/errors#prompt-is-too-long)로 중지됩니다.
771 780
772v2.1.223 이전에는 Claude Code가 Sonnet 5, Opus 4.8, Opus 5 세션만 200K로 유지했습니다. [환경 변수](/docs/ko/env-vars)를 참조하세요.781v2.1.223 이전에는 Claude Code가 Sonnet 5, Opus 4.8 및 Opus 5 세션만 200K로 유지했습니다. [환경 변수](/docs/ko/env-vars)를 참조하세요.
773 782
7741M 컨텍스트 윈도우는 200K를 초과하는 토큰에 대한 프리미엄 없이 표준 모델 가격을 사용합니다. 확장 컨텍스트가 구독에 포함된 플랜의 경우 사용량은 구독으로 계속 적용됩니다. 확장 컨텍스트에 사용 크레딧을 통해 액세스하는 플랜의 경우 토큰은 사용 크레딧으로 청구됩니다.7831M 컨텍스트 윈도우는 200K를 초과하는 토큰에 대한 프리미엄 없이 표준 모델 가격을 사용합니다. 확장 컨텍스트가 구독에 포함된 플랜의 경우, 사용은 구독으로 계속 적용됩니다. 확장 컨텍스트에 사용 크레딧을 통해 액세스하는 플랜의 경우, 토큰은 사용 크레딧으로 청구됩니다.
775 784
776계정이 1M 컨텍스트를 지원하면 최신 버전의 Claude Code에서 `/model` 선택기에 옵션이 나타납니다. 보이지 않으면 세션을 다시 시작해 보세요.785계정이 1M 컨텍스트를 지원하면, 옵션이 최신 버전의 Claude Code의 `/model` 선택기에 나타납니다. 보이지 않으면, 세션을 다시 시작하고, 제3자 제공자에서 배포가 `ANTHROPIC_DEFAULT_*_MODEL` 변수로 [모델을 고정](#pin-models-for-third-party-deployments)했는지 확인하세요.
777 786
778모델 별칭 또는 전체 모델 이름과 함께 `[1m]` 접미사를 사용할 수도 있습니다:787모델 별칭 또는 전체 모델 이름으로 `[1m]` 접미사를 사용할 수도 있습니다:
779 788
780```text theme={null}789```text theme={null}
781# opus[1m] 또는 sonnet[1m] 별칭 사용790# opus[1m] 또는 sonnet[1m] 별칭 사용
790 Sonnet 5.5 및 Sonnet 5 컨텍스트 윈도우799 Sonnet 5.5 및 Sonnet 5 컨텍스트 윈도우
791</h4>800</h4>
792 801
793Anthropic API에서 Sonnet 5.5 및 Sonnet 5는 항상 1M 컨텍스트 윈도우로 실행됩니다. 200K 변형이 없고, 선택할 `[1m]` 접미사가 없으며, 어떤 플랜에서도 사용 크레딧이 필요하지 않습니다. 세션은 윈도우가 채워지기 전에 자동 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/ko/env-vars)를 설정하여 다른 임계값을 선택하세요.802Anthropic API에서, Sonnet 5.5 및 Sonnet 5는 항상 1M 컨텍스트 윈도우로 실행됩니다. 200K 변형이 없고, 선택할 `[1m]` 접미사가 없으며, 어떤 플랜에서도 사용 크레딧이 필요하지 않습니다. 세션은 윈도우가 채워지기 전에 자동 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/ko/env-vars)를 설정하여 다른 임계값을 선택합니다.
794 803
795두 가지 구성이 윈도우를 200K로 예산합니다:804두 가지 구성이 윈도우를 200K로 예산합니다:
796 805
797* **LLM 게이트웨이**: `ANTHROPIC_BASE_URL`이 [게이트웨이](/docs/ko/llm-gateway)를 가리킬 때 Claude Code는 1M 지원을 확인할 수 없습니다. 전체 윈도우를 사용하려면 모델 선택기에서 Sonnet 5.5 (1M context)를 선택하세요. 이는 `sonnet[1m]`으로 매핑됩니다. 또는 Sonnet 5의 경우 `/model claude-sonnet-5[1m]`을 실행하세요.806* **LLM 게이트웨이**: `ANTHROPIC_BASE_URL`이 [게이트웨이](/docs/ko/llm-gateway)를 가리킬 때, Claude Code는 1M 지원을 확인할 수 없습니다. 전체 윈도우를 사용하려면, 모델 선택기에서 Sonnet 5.5(1M context)를 선택하세요. 이는 `sonnet[1m]`으로 매핑되거나, Sonnet 5의 경우 `/model claude-sonnet-5[1m]`을 실행합니다.
798* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**: 기본 1M 윈도우가 있는 모든 모델의 세션을 200K 윈도우로 유지합니다. [확장 컨텍스트](#extended-context)에서 유지가 강제되는 방법을 참조하세요. 컨텍스트를 제한해야 하는 배포에 유용합니다.807* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**: 기본 1M 윈도우가 있는 모든 모델의 세션을 200K 윈도우로 유지합니다. [확장 컨텍스트](#extended-context)에서 보류가 적용되는 방식을 참조하세요. 컨텍스트를 제한해야 하는 배포에 유용합니다.
799 808
800<h2 id="context-window-and-auto-compaction">809<h2 id="context-window-and-auto-compaction">
801 컨텍스트 윈도우 및 자동 압축810 컨텍스트 윈도우 및 자동 압축
945* 기본 모델이 1M 컨텍스트를 [지원할 때만](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) `[1m]`을 추가합니다.954* 기본 모델이 1M 컨텍스트를 [지원할 때만](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) `[1m]`을 추가합니다.
946* 접미사는 모델별이 아닌 변수별로 읽혀집니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서 한 변수의 `[1m]` 없는 모델 ID는 다른 변수가 접미사와 함께 동일한 모델을 설정하더라도 200K 컨텍스트를 사용합니다. Sonnet 5는 항상 이러한 제공자에서 1M 윈도우로 실행되며 접미사가 필요하지 않습니다.955* 접미사는 모델별이 아닌 변수별로 읽혀집니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서 한 변수의 `[1m]` 없는 모델 ID는 다른 변수가 접미사와 함께 동일한 모델을 설정하더라도 200K 컨텍스트를 사용합니다. Sonnet 5는 항상 이러한 제공자에서 1M 윈도우로 실행되며 접미사가 필요하지 않습니다.
947 956
957`ANTHROPIC_DEFAULT_*_MODEL` 변수를 설정하면 `/model` 선택기는 패밀리의 기본 제공 행 대신 해당 모델에 대한 하나의 행을 표시하며, 1M 컨텍스트 행을 포함합니다. 해당 변수에 접미사를 추가하지 않고 1M 윈도우에 도달하려면 사용자가 `/model opus[1m]`을 실행하고, Claude Code는 변수가 이름을 지정하는 모델에 접미사를 적용합니다. `/model sonnet[1m]`도 동일한 방식으로 작동합니다.
958
948<Note>959<Note>
949 [MDM 또는 관리 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)을 통해 전달된 `availableModels` 허용 목록은 타사 제공자를 사용할 때도 여전히 적용됩니다. [서버 관리 설정은 그곳에 전달되지 않습니다](/docs/ko/server-managed-settings#platform-availability).960 [MDM 또는 관리 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)을 통해 전달된 `availableModels` 허용 목록은 타사 제공자를 사용할 때도 여전히 적용됩니다. [서버 관리 설정은 그곳에 전달되지 않습니다](/docs/ko/server-managed-settings#platform-availability).
950 961
1042| - | - |1053| - | - |
1043| `DISABLE_PROMPT_CACHING` | 모든 모델에 대해 prompt caching을 비활성화하려면 `1`로 설정합니다. 모델별 설정보다 우선합니다. |1054| `DISABLE_PROMPT_CACHING` | 모든 모델에 대해 prompt caching을 비활성화하려면 `1`로 설정합니다. 모델별 설정보다 우선합니다. |
1044| `DISABLE_PROMPT_CACHING_HAIKU` | [기본 Haiku 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 prompt caching을 비활성화하려면 `1`로 설정합니다. |1055| `DISABLE_PROMPT_CACHING_HAIKU` | [기본 Haiku 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 prompt caching을 비활성화하려면 `1`로 설정합니다. |
1045| `DISABLE_PROMPT_CACHING_SONNET` | Sonnet 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |1056| `DISABLE_PROMPT_CACHING_SONNET` | [기본 Sonnet 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 prompt caching을 비활성화하려면 `1`로 설정합니다. |
1046| `DISABLE_PROMPT_CACHING_OPUS` | Opus 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |1057| `DISABLE_PROMPT_CACHING_OPUS` | [기본 Opus 모델](/docs/ko/prompt-caching#disable-prompt-caching)에 대해 prompt caching을 비활성화하려면 `1`로 설정합니다. |
1047| `DISABLE_PROMPT_CACHING_FABLE` | Fable 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |1058| `DISABLE_PROMPT_CACHING_FABLE` | Fable 모델에 대해서만 prompt caching을 비활성화하려면 `1`로 설정합니다. |
1048 1059
1049메인 대화와 subagents에 대해 캐시 TTL을 별도로 선택하려면 [TTL을 직접 선택](/docs/ko/prompt-caching#choose-the-ttl-yourself)을 참조하세요. 캐시 미스를 트리거하는 것이 무엇인지 알아보려면 [Claude Code가 prompt caching을 사용하는 방법](/docs/ko/prompt-caching)을 참조하세요.1060메인 대화와 subagents에 대해 캐시 TTL을 별도로 선택하려면 [TTL을 직접 선택](/docs/ko/prompt-caching#choose-the-ttl-yourself)을 참조하세요. 캐시 미스를 트리거하는 것이 무엇인지 알아보려면 [Claude Code가 prompt caching을 사용하는 방법](/docs/ko/prompt-caching)을 참조하세요.
