> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 모든 설정

> Claude Code settings.json의 모든 키에 대한 완전한 참조: 각 키의 위치, 유형 및 기본값, 붙여넣기 가능한 예제, 모든 키의 인덱스.

[인덱스로 돌아가기](#all-settings)

이 참조 페이지는 Claude Code가 설정 파일에서 읽는 각 키와 대신 `~/.claude.json`에 유지하는 [짧은 키 그룹](#global-config-settings)을 나열합니다. 파일을 선택하거나 우선순위를 확인하려면 [설정 파일 및 우선순위](https://code.claude.com/docs/ko/settings.md)에서 시작하십시오.

## 설정 색인

아래의 각 키는 해당 항목으로 연결됩니다. 범위는 키를 넣을 수 있는 [파일](https://code.claude.com/docs/ko/settings.md#settings-files-and-who-they-affect)을 나타냅니다. `사용자`는 `~/.claude/settings.json`, `프로젝트`는 `.claude/settings.json`, `로컬`은 `.claude/settings.local.json`, `관리형`은 [조직이 배포하는 설정](https://code.claude.com/docs/ko/managed-settings.md)입니다. `모든 파일`은 네 가지 모두를 의미하며, `전역 구성`은 [`~/.claude.json`](#global-config-settings)을 의미합니다.

| Key | Description | Topic | Scope |
| :- | :- | :- | :- |
| [`advisorModel`](#advisormodel) | Claude가 [advisor 도구](https://code.claude.com/docs/ko/advisor.md)에 질문할 때 답변할 모델을 선택합니다 | 모델 및 응답 | 모든 파일 |
| [`agent`](#agent) | 모든 세션을 프롬프트, 도구, 모델을 갖춘 지정된 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)로 시작합니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`agentPushNotifEnabled`](#agentpushnotifenabled) | Claude가 필요하다고 판단할 때 [휴대폰으로 푸시 알림](https://code.claude.com/docs/ko/remote-control.md#mobile-push-notifications)을 보낼 수 있도록 합니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`allowAllClaudeAiMcps`](#allowallclaudeaimcps) | 배포된 [`managed-mcp.json`](https://code.claude.com/docs/ko/managed-mcp#exclusive-control-with-managed-mcp-json)과 함께 Claude Code가 직접 가져오는 [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md)를 로드합니다 | MCP | 관리형 |
| [`allowClaudeInChromeWithManagedMcp`](#allowclaudeinchromewithmanagedmcp) | 배포된 [`managed-mcp.json`](https://code.claude.com/docs/ko/managed-mcp#exclusive-control-with-managed-mcp-json)과 함께 기본 제공 [Claude in Chrome](https://code.claude.com/docs/ko/chrome.md) 서버를 실행할 수 있도록 합니다 | MCP | 관리형 |
| [`allowedChannelPlugins`](#allowedchannelplugins) | 메시지를 푸시할 수 있는 [채널 플러그인](https://code.claude.com/docs/ko/channels.md#restrict-which-channel-plugins-can-run)의 기본 허용 목록을 대체합니다 | 플러그인 및 스킬 | 관리형 |
| [`allowedHttpHookUrls`](#allowedhttphookurls) | [HTTP 훅](https://code.claude.com/docs/ko/hooks.md)이 대상으로 삼을 수 있는 URL을 제한합니다 | 훅 및 자동화 | 모든 파일 |
| [`allowedMcpServers`](#allowedmcpservers) | 사용자가 추가할 수 있는 [MCP 서버](https://code.claude.com/docs/ko/mcp.md)를 허용 목록으로 지정합니다 | MCP | 모든 파일 |
| [`allowedProviders`](#allowedproviders) | 머신에서 사용할 수 있는 [API 제공자](https://code.claude.com/docs/ko/third-party-integrations.md)를 제한합니다 | 인증 및 제공자 | 관리형 |
| [`allowManagedHooksOnly`](#allowmanagedhooksonly) | 조직이 배포한 [훅](https://code.claude.com/docs/ko/hooks.md)만 실행합니다 | 훅 및 자동화 | 관리형 |
| [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) | 관리형 [MCP](https://code.claude.com/docs/ko/mcp.md) 허용 목록만 적용되도록 합니다 | MCP | 관리형 |
| [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly) | [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)을 [권한 규칙](https://code.claude.com/docs/ko/permissions.md#managed-settings)의 유일한 설정 소스로 지정합니다 | 권한 설정 | 관리형 |
| [`alwaysThinkingEnabled`](#alwaysthinkingenabled) | 모든 세션에서 [확장 사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking)를 끕니다 | 모델 및 응답 | 모든 파일 |
| [`apiKeyHelper`](#apikeyhelper) | 직접 지정한 명령으로 [API 자격 증명](https://code.claude.com/docs/ko/authentication.md#credential-management)을 생성합니다 | 인증 및 제공자 | 모든 파일 |
| [`askUserQuestionTimeout`](#askuserquestiontimeout) | 답변되지 않은 질문이 유휴 시간 후 [자동으로 계속](https://code.claude.com/docs/ko/tools-reference.md#question-auto-continue-timeout)되도록 합니다 | 인터페이스 및 터미널 | 사용자 또는 관리형 |
| [`appendPlugins`](#appendplugins) | 사용자가 설치한 모든 mod 다음에 조직의 [mod](https://code.claude.com/docs/ko/plugins/mods/admin.md)를 실행합니다 | 플러그인 및 스킬 | 사용자 또는 관리형 |
| [`attribution`](#attribution) | Claude Code가 커밋과 풀 리퀘스트에 추가하는 작성자 표시를 사용자 지정합니다 | Git 및 작성자 표시 | 모든 파일 |
| [`attribution.commit`](#attribution-commit) | Claude Code가 커밋에 추가하는 트레일러를 변경하거나 숨깁니다 | Git 및 작성자 표시 | 모든 파일 |
| [`attribution.pr`](#attribution-pr) | 풀 리퀘스트 설명의 작성자 표시 줄을 변경하거나 숨깁니다 | Git 및 작성자 표시 | 모든 파일 |
| [`attribution.sessionUrl`](#attribution-sessionurl) | [클라우드](https://code.claude.com/docs/ko/claude-code-on-the-web.md) 및 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 커밋에서 claude.ai 세션 링크를 생략합니다 | Git 및 작성자 표시 | 모든 파일 |
| [`autoCompactEnabled`](#autocompactenabled) | [자동 압축](https://code.claude.com/docs/ko/context-window.md)을 끄거나 켭니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`autoCompactWindow`](#autocompactwindow) | Claude Code가 [압축](https://code.claude.com/docs/ko/context-window.md)하기 전에 컨텍스트가 얼마나 찰지 설정합니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`autoConnectIde`](#autoconnectide) | 외부 터미널에서 실행 중인 [VS Code](https://code.claude.com/docs/ko/vs-code.md) 또는 [JetBrains](https://code.claude.com/docs/ko/jetbrains.md#from-external-terminals) IDE에 자동으로 연결합니다 | 전역 구성 설정 | 전역 구성 |
| [`autoContinueAtUsageLimit`](#autocontinueatusagelimit) | 열린 세션에서 대기하다가 claude.ai 사용 한도가 재설정된 후 [작업을 자동으로 계속](https://code.claude.com/docs/ko/interactive-mode.md#wait-for-a-usage-limit-to-reset)합니다 | 인터페이스 및 터미널 | 사용자 또는 관리형 |
| [`autoInstallIdeExtension`](#autoinstallideextension) | VS Code 터미널에서 [IDE 확장 프로그램](https://code.claude.com/docs/ko/vs-code.md#install-the-extension)의 자동 설치를 끕니다 | 전역 구성 설정 | 전역 구성 |
| [`autoMemoryDirectory`](#automemorydirectory) | [자동 메모리](https://code.claude.com/docs/ko/memory.md#auto-memory)를 원하는 디렉터리에 저장합니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`autoMemoryEnabled`](#automemoryenabled) | [자동 메모리](https://code.claude.com/docs/ko/memory.md#auto-memory)를 끄거나 켭니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`autoMode`](#automode) | [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 분류기에 자체 허용 및 거부 규칙을 추가합니다 | 권한 설정 | 사용자 또는 관리형 |
| [`autoMode.classifyAllShell`](#automode-classifyallshell) | 좁은 범위의 허용 규칙과 일치하는 명령을 포함하여 모든 셸 명령을 [자동 모드 분류기](https://code.claude.com/docs/ko/permission-modes.md#what-the-classifier-blocks-by-default)로 보냅니다 | 권한 설정 | 사용자 또는 관리형 |
| [`autoScrollEnabled`](#autoscrollenabled) | 전체 화면 렌더링에서 [새 출력을 따라](https://code.claude.com/docs/ko/fullscreen.md#auto-follow) 맨 아래로 이동합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`autoUpdatesChannel`](#autoupdateschannel) | latest 대신 stable [릴리스 채널](https://code.claude.com/docs/ko/setup.md#configure-release-channel)을 따릅니다 | 업데이트 및 버전 관리 | 모든 파일 |
| [`availableModels`](#availablemodels) | 사용자가 선택할 수 있는 [모델을 제한](https://code.claude.com/docs/ko/model-config.md#restrict-model-selection)합니다 | 모델 및 응답 | 모든 파일 |
| [`availableModelsMatch`](#availablemodelsmatch) | 각 `availableModels` 모델 ID 항목이 [지정한 버전만 허용](https://code.claude.com/docs/ko/model-config.md#block-specific-models-or-versions)하도록 합니다 | 모델 및 응답 | 관리형 |
| [`awaySummaryEnabled`](#awaysummaryenabled) | 터미널로 돌아왔을 때 표시되는 [세션 요약](https://code.claude.com/docs/ko/interactive-mode.md#session-recap)을 끕니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`awsAuthRefresh`](#awsauthrefresh) | 직접 지정한 명령으로 `.aws`의 만료된 [Bedrock 자격 증명](https://code.claude.com/docs/ko/amazon-bedrock.md#advanced-credential-configuration)을 갱신합니다 | 인증 및 제공자 | 모든 파일 |
| [`awsCredentialExport`](#awscredentialexport) | 직접 지정한 명령에서 [Bedrock 자격 증명](https://code.claude.com/docs/ko/amazon-bedrock.md#advanced-credential-configuration)을 JSON으로 제공합니다 | 인증 및 제공자 | 모든 파일 |
| [`axScreenReader`](#axscreenreader) | [스크린 리더 친화적인 출력](https://code.claude.com/docs/ko/accessibility.md)을 렌더링합니다 | 인터페이스 및 터미널 | 사용자 또는 관리형 |
| [`bashEditDiffEnabled`](#basheditdiffenabled) | 모든 권한 모드에서 [Bash 명령 실행 중 변경된 파일](https://code.claude.com/docs/ko/hooks.md#bash)을 기록합니다 | 인터페이스 및 터미널 | 사용자 또는 관리형 |
| [`bashOutputMaxChars`](#bashoutputmaxchars) | 성공한 명령의 [출력](https://code.claude.com/docs/ko/tools-reference.md#output-limits) 중 Claude가 인라인으로 받는 양을 설정합니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`blockedMarketplaces`](#blockedmarketplaces) | 조직의 [플러그인 마켓플레이스](https://code.claude.com/docs/ko/plugins/overview.md) 소스를 차단합니다 | 플러그인 및 스킬 | 관리형 |
| [`browserExternalPageTools`](#browserexternalpagetools) | [데스크톱](https://code.claude.com/docs/ko/desktop.md) Browser 창의 외부 페이지에서 Claude의 도구를 사용하지 못하도록 합니다 | 도구 | 관리형 |
| [`channelsEnabled`](#channelsenabled) | 조직에서 [채널](https://code.claude.com/docs/ko/channels.md#enable-channels-for-your-organization)을 허용합니다 | 플러그인 및 스킬 | 관리형 |
| [`claudeInChromeDefaultEnabled`](#claudeinchromedefaultenabled) | 대화형 CLI와 VS Code 확장 프로그램에서 세션이 시작될 때 [Chrome 통합](https://code.claude.com/docs/ko/chrome.md)을 켭니다 | 전역 구성 설정 | 전역 구성 |
| [`claudeMd`](#claudemd) | 관리형 설정에서 조직 전체 [CLAUDE.md](https://code.claude.com/docs/ko/memory.md#deploy-organization-wide-claude-md) 지침을 주입합니다 | 메모리 및 컨텍스트 | 관리형 |
| [`claudeMdExcludes`](#claudemdexcludes) | 메모리를 로드할 때 특정 [CLAUDE.md](https://code.claude.com/docs/ko/memory.md#exclude-specific-claude-md-files) 파일을 건너뜁니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`cleanupPeriodDays`](#cleanupperioddays) | Claude Code가 [트랜스크립트](https://code.claude.com/docs/ko/data-usage.md#data-retention)를 삭제하기 전에 보관할 일수를 선택합니다 | 개인정보 보호 및 텔레메트리 | 모든 파일 |
| [`companyAnnouncements`](#companyannouncements) | 시작 시 조직의 공지 사항을 표시합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`copyFullResponse`](#copyfullresponse) | [`/copy`](https://code.claude.com/docs/ko/commands)가 선택기를 표시하지 않고 전체 응답을 복사하도록 합니다 | 전역 구성 설정 | 전역 구성 |
| [`copyOnSelect`](#copyonselect) | [전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md#use-the-mouse) 및 에이전트 뷰에서 마우스로 선택한 텍스트의 자동 복사를 끕니다 | 전역 구성 설정 | 전역 구성 |
| [`crossSessionInbound`](#crosssessioninbound) | Claude Code가 [다른 세션의 메시지](https://code.claude.com/docs/ko/cross-session-messaging.md#control-inbound-messages)를 전달할지, 전달하지 않고 알림만 표시할지, 거부할지 선택합니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`defaultShell`](#defaultshell) | [`!` 접두사](https://code.claude.com/docs/ko/interactive-mode#shell-mode-with-prefix)로 입력한 셸 명령을 Bash와 PowerShell 중 무엇으로 실행할지 선택합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`defaultToAgentsView`](#defaulttoagentsview) | 인수 없이 `claude`를 실행할 때 새 대화 대신 [에이전트 뷰](https://code.claude.com/docs/ko/agent-view.md)를 엽니다 | 전역 구성 설정 | 전역 구성 |
| [`deniedMcpServers`](#deniedmcpservers) | URL, 명령 또는 이름으로 특정 [MCP 서버](https://code.claude.com/docs/ko/mcp.md)를 차단합니다 | MCP | 모든 파일 |
| [`deniedModels`](#deniedmodels) | `availableModels`가 허용하는 모델이라도 [특정 모델을 차단](https://code.claude.com/docs/ko/model-config.md#block-specific-models-or-versions)합니다 | 모델 및 응답 | 관리형 |
| [`desktopSessionCleanupPeriodDays`](#desktopsessioncleanupperioddays) | [Claude Desktop 및 Cowork 트랜스크립트](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)의 보관 기한을 일 단위로 설정합니다 | 개인정보 보호 및 텔레메트리 | 사용자 또는 관리형 |
| [`dialogExpiry`](#dialogexpiry) | [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 또는 SDK 호스트가 전달된 대화상자에 응답할 때까지 Claude Code가 대화상자를 취소하기 전에 기다리는 시간을 설정합니다 | 인터페이스 및 터미널 | 사용자 또는 관리형 |
| [`diffTool`](#difftool) | Claude가 제안한 파일 변경 사항을 [VS Code](https://code.claude.com/docs/ko/vs-code.md) 또는 [JetBrains](https://code.claude.com/docs/ko/jetbrains.md#features) diff 뷰어에서 열지, 터미널에 그대로 둘지 선택합니다 | 전역 구성 설정 | 전역 구성 |
| [`disableAgentView`](#disableagentview) | 백그라운드 에이전트와 [에이전트 뷰](https://code.claude.com/docs/ko/agent-view.md)를 끕니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`disableAllHooks`](#disableallhooks) | [훅](https://code.claude.com/docs/ko/hooks.md), 사용자 지정 [상태줄](https://code.claude.com/docs/ko/statusline.md), 사용자 지정 [`@` 파일 제안](https://code.claude.com/docs/ko/interactive-mode#quick-commands) 명령을 한 번에 끕니다 | 훅 및 자동화 | 모든 파일 |
| [`disableArtifact`](#disableartifact) | deprecated 되었습니다. [Artifact 도구](https://code.claude.com/docs/ko/artifacts.md)를 끄려면 `enableArtifact`를 사용합니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`disableAutoMode`](#disableautomode) | 권한 모드 순환에서 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode)를 제거합니다 | 권한 설정 | 모든 파일 |
| [`disableBrowserExternalNavigation`](#disablebrowserexternalnavigation) | 사람과 Claude 모두 localhost에만 접근할 수 있도록 [데스크톱](https://code.claude.com/docs/ko/desktop.md) Browser 창을 제한합니다 | 도구 | 관리형 |
| [`disableBundledSkills`](#disablebundledskills) | Claude Code에 포함된 [스킬](https://code.claude.com/docs/ko/skills.md#bundled-skills)과 [워크플로](https://code.claude.com/docs/ko/workflows.md)를 끕니다 | 플러그인 및 스킬 | 모든 파일 |
| [`disableClaudeAiConnectors`](#disableclaudeaiconnectors) | Claude Code가 [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#disable-claude-ai-connectors)를 가져오지 않도록 커넥터를 끕니다 | MCP | 모든 파일 |
| [`disableCommandPluginSources`](#disablecommandpluginsources) | 마켓플레이스에서 선언한 명령을 실행하여 설치하는 [플러그인](https://code.claude.com/docs/ko/plugins/overview.md)을 차단합니다 | 플러그인 및 스킬 | 관리형 |
| [`disableDeepLinkRegistration`](#disabledeeplinkregistration) | Claude Code가 [`claude-cli://` 핸들러](https://code.claude.com/docs/ko/deep-links)를 등록하지 않도록 합니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`disableDesktopLocalSessions`](#disabledesktoplocalsessions) | 기기에서 실행되는 [Desktop Code 세션](https://code.claude.com/docs/ko/desktop.md#local-sessions-on-managed-devices)을 끄고, 다른 호스트로의 SSH와 클라우드만 남깁니다 | 원격, 데스크톱 및 알림 | 관리형 |
| [`disabledMcpjsonServers`](#disabledmcpjsonservers) | 프로젝트의 [`.mcp.json`](https://code.claude.com/docs/ko/mcp#project-scope)에서 특정 서버를 거부합니다 | MCP | 모든 파일 |
| [`disableMobileSimulatorTools`](#disablemobilesimulatortools) | [데스크톱](https://code.claude.com/docs/ko/desktop.md) iOS Simulator 창에서 Claude의 도구를 차단합니다 | 도구 | 관리형 |
| [`disableRemoteControl`](#disableremotecontrol) | [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 시작할 수 있는 모든 곳에서 끕니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`disableSideloadFlags`](#disablesideloadflags) | [플러그인](https://code.claude.com/docs/ko/plugins/overview.md), [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md), [MCP 서버](https://code.claude.com/docs/ko/mcp.md)를 사이드로드하는 CLI 플래그를 거부합니다 | 엔터프라이즈 및 관리형 설정 | 관리형 |
| [`disableSkillShellExecution`](#disableskillshellexecution) | [스킬](https://code.claude.com/docs/ko/skills.md)과 사용자 지정 명령이 인라인 셸을 실행하지 않도록 합니다 | 플러그인 및 스킬 | 모든 파일 |
| [`disableWorkflows`](#disableworkflows) | 모든 사용자의 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)를 끕니다. 본인에게만 적용하려면 `enableWorkflows`를 사용합니다 | 훅 및 자동화 | 모든 파일 |
| [`editorMode`](#editormode) | 입력 프롬프트에서 [vim 키 바인딩](https://code.claude.com/docs/ko/interactive-mode.md#vim-editor-mode)을 사용합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`effortLevel`](#effortlevel) | 자체 저장된 수준이 없는 모델의 기본 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 설정합니다 | 모델 및 응답 | 모든 파일 |
| [`emojiCompletionEnabled`](#emojicompletionenabled) | 프롬프트 입력에서 [`:shortcode:` 이모지 제안 및 대체](https://code.claude.com/docs/ko/interactive-mode#emoji-shortcodes)를 끕니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`enableAllProjectMcpServers`](#enableallprojectmcpservers) | 프로젝트 [`.mcp.json`](https://code.claude.com/docs/ko/mcp#project-server-approvals-and-workspace-trust) 파일의 모든 서버를 확인 요청 없이 승인합니다 | MCP | 모든 파일 |
| [`enableArtifact`](#enableartifact) | 어느 파일에서든 `false`로 [Artifact 도구](https://code.claude.com/docs/ko/artifacts.md)를 끕니다. 어떤 파일도 다시 켤 수 없습니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`enabledMcpjsonServers`](#enabledmcpjsonservers) | 프로젝트의 [`.mcp.json`](https://code.claude.com/docs/ko/mcp#project-server-approvals-and-workspace-trust)에서 특정 서버를 승인합니다 | MCP | 모든 파일 |
| [`enabledPlugins`](#enabledplugins) | 범위별로 개별 [플러그인](https://code.claude.com/docs/ko/plugins/overview.md)을 켜거나 끕니다 | 플러그인 및 스킬 | 모든 파일 |
| [`enableWorkflows`](#enableworkflows) | 요금제의 기본값과 관계없이 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)를 켜거나 끕니다 | 훅 및 자동화 | 모든 파일 |
| [`enforceAvailableModels`](#enforceavailablemodels) | [`/model` Default 선택](https://code.claude.com/docs/ko/model-config#enforce-the-allowlist-for-the-default-model)을 `availableModels` 허용 목록 안으로 유지합니다 | 모델 및 응답 | 모든 파일 |
| [`env`](#env) | 모든 세션과 그 하위 프로세스에 대한 [환경 변수](https://code.claude.com/docs/ko/env-vars.md#in-settings-files)를 설정합니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`externalEditorContext`](#externaleditorcontext) | [Ctrl+G](https://code.claude.com/docs/ko/interactive-mode.md#general-controls)를 눌러 편집할 때 Claude의 마지막 응답을 주석으로 표시합니다 | 전역 구성 설정 | 전역 구성 |
| [`extraKnownMarketplaces`](#extraknownmarketplaces) | 저장소 또는 조직에 대한 [마켓플레이스](https://code.claude.com/docs/ko/plugins/overview.md)를 등록합니다 | 플러그인 및 스킬 | 모든 파일 |
| [`fallbackModel`](#fallbackmodel) | 기본 모델이 과부하 상태일 때 사용할 [백업 모델](https://code.claude.com/docs/ko/model-config.md#fallback-model-chains)을 지정합니다 | 모델 및 응답 | 모든 파일 |
| [`fastMode`](#fastmode) | 사용 가능한 세션에서 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)를 켭니다 | 모델 및 응답 | 모든 파일 |
| [`fastModePerSessionOptIn`](#fastmodepersessionoptin) | 세션마다 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)를 켜도록 요구합니다 | 모델 및 응답 | 모든 파일 |
| [`feedbackDrafts`](#feedbackdrafts) | Claude가 검토용 [피드백 초안](https://code.claude.com/docs/ko/tools-reference.md#sendfeedback-tool-behavior)을 대기열에 추가할지 제어합니다 | 개인정보 보호 및 텔레메트리 | 사용자 또는 관리형 |
| [`feedbackSurveyRate`](#feedbacksurveyrate) | [세션 품질 설문](https://code.claude.com/docs/ko/data-usage.md#session-quality-surveys)이 표시되는 빈도를 변경합니다 | 개인정보 보호 및 텔레메트리 | 모든 파일 |
| [`fileCheckpointingEnabled`](#filecheckpointingenabled) | [`/rewind`](https://code.claude.com/docs/ko/checkpointing)가 복원하는 파일 스냅샷을 끄거나 켭니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`fileSuggestion`](#filesuggestion) | 직접 지정한 명령으로 [`@` 파일 자동 완성](https://code.claude.com/docs/ko/interactive-mode#quick-commands)을 제공합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`footerLinksRegexes`](#footerlinksregexes) | 출력의 이슈 또는 리뷰 ID를 입력 상자 아래의 [클릭 가능한 링크](https://code.claude.com/docs/ko/statusline.md#clickable-links)로 만듭니다 | 인터페이스 및 터미널 | 사용자 또는 관리형 |
| [`forceLoginGatewayUrl`](#forcelogingatewayurl) | 로그인 화면이 연결할 [게이트웨이 URL](https://code.claude.com/docs/ko/claude-apps-gateway#set-the-gateway-url)을 설정합니다 | 인증 및 제공자 | 사용자 또는 관리형 |
| [`forceLoginMethod`](#forceloginmethod) | \[로그인을 claude.ai, Claude Console 또는 [클라우드 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)로 제한]\(/ko/authentication#restrict-login-to-your-organization)합니다 | 인증 및 제공자 | 모든 파일 |
| [`forceLoginOrgUUID`](#forceloginorguuid) | [claude.ai 로그인을 조직으로 고정](https://code.claude.com/docs/ko/authentication.md#restrict-login-to-your-organization)합니다. 관리형 소스에서만 적용됩니다 | 인증 및 제공자 | 모든 파일 |
| [`forceRemoteSettingsRefresh`](#forceremotesettingsrefresh) | [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)을 새로 가져올 때까지 시작을 차단합니다 | 엔터프라이즈 및 관리형 설정 | 관리형 |
| [`gatewayInternalNetworks`](#gatewayinternalnetworks) | 조직이 내부적으로 사용하는 공용 IPv4 공간의 [클라우드 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)에 `/login`이 접근할 수 있도록 합니다 | 인증 및 제공자 | 관리형 |
| [`gcpAuthRefresh`](#gcpauthrefresh) | 직접 지정한 명령으로 [Google Cloud 자격 증명](https://code.claude.com/docs/ko/google-vertex-ai.md#advanced-credential-configuration)을 갱신합니다 | 인증 및 제공자 | 모든 파일 |
| [`hooks`](#hooks) | Claude Code 수명 주기의 특정 시점에 직접 지정한 명령을 [훅](https://code.claude.com/docs/ko/hooks.md)으로 실행합니다 | 훅 및 자동화 | 모든 파일 |
| [`httpHookAllowedEnvVars`](#httphookallowedenvvars) | [HTTP 훅](https://code.claude.com/docs/ko/hooks.md)이 헤더에 넣을 수 있는 환경 변수를 제한합니다 | 훅 및 자동화 | 모든 파일 |
| [`idleCompaction`](#idlecompaction) | 사용자가 자리를 비운 긴 대화를 Claude Code가 압축하지 않도록 합니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`includeCoAuthoredBy`](#includecoauthoredby) | deprecated 되었습니다. 커밋 및 PR 작성자 표시를 숨기거나 변경하려면 `attribution`을 사용합니다 | Git 및 작성자 표시 | 모든 파일 |
| [`includeGitInstructions`](#includegitinstructions) | Claude의 컨텍스트에서 기본 제공 커밋 및 PR 지침을 제거합니다 | Git 및 작성자 표시 | 모든 파일 |
| [`inputNeededNotifEnabled`](#inputneedednotifenabled) | Claude가 사용자 입력을 기다릴 때 [푸시 알림](https://code.claude.com/docs/ko/remote-control.md#mobile-push-notifications)을 받습니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`isolatePeerMachines`](#isolatepeermachines) | Claude가 [다른 머신에 있는 세션에 메시지를 보내기](https://code.claude.com/docs/ko/cross-session-messaging.md#require-approval-for-cross-machine-messages) 전에 사용자에게 확인을 요청합니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`keybindingFlavor`](#keybindingflavor) | deprecated 되었으며 효과가 없습니다. 단어 편집 단축키는 항상 [readline 규칙을 따릅니다](https://code.claude.com/docs/ko/interactive-mode.md#make-ctrl-w-delete-back-to-whitespace) | 인터페이스 및 터미널 | 모든 파일 |
| [`language`](#language) | Claude가 영어 이외의 언어로 응답하도록 합니다 | 모델 및 응답 | 모든 파일 |
| [`leftArrowOpensAgents`](#leftarrowopensagents) | [세션을 백그라운드로 보내고 에이전트 뷰를 여는](https://code.claude.com/docs/ko/agent-view.md#switch-sessions-without-leaving-the-terminal) `←` 단축키를 끕니다 | 전역 구성 설정 | 전역 구성 |
| [`managedMcpServers`](#managedmcpservers) | 사용자가 추가한 서버와 함께 모든 사용자에게 원격 [MCP 서버](https://code.claude.com/docs/ko/managed-mcp.md#provide-servers-through-managed-settings)를 제공합니다 | MCP | 관리형 |
| [`managedSourcesBehavior`](#managedsourcesbehavior) | 우선순위가 가장 높은 소스만 사용하는 대신 배포한 모든 [관리형 소스](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)를 결합합니다 | 엔터프라이즈 및 관리형 설정 | 관리형 |
| [`maxEffortLevel`](#maxeffortlevel) | 모든 제공자에서 전체 모델 또는 모델별로 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)의 상한을 설정합니다 | 모델 및 응답 | 모든 파일 |
| [`maxProseWidth`](#maxprosewidth) | 넓은 터미널에서 Claude 응답의 본문 텍스트 너비 상한을 설정합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`minimumVersion`](#minimumversion) | [자동 업데이트](https://code.claude.com/docs/ko/setup.md#pin-a-minimum-version)가 지정한 버전보다 낮은 버전을 설치하지 않도록 합니다 | 업데이트 및 버전 관리 | 모든 파일 |
| [`model`](#model) | Claude Code가 시작할 때 사용하는 [모델](https://code.claude.com/docs/ko/model-config.md#set-a-default-model-for-new-sessions)을 변경합니다 | 모델 및 응답 | 모든 파일 |
| [`modelOverrides`](#modeloverrides) | [모델 ID를 Bedrock ARN 등 제공자의 ID에 매핑](https://code.claude.com/docs/ko/model-config.md#override-model-ids-per-version)합니다 | 모델 및 응답 | 모든 파일 |
| [`modelPicker`](#modelpicker) | [`/model` 선택기](https://code.claude.com/docs/ko/model-config#available-models)에 나열할 모델을 원하는 순서와 레이블로 선택합니다 | 모델 및 응답 | 사용자 또는 관리형 |
| [`modelPricing`](#modelpricing) | 정가 대신 조직의 계약 요율로 지출을 보고합니다 | 모델 및 응답 | 관리형 |
| [`modelSettings`](#modelsettings) | 모델별로 저장된 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level) 또는 [자동 압축 윈도우](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)를 유지하거나, 특정 모델의 effort 상한을 설정합니다 | 모델 및 응답 | 모든 파일 |
| [`otelHeadersHelper`](#otelheadershelper) | 직접 지정한 명령으로 순환되는 [OpenTelemetry](https://code.claude.com/docs/ko/monitoring-usage.md#dynamic-headers) 헤더를 생성합니다 | 인증 및 제공자 | 모든 파일 |
| [`outputStyle`](#outputstyle) | [출력 스타일](https://code.claude.com/docs/ko/output-styles.md)로 Claude의 역할, 어조, 출력 형식을 변경합니다 | 모델 및 응답 | 모든 파일 |
| [`parentSettingsBehavior`](#parentsettingsbehavior) | [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)을 배포할 때 [SDK 또는 IDE 호스트](https://code.claude.com/docs/ko/managed-settings.md#let-an-embedding-host-add-policy)가 전달하는 제한을 적용하거나 무시합니다 | 엔터프라이즈 및 관리형 설정 | 관리형 |
| [`permissionExplainerEnabled`](#permissionexplainerenabled) | 셸 권한 프롬프트의 `Ctrl+E` 명령 설명과 함께 v2.1.257에서 제거되었습니다 | 전역 구성 설정 | 전역 구성 |
| [`permissions`](#permissions) | 허용, 확인, 거부 규칙과 시작 [권한 모드](https://code.claude.com/docs/ko/permission-modes.md)를 설정합니다 | 권한 설정 | 모든 파일 |
| [`permissions.additionalDirectories`](#permissions-additionaldirectories) | Claude에게 [현재 디렉터리 외부의 디렉터리](https://code.claude.com/docs/ko/permissions.md#working-directories)에 대한 파일 접근 권한을 부여합니다 | 권한 설정 | 모든 파일 |
| [`permissions.allow`](#permissions-allow) | 나열된 [도구 사용](https://code.claude.com/docs/ko/permissions.md#permission-rule-syntax)을 확인 요청 없이 승인합니다 | 권한 설정 | 모든 파일 |
| [`permissions.ask`](#permissions-ask) | 나열된 [도구 사용](https://code.claude.com/docs/ko/permissions.md#permission-rule-syntax) 전에 항상 확인을 요청합니다 | 권한 설정 | 모든 파일 |
| [`permissions.blockReadsOutsideWorkingDirectories`](#permissions-blockreadsoutsideworkingdirectories) | 모든 권한 모드에서 파일 도구가 [작업 디렉터리](https://code.claude.com/docs/ko/permissions.md#working-directories) 외부의 읽기를 거부하도록 합니다 | 권한 설정 | 모든 파일 |
| [`permissions.defaultMode`](#permissions-defaultmode) | 새 세션이 시작되는 [권한 모드](https://code.claude.com/docs/ko/permission-modes.md#which-mode-a-session-starts-in)를 설정합니다 | 권한 설정 | 모든 파일 |
| [`permissions.deny`](#permissions-deny) | 비밀 정보가 담긴 파일 읽기를 포함하여 나열된 [도구 사용](https://code.claude.com/docs/ko/permissions.md#permission-rule-syntax)을 차단합니다 | 권한 설정 | 모든 파일 |
| [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) | 누구도 [bypassPermissions 모드](https://code.claude.com/docs/ko/permission-modes.md#skip-all-checks-with-bypasspermissions-mode)에 진입하지 못하도록 합니다 | 권한 설정 | 모든 파일 |
| [`plansDirectory`](#plansdirectory) | [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)가 플랜 파일을 작성할 위치를 선택합니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`pluginConfigs`](#pluginconfigs) | [플러그인](https://code.claude.com/docs/ko/plugins/overview.md) 구성 대화상자에 입력한 답변을 저장합니다 | 플러그인 및 스킬 | 사용자 또는 관리형 |
| [`pluginSuggestionMarketplaces`](#pluginsuggestionmarketplaces) | `/plugin`에서 플러그인 설치 제안을 표시할 수 있는 [마켓플레이스](https://code.claude.com/docs/ko/plugins/org.md#restrict-what-users-can-install)를 선택합니다 | 플러그인 및 스킬 | 관리형 |
| [`pluginTrustMessage`](#plugintrustmessage) | [플러그인](https://code.claude.com/docs/ko/plugins/overview.md) 신뢰 경고에 자체 문구를 추가합니다 | 플러그인 및 스킬 | 관리형 |
| [`policyHelper`](#policyhelper) | 시작 시 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md#compute-the-policy-with-a-helper-program)을 계산하는 실행 파일을 실행합니다 | 엔터프라이즈 및 관리형 설정 | 관리형 |
| [`policyHelper.path`](#policyhelper-path) | Claude Code가 실행할 [헬퍼 실행 파일](https://code.claude.com/docs/ko/managed-settings.md#compute-the-policy-with-a-helper-program)을 지정합니다 | 엔터프라이즈 및 관리형 설정 | 관리형 |
| [`policyHelper.refreshIntervalMs`](#policyhelper-refreshintervalms) | 일정 간격으로 백그라운드에서 [헬퍼](https://code.claude.com/docs/ko/managed-settings.md#compute-the-policy-with-a-helper-program)를 다시 실행합니다 | 엔터프라이즈 및 관리형 설정 | 관리형 |
| [`policyHelper.timeoutMs`](#policyhelper-timeoutms) | Claude Code가 [헬퍼](https://code.claude.com/docs/ko/managed-settings.md#compute-the-policy-with-a-helper-program)를 기다리는 시간을 설정합니다 | 엔터프라이즈 및 관리형 설정 | 관리형 |
| [`preferredNotifChannel`](#preferrednotifchannel) | 작업 완료 시 [터미널 벨 또는 데스크톱 알림](https://code.claude.com/docs/ko/terminal-config.md#get-a-terminal-bell-or-notification)을 선택합니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`prefersReducedMotion`](#prefersreducedmotion) | 스피너, 반짝임, 깜박임 애니메이션을 [줄이거나 끕니다](https://code.claude.com/docs/ko/accessibility.md#accessibility-settings) | 인터페이스 및 터미널 | 모든 파일 |
| [`prependPlugins`](#prependplugins) | 사용자가 설치한 모든 mod 전에 조직의 [mod](https://code.claude.com/docs/ko/plugins/mods/admin.md)를 실행합니다 | 플러그인 및 스킬 | 사용자 또는 관리형 |
| [`processWrapper`](#processwrapper) | macOS 및 Linux에서 Claude Code의 백그라운드 프로세스를 [회사 런처](https://code.claude.com/docs/ko/corporate-launcher.md)를 통해 실행합니다 | 에이전트, 세션 및 워크트리 | 사용자 또는 관리형 |
| [`promptCacheTtl`](#promptcachettl) | 기본 대화의 [프롬프트 캐시 수명](https://code.claude.com/docs/ko/prompt-caching.md#cache-lifetime)을 선택합니다 | 모델 및 응답 | 모든 파일 |
| [`promptSuggestionEnabled`](#promptsuggestionenabled) | 입력 상자에 회색으로 표시되는 [프롬프트 제안](https://code.claude.com/docs/ko/interactive-mode.md#prompt-suggestions)을 숨깁니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`prStatusFooterEnabled`](#prstatusfooterenabled) | 프롬프트 푸터의 [PR 리뷰 상태](https://code.claude.com/docs/ko/interactive-mode.md#pr-review-status) 배지와 그 뒤에서 수행되는 풀 리퀘스트 확인을 끕니다 | 전역 구성 설정 | 전역 구성 |
| [`prUrlTemplate`](#prurltemplate) | PR 링크가 github.com 대신 내부 코드 리뷰 도구를 가리키도록 합니다 | Git 및 작성자 표시 | 모든 파일 |
| [`remote.defaultEnvironmentId`](#remote-defaultenvironmentid) | `claude --cloud`의 기본 [클라우드 환경](https://code.claude.com/docs/ko/cloud-environments.md)을 선택합니다. 자체 호스팅 `ccpool_` ID는 사용자 및 관리형 설정과 `--settings`에서만 읽습니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`remoteControlAtStartup`](#remotecontrolatstartup) | 세션이 시작될 때 [Remote Control](https://code.claude.com/docs/ko/remote-control.md#enable-remote-control-for-all-sessions)을 자동으로 연결합니다 | 원격, 데스크톱 및 알림 | 모든 파일 |
| [`requiredMaximumVersion`](#requiredmaximumversion) | 조직이 허용하는 버전보다 새로운 버전에서는 [시작을 거부](https://code.claude.com/docs/ko/setup.md#pin-a-minimum-version)합니다 | 업데이트 및 버전 관리 | 관리형 |
| [`requiredMinimumVersion`](#requiredminimumversion) | 조직이 요구하는 버전보다 오래된 버전에서는 [시작을 거부](https://code.claude.com/docs/ko/setup.md#pin-a-minimum-version)합니다 | 업데이트 및 버전 관리 | 관리형 |
| [`respectGitignore`](#respectgitignore) | gitignore된 파일을 [`@` 파일 선택기](https://code.claude.com/docs/ko/interactive-mode#quick-commands)에서 제외합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`respondToBashCommands`](#respondtobashcommands) | [`!` 셸 명령](https://code.claude.com/docs/ko/interactive-mode#shell-mode-with-prefix)이 실행된 후 Claude가 응답하지 않도록 합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`sandbox`](#sandbox) | macOS, Linux, WSL2에서 [Bash 명령을 파일 시스템과 네트워크로부터 격리](https://code.claude.com/docs/ko/sandboxing.md)합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.allowAppleEvents`](#sandbox-allowappleevents) | macOS에서 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 명령이 Apple Events를 보낼 수 있도록 합니다 | 샌드박스 설정 | 사용자 또는 관리형 |
| [`sandbox.allowNestedUserNamespaces`](#sandbox-allownestedusernamespaces) | Linux 및 WSL2에서 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#chromium-or-rootless-podman-fails-inside-the-sandbox-on-linux) 명령이 사용자 네임스페이스를 생성할 수 있도록 합니다 | 샌드박스 설정 | 사용자 또는 관리형 |
| [`sandbox.allowUnsandboxedCommands`](#sandbox-allowunsandboxedcommands) | Claude가 차단된 명령을 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#the-unsandboxed-retry-escape-hatch) 외부에서 재시도하도록 허용하거나 금지합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.autoAllowBashIfSandboxed`](#sandbox-autoallowbashifsandboxed) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#auto-allow-mode) 명령을 권한 프롬프트 없이 실행합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.bwrapPath`](#sandbox-bwrappath) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md)가 `PATH` 외부의 bubblewrap 바이너리를 가리키도록 합니다 | 샌드박스 설정 | 관리형 |
| [`sandbox.credentials`](#sandbox-credentials) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#protect-credentials) 내부에서 자격 증명 파일과 변수를 숨기거나 마스킹합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.credentials.allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) | 신뢰할 수 있는 테스트 네트워크에서 [마스킹된 자격 증명](https://code.claude.com/docs/ko/sandboxing.md#mask-credentials)이 일반 HTTP 서비스에 도달할 수 있도록 합니다 | 샌드박스 설정 | 사용자 또는 관리형 |
| [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs) | 사용자 지정 이름의 AWS 키 변수를 [재서명](https://code.claude.com/docs/ko/sandboxing.md#re-sign-aws-requests)용 하나의 자격 증명으로 연결합니다 | 샌드박스 설정 | 사용자 또는 관리형 |
| [`sandbox.credentials.envVars`](#sandbox-credentials-envvars) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#mask-environment-variables) 내부에서 환경 변수를 설정 해제하거나 마스킹합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.credentials.files`](#sandbox-credentials-files) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#mask-credential-files) 내부에서 자격 증명 파일 읽기를 차단하거나 마스킹합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.credentials.sigv4`](#sandbox-credentials-sigv4) | 스트리밍, 사전 서명 또는 [SigV4A AWS 요청](https://code.claude.com/docs/ko/sandboxing.md#re-sign-aws-requests)을 실패시킬지 통과시킬지 선택합니다 | 샌드박스 설정 | 사용자 또는 관리형 |
| [`sandbox.enabled`](#sandbox-enabled) | macOS, Linux, WSL2에서 [Bash 샌드박싱](https://code.claude.com/docs/ko/sandboxing.md#get-started)을 켭니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.enableWeakerNestedSandbox`](#sandbox-enableweakernestedsandbox) | 권한 없는 컨테이너 내부에서 Linux [샌드박스](https://code.claude.com/docs/ko/sandboxing.md)를 실행합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.enableWeakerNetworkIsolation`](#sandbox-enableweakernetworkisolation) | macOS의 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#go-based-clis-fail-tls-verification-on-macos) 내부에서 `gh`, `gcloud`, `terraform`이 MITM 프록시 뒤에서 TLS를 검증할 수 있도록 합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.excludedCommands`](#sandbox-excludedcommands) | Claude Code가 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 외부에서 실행할 수 있는 명령을 지정합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.failIfUnavailable`](#sandbox-failifunavailable) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md)를 시작할 수 없을 때 샌드박스 없이 실행하는 대신 시작을 거부합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.filesystem`](#sandbox-filesystem) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#filesystem-isolation) 명령이 읽고 쓸 수 있는 경로를 제어합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.filesystem.allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly) | 개발자가 [조직이 차단한 읽기 경로](https://code.claude.com/docs/ko/sandboxing.md#keep-developers-from-widening-the-policy)를 다시 열지 못하도록 합니다 | 샌드박스 설정 | 관리형 |
| [`sandbox.filesystem.allowRead`](#sandbox-filesystem-allowread) | [`denyRead`](#sandbox-filesystem-denyread)가 차단한 영역 내부의 읽기를 다시 허용합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.filesystem.allowWrite`](#sandbox-filesystem-allowwrite) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 명령이 쓸 수 있는 경로를 추가합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 명령이 특정 경로를 읽지 못하도록 차단합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.filesystem.denyWrite`](#sandbox-filesystem-denywrite) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 명령이 특정 경로에 쓰지 못하도록 차단합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.filesystem.disabled`](#sandbox-filesystem-disabled) | 네트워크 격리는 유지하면서 [파일 시스템 격리를 끕니다](https://code.claude.com/docs/ko/sandboxing.md#disable-filesystem-isolation) | 샌드박스 설정 | 사용자 또는 관리형 |
| [`sandbox.ignoreViolations`](#sandbox-ignoreviolations) | 명령이 탐색할 것으로 예상되는 경로에 대한 위반 보고를 표시하지 않습니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network`](#sandbox-network) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#network-isolation) 명령이 접근할 수 있는 호스트, 포트, 소켓을 제어합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network.allowAllUnixSockets`](#sandbox-network-allowallunixsockets) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 명령이 모든 Unix 소켓에 연결할 수 있도록 합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 명령이 확인을 요청하지 않도록 도메인을 미리 허용합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network.allowLocalBinding`](#sandbox-network-allowlocalbinding) | macOS에서 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 명령이 네트워크 포트에서 수신 대기하고 localhost에 연결할 수 있도록 합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network.allowMachLookup`](#sandbox-network-allowmachlookup) | iOS Simulator나 Playwright 같은 macOS [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 도구가 XPC 서비스에 접근할 수 있도록 합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network.allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly) | 네트워크 허용 목록을 [관리형 설정](https://code.claude.com/docs/ko/sandboxing.md#keep-developers-from-widening-the-policy)으로 고정합니다 | 샌드박스 설정 | 관리형 |
| [`sandbox.network.allowUnixSockets`](#sandbox-network-allowunixsockets) | macOS에서 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 명령이 사용할 수 있는 Unix 소켓 경로를 나열합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network.deniedDomains`](#sandbox-network-denieddomains) | 허용된 와일드카드 내부에 있더라도 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 명령의 도메인을 차단합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network.httpProxyPort`](#sandbox-network-httpproxyport) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#custom-proxy-configuration) HTTP 트래픽을 자체 프록시로 라우팅합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network.socksProxyPort`](#sandbox-network-socksproxyport) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#custom-proxy-configuration) SOCKS 트래픽을 자체 프록시로 라우팅합니다 | 샌드박스 설정 | 모든 파일 |
| [`sandbox.network.strictAllowlist`](#sandbox-network-strictallowlist) | [허용 목록](https://code.claude.com/docs/ko/sandboxing.md#network-isolation) 외부의 호스트를 확인 요청 없이 거부합니다 | 샌드박스 설정 | 사용자 또는 관리형 |
| [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md#network-isolation) 프록시가 HTTPS 요청을 읽을 수 있도록 TLS를 종료하게 합니다 | 샌드박스 설정 | 사용자 또는 관리형 |
| [`sandbox.ripgrep`](#sandbox-ripgrep) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 내부에서 자체 ripgrep 바이너리를 사용합니다 | 샌드박스 설정 | 사용자 또는 관리형 |
| [`sandbox.socatPath`](#sandbox-socatpath) | [샌드박스](https://code.claude.com/docs/ko/sandboxing.md) 프록시가 `PATH` 외부의 `socat` 바이너리를 가리키도록 합니다 | 샌드박스 설정 | 관리형 |
| [`showClearContextOnPlanAccept`](#showclearcontextonplanaccept) | [플랜 승인 화면](https://code.claude.com/docs/ko/permission-modes.md#review-and-approve-a-plan)에 "컨텍스트 지우기" 옵션을 표시합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`showThinkingSummaries`](#showthinkingsummaries) | 접힌 요약 대신 Claude의 [사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking) 요약을 표시합니다 | 모델 및 응답 | 모든 파일 |
| [`showTurnDuration`](#showturnduration) | 각 응답 후 표시되는 "Cooked for" 소요 시간을 숨깁니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`skillListingBudgetFraction`](#skilllistingbudgetfraction) | [스킬 목록](https://code.claude.com/docs/ko/skills.md#skill-descriptions-are-cut-short)에 할당하는 컨텍스트를 늘리거나 줄입니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`skillListingMaxDescChars`](#skilllistingmaxdescchars) | [스킬 목록](https://code.claude.com/docs/ko/skills.md#skill-descriptions-are-cut-short)에서 각 스킬의 설명 길이 상한을 설정합니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`skillOverrides`](#skilloverrides) | SKILL.md를 편집하지 않고 [스킬을 숨기거나 접습니다](https://code.claude.com/docs/ko/skills.md#override-skill-visibility-from-settings) | 플러그인 및 스킬 | 모든 파일 |
| [`skipAutoPermissionPrompt`](#skipautopermissionprompt) | 기본 제공 기본값을 통하지 않고 직접 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode)에 처음 진입할 때 Claude Code가 표시하는 일회성 안내를 건너뜁니다 | 권한 설정 | 사용자 또는 관리형 |
| [`skipDangerousModePermissionPrompt`](#skipdangerousmodepermissionprompt) | [bypassPermissions 모드](https://code.claude.com/docs/ko/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) 전의 확인 대화상자를 건너뜁니다 | 권한 설정 | 사용자, 로컬 또는 관리형 |
| [`skipWebFetchPreflight`](#skipwebfetchpreflight) | Anthropic에 접근할 수 없을 때 [WebFetch 호스트 이름 확인](https://code.claude.com/docs/ko/tools-reference.md#webfetch-tool-behavior)을 건너뜁니다 | 개인정보 보호 및 텔레메트리 | 모든 파일 |
| [`spellcheck`](#spellcheck) | 설치한 [맞춤법 검사기](https://code.claude.com/docs/ko/interactive-mode.md#check-spelling-as-you-type)로 프롬프트 입력의 철자가 틀린 단어에 밑줄을 표시합니다 | 인터페이스 및 터미널 | 사용자 또는 관리형 |
| [`spinnerTipsEnabled`](#spinnertipsenabled) | Claude가 작업하는 동안 스피너의 팁을 숨깁니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`spinnerTipsOverride`](#spinnertipsoverride) | 스피너 순환에 자체 팁을 추가하거나 기본 제공 팁을 대체합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`spinnerVerbs`](#spinnerverbs) | 턴이 실행되는 동안 표시되는 동사를 추가하거나 대체합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`sshConfigs`](#sshconfigs) | Desktop 환경 선택기에 [SSH 연결](https://code.claude.com/docs/ko/desktop.md#pre-configure-ssh-connections-for-your-team)을 추가합니다 | 원격, 데스크톱 및 알림 | 사용자 또는 관리형 |
| [`sshHostAllowlist`](#sshhostallowlist) | [Desktop SSH 세션](https://code.claude.com/docs/ko/desktop.md#restrict-which-ssh-hosts-users-can-connect-to)이 접근할 수 있는 호스트를 제한합니다 | 원격, 데스크톱 및 알림 | 관리형 |
| [`sshHostCommands`](#sshhostcommands) | Desktop 환경 선택기에 [명령으로 호스트를 지정하는 SSH 연결](https://code.claude.com/docs/ko/desktop.md#create-an-ssh-connection-from-a-command)을 추가합니다 | 원격, 데스크톱 및 알림 | 사용자 또는 관리형 |
| [`statusLine`](#statusline) | 직접 지정한 명령을 실행하여 프롬프트 아래에 [상태줄](https://code.claude.com/docs/ko/statusline.md)을 렌더링합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`strictKnownMarketplaces`](#strictknownmarketplaces) | 사용자가 추가하고 설치할 수 있는 [마켓플레이스](https://code.claude.com/docs/ko/plugins/overview.md) 소스를 허용 목록으로 지정합니다 | 플러그인 및 스킬 | 관리형 |
| [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | 사용자 및 프로젝트 소스의 [스킬](https://code.claude.com/docs/ko/skills.md), [에이전트](https://code.claude.com/docs/ko/sub-agents.md), [훅](https://code.claude.com/docs/ko/hooks.md), [MCP 서버](https://code.claude.com/docs/ko/mcp.md)를 차단합니다 | 플러그인 및 스킬 | 관리형 |
| [`strictPluginOnlyCustomization.agents`](#strictpluginonlycustomization-agents) | [에이전트](https://code.claude.com/docs/ko/sub-agents.md)를 플러그인 및 관리형 소스로 제한합니다 | 플러그인 및 스킬 | 관리형 |
| [`strictPluginOnlyCustomization.hooks`](#strictpluginonlycustomization-hooks) | [훅](https://code.claude.com/docs/ko/hooks.md)을 플러그인 및 관리형 소스로 제한합니다 | 플러그인 및 스킬 | 관리형 |
| [`strictPluginOnlyCustomization.mcp`](#strictpluginonlycustomization-mcp) | [MCP 서버](https://code.claude.com/docs/ko/mcp.md)를 플러그인 및 관리형 소스로 제한합니다 | 플러그인 및 스킬 | 관리형 |
| [`strictPluginOnlyCustomization.skills`](#strictpluginonlycustomization-skills) | [스킬](https://code.claude.com/docs/ko/skills.md)을 플러그인 및 관리형 소스로 제한합니다 | 플러그인 및 스킬 | 관리형 |
| [`subagentPromptCacheTtl`](#subagentpromptcachettl) | 서브에이전트 및 기본 대화 외부의 기타 요청에 대한 [프롬프트 캐시 수명](https://code.claude.com/docs/ko/prompt-caching.md#cache-lifetime)을 선택합니다 | 모델 및 응답 | 모든 파일 |
| [`subagentStatusLine`](#subagentstatusline) | 직접 지정한 명령으로 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md) 작업 표시의 행을 다시 작성합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`switchModelsOnFlag`](#switchmodelsonflag) | [안전 분류기](https://code.claude.com/docs/ko/model-config.md#ask-before-switching)가 요청에 플래그를 지정하면 모델을 자동으로 전환하거나 일시 중지합니다 | 모델 및 응답 | 모든 파일 |
| [`syncClaudeAiPlugins`](#syncclaudeaiplugins) | [claude.ai 계정에서 활성화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins) 로드를 중지하고 새 플러그인 다운로드를 중지합니다 | 플러그인 및 스킬 | 사용자, 로컬 또는 관리형 |
| [`syncClaudeAiSkills`](#syncclaudeaiskills) | [claude.ai 계정에서 활성화된 스킬](https://code.claude.com/docs/ko/skills.md#how-synced-skills-behave) 로드를 중지하고 새 스킬 다운로드를 중지합니다 | 플러그인 및 스킬 | 사용자, 로컬 또는 관리형 |
| [`syntaxHighlightingDisabled`](#syntaxhighlightingdisabled) | diff와 코드 블록의 구문 강조를 끕니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`taskOutputMaxChars`](#taskoutputmaxchars) | 크기를 지정하던 `TaskOutput` 도구와 함께 v2.1.277에서 제거되었습니다 | 메모리 및 컨텍스트 | 모든 파일 |
| [`teammateDefaultModel`](#teammatedefaultmodel) | v2.1.234에서 제거되었습니다. Claude Code가 팀원의 모델을 선택하는 방법은 [팀원 및 모델 지정](https://code.claude.com/docs/ko/agent-teams.md#specify-teammates-and-models)을 참조하세요 | 전역 구성 설정 | 전역 구성 |
| [`teammateMode`](#teammatemode) | [에이전트 팀 팀원의 표시 방식](https://code.claude.com/docs/ko/agent-teams.md#choose-a-display-mode)을 선택합니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`terminalProgressBarEnabled`](#terminalprogressbarenabled) | 진행률 표시줄을 지원하는 터미널에서 터미널 진행률 표시줄을 숨깁니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`terminalTitleFromRename`](#terminaltitlefromrename) | [`/rename`](https://code.claude.com/docs/ko/sessions#name-your-sessions)과 `--name`이 터미널 탭 제목을 변경하지 않도록 합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`theme`](#theme) | 기본 제공 또는 사용자 지정 인터페이스 [색상 테마](https://code.claude.com/docs/ko/terminal-config.md#match-the-color-theme)를 선택합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`timeFormat`](#timeformat) | 인터페이스의 시간을 12시간제 또는 24시간제, UTC 또는 strftime 패턴으로 표시합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`timeZone`](#timezone) | 인터페이스의 시간을 시스템과 다른 시간대로 표시합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`tui`](#tui) | [전체 화면](https://code.claude.com/docs/ko/fullscreen.md) 또는 클래식 터미널 렌더러를 선택합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`ultracode`](#ultracode) | 요청하지 않아도 Claude가 실질적인 작업마다 [워크플로](https://code.claude.com/docs/ko/workflows.md#let-claude-decide-with-ultracode)를 계획하도록 합니다 | 모델 및 응답 | 모든 파일 |
| [`useAutoModeDuringPlan`](#useautomodeduringplan) | [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)에서 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 분류기가 셸 명령을 검토하도록 합니다. 대신 확인 요청을 받으려면 `false`로 설정합니다 | 권한 설정 | 사용자, 로컬 또는 관리형 |
| [`verbose`](#verbose) | 잘린 요약 대신 [전체 도구 출력](https://code.claude.com/docs/ko/cli-reference.md#cli-flags)을 표시합니다. 둘 다 설정된 경우 `viewMode`가 우선합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`viewMode`](#viewmode) | 모든 세션을 [default, verbose 또는 focus 뷰](https://code.claude.com/docs/ko/cli-reference.md#cli-flags)로 시작합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`vimInsertModeRemaps`](#viminsertmoderemaps) | `jj`와 같은 두 키 [INSERT 모드 시퀀스](https://code.claude.com/docs/ko/interactive-mode.md#remap-insert-mode-key-sequences)를 Escape에 매핑합니다 | 인터페이스 및 터미널 | 사용자 또는 관리형 |
| [`voice`](#voice) | [음성 받아쓰기](https://code.claude.com/docs/ko/voice-dictation.md)를 켜고 길게 누르기 또는 탭 모드를 선택합니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`voiceEnabled`](#voiceenabled) | 이전 단일 키 형식으로 [음성 받아쓰기](https://code.claude.com/docs/ko/voice-dictation.md)를 켭니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`wheelScrollAccelerationEnabled`](#wheelscrollaccelerationenabled) | 전체 화면 렌더링에서 [마우스 휠 가속](https://code.claude.com/docs/ko/fullscreen.md#mouse-wheel-scrolling)을 끕니다 | 인터페이스 및 터미널 | 모든 파일 |
| [`workflowKeywordTriggerEnabled`](#workflowkeywordtriggerenabled) | 프롬프트의 `ultracode` 단어로 [워크플로](https://code.claude.com/docs/ko/workflows.md)를 시작할 수 있도록 합니다. 워크플로를 시작하지 않고 입력하려면 `false`로 설정합니다 | 훅 및 자동화 | 모든 파일 |
| [`workflowSizeGuideline`](#workflowsizeguideline) | [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)에서 Claude가 목표로 하는 에이전트 수를 설정합니다 | 훅 및 자동화 | 모든 파일 |
| [`worktree`](#worktree) | Claude Code가 git [worktree](https://code.claude.com/docs/ko/worktrees.md)를 생성하는 방식을 구성합니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`worktree.baseRef`](#worktree-baseref) | 원격 기본 브랜치 또는 로컬 HEAD에서 새 [worktree](https://code.claude.com/docs/ko/worktrees.md)를 분기합니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`worktree.bgIsolation`](#worktree-bgisolation) | 백그라운드 세션이 [worktree](https://code.claude.com/docs/ko/worktrees.md) 없이 작업 사본을 편집할 수 있도록 합니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`worktree.location`](#worktree-location) | [Desktop SSH 세션](https://code.claude.com/docs/ko/desktop.md#ssh-sessions)이 원격 머신에서 워크트리를 생성할 위치를 선택합니다 | 에이전트, 세션 및 워크트리 | 사용자 |
| [`worktree.sparsePaths`](#worktree-sparsepaths) | 각 [worktree](https://code.claude.com/docs/ko/worktrees.md)에서 필요한 디렉터리만 체크아웃합니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`worktree.symlinkDirectories`](#worktree-symlinkdirectories) | 큰 디렉터리를 복제하는 대신 각 [worktree](https://code.claude.com/docs/ko/worktrees.md)에 심볼릭 링크로 연결합니다 | 에이전트, 세션 및 워크트리 | 모든 파일 |
| [`wslInheritsWindowsSettings`](#wslinheritswindowssettings) | WSL이 Windows 정책 체인에서 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)을 읽도록 합니다 | 엔터프라이즈 및 관리형 설정 | 관리형 |

## 모델 및 응답

Claude Code가 사용하는 모델과 응답 방식을 선택합니다. 이러한 설정이 `/model` 명령 및 환경 변수와 어떻게 상호 작용하는지는 [모델 구성](https://code.claude.com/docs/ko/model-config.md)을 참조하세요.

### `advisorModel`

Claude가 서버 측 [advisor 도구](https://code.claude.com/docs/ko/advisor.md)를 호출할 때 응답할 모델을 선택합니다. advisor를 끄려면 이 키를 설정 해제합니다. advisor는 최소한 메인 모델과 동등한 성능을 갖춰야 합니다. 허용되는 조합과 허용되지 않는 모델을 선택했을 때 어떻게 되는지는 [advisor 모델 선택](https://code.claude.com/docs/ko/advisor.md#choose-an-advisor-model)을 참조하세요.

일반적으로 이 키를 직접 편집하지 않습니다. `/advisor`를 실행하면 현재 선택, advisor로 사용할 수 있는 모델, **No advisor**를 보여 주는 선택기가 열립니다. Claude Code는 선택한 항목을 `~/.claude/settings.json`의 이 키에 저장합니다. [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 클라이언트에서 선택하거나 원격 워커에 연결된 세션에서 선택하면 해당 선택은 그 세션에만 적용되며 이 키는 변경되지 않습니다.

계정에 [사용량 크레딧 동의](https://code.claude.com/docs/ko/advisor.md#fable-advisor-and-usage-credits)가 필요한 경우 먼저 `/model fable`을 실행하여 동의해야 합니다. 동의하기 전까지는 `/advisor`에서 Fable을 선택해도 아무것도 저장되지 않으며, Claude Code가 먼저 `/model fable`을 실행하라고 안내합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열. 해당 모델 계열의 Claude Code 현재 기본 버전으로 해석되는 별칭 `"fable"`, `"opus"`, `"sonnet"` 중 하나 또는 `"claude-opus-5-5"`와 같은 전체 모델 ID
* **기본값**: 설정되지 않음. 따라서 advisor가 꺼져 있습니다
* **세션별 재정의**: 한 세션에 대해서는 `--advisor`가 이 키보다 우선합니다. [`CLAUDE_CODE_DISABLE_ADVISOR_TOOL`](https://code.claude.com/docs/ko/env-vars)은 advisor를 끄며, 이 키로 다시 켤 수 없습니다

```json settings.json theme={null}
{
  "advisorModel": "opus"
}
```

이 키는 Amazon Bedrock 및 Claude Platform on AWS처럼 advisor를 [사용할 수 없는](https://code.claude.com/docs/ko/advisor.md#requirements) 공급자에서는 효과가 없습니다. `"fable"`에는 [Fable 액세스](https://code.claude.com/docs/ko/advisor.md#choose-an-advisor-model)가 필요합니다.

### `alwaysThinkingEnabled`

이 값을 `false`로 설정하면 모든 세션에서 [확장 사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking)를 끕니다. 사고는 기본적으로 켜져 있으므로 `true`는 아무것도 바꾸지 않습니다. 대부분 파일을 편집하는 대신 `/config`를 통해 설정합니다.

Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 모델처럼 항상 사고하는 모델에서는 `false`가 효과가 없습니다. [서드파티 공급자](https://code.claude.com/docs/ko/third-party-integrations.md)에서는 Claude Code가 사고를 끄는 대신 `thinking` 매개변수를 생략하므로 적응형 추론 모델은 여전히 사고할 수 있습니다. Anthropic API에서 사고를 끈 상태에서는, Opus 5처럼 [해당 조합을 허용하지 않는](https://code.claude.com/docs/ko/errors.md#effort-isnt-available-with-thinking-turned-off) 것으로 알려진 모델에 Claude Code가 더 높은 수준 대신 effort `high`를 보냅니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: 효과 없음. 사고가 이미 켜져 있습니다
  * `false`: Claude Code가 모든 세션에서 확장 사고를 끕니다
* **기본값**: 설정되지 않음. 따라서 지원하는 모델에서는 사고가 켜져 있습니다
* **세션별 재정의**: 한 세션에 대해서는 [`MAX_THINKING_TOKENS`](https://code.claude.com/docs/ko/env-vars)가 이 키보다 우선합니다. `0`은 `false`와 동일한 모델 및 공급자 제한 아래에서 사고를 끄고, 양수 값은 이 키가 `false`여도 사고를 켭니다. 적응형 추론 모델에서는 숫자 자체가 무시됩니다

```json settings.json theme={null}
{
  "alwaysThinkingEnabled": false
}
```

### `availableModels`

메인 세션, [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md), [스킬](https://code.claude.com/docs/ko/skills.md), [advisor](https://code.claude.com/docs/ko/advisor.md)에 사용자가 선택할 수 있는 모델을 제한합니다. 관리형 목록은 `/model`, `--model`, 개발자 자신의 파일에 있는 `model` 키를 제한하며, 목록에 없는 모델은 선택할 수 없습니다. 기본 접두사 매칭에서는 이 키만으로 Default 옵션에 영향을 주지 않으므로, 그러려면 [`enforceAvailableModels`](#enforceavailablemodels)와 함께 사용하세요.

* **범위**: [`Any file`](#scopes). 조직 전체에 적용하려면 관리형 설정에 배포합니다.
* **유형**: 모델 별칭 또는 ID의 배열
* **기본값**: 설정되지 않음. 따라서 모든 모델을 사용할 수 있습니다

이 예시는 Sonnet 및 Haiku 모델만 선택할 수 있도록 합니다:

```json settings.json theme={null}
{
  "availableModels": ["sonnet", "haiku"]
}
```

`"claude-opus-5"`와 같은 모델 ID 항목은 Opus 5.5처럼 이를 확장하는 이후 버전도 허용합니다. 그러한 버전 중 하나를 차단하려면 [`deniedModels`](#deniedmodels)를 사용하세요. 각 모델 ID 항목이 명시한 버전만 허용하도록 하려면 [`availableModelsMatch`](#availablemodelsmatch)를 사용하세요. [모델 선택 제한](https://code.claude.com/docs/ko/model-config.md#restrict-model-selection)을 참조하세요. 서드파티 공급자 ID에 대해서는 [서드파티 배포용 모델 고정](https://code.claude.com/docs/ko/model-config.md#pin-models-for-third-party-deployments)을 참조하세요.

### `availableModelsMatch`

[`availableModels`](#availablemodels) 항목이 모델 ID와 일치하는 방식을 선택합니다. 기본적으로 모델 ID 항목은 이를 확장하는 이후 버전도 허용하므로 `"claude-opus-5"`는 Opus 5.5를 허용합니다. `"exact"`를 사용하면 각 모델 ID 항목은 명시한 버전만 허용하므로, 해당 모델의 새 버전은 목록에 추가할 때까지 차단된 상태로 유지됩니다. Claude Code v2.1.283 이상이 필요합니다.

* **범위**: [`Managed`](#scopes). Claude Code는 사용자, 프로젝트, 로컬 설정과 `--settings`에 있는 이 키를 경고와 함께 무시합니다
* **유형**: 문자열. 다음 중 하나:
  * `"prefix"`: 모델 ID 항목은 해당 버전과, 다른 세그먼트로 이를 확장하는 모든 모델 ID를 허용합니다
  * `"exact"`: 모델 ID 항목은 명시한 버전만 허용하므로, `"claude-opus-5"`는 Opus 5를 허용하지만 `claude-opus-5-5`는 허용하지 않습니다. `"claude-opus-4-5"`와 같은 항목은 날짜가 포함된 Anthropic 모델 ID `claude-opus-4-5-20251101`도 허용합니다. `"opus"`와 같은 계열 별칭은 여전히 계열 전체를 허용하며, `best`, `opusplan`, `default` 항목은 무시됩니다
* **기본값**: `"prefix"`

이 예시는 Opus 5와 Sonnet 5를 허용하고 둘 다 이후 릴리스는 허용하지 않습니다:

```json managed-settings.json theme={null}
{
  "availableModels": ["claude-opus-5", "claude-sonnet-5"],
  "availableModelsMatch": "exact"
}
```

`"exact"`를 사용하면 목록에 모델이나 계열이 하나 이상 명시되어 있을 때마다 Default 옵션도 목록의 모델로 제한됩니다. [특정 모델 또는 버전 차단](https://code.claude.com/docs/ko/model-config.md#block-specific-models-or-versions)을 참조하세요.

### `deniedModels`

[`availableModels`](#availablemodels) 허용 목록의 유무와 관계없이, 그리고 해당 목록이 허용하더라도 특정 모델을 차단합니다. Claude Code는 차단된 모델을 `/model` 선택기에서 숨기며, `availableModels`가 적용되는 어디에서도 해당 모델을 선택할 수 없습니다. [특정 모델 또는 버전 차단](https://code.claude.com/docs/ko/model-config.md#block-specific-models-or-versions)에서 설명하듯이 Default 옵션을 사용하는 세션도 차단된 모델을 실행하지 않습니다. Claude Code v2.1.283 이상이 필요합니다.

* **범위**: [`Managed`](#scopes). Claude Code는 사용자, 프로젝트, 로컬 설정과 `--settings`에 있는 이 키를 경고와 함께 무시합니다
* **유형**: 모델 별칭 또는 ID의 배열
  * `"opus"`와 같은 계열 별칭은 해당 계열의 모든 모델을 차단합니다
  * `"claude-opus-5-5"`와 같은 모델 ID는 날짜가 포함된 ID와 공급자별 ID를 포함하여 모든 표기의 해당 버전을 차단합니다
  * `"claude-opus-5"`처럼 마이너 버전이 없는 모델 ID는 Opus 5.5와 같은 이후 마이너 버전도 차단합니다. Opus 5만 차단하려면 `"claude-opus-5-0"`을 작성합니다
  * `best`, `opusplan`, `default` 항목은 무시됩니다
* **기본값**: 설정되지 않음. 따라서 차단되는 모델이 없습니다

이 예시는 Opus 및 Sonnet 모델을 허용하고 Opus 5.5를 차단합니다:

```json managed-settings.json theme={null}
{
  "availableModels": ["opus", "sonnet"],
  "deniedModels": ["claude-opus-5-5"]
}
```

[특정 모델 또는 버전 차단](https://code.claude.com/docs/ko/model-config.md#block-specific-models-or-versions)을 참조하세요.

### `effortLevel`

수준을 저장하지 않은 모델에 대한 기본 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 설정합니다. 낮은 수준은 간단한 작업에서 더 빠르고 저렴하며, 높은 수준은 복잡한 문제에서 더 깊이 추론합니다.

로컬 머신의 대화형 세션에서 `/effort low`, `medium`, `high`, `xhigh`를 실행하면 Claude Code는 이 키에 쓰는 대신 활성 모델에 대한 수준을 [`modelSettings`](#modelsettings) 아래에 저장합니다. v2.1.251 이전에는 `/effort`가 이 키에 썼습니다.

같은 설정 파일 내에서 Claude Code는 이 키보다 모델의 저장된 수준을 사용합니다. 파일 간 우선순위는 [`modelSettings`](#modelsettings)에 설명되어 있습니다.

원격 워커에 연결된 세션, `-p` 실행, Agent SDK에서는 `/effort`가 해당 세션에만 적용됩니다. 해당 세션에만 적용되는 대화형 선택 항목은 [effort 수준 조정](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)에 나열되어 있습니다. `/effort`가 출력하는 메시지에서 어떤 방식으로 적용되었는지 알려 줍니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열. 다음 중 하나:
  * `"low"`: 가장 적은 추론. 지능에 민감하지 않은 짧고 범위가 정해진 지연 시간 민감 작업용
  * `"medium"`: 어느 정도의 지능을 절충할 수 있는 비용 민감 작업에서 토큰 사용량을 줄입니다
  * `"high"`: 토큰 사용량과 지능의 균형을 맞춥니다
  * `"xhigh"`: 더 많은 토큰을 사용하여 더 깊이 추론합니다
* **기본값**: 설정되지 않음
* **세션별 재정의**: 한 세션에 대해서는 `--effort`가 이 키보다 우선하며, [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/ko/env-vars)은 둘 다보다 우선합니다

```json settings.json theme={null}
{
  "effortLevel": "xhigh"
}
```

사용자 설정 파일 `~/.claude/settings.json`에서 이 키는 `/effort`가 모델별로 수준을 저장하기 전에 쓰던 이전 형식이며, Opus 5, Fable 5.1 및 이전 모델처럼 이전에 적용되던 곳에 계속 적용됩니다. Opus 5.5 및 그 이후에 출시된 모델은 이 키를 무시하고 수준을 저장하기 전까지 자체 기본값으로 시작하며, `/effort`는 해당 수준을 [`modelSettings`](#modelsettings) 아래에 씁니다. 프로젝트, 로컬, 관리형 설정과 `--settings`에서는 이 키가 모든 모델에 적용됩니다.

### `enforceAvailableModels`

`/model` 선택기에는 **Default** 옵션이 있으며, 이 옵션이 어떤 모델로 해석되는지는 [`default` 모델 설정](https://code.claude.com/docs/ko/model-config#default-model-setting)에 설명되어 있습니다. [`availableModels`](#availablemodels) 허용 목록은 지정할 수 있는 모델을 제한하지만, 기본 [접두사 매칭](#availablemodelsmatch)에서는 계정 유형의 기본값을 다시 매핑하지 않으므로 **Default**가 여전히 목록 밖의 모델로 해석될 수 있습니다. 이 키는 그 공백을 메웁니다. Claude Code v2.1.175 이상이 필요합니다.

조직에서 관리형 설정을 배포하는 경우 Claude Code는 관리형 소스에서만 이 키를 읽고 다른 파일의 이 키는 무시합니다.

시작 시 모델 검사에 이 키가 어떻게 적용되는지는 [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md#when-your-organization-enforces-a-model-allowlist) 및 [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md#when-your-organization-enforces-a-model-allowlist)을 참조하세요.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: **Default**가 `availableModels` 밖의 모델로 해석될 경우 Claude Code는 목록에서 처음으로 사용 가능한 모델로 해석합니다
  * `false`: 이 키는 **Default**가 해석되는 방식을 바꾸지 않습니다
* **기본값**: `false`

이 예시는 지정 선택을 Sonnet 및 Haiku 모델로 제한하고 **Default**가 그중 처음으로 사용 가능한 모델로 해석되도록 합니다:

```json settings.json theme={null}
{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}
```

`availableModels`가 설정되지 않았거나 비어 있으면 이 키는 효과가 없습니다. [Default 모델에 허용 목록 적용](https://code.claude.com/docs/ko/model-config.md#enforce-the-allowlist-for-the-default-model)을 참조하세요. Claude Code v2.1.175 이상이 필요합니다.

### `fallbackModel`

기본 모델이 과부하 상태이거나 사용할 수 없을 때 Claude Code가 순서대로 시도할 백업 모델을 지정합니다. Claude Code는 턴의 나머지 부분 동안 체인에서 다음으로 사용 가능한 모델로 전환하고 알림을 표시합니다. 체인이 없으면 Claude Code는 같은 모델을 재시도한 뒤 서버의 오류를 표시하며, 사용자가 직접 재시도하거나 모델을 전환해야 합니다.

전환하면 폴백 모델에서 [프롬프트 캐시](https://code.claude.com/docs/ko/prompt-caching.md#switching-models)가 비어 있는 상태로 한 턴이 진행됩니다. 다음 메시지에서는 다시 기본 모델을 먼저 시도합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 모델 별칭 또는 ID의 배열. `"default"`는 기본 모델로 확장됩니다
* **기본값**: 설정되지 않음. 따라서 실패한 요청을 다른 모델로 재시도하지 않습니다
* **세션별 재정의**: 한 세션에 대해서는 `--fallback-model`이 이 키보다 우선합니다

이 예시는 기본 모델이 실패하면 Sonnet 5를 먼저 시도한 다음 Haiku 4.5를 시도합니다:

```json settings.json theme={null}
{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}
```

대부분의 배열 설정과 달리 이 키는 설정 파일 간에 병합되지 않습니다. 이 키를 정의한 우선순위가 가장 높은 파일이 체인 전체를 제공합니다. 프로젝트 파일에서 `["claude-sonnet-5"]`를 설정하고 사용자 파일에서 `["claude-haiku-4-5"]`를 설정하면 체인은 `["claude-sonnet-5"]`뿐입니다. Claude Code는 목록에서 서로 다른 허용 모델을 최대 세 개까지 유지하고 나머지는 무시합니다. [폴백 모델 체인](https://code.claude.com/docs/ko/model-config.md#fallback-model-chains)을 참조하세요.

### `fastMode`

사용 가능한 세션에서 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md)를 켭니다. 토큰당 비용이 더 높더라도 속도가 필요한 빠른 반복이나 실시간 디버깅 같은 대화형 작업에 적합합니다. 일반적으로 이 키를 직접 편집하지 않습니다. `/fast`를 실행하면 `~/.claude/settings.json`에 `fastMode: true`가 기록되고, 다시 실행하여 빠른 모드를 끄면 키가 제거됩니다. 빠른 모드는 Opus 5.5, Opus 5, Opus 4.8에서만 실행됩니다. 다른 모델에서 켜면 Opus로 전환되며, 지원되지 않는 모델로 전환하면 꺼집니다. [빠른 모드가 켜진 상태에서 모델 전환](https://code.claude.com/docs/ko/fast-mode.md#switch-models-while-fast-mode-is-on)을 참조하세요.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 사용 가능한 세션에서 빠른 모드를 켭니다
  * `false`: 빠른 모드가 꺼진 상태로 유지됩니다
* **기본값**: 설정되지 않음. 따라서 빠른 모드가 꺼져 있습니다
* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_FAST_MODE`](https://code.claude.com/docs/ko/env-vars)는 한 세션에 대해 빠른 모드를 끄며, 이 키로 다시 켤 수 없습니다

```json settings.json theme={null}
{
  "fastMode": true
}
```

### `fastModePerSessionOptIn`

일반적으로 `/fast`를 실행하면 [`fastMode`](#fastmode)가 사용자 설정에 저장되므로 이후 모든 세션이 시작될 때 빠른 모드가 켜집니다. 이를 막으려면 이 키를 `true`로 설정합니다. 그러면 저장된 `fastMode: true`가 더 이상 세션 시작 시 빠른 모드를 켜지 않으며, 각 사용자는 빠른 모드를 원하는 세션마다 `/fast`를 실행해야 합니다. Claude Code는 파일의 `fastMode` 키를 그대로 두므로 이 키를 끄면 이전 동작이 복원됩니다.

Team 또는 Enterprise 플랜의 Owner는 [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)을 통해 조직 전체에 배포할 수 있습니다. 관리형 설정에서 이 키를 설정하면 대화형 터미널 세션 외부에서는 `/fast on`이 거부되고 조직에서 빠른 모드를 비활성화했다고 알립니다. 여기에는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md), [VS Code 확장](https://code.claude.com/docs/ko/vs-code.md), [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)이 포함됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: 저장된 `fastMode: true`가 더 이상 세션 시작 시 빠른 모드를 켜지 않으므로 각 사용자가 원하는 세션마다 `/fast`를 실행합니다. 관리형 설정에서 이 키를 설정하지 않는 한 `--settings`로 전달된 `fastMode: true`는 해당 세션에 여전히 적용됩니다
  * `false`: 저장된 `fastMode: true`가 이후 모든 세션이 시작될 때 빠른 모드를 켭니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "fastModePerSessionOptIn": true
}
```

[세션별 옵트인 요구](https://code.claude.com/docs/ko/fast-mode.md#require-per-session-opt-in)를 참조하세요.

### `language`

Claude가 기본적으로 영어가 아닌 언어로 응답하도록 합니다. 응답에 대한 고정된 목록은 없습니다. Claude Code는 이 값을 해당 언어로 항상 응답하라는 지시로 Claude에 그대로 전달하므로 Claude가 읽을 수 있는 모든 언어 이름이 작동합니다. Claude Code는 값을 확인하지 않으므로 철자가 틀린 이름은 오류를 발생시키지 않고 작성된 그대로 Claude에 전달됩니다. 같은 값이 [음성 받아쓰기](https://code.claude.com/docs/ko/voice-dictation.md#change-the-dictation-language)의 언어와 자동 생성되는 세션 제목의 언어도 설정하며, 음성 받아쓰기에는 [지원되는 받아쓰기 언어](https://code.claude.com/docs/ko/voice-dictation.md#change-the-dictation-language)의 고정 목록이 있습니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열. `"japanese"`, `"spanish"`, `"french"`와 같은 모든 언어 이름. Claude Code는 검증하지 않습니다
* **기본값**: 설정되지 않음. 이 경우 세션 제목은 대화 언어를 따릅니다

```json settings.json theme={null}
{
  "language": "japanese"
}
```

### `maxEffortLevel`

세션이 사용할 수 있는 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)의 상한을 정하고, 그보다 낮은 수준은 계속 사용할 수 있도록 합니다. 더 높은 수준은 상한에서 대신 실행되며, 여기에는 `/effort`, `/model` 선택기, `--effort`, [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/ko/env-vars), 스킬이나 서브에이전트의 `effort` frontmatter, 모델 자체 기본값에서 온 수준이 포함됩니다. Claude Code가 각 요청 전에 직접 상한을 적용하므로 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry를 포함한 모든 공급자에서 유지됩니다. Claude Code v2.1.267 이상이 필요합니다.

* **범위**: [`Any file`](#scopes). 조직 전체에 적용하려면 관리형 설정에 배포합니다. 여러 범위에서 상한을 설정하면 가장 낮은 값이 적용되므로, 한 범위에서 설정한 상한을 다른 범위에서 올릴 수 없습니다
* **유형**: 문자열. `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` 중 하나. `"max"` 값은 상한을 설정하지 않습니다
* **기본값**: 설정되지 않음. 따라서 상한이 적용되지 않습니다
* **모델별 상한**: 모델의 [`modelSettings`](#modelsettings) 항목에 `maxEffortLevel`을 추가합니다. 해당 항목은 사용자 설정이나 하나의 [관리형 소스](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)처럼 둘 다 설정한 설정 소스 내에서만 그 모델에 대해 이 키를 대체합니다. 해당 소스의 상한에서 모델을 제외하려면 그곳에 `"max"`를 설정합니다. Claude Code는 다른 소스의 상한은 여전히 적용합니다

이 예시는 모든 모델의 상한을 `medium`으로 정하고 Sonnet 4.6은 제외합니다:

```json settings.json theme={null}
{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}
```

조직에서 모델에 대한 [effort 제한](https://code.claude.com/docs/ko/model-config.md#organization-effort-limits)도 설정한 경우 두 상한 중 낮은 값이 적용됩니다.

### `model`

모든 새 세션이 사용할 모델을 설정하여 매번 `/model`로 모델을 선택하지 않아도 되도록 합니다. 여기에서 설정해도 세션 중간에 전환하는 것은 막지 않습니다. 관리자가 사용자 선택을 재정의하도록 [조직 기본 모델](https://code.claude.com/docs/ko/model-config.md#organization-default-model)을 설정한 경우, 사용자, 프로젝트, 로컬 설정에서 이 키를 설정하더라도 해당 모델이 사용됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열. 모델 별칭 또는 전체 모델 ID
* **기본값**: 설정되지 않음. 따라서 Claude Code는 계정의 기본 모델을 사용합니다
* **세션별 재정의**: `--model`은 [`ANTHROPIC_MODEL`](https://code.claude.com/docs/ko/env-vars)보다 우선하며, 둘 다 한 세션에 대해서는 관리형 `model`을 포함하여 이 키보다 우선합니다. [`availableModels`](#availablemodels) 목록은 여전히 선택에 적용됩니다

```json settings.json theme={null}
{
  "model": "claude-sonnet-5"
}
```

여기의 값은 [`ANTHROPIC_DEFAULT_MODEL`](https://code.claude.com/docs/ko/model-config#set-a-default-model-for-new-sessions)보다 우선하며, Claude Code는 다른 어떤 것도 모델을 선택하지 않을 때만 `ANTHROPIC_DEFAULT_MODEL`을 사용합니다.

### `modelOverrides`

Anthropic 모델 ID를 Amazon Bedrock 추론 프로필 ARN과 같은 공급자별 모델 ID에 매핑합니다. 그러면 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. 관리자는 [Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry](https://code.claude.com/docs/ko/model-config.md#override-model-ids-per-version)에서 거버넌스, 비용 할당 또는 지역 라우팅을 위해 각 모델 버전을 특정 추론 프로필, 버전 이름 또는 배포로 라우팅하는 데 이를 사용합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 모델 ID를 공급자 모델 ID에 매핑하는 객체
* **기본값**: 설정되지 않음

이 예시는 Opus 4.6에 대한 모든 호출을 지정된 Bedrock 추론 프로필로 라우팅합니다:

```json settings.json theme={null}
{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789012:inference-profile/example"
  }
}
```

[버전별 모델 ID 재정의](https://code.claude.com/docs/ko/model-config.md#override-model-ids-per-version)를 참조하세요.

### `modelPicker`

`/model` 선택기가 제공하는 모델을 작성한 순서대로 원하는 레이블로 나열하여, 선택기가 기본 제공 라인업 뒤에 또는 그 대신 조직에서 실행하는 모델을 나열하도록 합니다. 각 행의 `model`은 그대로 사용되므로 `--model`이 허용하는 모든 것을 허용합니다. 즉 `opus`와 같은 별칭, Anthropic 모델 ID, 또는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, LLM 게이트웨이용 공급자 형식 ID를 사용할 수 있습니다. Claude Code v2.1.242 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes). Claude Code는 관리형 설정, `--settings`, 사용자 설정에서 이 키를 읽고, 복제한 저장소가 선택기의 레이블을 바꿀 수 없도록 프로젝트 및 로컬 설정에서는 무시합니다. 이 세 가지 중 키를 설정한 가장 높은 소스가 라인업 전체를 제공하며, Claude Code는 두 소스의 라인업을 결합하지 않습니다.
* **유형**: 행의 `options` 배열과 선택적 `replaceBuiltInOptions` Boolean을 가진 객체
* **기본값**: 설정되지 않음. 따라서 선택기는 기본 제공 라인업을 표시합니다

이 예시는 기본 제공 라인업 뒤에 팀이 알아볼 수 있는 이름으로 두 개의 Bedrock 배포를 추가합니다:

```json managed-settings.json theme={null}
{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}
```

#### `modelPicker`의 필드

이 키는 두 개의 필드를 받습니다. 하나는 행 자체에 대한 것이고, 다른 하나는 행이 기본 제공 라인업을 대체할지 또는 추가될지에 대한 것입니다.

| 필드 | 유형 | 동작 |
| :- | :- | :- |
| `options` | 행의 배열. 각 행에는 필수 `model`과 선택적 `label`, `description`, `behavesAs`가 있습니다 | 선택기가 이 순서대로 표시하는 행입니다. 단, 회색으로 표시된 행은 맨 아래로 이동합니다. `label`이 없으면 Claude Code는 알고 있는 모델이면 기본 제공 이름으로, 그렇지 않으면 모델 ID로 행 제목을 붙이며, `description`이 없으면 일반적인 두 번째 줄을 작성합니다 |
| `replaceBuiltInOptions` | Boolean, 기본값 `false` | `true`로 설정하면 이 행들, **Default**, 세션이 이미 사용 중인 모델의 행만 표시합니다. 설정하지 않으면 이 행들이 기본 제공 라인업 뒤에 추가됩니다 |

`options`의 항목은 `model` 옆에 선택적 `behavesAs` 문자열도 가질 수 있으며, 이를 위해서는 v2.1.257 이상이 필요합니다. `model`이 현재 버전보다 새로운 항목에 `claude-opus-4-8`처럼 현재 Claude Code 버전이 이미 알고 있는 모델의 ID로 설정합니다. 그러면 Claude Code는 해당 모델을 알 수 없는 모델로 취급하는 대신 알려진 모델의 기능과 effort 기본값을 항목에 적용합니다. 항목의 레이블과 Claude Code가 요청에서 보내는 모델 ID는 변경되지 않습니다.

`replaceBuiltInOptions`를 켜면 Claude Code는 다른 모든 행을 숨깁니다. 여기에는 기본 제공 라인업, [`availableModels`](#availablemodels) 항목에 대해 추가하는 행, [게이트웨이 검색](https://code.claude.com/docs/ko/llm-gateway-protocol.md#model-discovery)이 찾은 모델, [`ANTHROPIC_CUSTOM_MODEL_OPTION`](https://code.claude.com/docs/ko/model-config#add-a-custom-model-option)이 포함됩니다. 끄면 Claude Code는 기본 제공 라인업이 이미 포함하는 나열된 모델을 건너뜁니다. 레이블은 선택기에 표시되는 내용만 바꾸며 Claude Code가 실행하는 모델은 바꾸지 않습니다.

[`availableModels`](#availablemodels) 허용 목록은 이 행들에도 여전히 적용됩니다. 나열된 모델을 허용 목록에 추가하기 전에 [병합 동작](https://code.claude.com/docs/ko/model-config.md#merge-behavior)을 읽어 보세요. 특정 모델 ID는 해당 계열의 와일드카드 항목을 좁힙니다. Claude Code는 선택기를 표시하기 전에 각 행을 세션과 대조하여 확인하기도 합니다:

* **제거됨**: 폐기된 모델이나 조직에 액세스 권한이 없는 모델처럼 Claude Code가 제공할 수 없는 행
* **회색으로 표시됨**: 아직 선택할 수 없는 행으로, 이유와 함께 표시됩니다
* **남은 행 없음**: Claude Code는 평소처럼 허용 목록으로 필터링된 기본 제공 라인업을 유지합니다

Claude Code는 구문 분석할 수 없는 행을 제거하고 나머지는 유지합니다. [손상된 설정 파일 수정](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file)을 참조하세요.

### `modelPricing`

정가 대신 조직에서 지불하는 요율로 지출을 보고합니다. 조직에 계약 요율이 있을 때 설정하면 개발자에게 표시되는 금액이 청구서와 일치합니다. Claude Code는 `/usage`, [상태줄](https://code.claude.com/docs/ko/statusline.md), Agent SDK의 `total_cost_usd`, [`--max-budget-usd`](https://code.claude.com/docs/ko/cli-reference) 제한, [OpenTelemetry](https://code.claude.com/docs/ko/monitoring-usage.md) 비용 지표 및 이벤트에 요율을 적용합니다. 요율은 직접 제공해야 합니다. Claude Code는 계약이나 Claude Console에서 요율을 읽지 않습니다. Claude Code v2.1.242 이상이 필요합니다.

* **범위**: [`Managed`](#scopes). 서버 관리형 설정, MDM 정책, `managed-settings.json` 파일 또는 [정책 헬퍼](https://code.claude.com/docs/ko/managed-settings.md#compute-the-policy-with-a-helper-program)를 통해 키를 배포합니다. Claude Code는 사용자, 프로젝트, 로컬 설정, `--settings`, 그리고 Windows에서는 사용자가 쓸 수 있는 [HKCU 레지스트리](https://code.claude.com/docs/ko/managed-settings.md#where-each-mechanism-stores-the-policy)에 있는 이 키를 무시합니다. 서버 관리형 설정을 사용하면 각 세션은 해당 세션의 [설정 가져오기](https://code.claude.com/docs/ko/server-managed-settings.md#fetch-and-caching-behavior)가 설정을 확인할 때까지 정가로 비용을 보고합니다. Claude Code를 임베드하고 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/ko/env-vars)를 설정하는 호스트 애플리케이션은 SDK [`managedSettings`](https://code.claude.com/docs/ko/agent-sdk/typescript#options) 옵션을 통해 자체 요율표를 제공할 수 있으며, Claude Code는 어떤 관리형 소스도 이 키를 설정하지 않을 때만, 그리고 Claude Code v2.1.246 이상에서만 이를 사용합니다.
* **유형**: 선택적 `multiplier`와 선택적 `overrides` 맵을 가진 객체
* **기본값**: 설정되지 않음. 따라서 호스트 애플리케이션이 요율표를 제공하지 않는 한 Claude Code는 정가를 보고합니다

일률적인 할인이나 인상에는 `multiplier`만, 모델별 요율에는 `overrides`만 설정하거나 둘 다 설정합니다.

이 예시는 Sonnet 4.6의 계약 요율을 설정한 다음 Sonnet 행을 포함한 모든 금액을 15% 줄입니다:

```json managed-settings.json theme={null}
{
  "modelPricing": {
    "multiplier": 0.85,
    "overrides": {
      "claude-sonnet-4-6": {
        "input": 2.4,
        "output": 12,
        "cacheRead": 0.24,
        "cacheWrite": 3
      }
    }
  }
}
```

모든 금액을 인상하려면 `multiplier`를 1보다 크게, 최대 10까지 설정합니다. 인상에는 Claude Code v2.1.271 이상이 필요합니다. 이전 버전은 1보다 큰 `multiplier`를 경고와 함께 무시하고 설정의 나머지 부분은 유지합니다.

요율이 적용되었는지 확인하는 방법을 포함한 단계는 [계약 요율로 지출 보고](https://code.claude.com/docs/ko/costs.md#report-spend-at-your-contracted-rates)를 참조하세요.

#### `modelPricing`의 필드

| 필드 | 유형 | 동작 |
| :- | :- | :- |
| `multiplier` | 0보다 크고 10 이하인 숫자 | `overrides` 행이 적용되는지 여부와 관계없이 Claude Code가 계산하는 모든 비용을 조정합니다. 1 미만은 할인, 1 초과는 인상입니다 |
| `overrides` | 모델 ID를 `input`, `output`, `cacheRead`, `cacheWrite`(각각 0\~10000)를 가진 요율 객체에 매핑하는 맵 | 해당 모델의 백만 토큰당 USD 요율이며, 네 가지 모두 필수입니다. `cacheWrite`는 5분 및 1시간 캐시 쓰기를 모두 포함합니다. [`modelPricing` 행이 적용되는 모델](#which-models-a-modelpricing-row-applies-to)을 참조하세요 |

Claude Code는 빠른 모드 추가 요금이나 [미국 전용 추론 요율](https://platform.claude.com/docs/en/about-claude/pricing)을 더하지 않고 작성한 그대로 행의 요율을 사용합니다. `multiplier`도 설정하면 Claude Code는 행의 요율 위에 이를 적용합니다. Claude Code는 구문 분석할 수 없는 요율이 있는 행이나 구문 분석할 수 없는 `multiplier`를 제거하고 나머지는 유지합니다. [손상된 설정 파일 수정](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file)을 참조하세요.

#### `modelPricing` 행이 적용되는 모델

Claude Code는 행의 키를 기준으로 행이 적용되는 모델을 결정합니다:

* **기본 제공 모델의 ID**: Claude Code 자체가 기본 제공 모델에 사용하는 키로, `claude-sonnet-4-6`과 같은 모델 자체 ID이든 Bedrock, Agent Platform, Foundry ID이든 해당됩니다. Claude Code는 해당 모델의 모든 날짜 스냅샷 ID와 공급자별 ID에 행을 적용합니다.
* **그 밖의 키**: 게이트웨이 모델 별칭처럼 기본 제공 모델의 ID가 아닌 키입니다. Claude Code는 해당 ID 하나에만 행을 적용합니다. 모델 ID가 키 중 하나와 정확히 일치하면서 기본 제공 모델의 ID로 키가 지정된 행에도 해당하는 경우, Claude Code는 정확히 일치하는 항목을 사용합니다.
* **Bedrock 애플리케이션 추론 프로필**: Claude Code가 [`modelOverrides`](#modeloverrides) 맵이나 [`bedrock:GetInferenceProfile` 조회](https://code.claude.com/docs/ko/amazon-bedrock#iam-configuration)를 통해 프로필을 라우팅 대상 모델로 확인하면, Claude Code는 해당 모델의 행을 프로필에 적용합니다.

### `modelSettings`

사용하는 각 모델에 대한 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)을 저장합니다. Claude Code v2.1.251 이상이 필요합니다.

로컬 머신의 대화형 세션에서 `/effort` 또는 `/model` 선택기의 effort 슬라이더로 `low`, `medium`, `high`, `xhigh`를 기본값으로 저장하면 Claude Code는 사용 중인 모델 아래 여기에 해당 수준을 기록하므로, 이 키를 직접 편집할 일은 거의 없습니다. [VS Code 확장의 모델 선택기](https://code.claude.com/docs/ko/vs-code.md#use-the-prompt-box)에서 이러한 수준 중 하나를 선택하면 Claude Code는 같은 방식으로 여기에 저장합니다. `/effort`가 해당 세션에만 적용되는 세션은 [`effortLevel`](#effortlevel) 항목에 나열되어 있습니다.

저장한 수준을 변경하거나 제거하려면 키를 직접 편집합니다.

여기의 모델별 `effortLevel`은 같은 설정 파일의 최상위 [`effortLevel`](#effortlevel)보다 우선합니다. 파일 간에는 Claude Code가 각 모델을 개별적으로 해석합니다. 해당 모델에 대한 `effortLevel` 또는 [해당 모델에 적용되는](#effortlevel) 최상위 `effortLevel`을 설정한 우선순위가 가장 높은 [설정 파일](https://code.claude.com/docs/ko/settings.md#settings-precedence)이 결정하므로, 관리형 설정의 `effortLevel`은 사용자 설정에 저장한 수준보다 우선합니다. 실행 시 `--effort`처럼 저장된 수준을 재정의할 수 있는 다른 항목은 [effort 수준 조정](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)에 나열되어 있습니다.

한 모델의 수준을 설정하는 대신 effort 상한을 정하려면 해당 모델의 항목에 [`maxEffortLevel`](#maxeffortlevel) 필드를 추가합니다. 이 필드에는 Claude Code v2.1.267 이상이 필요합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 모델 이름을 다음 필드 중 일부를 가진 객체에 매핑하는 객체:
  * `effortLevel`: `"low"`, `"medium"`, `"high"`, `"xhigh"` 중 하나
  * [`maxEffortLevel`](#maxeffortlevel): 모델이 실행될 수 있는 가장 높은 effort 수준
  * `autoCompactWindow`: `100000`에서 `1000000` 사이의 토큰 수 또는 모델에 맞게 조정된 윈도우를 의미하는 `"auto"`. [`/autocompact`](https://code.claude.com/docs/ko/model-config#set-the-auto-compact-window)가 여기에 저장합니다. 해당 모델에 대해서는 이 값이 같은 설정 파일의 최상위 [`autoCompactWindow`](#autocompactwindow)보다 우선합니다. Claude Code v2.1.288 이상이 필요합니다
* **기본값**: 설정되지 않음

Claude Code는 각 항목을 `claude-opus-5-5`와 같은 모델의 표준 이름 아래에 기록하며, 해당 모델의 별칭, 날짜 접미사가 붙은 ID, `[1m]` ID, 인식되는 공급자별 ID를 같은 항목에 매칭합니다.

이 예시는 다른 모델은 각자의 저장된 수준이나 기본 수준을 사용하는 동안 Opus 5.5를 `high`로 유지합니다:

```json settings.json theme={null}
{
  "modelSettings": {
    "claude-opus-5-5": {
      "effortLevel": "high"
    }
  }
}
```

사용 중인 모델에 대해 저장된 수준을 지우려면 `/effort auto`를 실행합니다. Claude Code는 다른 항목과 최상위 `effortLevel`은 그대로 둡니다.

### `outputStyle`

이름으로 [출력 스타일](https://code.claude.com/docs/ko/output-styles.md)을 선택합니다. 출력 스타일은 Claude의 역할, 어조, 출력 형식을 바꾸는 저장된 지침 세트로, 기본 제공 Explanatory 및 Learning 스타일이나 직접 작성한 스타일이 이에 해당합니다.

세션 중에 이 키를 변경하면 Claude는 다음 메시지부터 새 스타일을 사용합니다. 해당 메시지의 프롬프트 캐싱 비용은 [출력 스타일 변경](https://code.claude.com/docs/ko/prompt-caching.md#changing-output-style)을 참조하세요. v2.1.251 이전에는 `/clear`를 실행하거나 새 세션을 시작한 후에야 편집 내용이 적용되었습니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열. [기본 제공](https://code.claude.com/docs/ko/output-styles.md#built-in-output-styles) 또는 [사용자 지정](https://code.claude.com/docs/ko/output-styles.md#create-a-custom-output-style) 출력 스타일의 이름
* **기본값**: 설정되지 않음. 따라서 Claude Code는 기본 스타일을 사용합니다

이 예시는 작업 사이에 교육적인 인사이트를 추가하는 기본 제공 Explanatory 스타일을 선택합니다:

```json settings.json theme={null}
{
  "outputStyle": "Explanatory"
}
```

### `promptCacheTtl`

[프롬프트 캐시](https://code.claude.com/docs/ko/prompt-caching.md)가 메인 대화를 유지하는 기간을 선택합니다. 이 키는 대화형, `-p`, Agent SDK 턴과 Claude Code가 이와 함께 인라인으로 실행하는 헬퍼에 적용됩니다. 1시간 수명은 더 긴 휴식 동안에도 캐시를 유지하며, API는 5분 수명보다 [각 캐시 쓰기에 더 높은 요율을 청구](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)합니다. Claude Code v2.1.242 이상이 필요합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열. 다음 중 하나:
  * `"5m"`: 캐시가 5분 동안 유지됩니다
  * `"1h"`: 캐시가 1시간 동안 유지됩니다
* **기본값**: 설정되지 않음. 따라서 각 메인 대화 요청은 [기본 수명](https://code.claude.com/docs/ko/prompt-caching.md#which-ttl-each-request-gets)을 받습니다
* **세션별 재정의**: [`FORCE_PROMPT_CACHING_5M`](https://code.claude.com/docs/ko/env-vars)이 다른 모든 것보다 우선하고, 그다음 [`CLAUDE_CODE_PROMPT_CACHE_TTL`](https://code.claude.com/docs/ko/env-vars), 그다음 이 키, 마지막으로 [`ENABLE_PROMPT_CACHING_1H`](https://code.claude.com/docs/ko/env-vars) 순입니다

이 예시는 메인 대화를 1시간 수명으로 유지하고 서브에이전트는 5분으로 둡니다:

```json settings.json theme={null}
{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}
```

각 수명의 비용은 [캐시 수명](https://code.claude.com/docs/ko/prompt-caching.md#cache-lifetime)을 참조하세요.

### `showThinkingSummaries`

대화형 세션에서 Claude의 [확장 사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking) 요약을 확인합니다. `Ctrl+O`로 사고를 펼칠 때 전체 요약을 보려면 설정합니다. 설정하지 않았거나 `false`이면 Anthropic API가 thinking 블록을 편집하여 가리고 Claude Code는 접힌 스텁을 표시합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: `Ctrl+O`로 사고를 펼치면 전체 사고 요약이 표시됩니다
  * `false`: Anthropic API가 thinking 블록을 가리고 Claude Code는 접힌 스텁을 표시합니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "showThinkingSummaries": true
}
```

가리기는 표시되는 내용만 바꾸며 모델이 생성하는 내용은 바꾸지 않습니다. 사고 비용을 줄이려면 대신 [예산을 낮추거나 사고를 비활성화](https://code.claude.com/docs/ko/model-config.md#extended-thinking)하세요.

### `subagentPromptCacheTtl`

[프롬프트 캐시](https://code.claude.com/docs/ko/prompt-caching.md)가 Claude Code가 메인 대화 외부에서 보내는 요청을 유지하는 기간을 선택합니다. 이 키는 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md), [워크플로](https://code.claude.com/docs/ko/workflows.md), 그리고 압축 및 세션 제목과 같은 Claude Code 자체의 백그라운드 및 헬퍼 요청에 적용됩니다. 1시간 수명은 더 긴 휴식 동안에도 캐시를 유지하며, API는 5분 수명보다 [각 캐시 쓰기에 더 높은 요율을 청구](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)합니다. Claude Code v2.1.242 이상이 필요합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열. 다음 중 하나:
  * `"5m"`: 캐시가 5분 동안 유지됩니다
  * `"1h"`: 캐시가 1시간 동안 유지됩니다
* **기본값**: 설정되지 않음. 따라서 이러한 각 요청은 [기본 수명](https://code.claude.com/docs/ko/prompt-caching.md#which-ttl-each-request-gets)을 받습니다
* **세션별 재정의**: [`FORCE_PROMPT_CACHING_5M`](https://code.claude.com/docs/ko/env-vars)이 다른 모든 것보다 우선하고, 그다음 [`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`](https://code.claude.com/docs/ko/env-vars), 그다음 이 키, 그다음 모든 요청에 1시간 수명을 요청하는 [`ENABLE_PROMPT_CACHING_1H`](https://code.claude.com/docs/ko/env-vars) 순입니다. 서브에이전트 자체 frontmatter 값의 순위는 [TTL 직접 선택](https://code.claude.com/docs/ko/prompt-caching.md#choose-the-ttl-yourself)을 참조하세요

이 예시는 서브에이전트와 메인 대화 외부의 다른 요청에 1시간 수명을 부여합니다:

```json settings.json theme={null}
{
  "subagentPromptCacheTtl": "1h"
}
```

이 키는 [`promptCacheTtl`](#promptcachettl)이 다루지 않는 요청을 다루므로, Claude Code가 보내는 모든 요청의 수명을 선택하려면 둘 다 설정하세요. 서브에이전트의 캐시가 메인 대화의 캐시와 어떻게 다른지는 [서브에이전트와 캐시](https://code.claude.com/docs/ko/prompt-caching.md#subagents-and-the-cache)를 참조하세요.

### `switchModelsOnFlag`

[안전 분류기가 요청에 플래그를 지정](https://code.claude.com/docs/ko/model-config.md#automatic-model-fallback)할 때 수행할 작업을 선택합니다. 폴백 모델로 전환하여 계속하거나, 일시 중지하여 전환과 프롬프트 편집 중에서 선택할 수 있도록 합니다.

* **범위**: [`Any file`](#scopes). `/config`에서 **Switch models when a message is flagged**로 표시되며, 옵션은 **Switch automatically**와 **Ask each time**입니다.
* **유형**: Boolean
  * `true`: Claude Code가 폴백 모델로 전환하고 계속합니다
  * `false`: 대화형 세션에서는 Claude Code가 일시 중지하여 전환과 프롬프트 편집 중에서 선택할 수 있도록 합니다. `-p` 실행처럼 대화 상자를 표시할 수 없는 곳에서는 플래그가 지정된 요청이 오류로 종료됩니다
* **기본값**: 설정되지 않음. Claude Code는 자동으로 전환하지만, 대화형 세션에서는 [먼저 확인](https://code.claude.com/docs/ko/model-config.md#ask-before-switching)할 수 있습니다

```json settings.json theme={null}
{
  "switchModelsOnFlag": false
}
```

[전환 전에 확인](https://code.claude.com/docs/ko/model-config.md#ask-before-switching)을 참조하세요.

### `ultracode`

[ultracode](https://code.claude.com/docs/ko/workflows.md#let-claude-decide-with-ultracode)를 켠 상태로 세션을 시작합니다. 켜면 Claude는 요청을 기다리지 않고 실질적인 각 작업에 대해 워크플로를 계획합니다. Claude는 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)가 활성화되어 있고 모델이 `xhigh` effort를 지원할 때만 워크플로를 계획합니다. 이 키는 세션의 effort 수준을 바꾸지 않습니다. ultracode는 세션이 사용하는 수준에서 실행됩니다. Claude Code는 이 키를 읽기만 하고 쓰지는 않습니다. `/effort ultracode`는 현재 세션에 대해서만 ultracode를 켭니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: 동적 워크플로가 활성화되어 있고 모델이 `xhigh`를 지원하면 ultracode를 켠 상태로 세션이 시작됩니다
  * `false`: ultracode를 끈 상태로 세션이 시작됩니다
* **기본값**: 설정되지 않음. 따라서 ultracode가 꺼져 있습니다
* **세션별 재정의**: `/effort ultracode`는 이 키 없이 한 세션에 대해 ultracode를 켜고, `/effort ultracode off`는 이 키가 `true`일 때 한 세션에 대해 ultracode를 끕니다. `--effort ultracode` 플래그도 `xhigh` effort로 한 세션에 대해 ultracode를 켭니다

```json settings.json theme={null}
{
  "ultracode": true
}
```

세션의 effort 수준은 [`effortLevel`](#effortlevel), [`modelSettings`](#modelsettings) 및 기타 [effort 소스](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)에서 결정되며, [`maxEffortLevel`](#maxeffortlevel)과 같은 [effort 상한](https://code.claude.com/docs/ko/model-config.md#organization-effort-limits)은 ultracode를 끄지 않고 해당 수준을 낮춥니다. 이 동작과 `/effort ultracode off` 형식에는 Claude Code v2.1.284 이상이 필요합니다. v2.1.284 이전에는 `ultracode: true`가 세션을 `xhigh` effort로 실행했으며, `xhigh` 미만의 effort 상한이 있으면 ultracode가 꺼진 상태로 유지되었습니다. Agent SDK `apply_flag_settings` 제어 요청도 이 키를 허용합니다.

## 권한 설정

Claude가 묻지 않고 수행할 수 있는 작업, 세션이 시작되는 권한 모드, 자동 모드 분류기가 허용하는 항목을 결정합니다. 규칙 구문과 권한 모델은 [권한 구성](https://code.claude.com/docs/ko/permissions.md)을 참조하십시오.

### `allowManagedPermissionRulesOnly`

관리형 설정을 권한 규칙의 유일한 설정 소스로 만듭니다. 그러면 Claude Code는 사용자, 프로젝트, 로컬 및 `--settings` 파일의 `allow`, `ask`, `deny` 규칙을 무시하고, `--allowedTools`를 무시하며, 권한 프롬프트에서 항상 허용 선택지를 숨기고, 새 규칙 저장을 중단합니다.

[임베딩 호스트의 상위 설정](https://code.claude.com/docs/ko/managed-settings.md#let-an-embedding-host-add-policy)이 적용되는 경우 Claude Code는 이를 관리형 계층의 일부로 취급합니다. 해당 설정의 `allow` 규칙과 `additionalDirectories`는 제외하고, `deny` 및 `ask` 규칙은 유지하되 패턴이 `!`로 시작하는 `Read` 및 `Edit` 규칙은 제외합니다. 이 키의 설정 여부와 관계없이 호스트는 `!` 규칙으로 관리형 규칙에서 경로를 제외할 수 없습니다.

`--disallowedTools` 규칙과 현재 세션의 `deny` 및 `ask` 규칙은 Claude Code가 세션 도중 설정을 다시 로드한 후에도 계속 적용됩니다. 이러한 규칙은 제한만 하므로 관리형 규칙이 부여하는 범위를 넓힐 수 없습니다. v2.1.257 이전에는 Claude Code가 첫 설정 재로드 시 이러한 명령줄 및 세션 규칙을 제외했습니다.

`--disallowedTools` 또는 세션 규칙의 `!` 패턴이 제외할 수 있는 범위는 [Read 및 Edit 규칙](https://code.claude.com/docs/ko/permissions.md#read-and-edit)을 참조하십시오.

이 키를 설정하면 Claude Code v2.1.282 이상은 다음 소스의 스킬 및 `.claude/commands/` 파일에 있는 [`allowed-tools`](https://code.claude.com/docs/ko/skills#pre-approve-tools-for-a-skill) frontmatter도 무시합니다.

* 저장소의 `.claude/` 디렉터리
* [claude.ai에서 동기화된 스킬](https://code.claude.com/docs/ko/skills.md#where-synced-skills-load)을 포함한 `~/.claude/skills/` 및 `~/.claude/commands/` 디렉터리
* `--add-dir` 디렉터리
* `~/.claude/skills/` 또는 프로젝트의 `.claude/skills/` 안에 있는 [`.claude-plugin` 매니페스트로 선언된 플러그인](https://code.claude.com/docs/ko/plugins/loading#plugins-shared-through-a-repository)
* 하나의 세션에만 로드되어 ID가 [`@inline`](https://code.claude.com/docs/ko/plugins/loading#find-where-a-plugin-came-from)으로 끝나는 플러그인(다음 조건을 모두 충족하는 경우)
  * 세션이 Claude Desktop 앱 자체가 Claude Code를 시작하는 [Code 세션](https://code.claude.com/docs/ko/desktop.md#environment-configuration) 또는 [Cowork 세션](https://code.claude.com/docs/ko/managed-settings.md#where-and-when-a-policy-applies)이며, 클라우드 세션이 아닌 경우
  * 임베딩 호스트의 [상위 설정](https://code.claude.com/docs/ko/managed-settings.md#let-an-embedding-host-add-policy)만이 아니라 관리형 설정에서 이 키를 설정한 경우
  * 세션이 Claude Code v2.1.305 이상을 실행하는 경우

관리형 설정의 스킬과 번들 스킬은 `allowed-tools`를 유지합니다. 해당 Desktop 세션 외부의 `@inline` 플러그인도 [`anthropic-skills`](https://code.claude.com/docs/ko/skills#names-reserved-for-synced-skills)라는 이름의 플러그인을 제외하고 이를 유지합니다. 스킬의 `disallowed-tools`는 계속 적용됩니다. Claude Code가 이 필드를 무시할 때 개발자에게 표시되는 내용은 [관리형 권한 규칙만 적용되는 경우](https://code.claude.com/docs/ko/skills.md#when-only-managed-permission-rules-apply)를 참조하십시오.

* **범위**: [`Managed`](#scopes)
* **타입**: Boolean
  * `true`: 관리형 설정이 권한 규칙의 유일한 설정 소스가 됩니다
  * `false`: Claude Code가 관리형 규칙에 더해 사용자, 프로젝트, 로컬 및 `--settings` 파일의 권한 규칙을 적용합니다
* **기본값**: 설정되지 않음. 따라서 Claude Code는 관리형 규칙에 더해 사용자, 프로젝트, 로컬 설정과 `--settings`의 권한 규칙을 적용합니다

```json managed-settings.json theme={null}
{
  "allowManagedPermissionRulesOnly": true
}
```

이 키는 MCP 서버 허용 목록을 잠그지 않습니다. 이를 위해서는 [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly)를 설정하십시오. [관리형 전용 설정](https://code.claude.com/docs/ko/managed-settings.md#managed-only-settings)을 참조하십시오.

### `autoMode`

[자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 분류기가 차단하고 허용하는 항목에 자체 규칙을 추가합니다. 이를 사용해 조직이 신뢰하는 저장소, 버킷, 도메인을 분류기에 알려 일상적인 내부 작업을 더 이상 차단하지 않도록 합니다. 분류기에는 [기본 제공 허용 및 거부 규칙](https://code.claude.com/docs/ko/auto-mode-config.md#inspect-the-defaults-and-your-effective-config)이 포함되어 있습니다. 배열에 리터럴 문자열 `"$defaults"`를 포함하면 해당 위치에 기본 제공 규칙을 유지하고 그 주변에 자체 규칙을 추가할 수 있습니다. 이를 생략하면 기본 제공 규칙이 자체 규칙으로 대체됩니다.

* **범위**: [`User or managed`](#scopes)
* **타입**: 산문 규칙으로 구성된 `environment`, `allow`, `soft_deny`, `hard_deny` 배열과 [`classifyAllShell`](#automode-classifyallshell) Boolean을 포함하는 객체
* **기본값**: 설정되지 않음. 따라서 분류기는 [기본 제공 규칙](https://code.claude.com/docs/ko/auto-mode-config.md#inspect-the-defaults-and-your-effective-config)만 사용합니다

이 예시는 `"$defaults"`를 통해 기본 제공 `soft_deny` 규칙을 유지하고, `terraform apply`를 차단하는 규칙을 하나 더 추가합니다.

```json settings.json theme={null}
{
  "autoMode": {
    "soft_deny": ["$defaults", "Never run terraform apply"]
  }
}
```

이러한 파일 중 둘 이상이 같은 배열을 설정하면 Claude Code는 항목을 연결합니다. 규칙 형식과 각 배열이 적용되는 방식은 [자동 모드 구성](https://code.claude.com/docs/ko/auto-mode-config.md)을 참조하십시오.

### `autoMode.classifyAllShell`

자동 모드가 활성화된 동안 모든 Bash 및 PowerShell 명령을 자동 모드 분류기로 보냅니다. 기본적으로 자동 모드는 임의의 코드를 실행할 수 있는 허용 규칙만 일시 중지합니다. 즉, `Bash(*)` 같은 도구 전체 및 와일드카드 규칙과 `Bash(python *)` 같은 인터프리터 또는 셸 래퍼 접두사입니다. `Bash(npm test)`처럼 다른 허용 규칙과 일치하는 명령은 [명령별 허용 도메인](https://code.claude.com/docs/ko/sandboxing.md#per-command-allowed-domains-in-auto-mode)을 포함하지 않는 한 분류기를 건너뜁니다. 분류기를 건너뛰면 규칙의 접두사가 예상하지 못한 파괴적인 인수가 감지되지 않고 통과할 수 있습니다. 이 키를 설정하면 세션 동안 모든 셸 허용 규칙이 일시 중지되어 분류기가 모든 명령을 검토합니다. Claude Code v2.1.193 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes). [`autoMode`](#automode)를 읽는 모든 위치에서 읽습니다.
* **타입**: Boolean
  * `true`: 자동 모드가 활성화된 동안 Claude Code는 모든 Bash 및 PowerShell 명령을 분류기로 보내고 셸 허용 규칙을 일시 중지합니다. 자동 모드 외부에서는 규칙이 계속 적용됩니다
  * `false`: 자동 모드는 `Bash(*)` 및 `Bash(python *)`처럼 임의의 코드를 실행할 수 있는 허용 규칙만 일시 중지합니다. 다른 허용 규칙과 일치하는 명령은 [명령별 허용 도메인](https://code.claude.com/docs/ko/sandboxing.md#per-command-allowed-domains-in-auto-mode)을 포함하지 않는 한 분류기를 건너뛰고, 그 외의 모든 셸 명령은 분류기를 거칩니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "autoMode": {
    "classifyAllShell": true
  }
}
```

[모든 셸 명령을 분류기로 라우팅](https://code.claude.com/docs/ko/auto-mode-config.md#route-all-shell-commands-through-the-classifier)을 참조하십시오.

### `disableAutoMode`

`Shift+Tab` 순환에서 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode)를 제거합니다. `--permission-mode auto`, 설정 파일 또는 기본 제공 기본값 등으로 인해 원래 [자동 모드로 시작](https://code.claude.com/docs/ko/permission-modes.md#which-mode-a-session-starts-in)될 세션은 대신 `default`로 시작합니다. 관리자는 조직의 개발자가 자동 모드를 사용하지 못하도록 관리형 설정에서 이를 설정합니다.

* **범위**: [`Any file`](#scopes). 사용자가 재정의할 수 없는 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 가장 유용합니다. `permissions` 아래에서 `permissions.disableAutoMode`로도 허용됩니다.
* **타입**: 문자열 `"disable"`
* **기본값**: 설정되지 않음

```json settings.json theme={null}
{
  "disableAutoMode": "disable"
}
```

### `permissions`

Claude가 묻지 않고 사용할 수 있는 도구, 항상 확인을 요청하는 도구, 차단되는 도구를 제어하고, 세션이 시작되는 [권한 모드](https://code.claude.com/docs/ko/permission-modes.md)를 설정합니다. 아래의 모든 `permissions.*` 키는 이 객체 아래에 중첩됩니다.

* **범위**: [`Any file`](#scopes)
* **타입**: `allow`, `ask`, `deny`, `additionalDirectories`, `blockReadsOutsideWorkingDirectories`, `defaultMode`, `disableBypassPermissionsMode`, `disableAutoMode`를 포함하는 객체
* **기본값**: 설정되지 않음

이 예시는 `npm run` 명령을 묻지 않고 승인하고, `git push` 전에 확인을 요청하며, `.env` 읽기를 차단하고, 세션을 `acceptEdits`로 시작합니다.

```json settings.json theme={null}
{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits"
  }
}
```

세 가지 규칙 배열은 하나의 구문을 공유합니다. `permissions.allow` 아래의 [권한 규칙 구문](#permission-rule-syntax)을 참조하십시오. 여러 파일의 권한 규칙이 결합되는 방식은 [범위 간 권한 규칙 병합 방식](https://code.claude.com/docs/ko/permissions.md#settings-precedence)을, 일반적인 설정 키가 결합되는 방식은 설정 가이드의 [설정 우선순위](https://code.claude.com/docs/ko/settings.md#settings-precedence)를 참조하십시오.

### `useAutoModeDuringPlan`

Claude Code가 플랜 모드에서 자동 모드 분류기를 사용해 셸 명령을 검토할지 여부를 선택합니다. 기본값 `true`에서는 자동 모드를 사용할 수 있을 때 계획 중 분류기가 각 명령을 검토하며, [중요 경로 제거](https://code.claude.com/docs/ko/permission-modes.md#critical-paths)를 제외하고는 프롬프트가 표시되지 않습니다. 기본 제공 읽기 전용 집합 외의 모든 명령에 대해 권한 프롬프트를 받으려면 `false`로 설정하십시오. `/config`에는 **Use auto mode during plan**으로 표시됩니다.

* **범위**: [`User, local, or managed`](#scopes). 저장소는 사용자를 대신해 이를 끌 수 없습니다.
* **타입**: Boolean
  * `true`: 설정되지 않은 경우와 동일합니다. 자동 모드를 사용할 수 있을 때 분류기가 계획 중 각 셸 명령을 검토하며, [중요 경로 제거](https://code.claude.com/docs/ko/permission-modes.md#critical-paths)를 제외하고는 확인을 요청하지 않습니다. 이러한 파일 중 하나라도 `false`를 설정하면 꺼집니다
  * `false`: 기본 제공 읽기 전용 집합 외의 모든 명령에 대해 권한 프롬프트가 표시됩니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "useAutoModeDuringPlan": false
}
```

### `permissions.allow`

Claude Code가 묻지 않고 승인하는 도구 사용을 나열합니다. MCP 규칙에서 `*`는 `mcp__github__get_*`처럼 `mcp__<server>__` 접두사 뒤의 도구 이름에만 사용할 수 있으며, 서버 이름에는 사용할 수 없습니다.

* **범위**: [`Any file`](#scopes)
* **타입**: 권한 규칙 문자열 배열
* **기본값**: 설정되지 않음
* **세션별 재정의**: `--allowedTools`는 하나의 세션에 대한 허용 규칙을 추가하며, 모든 설정 파일의 거부 규칙은 여전히 해당 규칙이 지정하는 도구를 차단합니다

이 예시는 `git diff`를 승인하고 Claude Code가 묻지 않고 `.zshrc`를 읽을 수 있게 합니다.

```json settings.json theme={null}
{
  "permissions": {
    "allow": ["Bash(git diff *)", "Read(~/.zshrc)"]
  }
}
```

Claude Code는 사용자가 해당 폴더의 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 후에만 프로젝트의 `.claude/settings.json`에 있는 `allow` 규칙을 적용합니다.

#### 권한 규칙 구문

권한 규칙은 `Tool` 또는 `Tool(specifier)` 형식을 따릅니다. Claude Code는 `deny` 규칙을 먼저 평가한 다음 `ask`, 그다음 `allow`를 평가하며, 각 규칙의 구체성과 관계없이 처음 일치하는 규칙이 결정합니다. [권한 규칙 평가 순서](https://code.claude.com/docs/ko/permissions.md#manage-permissions)를 참조하십시오.

각 행은 하나의 규칙 형태와 일치하는 대상을 보여 줍니다.

| 규칙 | 일치하는 대상 |
| :- | :- |
| `Bash` | 모든 Bash 명령 |
| `Bash(npm run *)` | `npm run`으로 시작하는 명령 |
| `Read(./.env)` | `.env` 파일 읽기 |
| `WebFetch(domain:example.com)` | example.com에 대한 가져오기 요청 |

와일드카드 동작, Read, Edit, WebFetch, MCP, Agent 규칙의 도구별 패턴, Bash 패턴의 보안 제한 사항을 포함한 전체 규칙 구문은 [권한 규칙 구문](https://code.claude.com/docs/ko/permissions.md#permission-rule-syntax)을 참조하십시오.

### `permissions.ask`

`acceptEdits` 또는 `bypassPermissions`처럼 원래는 승인할 권한 모드에서도 확인을 요청하는 도구 사용을 나열합니다. `dontAsk` 모드에서는 Claude Code가 확인을 요청하는 대신 일치하는 도구 사용을 거부합니다.

* **범위**: [`Any file`](#scopes)
* **타입**: 권한 규칙 문자열 배열
* **기본값**: 설정되지 않음

```json settings.json theme={null}
{
  "permissions": {
    "ask": ["Bash(git push *)"]
  }
}
```

### `permissions.deny`

Claude Code가 차단하는 도구 사용을 나열합니다. API 키, 시크릿 또는 환경 값이 담긴 파일에 사용하십시오. Claude Code는 일치하는 파일을 파일 검색 및 검색 결과에서 제외하고, 해당 파일 읽기를 거부하며, 일치하는 경로에서 [Edit 및 Write 도구](https://code.claude.com/docs/ko/permissions.md#read-and-edit)를 차단합니다.

Read 및 Edit 거부 규칙은 Claude의 기본 제공 파일 도구, `cat`, `head`, `tail`, `sed`, `tee`처럼 Claude Code가 Bash에서 인식하는 파일 명령, 그리고 `> file` 및 `< file` 같은 Bash [리디렉션](https://code.claude.com/docs/ko/permissions.md#redirections)의 대상에 적용됩니다. `grep -r pattern .`처럼 파일 이름을 지정하지 않고 파일을 읽는 명령이나 임의의 하위 프로세스에는 적용되지 않으므로, OS 수준의 적용을 위해서는 [샌드박스를 활성화](https://code.claude.com/docs/ko/sandboxing.md)하십시오.

* **범위**: [`Any file`](#scopes)
* **타입**: 권한 규칙 문자열 배열
* **기본값**: 설정되지 않음
* **세션별 재정의**: `--disallowedTools`는 이 키와 함께 하나의 세션에 대한 거부 규칙을 추가합니다

이 예시는 `.env` 파일, `secrets` 디렉터리, 자격 증명 파일 읽기를 거부하고 `curl` 명령을 차단합니다.

```json settings.json theme={null}
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(curl *)"
    ]
  }
}
```

도구 이름에는 glob 패턴을 사용할 수 있으므로 `"*"`는 모든 도구를, `"mcp__*"`는 모든 MCP 도구를 거부합니다. Claude Code는 Claude가 사용할 수 있는 다른 도구가 하나라도 남아 있는 한 [`EndConversation`](https://code.claude.com/docs/ko/tools-reference#endconversation-tool-behavior) 도구에 대한 거부 규칙을 무시합니다. `Bash` 거부 규칙은 Claude가 작성한 그대로의 명령과 일치하므로 `Bash(curl *)`는 `/usr/bin/curl` 또는 `sh -c 'curl …'`을 막지 못합니다. [Bash 규칙이 일치하지 않는 항목](https://code.claude.com/docs/ko/permissions.md#bash-rule-limits)을 참조하십시오. 이 키는 deprecated된 `ignorePatterns` 구성을 대체합니다.

### `permissions.additionalDirectories`

시작한 디렉터리 외부의 디렉터리를 추가 [작업 디렉터리](https://code.claude.com/docs/ko/permissions.md#working-directories)로 지정해 Claude에 파일 접근 권한을 부여합니다. 대부분의 `.claude/` 구성은 이러한 디렉터리에서 [검색되지 않습니다](https://code.claude.com/docs/ko/permissions.md#additional-directories-grant-file-access-not-configuration).

* **범위**: [`Any file`](#scopes). 단, 프로젝트 및 로컬 항목이 부여하는 [샌드박스 쓰기 접근에는 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox)이 있습니다
* **타입**: 디렉터리 경로 배열
* **기본값**: 설정되지 않음
* **세션별 재정의**: `--add-dir` 및 `/add-dir`은 이 키와 함께 하나의 세션에 대한 디렉터리를 추가합니다

```json settings.json theme={null}
{
  "permissions": {
    "additionalDirectories": ["../docs/"]
  }
}
```

`allow` 규칙과 마찬가지로 프로젝트의 `.claude/settings.json`에 있는 항목은 사용자가 해당 폴더의 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 후에만 적용됩니다.

### `permissions.blockReadsOutsideWorkingDirectories`

`bypassPermissions`를 포함한 모든 권한 모드에서 Claude의 파일 도구가 [작업 디렉터리](https://code.claude.com/docs/ko/permissions.md#working-directories) 외부의 읽기를 거부하도록 합니다. Claude Code는 해당 경로에 대한 `Read`, `Grep`, `Glob`, `LSP` 호출을 거부하고, `/add-dir`로 디렉터리를 추가하도록 사용자에게 요청하라고 Claude에 알립니다. `~/.claude/` 아래의 스킬, 플러그인, 규칙, 에이전트, 명령, `CLAUDE.md` 메모리 파일처럼 Claude Code 자체에 필요한 파일은 계속 읽을 수 있습니다. Claude Code v2.1.257 이상이 필요합니다.

Claude Code는 셸 명령을 같은 방식으로 거부하지 않습니다.

* [어떤 모드에서도 자동 승인되지 않는 작업](https://code.claude.com/docs/ko/permission-modes.md#actions-no-mode-auto-approves)에서는 이러한 경로를 읽는 셸 명령이 언제 확인을 요청하는지 다룹니다
* [차단 상태에서의 샌드박스 명령](#sandboxed-commands-under-the-block)에서는 샌드박스 명령이 읽을 수 있는 항목을 다룹니다

디렉터리를 두 번 이상 변경하거나 서브셸을 실행하는 명령처럼 셸 파서가 추적할 수 없는 Bash 명령은 자동 모드 및 `bypassPermissions` 모드에서도 확인을 요청합니다. 이 프롬프트는 명령이 작업 디렉터리 외부의 경로를 지정하지 않는 경우에도 표시됩니다. 명령이 [샌드박스](https://code.claude.com/docs/ko/sandboxing.md)에서 실행되고 샌드박스가 차단을 적용하는 경우에는 이 프롬프트가 적용되지 않습니다.

[작업 디렉터리 외부에서 처음 읽기 전에 자동 모드가 표시하는 프롬프트](https://code.claude.com/docs/ko/permission-modes.md#first-read-outside-the-working-directories)에서 이러한 읽기를 차단하도록 선택하면 Claude Code도 여기에 `true`를 기록합니다.

* **범위**: [`Any file`](#scopes). 어느 파일에서든 `true`가 적용되므로, 저장소는 자체적으로 차단을 켤 수는 있지만 사용자의 차단을 해제할 수는 없습니다.
* **타입**: Boolean
  * `true`: Claude의 파일 도구가 작업 디렉터리 외부의 읽기를 거부합니다
  * `false`: 설정되지 않은 경우와 동일합니다. 다른 파일이 `true`를 설정하면 차단은 계속 적용됩니다
* **기본값**: 설정되지 않음. 따라서 작업 디렉터리 외부의 읽기는 [권한 모드](https://code.claude.com/docs/ko/permission-modes.md)를 따릅니다

```json settings.json theme={null}
{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": true
  }
}
```

`--add-dir`, `/add-dir` 또는 사용자나 관리형 설정의 `additionalDirectories`로 추가한 디렉터리는 차단 시 작업 디렉터리로 간주됩니다. 저장소 설정에서만 추가된 디렉터리는 간주되지 않습니다. 즉, `.claude/settings.json`에 있는 디렉터리와, git이 `.claude/settings.local.json` 파일을 추적되지 않는 파일로 보고하는 경우를 제외한 해당 파일의 디렉터리는 간주되지 않습니다. git 저장소가 아닌 디렉터리이거나 git이 해당 파일을 추적하는 경우 Claude Code는 `.claude/settings.local.json`을 저장소 설정으로 취급하므로, 계속 읽을 수 있게 하려는 디렉터리는 대신 사용자 설정에 넣으십시오.

[`autoMemoryDirectory`](#automemorydirectory)가 프로젝트의 `.claude/settings.json` 또는 [저장소에서 제공된 것으로 취급되는](https://code.claude.com/docs/ko/permissions.md#when-your-local-settings-file-needs-trust) `.claude/settings.local.json`에서 오는 경우, Claude Code는 해당 디렉터리에서 [자동 메모리](https://code.claude.com/docs/ko/memory.md#storage-location)를 로드하지 않으며 해당 디렉터리에 저장하지도 않습니다.

차단을 해제하려면 이 키를 설정한 모든 설정 파일에서 키를 제거한 다음 새 세션을 시작하십시오.

#### 차단 상태에서의 샌드박스 명령

[샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)이 켜져 있으면 차단이 샌드박스 명령에도 적용됩니다. Claude Code는 샌드박스 명령에 대해 홈 디렉터리와 사용자 파일을 보관하는 다른 루트(`/Users`, `/home`, `/root`, `/Volumes`, `/mnt`, `/media`, `/run/media`, `/srv`)에 대한 읽기 접근을 거부합니다. 그런 다음 작업 디렉터리, 세션에서 Claude Code가 생성하는 [워크트리](https://code.claude.com/docs/ko/worktrees.md), 세션 임시 디렉터리, 스킬 및 플러그인처럼 명령에 필요한 `~/.claude`의 일부를 다시 엽니다. 차단이 적용되는 동안 저장소 설정의 `allowRead` 및 `allowWrite` 항목은 간주되지 않습니다.

Claude Code가 세션 도중 진입한 워크트리를 포함하여 세션의 작업 디렉터리가 연결된 [git worktree](https://code.claude.com/docs/ko/worktrees.md)인 경우, 저장소의 공통 `.git` 디렉터리는 샌드박스 명령이 계속 읽고 쓸 수 있으므로 git이 해당 위치에서 계속 작동합니다.

다음 경우에는 차단이 샌드박스 명령에 적용되지 않지만 Claude의 파일 도구는 계속 차단을 적용합니다.

* [`sandbox.filesystem.disabled`](#sandbox-filesystem-disabled)를 통해 파일 시스템 격리가 꺼진 경우
* [`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly)가 설정된 경우
* Claude Code를 시작한 디렉터리의 경로에 `*`, `?`, `[` 같은 glob 문자가 포함된 경우

차단 상태에서 Claude Code는 `git`이 사용자의 ID와 설정을 유지하도록 전역 git 구성 파일을 샌드박스 명령에 다시 엽니다.

* `~/.gitconfig`
* `$XDG_CONFIG_HOME/git`(기본값 `~/.config/git`) 아래의 `config`, `ignore`, `attributes` 파일
* 전역 git 구성이 `[include]`, `[includeIf]`, `core.excludesFile` 또는 `core.attributesFile`을 통해 지정하는 파일

Claude Code는 각 파일을 개별적으로 판단합니다. 파일이 직접 또는 심볼릭 링크를 통해 샌드박스 명령이 쓸 수 있는 위치에 있으면 Claude Code는 해당 파일이 지정하는 파일을 다시 열지 않습니다.

Linux 및 WSL2에서는 심볼릭 링크인 구성 파일이 자체 경로에서 읽을 수 없는 상태로 남을 수 있으며, 이 경우 `git`은 해당 파일 없이 실행됩니다. `~/.git-credentials` 및 `$XDG_CONFIG_HOME/git/credentials`는 계속 차단됩니다.

다시 열린 파일에 `http.extraHeader` 토큰 같은 시크릿이 있으면 해당 경로를 [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread)에 추가하십시오. 파일을 포함하는 `denyRead` 항목은 항상 이 재열기보다 우선합니다.

### `permissions.defaultMode`

새 세션이 시작되는 [권한 모드](https://code.claude.com/docs/ko/permission-modes.md)를 설정합니다. 설정하지 않으면 세션은 사용 환경의 [기본 제공 기본값](https://code.claude.com/docs/ko/permission-modes.md#which-mode-a-session-starts-in)으로 시작합니다.

* **범위**: [`Any file`](#scopes). `auto` 및 `bypassPermissions`는 프로젝트 또는 로컬 설정에서는 적용되지 않으므로 대신 `~/.claude/settings.json`에서 설정하십시오. v2.1.257 이전에는 `bypassPermissions`가 모든 파일에서 적용되었습니다. VS Code 확장이 시작하는 대화의 경우 Claude Code는 사용자, 관리형 및 `--settings` 값만 읽습니다.
* **타입**: 다음 중 하나의 문자열
  * `"default"`: Claude Code가 읽기만 묻지 않고 실행합니다
  * `"acceptEdits"`: Claude Code가 파일 편집과 `mkdir`, `mv` 같은 일반적인 파일 시스템 명령도 묻지 않고 실행합니다
  * `"plan"`: Claude Code가 읽고 계획하지만 사용자가 계획을 승인할 때까지 편집을 차단합니다
  * `"auto"`: Claude Code가 일상적인 프롬프트 없이 실행합니다. 셸 명령 및 네트워크 요청 같은 작업이 실행되기 전에 백그라운드 분류기가 해당 작업이 사용자의 요청과 일치하는지 확인합니다
  * `"dontAsk"`: Claude Code가 원래 확인을 요청할 모든 호출을 자동으로 거부합니다. 단, 설치한 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)는 여전히 [해당 호출 중 일부](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods)를 승인할 수 있습니다. 작업 디렉터리 내부의 파일 읽기, 승인이 필요 없는 기타 작업, 사전 승인된 도구는 [네트워크 경로](https://code.claude.com/docs/ko/permissions.md#network-paths)에서의 읽기를 제외하고 계속 실행됩니다
  * `"bypassPermissions"`: Claude Code가 모든 것을 묻지 않고 실행합니다
  * `"manual"`: `"default"`의 별칭입니다
* **기본값**: 설정되지 않음
* **세션별 재정의**: `--permission-mode`와 `bypassPermissions`에 해당하는 `--dangerously-skip-permissions`는 하나의 세션에서 이 키보다 우선합니다

```json settings.json theme={null}
{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}
```

권한 규칙은 모든 모드 위에 적용됩니다. `deny` 규칙은 `bypassPermissions`를 포함한 모든 모드에서 차단합니다. [권한 모드](https://code.claude.com/docs/ko/permission-modes.md)를 참조하십시오. 클라우드 세션에서 Claude Code는 이 키의 값 중 `acceptEdits`, `plan`, `default`, `auto`만 따릅니다. VS Code 확장이 시작하는 대화의 경우 [확장이 시작 권한 모드로 읽는 설정](https://code.claude.com/docs/ko/permission-modes.md#switch-permission-modes)을 참조하십시오.

### `permissions.disableBypassPermissionsMode`

누구도 `bypassPermissions` 모드로 진입하지 못하게 합니다. 그러면 Claude Code는 `--dangerously-skip-permissions` 플래그를 거부하고, [에이전트 정의의](https://code.claude.com/docs/ko/sub-agents.md#permission-modes) `permissionMode: bypassPermissions`를 무시하므로 서브에이전트는 상위 세션의 권한 모드로 실행됩니다.

* **범위**: [`Any file`](#scopes). 일반적으로 조직 정책을 적용하기 위해 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 설정합니다.
* **타입**: 문자열 `"disable"`
* **기본값**: 설정되지 않음
* **세션별 재정의**: 이 키는 `--dangerously-skip-permissions`보다 우선하며, 키가 설정된 동안 Claude Code는 해당 플래그를 거부합니다

```json settings.json theme={null}
{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}
```

v2.1.223 이전에는 Claude Code가 bypass가 비활성화된 상태에서도 frontmatter 권한 모드를 적용했습니다.

### `skipAutoPermissionPrompt`

기본 제공 기본값이 세션을 자동 모드로 시작할 때가 아니라, 사용자 자신의 설정이나 모드 선택기 등을 통해 사용자가 직접 처음 자동 모드로 진입할 때 Claude Code가 표시하는 [자동 모드](https://code.claude.com/docs/ko/permission-modes.md#eliminate-prompts-with-auto-mode) 설명 일회성 알림을 건너뜁니다. Claude Code는 해당 알림을 한 번 표시한 후 표시했다는 사실을 기록하므로, 이 키는 알림이 아직 표시되지 않은 경우에만 의미가 있습니다.

* **범위**: [`User or managed`](#scopes). 저장소는 사용자를 대신해 이를 설정할 수 없습니다.
* **타입**: Boolean
  * `true`: Claude Code가 알림을 건너뜁니다
  * `false`: 설정되지 않은 경우와 동일합니다. 이러한 파일 중 다른 파일이 `true`를 설정하지 않는 한 알림이 한 번 표시됩니다
* **기본값**: 설정되지 않음. 따라서 알림이 한 번 표시됩니다

```json settings.json theme={null}
{
  "skipAutoPermissionPrompt": true
}
```

### `skipDangerousModePermissionPrompt`

`--dangerously-skip-permissions` 또는 `defaultMode: "bypassPermissions"`로 인해 세션이 `bypassPermissions` 모드로 진입하기 전에 Claude Code가 표시하는 확인 대화 상자를 건너뜁니다. 해당 대화 상자를 한 번 수락하면 Claude Code가 사용자 설정의 이 키에 `true`를 기록합니다.

* **범위**: [`User, local, or managed`](#scopes). 신뢰할 수 없는 저장소는 사용자를 대신해 대화 상자를 건너뛸 수 없습니다.
* **타입**: Boolean
  * `true`: 세션이 `bypassPermissions` 모드로 진입하기 전에 Claude Code가 확인 대화 상자를 건너뜁니다
  * `false`: 설정되지 않은 경우와 동일합니다. 이러한 파일 중 다른 파일이 `true`를 설정하지 않는 한 대화 상자가 표시됩니다
* **기본값**: 설정되지 않음. 따라서 대화 상자가 표시됩니다

```json settings.json theme={null}
{
  "skipDangerousModePermissionPrompt": true
}
```

## 샌드박스 설정

Claude가 실행하는 명령을 파일시스템, 네트워크, 자격 증명으로부터 격리합니다. 샌드박싱 작동 방식 및 플랫폼 요구사항은 [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 참조하십시오.

### `sandbox`

[샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 사용하여 Claude가 실행하는 Bash 명령을 파일시스템 및 네트워크로부터 격리합니다. `enabled`로 샌드박스를 켜고, `filesystem`, `network`, `credentials` 하위 객체로 샌드박스된 명령이 접근할 수 있는 범위를 좁히거나 넓힙니다. 샌드박스는 macOS, Linux, WSL2에서 실행됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: `enabled`, `failIfUnavailable`, `autoAllowBashIfSandboxed`, `excludedCommands`, `allowUnsandboxedCommands`, `enableWeakerNestedSandbox`, `enableWeakerNetworkIsolation`, `allowAppleEvents`, `allowNestedUserNamespaces`, `bwrapPath`, `socatPath`, `ignoreViolations`, `ripgrep`과 `filesystem`, `network`, `credentials` 객체를 포함하는 객체
* **기본값**: 설정되지 않음. Claude Code는 샌드박스 없이 명령을 실행합니다.

다음은 샌드박스를 켜고, 샌드박스된 명령에 대한 권한 프롬프트를 건너뛰고, `docker`를 샌드박스 외부에서 실행하고, 두 개의 추가 쓰기 경로를 열고, AWS 자격 증명 파일을 숨기고, GitHub 및 npm을 미리 허용합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}
```

관리형 설정이 `enabled` 또는 `failIfUnavailable`과 같은 Boolean 키를 설정하면, 해당 값은 개발자가 설정한 모든 것을 재정의합니다. Claude Code는 세션이 로드하는 설정 범위 전체에서 배열 키를 병합하므로, 개발자는 항목을 추가할 수 있습니다. 관리형 전용 잠금은 [개발자가 정책을 확대하지 못하도록 유지](https://code.claude.com/docs/ko/sandboxing.md#keep-developers-from-widening-the-policy)를 참조하십시오. 조직에 샌드박스를 요구하려면 [관리형 설정으로 샌드박싱 적용](https://code.claude.com/docs/ko/sandboxing.md#enforce-sandboxing-with-managed-settings)을 참조하십시오.

### `sandbox.enabled`

Bash 명령에 대해 [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 켭니다. `/sandbox` 패널에서 모드를 선택하면, Claude Code는 현재 프로젝트의 `.claude/settings.local.json`에 이 키를 씁니다. 모든 프로젝트를 샌드박스하려면 `~/.claude/settings.json`에 설정하십시오.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: Boolean
  * `true`: Claude Code는 Bash 명령을 샌드박스합니다.
  * `false`: Bash 명령은 샌드박스 없이 실행됩니다.
* **기본값**: `false`

```json settings.json theme={null}
{
  "sandbox": {
    "enabled": true
  }
}
```

Linux 및 WSL2에서 샌드박스는 `bubblewrap` 및 `socat`이 필요합니다. [Linux 및 WSL2 설정](https://code.claude.com/docs/ko/sandboxing.md#set-up-linux-and-wsl2)을 참조하십시오. 샌드박스를 시작할 수 없을 때, [`failIfUnavailable`](#sandbox-failifunavailable)도 설정하지 않았다면 Claude Code는 명령을 샌드박스 없이 실행합니다.

### `sandbox.failIfUnavailable`

`sandbox.enabled`가 `true`이지만 의존성이 누락되었거나 플랫폼이 지원되지 않아 샌드박스를 시작할 수 없을 때 Claude Code가 시작 시 오류로 종료되도록 합니다. 이 키가 없으면 Claude Code는 명령을 샌드박스 없이 실행합니다. 샌드박싱을 보안 관문으로 요구하는 관리형 배포에서 이 설정을 사용할 수 있습니다.

샌드박스가 지원하지 않는 플랫폼에서는 이 키가 켜져 있으면 Claude Code가 시작되지 않습니다. [관리형 설정으로 샌드박싱 적용](https://code.claude.com/docs/ko/sandboxing.md#enforce-sandboxing-with-managed-settings)을 참조하십시오.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: Boolean
  * `true`: `sandbox.enabled`가 `true`이지만 샌드박스를 시작할 수 없을 때 Claude Code는 시작 시 오류로 종료됩니다.
  * `false`: 샌드박스를 시작할 수 없을 때 Claude Code는 명령을 샌드박스 없이 실행합니다.
* **기본값**: `false`

다음은 모든 관리 대상 머신이 명령을 샌드박스하거나 시작을 거부하도록 합니다:

```json managed-settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true
  }
}
```

[관리형 설정으로 샌드박싱 적용](https://code.claude.com/docs/ko/sandboxing.md#enforce-sandboxing-with-managed-settings)을 참조하십시오.

### `sandbox.autoAllowBashIfSandboxed`

Claude Code가 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행하도록 합니다. 샌드박스에서 실행할 수 없는 명령은 여전히 일반 권한 흐름을 거치며, `deny` 규칙 및 `Bash(git push *)`와 같은 콘텐츠 범위 `ask` 규칙은 여전히 적용됩니다. 단순 `Bash` ask 규칙은 샌드박스된 명령에 대해 건너뜁니다. 이를 `false`로 설정하여 샌드박스된 명령도 일반 권한 흐름을 거치도록 하면, `/sandbox` **모드** 탭에서 이를 일반 권한 모드라고 부릅니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code는 [자동 허용 모드](https://code.claude.com/docs/ko/sandboxing.md#auto-allow-mode)에서 설명하는 경우를 제외하고 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행합니다. `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`는 자동 허용을 끕니다.
  * `false`: 샌드박스된 명령은 일반 권한 흐름을 거치므로, 허용 규칙 및 권한 모드가 결정합니다. `/sandbox` **모드** 탭에서 이를 일반 권한 모드라고 부릅니다.
* **기본값**: `true`

다음은 샌드박스를 켜고 샌드박스된 명령을 일반 권한 흐름을 거치도록 합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false
  }
}
```

자동 허용 모드가 여전히 확인을 요청하는 경우와 플랜 모드에서의 동작은 [자동 허용 모드](https://code.claude.com/docs/ko/sandboxing.md#auto-allow-mode)를 참조하십시오.

### `sandbox.excludedCommands`

Claude Code가 샌드박스 외부에서 실행하는 명령(예: 샌드박스에서 작동하지 않는 도구)을 지정합니다. 각 항목은 `Bash(...)` [권한 규칙](https://code.claude.com/docs/ko/permissions.md#permission-rule-syntax)의 콘텐츠와 동일한 구문을 사용합니다: 정확한 명령, `docker *`와 같은 접두사, 또는 와일드카드 패턴입니다. 와일드카드가 없는 패턴은 정확히 일치하는 경우에만 해당하므로, `docker`는 인수가 없는 `docker`에만 일치합니다.

항목은 Bash 호출에 포함된 모든 명령을 포함할 때만 해당 호출을 샌드박스 외부로 꺼내며, 일부 호출 형태는 그렇더라도 샌드박스된 상태로 유지됩니다. `docker *` 항목만으로는 `npm ci && docker build .`를 샌드박스 외부로 꺼내지 않습니다.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: 명령 패턴의 배열
* **기본값**: 설정되지 않음. 제외되는 명령이 없습니다.

```json settings.json theme={null}
{
  "sandbox": {
    "excludedCommands": ["docker *"]
  }
}
```

Claude Code는 Bash 호출이 다음과 같은 형태 중 하나를 가질 때 해당 호출을 샌드박스된 상태로 유지합니다(이 외에도 있습니다):

* `sudo`, `eval`, 또는 `xargs`로 시작하는 명령
* 호출의 어디든 나타나는 `cd`, `pushd`, 또는 `popd`
* 명령 대체, 하위 셸, 또는 `if` 또는 `for`와 같은 제어 흐름 블록
* `docker build . > build.log`와 같은 리다이렉션(`2>&1`처럼 파일 디스크립터를 복제만 하는 것은 제외)
* 변수에서 오는 명령 이름
* 경로 인수가 절대 경로이거나, `~`로 시작하거나, `..` 세그먼트를 포함하는 `git clone`, `git init`, `git worktree add`, `git worktree move`, 또는 `git bundle create`

예를 들어, `cd build && docker compose up`은 `docker *` 항목 아래에서 샌드박스된 상태로 유지되며, `cd` 항목을 추가해도 변경되지 않습니다. `git *` 항목 아래에서 `git clone <url> vendor/lib`는 샌드박스 외부에서 실행되지만, `git clone <url> ~/tools`는 샌드박스된 상태로 유지됩니다. 클론은 대상 경로가 가리키는 곳이 어디든 실행 파일일 수도 있는 파일 트리 전체를 씁니다.

제외된 명령은 여전히 일반 권한 흐름을 거칩니다. 제외는 편의 기능이지 보안 경계가 아닙니다. 도구가 특정 위치에만 쓰기를 필요로 할 때는 [`filesystem.allowWrite`](#sandbox-filesystem-allowwrite)를 사용하면 샌드박스된 상태를 유지할 수 있습니다.

샌드박스가 [관리자 필수](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox)가 아닌 한, 세션이 로드하는 설정 범위의 항목은 하나의 목록으로 결합됩니다. 관리자 필수인 동안에는 Claude Code가 `.claude/settings.json` 및 `.claude/settings.local.json`의 항목을 무시하므로, 복제된 저장소가 명령을 샌드박스 외부로 꺼낼 수 없습니다. 관리형 설정, `--settings`, `~/.claude/settings.json`의 항목은 여전히 적용되며, 이 목록에 대한 관리형 전용 잠금은 없습니다.

### `sandbox.allowUnsandboxedCommands`

샌드박스가 명령을 차단한 후 Claude가 `dangerouslyDisableSandbox` 매개변수를 사용하여 샌드박스 외부에서 명령을 재시도하도록 합니다. `false`이면 Claude Code는 해당 매개변수를 무시합니다. 그러면 샌드박스가 실행 중인 동안 Claude가 실행하는 명령은 [`excludedCommands`](#sandbox-excludedcommands) 항목과 일치하지 않는 한 샌드박스됩니다. `/sandbox` **재정의** 탭은 해당 상태를 **엄격한 샌드박스 모드**로 표시합니다. 관리형 설정의 `false`는 해당 설정이 적용되는 개발자에 대해 엄격한 샌드박스 모드를 켭니다.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#turn-off-the-retry-with-strict-sandbox-mode) 있음
* **유형**: Boolean
  * `true`: 샌드박스가 명령을 차단한 후 Claude는 `dangerouslyDisableSandbox` 매개변수를 사용하여 샌드박스 외부에서 명령을 재시도할 수 있습니다.
  * `false`: Claude Code는 해당 매개변수를 무시하므로, 샌드박스가 실행 중인 동안 Claude가 실행하는 명령은 `excludedCommands` 항목과 일치하지 않는 한 샌드박스됩니다.
* **기본값**: `true`

다음은 관리형 설정이 적용되는 모든 사람에 대해 엄격한 샌드박스 모드를 적용합니다:

```json managed-settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false
  }
}
```

관리형 설정 또는 `--settings`의 `false`는 샌드박스를 [관리자 필수](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox)로도 만듭니다. 사용자 설정의 `false`는 프로젝트의 `true`보다 우선하지만 샌드박스를 관리자 필수로 만들지는 않습니다. 프로젝트 값보다 우선하려면 Claude Code v2.1.285 이상이 필요합니다.

샌드박스 없는 재시도를 누가 승인하는지는 권한 모드와 허용 규칙에 따라 다릅니다. [샌드박스 없는 재시도 탈출 해치](https://code.claude.com/docs/ko/sandboxing.md#the-unsandboxed-retry-escape-hatch)를 참조하십시오.

[`!` 셸 모드 프롬프트](https://code.claude.com/docs/ko/interactive-mode#shell-mode-with-prefix)에서 직접 입력한 명령이 언제 샌드박스에서 실행되는지 확인하려면 [엄격한 샌드박스 모드](https://code.claude.com/docs/ko/sandboxing.md#turn-off-the-retry-with-strict-sandbox-mode)를 참조하십시오.

### `sandbox.filesystem`

샌드박스된 명령이 읽고 쓸 수 있는 경로를 제어합니다. 기본적으로 작업 디렉터리, 사용자별 임시 디렉터리, `--add-dir`, `/add-dir` 또는 `permissions.additionalDirectories`로 추가한 디렉터리에 쓸 수 있으며, 자격 증명 파일을 포함한 파일시스템의 나머지 부분을 읽을 수 있습니다. 네 개의 경로 목록으로 범위를 좁히거나 넓히거나, `disabled`로 파일시스템 계층을 끕니다. [파일시스템 격리](https://code.claude.com/docs/ko/sandboxing.md#filesystem-isolation)에서 기본 경계를 참조하십시오.

* **범위**: [`Any file`](#scopes)
* **유형**: `allowWrite`, `denyWrite`, `denyRead`, `allowRead` 배열을 포함하는 객체이며, `allowManagedReadPathsOnly` 및 `disabled` Boolean도 포함합니다.
* **기본값**: 설정되지 않음. 기본 읽기 및 쓰기 경계가 적용됩니다.

다음은 샌드박스된 명령이 빌드 디렉터리 및 kubeconfig에 쓸 수 있도록 하고 AWS 자격 증명 파일을 숨깁니다:

```json settings.json theme={null}
{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    }
  }
}
```

Claude Code는 OS 샌드박스 경계에서 이러한 목록을 적용하므로, `kubectl`, `terraform`, `npm`과 같이 샌드박스된 명령이 시작하는 모든 하위 프로세스에 적용됩니다. Claude Code는 [권한 규칙](https://code.claude.com/docs/ko/sandboxing.md#permission-rules)을 동일한 목록에 추가합니다: `Edit` 허용 및 거부 규칙을 `allowWrite` 및 `denyWrite`에, `Read` 거부 규칙을 `denyRead`에, `WebFetch(domain:...)` 허용 및 거부 규칙을 [`network`](#sandbox-network) 도메인 목록에 추가합니다.

잠금이 적용되지 않는 한, Claude Code는 세션이 로드하는 설정 파일 전체에서 이러한 목록을 병합합니다. [`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly)는 `allowRead`를 관리형 설정의 항목으로만 제한하며, [`allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly)는 허용된 도메인에 대해 동일하게 수행합니다. [저장소 잠금](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox)은 저장소 설정 파일의 항목을 제외합니다.

[샌드박싱 구성](https://code.claude.com/docs/ko/sandboxing.md#configure-sandboxing)은 `--setting-sources`로 제외하는 소스를 다룹니다. 세션 중에 목록을 편집하면, Claude Code는 [실행 중인 세션에 변경사항을 적용](https://code.claude.com/docs/ko/settings.md#when-edits-take-effect)합니다.

#### 샌드박스 경로 접두사

`allowWrite`, `denyWrite`, `denyRead`, `allowRead`, [`credentials.files`](#sandbox-credentials-files)의 경로는 접두사로 확인됩니다:

| 접두사 | 의미 | 예시 |
| :- | :- | :- |
| `/` | 파일시스템 루트의 절대 경로 | `/tmp/build`는 `/tmp/build`로 유지됩니다. |
| `~/` | 홈 디렉터리 기준 상대 경로 | `~/.kube`는 `$HOME/.kube`가 됩니다. |
| `./` 또는 접두사 없음 | 프로젝트 설정의 경우 프로젝트 루트 기준 상대 경로, 사용자 설정의 경우 `~/.claude` 기준 상대 경로 | `.claude/settings.json`의 `./output`은 `<project-root>/output`으로 확인됩니다. |

절대 경로의 `//path` 접두사도 작동합니다. 프로젝트 상대 확인을 기대하면서 단일 슬래시 `/path`를 사용하는 경우, `./path`로 전환하십시오. 이 구문은 절대 경로에 `//path`를 사용하고 프로젝트 상대 경로에 `/path`를 사용하는 [Read 및 Edit 권한 규칙](https://code.claude.com/docs/ko/permissions.md#read-and-edit)과 다릅니다. 샌드박스 파일시스템 경로는 표준 규칙을 사용하므로 `/tmp/build`는 절대 경로입니다.

Claude Code는 디렉터리 경로에서 후행 슬래시를 제거하므로, `~/.aws` 및 `~/.aws/`는 동일한 디렉터리와 일치합니다. v2.1.224 이전에는 Claude Code가 후행 슬래시를 샌드박스에 전달했으며, Claude는 여전히 후행 슬래시로 작성된 `denyRead` 또는 `denyWrite` 항목 아래의 경로를 읽거나 쓸 수 있었습니다.

##### 샌드박스 경로에서 와일드카드가 작동하는 위치

와일드카드 `*`, `?`, `**`는 macOS에서는 네 가지 `sandbox.filesystem` 경로 목록 모두에서 작동하며, Linux와 WSL2에서는 더 적은 위치에서 작동합니다.

| `sandbox.filesystem` 목록 | Linux 및 WSL2에서 작동하는 것 | Linux 및 WSL2에서 작동하지 않는 예시 | 대신 작성할 내용 |
| :- | :- | :- | :- |
| `denyRead`, `allowRead` | 후행 `/**`는 작동하므로 `~/build/**`는 `~/build`와 같은 디렉터리를 포괄합니다. 그 외의 와일드카드는 항목의 [전체 경로](#sandbox-path-prefixes)에서 첫 번째 디렉터리 이름 뒤에서만 작동합니다. | `denyRead`의 `/**/*.pem`은 아무것도 포괄하지 않으므로 어떤 읽기도 차단하지 않음 | `/srv/**/*.pem`처럼 최상위 디렉터리마다 항목 하나씩 |
| `allowWrite`, `denyWrite` | 후행 `/**`만 작동하므로 `~/build/**`는 `~/build`와 같은 디렉터리를 포괄합니다 | `./src/*`는 `src` 안에서 이름 자체가 `*`인 파일이나 디렉터리만 포괄하며, 그런 것이 없으면 아무것도 포괄하지 않음 | `src` 아래의 모든 것을 포괄하는 `./src`, 또는 경로마다 항목 하나씩 |

`~/keys/*.pem`에서 와일드카드는 첫 번째 디렉터리 이름 뒤에 옵니다. 홈 디렉터리가 `/home/alice`인 경우 첫 번째 디렉터리 이름은 `home`입니다.

```text theme={null}
~/keys/*.pem              the entry
/home/alice/keys/*.pem    its full path
 ^^^^                     the first directory name, home
```

Linux와 WSL2에서 세션 내 `/sandbox`의 **Config** 탭은 후행 `/**` 이외의 와일드카드를 포함하는 `Edit` 권한 규칙에 대해 경고합니다. 이런 와일드카드는 샌드박스 처리된 명령에서 작동하지 않습니다. 규칙이 포괄해야 하는 각 경로 또는 해당 경로들을 담은 디렉터리를, 허용 규칙이라면 `allowWrite`에, 거부 규칙이라면 `denyWrite`에 추가하세요.

##### 대괄호, 중괄호, 소괄호가 포함된 디렉터리 이름

이름에 대괄호가 포함된 디렉터리를 허용하거나 차단하려면 `./app/[slug]`처럼 이름을 그대로 작성하세요. 이 항목에서 `[slug]`는 대괄호를 포함한 디렉터리의 실제 이름입니다.

```text theme={null}
app/
└── [slug]/
    └── page.tsx
```

이 항목은 디렉터리 아래의 모든 것을 포괄하므로 후행 `/**`는 붙이지 마세요. macOS와 Linux 및 WSL2에서 `app/[slug]` 디렉터리는 샌드박스 처리된 명령이 시작될 때 존재해야 합니다.

* **`[slug]` 같은 대괄호**: macOS의 모든 목록과 Linux 및 WSL2의 `denyRead`, `allowRead`에서 `./app/[slug]`의 대괄호는 패턴으로도 작동합니다. 그러면 이 항목은 `app/s`나 `app/g`처럼 `app` 아래에서 `slug`의 문자 하나로 이름 지어진 모든 경로와도 일치합니다. 이 항목이 `allowRead`에 있거나 macOS의 `allowWrite`에 있으면 샌드박스 처리된 명령이 그런 경로에도 접근할 수 있습니다. 접근해서는 안 되는 경로는 이름을 바꾸세요.
* **`[user-id]`나 `[post-id]`처럼 하이픈 왼쪽 문자가 오른쪽 문자보다 뒤에 정렬되는 대괄호**: `./app/[user-id]`는 모든 플랫폼의 모든 목록에서 정확히 그 이름을 가진 디렉터리만 포괄합니다. v2.1.304 이전에는 `denyRead` 또는 `allowRead`에 이런 항목이 있으면 Linux와 WSL2에서 샌드박스 처리된 명령이 시작되지 않았습니다.
* **중괄호와 소괄호**: 이들은 일반 문자이므로 `~/data/{keys,tokens}`는 두 가지 대안이 아니라 `{keys,tokens}`라는 이름의 디렉터리 하나를 포괄합니다. `~/data/keys`와 `~/data/tokens`를 포괄하려면 각각을 별도 항목으로 추가하세요.

### `sandbox.filesystem.allowWrite`

작업 디렉터리, 사용자별 임시 디렉터리, `--add-dir`, `/add-dir` 또는 `permissions.additionalDirectories`로 추가한 디렉터리 외에 샌드박스된 명령이 쓸 수 있는 경로를 추가합니다. `kubectl` 또는 빌드 도구와 같은 하위 프로세스가 프로젝트 외부에 쓰기를 필요로 할 때 사용하십시오.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: [샌드박스 경로 접두사](#sandbox-path-prefixes)를 사용하는 경로 문자열의 배열
* **기본값**: 설정되지 않음. 샌드박스된 명령은 작업 디렉터리, 사용자별 임시 디렉터리, `--add-dir` 또는 `/add-dir`로 추가한 디렉터리, [`permissions.additionalDirectories`](#permissions-additionaldirectories)의 디렉터리에 쓸 수 있습니다.

다음은 빌드가 `/tmp/build` 아래에 쓸 수 있도록 하고 `kubectl`이 kubeconfig를 업데이트하도록 합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"]
    }
  }
}
```

Claude Code는 세션이 로드하는 설정 범위 전체에서 `allowWrite` 항목과 `Edit(...)` 허용 권한 규칙의 경로를 병합하며, [`permissions.blockReadsOutsideWorkingDirectories`](#sandboxed-commands-under-the-block)가 켜져 있는 동안 저장소 설정의 항목을 제외합니다. [저장소 잠금](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox)도 저장소의 항목을 제외할 수 있습니다. `allowWrite` 항목은 [보호된 경로](https://code.claude.com/docs/ko/sandboxing.md#protected-paths)를 해제할 수 없습니다.

### `sandbox.filesystem.denyWrite`

샌드박스된 명령이 특정 경로(다른 방식으로 쓰기 가능한 디렉터리 내의 경로 포함)에 쓰는 것을 차단합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: [샌드박스 경로 접두사](#sandbox-path-prefixes)를 사용하는 경로 문자열의 배열
* **기본값**: 설정되지 않음

다음은 샌드박스된 명령이 시스템 구성을 변경하거나 바이너리를 설치하는 것을 방지합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "filesystem": {
      "denyWrite": ["/etc", "/usr/local/bin"]
    }
  }
}
```

Claude Code는 세션이 로드하는 모든 설정 범위에서 항목을 병합하고 `Edit(...)` 거부 권한 규칙의 경로를 추가합니다.

### `sandbox.filesystem.denyRead`

샌드박스된 명령이 특정 경로(예: 기본 읽기 정책이 노출할 자격 증명 파일)를 읽는 것을 차단합니다. 자격 증명 파일을 보호하고 샌드박스 프록시를 통해 사용 가능하게 유지하려면 대신 [`sandbox.credentials`](#sandbox-credentials)를 참조하십시오.

* **범위**: [`Any file`](#scopes)
* **유형**: [샌드박스 경로 접두사](#sandbox-path-prefixes)를 사용하는 경로 문자열의 배열
* **기본값**: 설정되지 않음. 샌드박스된 명령은 `~/.aws/credentials`와 같은 자격 증명 파일을 포함한 [기본 읽기 액세스](https://code.claude.com/docs/ko/sandboxing.md#filesystem-isolation)를 유지합니다.

```json settings.json theme={null}
{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/.aws/credentials"]
    }
  }
}
```

Claude Code는 세션이 로드하는 모든 설정 범위에서 항목을 병합하고 `Read(...)` 거부 권한 규칙의 경로를 추가합니다. [`filesystem.disabled`](#sandbox-filesystem-disabled)가 `true`이면, Claude Code는 이러한 항목을 적용하지 않습니다.

### `sandbox.filesystem.allowRead`

[`denyRead`](#sandbox-filesystem-denyread)가 차단하는 영역 내의 특정 경로에 대해 읽기를 다시 열어서 작업 공간 전용 읽기 액세스를 구축합니다. 정확한 또는 와일드카드 `denyRead` 항목은 더 광범위한 `allowRead` 내에서 차단된 상태로 유지되며, [겹침 표](https://code.claude.com/docs/ko/sandboxing.md#configure-sandboxing)에서 보여줍니다. 와일드카드 `denyRead` 항목(예: `~/**/.env`)이 디렉터리와 일치할 때, Claude Code는 해당 내용의 읽기도 차단합니다. v2.1.236 이전의 macOS에서는 Claude Code가 더 광범위한 `allowRead` 항목이 적용되는 곳에서 와일드카드 `denyRead` 항목이 일치하는 경로를 다시 열었으며, 일치하는 디렉터리의 내용을 읽을 수 있게 남겨두었습니다.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: [샌드박스 경로 접두사](#sandbox-path-prefixes)를 사용하는 경로 문자열의 배열
* **기본값**: 설정되지 않음

다음은 프로젝트 자체를 제외한 홈 디렉터리의 읽기를 차단합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}
```

Claude Code는 프로젝트 설정에서 `.` 항목을 프로젝트 루트로, 사용자 설정에서 `~/.claude`로 확인합니다. Claude Code는 [`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly)가 설정되지 않으면 세션이 로드하는 설정 파일 전체에서 항목을 병합하며, [`permissions.blockReadsOutsideWorkingDirectories`](#sandboxed-commands-under-the-block)가 켜져 있는 동안 저장소 설정의 항목을 제외합니다. [저장소 잠금](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox)도 저장소의 항목을 제외할 수 있습니다.

### `sandbox.filesystem.allowManagedReadPathsOnly`

관리형 설정에서 오는 [`allowRead`](#sandbox-filesystem-allowread) 항목만 인정하므로, 개발자가 조직이 차단한 경로에 대한 읽기 액세스를 다시 열 수 없습니다. Claude Code는 여전히 세션이 로드하는 모든 설정 범위에서 `denyRead` 항목을 병합합니다.

* **범위**: [`Managed`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code는 관리형 설정의 `allowRead` 항목만 인정합니다.
  * `false`: 다른 설정 파일의 `allowRead` 항목이 병합될 수 있습니다.
* **기본값**: `false`

다음은 홈 디렉터리의 읽기를 차단하고, `~/work`를 다시 열고, 개발자가 다른 것을 다시 열지 못하도록 합니다:

```json managed-settings.json theme={null}
{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["~/work"],
      "allowManagedReadPathsOnly": true
    }
  }
}
```

[개발자가 정책을 확대하지 못하도록 유지](https://code.claude.com/docs/ko/sandboxing.md#keep-developers-from-widening-the-policy)를 참조하십시오.

### `sandbox.filesystem.disabled`

네트워크 격리를 유지하면서 파일시스템 격리를 건너뜁니다. 샌드박스된 명령은 호스트 파일시스템에 대한 무제한 읽기 및 쓰기 액세스를 얻으며, 해당 네트워크 송신은 [`network.allowedDomains`](#sandbox-network-alloweddomains)로 제한됩니다. 명령이 쓰는 것이 아니라 연결하는 위치를 제어하기 위해 샌드박스할 때 사용하십시오. Claude Code v2.1.216 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes). 관리형 설정이 `sandbox.filesystem`을 조금이라도 구성하거나 `"mode": "deny"`인 `sandbox.credentials.files` 항목을 나열하는 경우, 관리형 설정만 이 키를 설정할 수 있습니다.
* **유형**: Boolean
  * `true`: Claude Code는 파일시스템 격리를 건너뛰고 네트워크 격리를 유지합니다.
  * `false`: 파일시스템 격리는 켜진 상태로 유지됩니다.
* **기본값**: `false`. 파일시스템 격리는 켜진 상태로 유지됩니다.

다음은 파일시스템을 열고 네트워크 송신을 GitHub 및 npm으로 제한합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}
```

계층이 꺼지면, Claude Code는 `denyRead` 또는 `credentials.files` `deny` 항목을 적용하지 않으며, `credentials.envVars` 항목 및 적용된 `mask` 항목은 계속 작동합니다. [`autoAllowBashIfSandboxed`](#sandbox-autoallowbashifsandboxed)는 여전히 기본값이 `true`이므로, 계속 확인을 요청하게 하려면 `false`로 설정하십시오. [파일시스템 격리 비활성화](https://code.claude.com/docs/ko/sandboxing.md#disable-filesystem-isolation)에서 이를 설정할 수 있는 전체 소스 목록과 격리가 꺼졌을 때 변경되는 사항을 참조하십시오. Claude Code v2.1.216 이상이 필요합니다.

### `sandbox.ignoreViolations`

명령이 시작 시 `/etc/hosts`를 확인하는 도구와 같이 프로브되고 거부될 것으로 예상되는 경로에 대한 샌드박스 위반 보고를 침묵시키므로, 해당 거부가 위반으로 표시되거나 Claude가 보는 것에 나타나지 않습니다. 샌드박스는 여전히 액세스를 차단합니다. 보고만 억제됩니다. 키는 명령과 일치하는 부분 문자열이며, `*`는 모든 명령과 일치하고, 값은 해당 명령에 대해 무시할 위반의 부분 문자열(예: 파일시스템 경로)입니다.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: 명령 부분 문자열을 위반 부분 문자열의 배열에 매핑하는 객체(일반적으로 경로)
* **기본값**: 설정되지 않음. 모든 위반이 보고됩니다.

```json settings.json theme={null}
{
  "sandbox": {
    "ignoreViolations": {
      "*": ["/etc/hosts"]
    }
  }
}
```

### `sandbox.enableWeakerNestedSandbox`

Linux 샌드박스를 권한 없는 Docker 컨테이너 내부에서 실행하며, bubblewrap이 새로운 `/proc`을 마운트할 수 없습니다. 대신 내부 샌드박스는 컨테이너의 기존 `/proc`을 바인드 마운트하며, 이는 새로운 마운트가 숨길 프로세스 정보를 노출합니다. 이는 보안을 감소시킵니다. 외부 컨테이너가 이미 필요한 격리를 제공할 때만 사용하십시오.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: Boolean
  * `true`: 내부 샌드박스는 새로운 `/proc`을 마운트하는 대신 컨테이너의 기존 `/proc`을 바인드 마운트합니다.
  * `false`: 샌드박스는 새로운 `/proc`을 마운트하며, 이는 권한 없는 Docker 컨테이너에서 작동하지 않습니다.
* **기본값**: `false`

```json settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "enableWeakerNestedSandbox": true
  }
}
```

Linux 및 WSL2만 해당합니다. [Bubblewrap이 컨테이너 내부에서 시작되지 않음](https://code.claude.com/docs/ko/sandboxing.md#bubblewrap-fails-to-start-inside-a-container)을 참조하십시오.

### `sandbox.enableWeakerNetworkIsolation`

샌드박스된 명령이 macOS에서 시스템 TLS 신뢰 서비스 `com.apple.trustd.agent`에 도달하도록 합니다. `gh`, `gcloud`, `terraform`과 같은 Go 기반 도구는 [`network.httpProxyPort`](#sandbox-network-httpproxyport)를 MITM 프록시 및 사용자 정의 CA와 함께 사용할 때 TLS 인증서를 확인하기 위해 필요합니다. 이는 신뢰 서비스를 통한 잠재적 데이터 유출 경로를 열어서 보안을 감소시킵니다.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: Boolean
  * `true`: macOS의 샌드박스된 명령은 `com.apple.trustd.agent`에 도달할 수 있습니다.
  * `false`: macOS의 샌드박스된 명령은 시스템 TLS 신뢰 서비스에 도달할 수 없습니다.
* **기본값**: `false`

```json settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "enableWeakerNetworkIsolation": true
  }
}
```

MITM 프록시를 사용하지 않으면, 대신 실패하는 도구를 [`excludedCommands`](#sandbox-excludedcommands)에 나열하십시오. [Go 기반 CLI가 macOS에서 TLS 검증에 실패함](https://code.claude.com/docs/ko/sandboxing.md#go-based-clis-fail-tls-verification-on-macos)을 참조하십시오.

### `sandbox.allowAppleEvents`

샌드박스된 명령이 macOS에서 Apple Events를 보내도록 합니다. `open`, `osascript`, URL을 브라우저에서 여는 도구에 필요하며, 없으면 오류 `-600`으로 실패합니다. 이는 코드 실행 격리를 제거합니다: 샌드박스된 명령은 사용자 프롬프트 없이 다른 애플리케이션을 샌드박스 없이 시작할 수 있으며, Terminal과 같은 실행 중인 애플리케이션에 AppleScript 명령을 보낼 수 있습니다. 이는 앱별 macOS 자동화 동의 프롬프트(TCC)를 따릅니다.

* **범위**: [`User or managed`](#scopes)
* **유형**: Boolean
  * `true`: macOS의 샌드박스된 명령은 Apple Events를 보낼 수 있습니다.
  * `false`: macOS의 샌드박스된 명령은 Apple Events를 보낼 수 없으므로, `open` 및 `osascript`는 오류 `-600`으로 실패합니다.
* **기본값**: `false`

```json settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "allowAppleEvents": true
  }
}
```

격리를 유지하면서 그러한 도구 중 하나를 실행하려면, 대신 [`excludedCommands`](#sandbox-excludedcommands)에 추가하십시오. [macOS의 Apple Events](https://code.claude.com/docs/ko/sandboxing.md#security-limitations)를 참조하십시오.

### `sandbox.allowNestedUserNamespaces`

Linux와 WSL2에서 샌드박스된 명령이 사용자 네임스페이스를 생성할 수 있도록 합니다. Chromium과 Electron 자체 샌드박스, 중첩된 bubblewrap, `unshare`에 필요합니다. 이 키를 `true`로 설정하면 보안 경계가 꺼집니다. 샌드박스된 명령의 코드가 샌드박스 외부에서 실행될 수 있습니다. 루트리스 Podman이나 Buildah의 경우, 샌드박스가 다른 방식으로도 이들을 막기 때문에 대신 [`excludedCommands`](#sandbox-excludedcommands)를 사용하십시오. Claude Code v2.1.305 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes). `true`는 `~/.claude/settings.json`, `--settings`로 전달된 JSON, 또는 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 온 경우에만 유효합니다. Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 `true`를 무시합니다. [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](https://code.claude.com/docs/ko/env-vars#variables)가 `1`로 설정된 세션에서는 Claude Code가 모든 소스의 `true`를 무시합니다. `false`는 [설정 우선순위](https://code.claude.com/docs/ko/settings.md#settings-precedence)에 따라 어떤 파일에서든 유효합니다.
* **유형**: Boolean
  * `true`: 샌드박스된 명령이 사용자 네임스페이스를 생성할 수 있습니다
  * `false`: 이 키가 추가로 허용하는 것이 없으며, 샌드박스의 기본값이 적용됩니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "allowNestedUserNamespaces": true
  }
}
```

이 키가 켜져 있으면 [보호된 경로](https://code.claude.com/docs/ko/sandboxing.md#protected-paths)와 [`credentials.files`](#sandbox-credentials-files) 항목을 포함한 샌드박스의 어떤 제한에도 악의적인 명령을 막는 역할을 기대하지 마십시오. [자동 허용 모드](https://code.claude.com/docs/ko/sandboxing.md#auto-allow-mode)에서는 그러한 명령이 권한 프롬프트 없이 실행될 수 있습니다. 조직에 보안 팀이 있다면 이 키를 켜기 전에 확인하십시오.

사용 중인 도구에 대한 해결 방법은 [Linux의 샌드박스 안에서 Chromium 또는 루트리스 Podman이 실패하는 경우](https://code.claude.com/docs/ko/sandboxing.md#chromium-or-rootless-podman-fails-inside-the-sandbox-on-linux)를 참조하십시오.

### `sandbox.ripgrep`

Claude Code가 사용하는 ripgrep 바이너리 대신 자신의 ripgrep 바이너리를 샌드박스에 지정합니다. 예를 들어 플랫폼이 다르게 빌드된 `rg`를 필요로 할 때입니다.

* **범위**: [`User or managed`](#scopes)
* **유형**: ripgrep 바이너리의 경로인 `command`를 포함하는 객체이며, 선택적 `args`(앞에 붙일 인수의 배열)도 포함합니다.
* **기본값**: 설정되지 않음. 샌드박스는 Claude Code와 동일한 ripgrep 바이너리를 사용합니다. 이는 [`USE_BUILTIN_RIPGREP`](https://code.claude.com/docs/ko/env-vars)을 `0`으로 설정하지 않으면 번들된 바이너리입니다.

```json settings.json theme={null}
{
  "sandbox": {
    "ripgrep": {
      "command": "/usr/local/bin/rg"
    }
  }
}
```

### `sandbox.bwrapPath`

샌드박스를 `PATH` 외부에 설치된 bubblewrap 바이너리(예: 에어갭 호스트의 벤더된 복사본)에 지정합니다. Claude Code는 시작 시 의존성 확인과 각 샌드박스된 명령을 래핑할 때 모두 이 경로를 사용합니다.

* **범위**: [`Managed`](#scopes). 사용자, 프로젝트, 로컬 파일이 샌드박스를 다른 바이너리로 지정하지 못하도록 Claude Code는 관리형 설정에서만 이 키를 읽습니다.
* **유형**: 문자열, 절대 경로. Claude Code는 상대 경로를 버리고 `PATH` 조회로 돌아갑니다.
* **기본값**: 설정되지 않음. Claude Code는 `PATH`에서 `bwrap`을 찾습니다.

```json managed-settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "bwrapPath": "/opt/admin/bwrap"
  }
}
```

Linux 및 WSL2만 해당합니다.

### `sandbox.socatPath`

샌드박스 네트워크 프록시를 `PATH` 외부에 설치된 `socat` 바이너리에 지정합니다.

* **범위**: [`Managed`](#scopes)
* **유형**: 문자열, 절대 경로. Claude Code는 상대 경로를 버리고 `PATH` 조회로 돌아갑니다.
* **기본값**: 설정되지 않음. Claude Code는 `PATH`에서 `socat`을 찾습니다.

```json managed-settings.json theme={null}
{
  "sandbox": {
    "enabled": true,
    "socatPath": "/opt/admin/socat"
  }
}
```

Linux 및 WSL2만 해당합니다.

### `sandbox.credentials`

[샌드박스된 명령으로부터 보호할](https://code.claude.com/docs/ko/sandboxing.md#protect-credentials) 자격 증명 파일 및 환경 변수를 선언합니다. 각 항목은 파일 `path` 또는 변수 `name` 및 `mode`를 지정합니다: `deny`는 자격 증명을 샌드박스 내부에 숨기고, `mask`는 샌드박스된 명령에 자리 표시자를 표시하면서 [샌드박스 프록시](https://code.claude.com/docs/ko/sandboxing.md#mask-credentials)가 아웃바운드 요청에서 실제 값을 대체합니다. Claude Code는 나열한 항목만 보호합니다. 기본 제공 자격 증명 거부 목록은 없습니다.

* **범위**: [`Any file`](#scopes). Claude Code는 `mask` 항목, `allowPlaintextInject`, `awsPairs`, `sigv4`를 사용자 설정, 관리형 설정, `--settings` 플래그에서만 적용합니다.
* **유형**: `files`, `envVars`, `allowPlaintextInject`, `awsPairs`, `sigv4`를 포함하는 객체
* **기본값**: 설정되지 않음. 보호되는 자격 증명이 없습니다.

다음은 AWS 자격 증명 파일을 숨기고 샌드박스된 명령에서 `GITHUB_TOKEN`을 제거합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "credentials": {
      "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
      "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
    }
  }
}
```

`deny` 파일 보호는 파일시스템 계층의 일부이므로, [파일시스템 격리를 비활성화](https://code.claude.com/docs/ko/sandboxing.md#disable-filesystem-isolation)할 때 적용되지 않습니다. 환경 변수 보호는 여전히 적용됩니다.

#### 관리형 설정의 잘못된 자격 증명 항목

관리형 `sandbox.credentials` 항목이 검증에 실패하면, Claude Code는 가능한 곳에서 자격 증명을 계속 보호합니다:

* 유효한 `path` 또는 `name` 및 `mask` 또는 `deny`의 `mode`를 여전히 가진 `files` 또는 `envVars`의 항목(예: `extract` 패턴에 캡처 그룹이 없는 항목)은 경고와 함께 `mode: "deny"`로 저하되므로, 자격 증명은 항목을 수정할 때까지 마스크되지 않고 차단된 상태로 유지됩니다. 저하된 `files` 항목은 명시적 `deny` 항목처럼 [`filesystem.disabled`](https://code.claude.com/docs/ko/sandboxing#disable-filesystem-isolation)를 고정하며, 경고는 관리형 설정이 파일시스템 격리를 끄면 읽기 차단이 적용되지 않음을 알립니다.
* 알 수 없는 `mode` 또는 잘못된 `path` 또는 `name`을 가진 항목은 제거됩니다.
* 각 경우에 경고가 표시됩니다. 항목이 저하되든 제거되든 나머지 유효한 항목은 여전히 적용됩니다.

v2.1.191 이상에 적용됩니다. v2.1.221 이전에는 모든 잘못된 항목이 제거되었습니다. 필드별 처리를 포함하는 다른 관리형 키는 [관리형 설정의 잘못된 항목](https://code.claude.com/docs/ko/managed-settings.md#invalid-entries-in-managed-settings)을 참조하십시오.

### `sandbox.credentials.files`

자격 증명 파일 또는 디렉터리를 샌드박스된 명령으로부터 보호합니다. `"mode": "deny"`를 사용하면, Claude Code는 샌드박스 내부에서 해당 경로의 읽기를 차단하며, 이는 [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread)와 동일한 읽기 차단입니다. `"mode": "mask"`를 사용하면, Linux 및 WSL2의 샌드박스된 명령은 파일의 센티널 복사본을 읽고, 샌드박스 프록시는 해당 항목의 `injectHosts`에 대한 아웃바운드 요청에서 실제 값을 대체합니다. macOS에서는 대신 파일을 샌드박스 내부에서 읽을 수 없습니다. `"mode": "mask"`는 Claude Code v2.1.221 이상이 필요합니다.

* **범위**: [`Any file`](#scopes). Claude Code는 프로젝트 `.claude/settings.json`과 로컬 `.claude/settings.local.json`의 `mask` 항목을 무시합니다.
* **유형**: 각각 `path` 및 `"deny"` 또는 `"mask"`의 `mode`를 포함하는 객체의 배열이며, 선택적 [파일용 마스크 필드](#mask-fields-for-files)도 포함합니다.
* **기본값**: 설정되지 않음. 보호되는 자격 증명 파일이 없습니다.

다음은 AWS 자격 증명 파일을 숨기고 `gh` 호스트 파일을 마스크하며, `api.github.com`에 대한 요청에서만 실제 값을 대체합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.config/gh/hosts.yml", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}
```

경로는 `sandbox.filesystem.*` 설정과 동일한 [접두사](#sandbox-path-prefixes)를 사용하며, Claude Code는 세션이 로드하는 모든 설정 범위에서 배열을 병합합니다. [자격 증명 보호](https://code.claude.com/docs/ko/sandboxing.md#protect-credentials)는 `--setting-sources`로 제외하는 소스에서 여전히 적용되는 것을 다룹니다. `mask` 항목은 Claude Code v2.1.221 이상이 필요합니다.

`mask` 대체는 샌드박스 프록시를 통해서만 실행되므로, [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 또는 일반 HTTP 테스트 네트워크의 경우 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject)를 설정하십시오. `mask`는 단일 파일에 적용되므로, 각 자격 증명 파일을 개별적으로 나열하십시오. Claude Code는 `deny` 항목의 `mask` 필드를 수용하지만 무시합니다. [자격 증명 마스크](https://code.claude.com/docs/ko/sandboxing.md#mask-credentials)는 어떤 설정 소스가 인정되는지를 다루고, [자격 증명 파일 마스크](https://code.claude.com/docs/ko/sandboxing.md#mask-credential-files)는 항목이 `deny`로 돌아가는 시기를 다룹니다.

#### 파일용 마스크 필드

`mask` 항목은 이러한 선택적 필드를 수용합니다. `extract` 또는 `decode` 없이는 Claude Code가 전체 파일 콘텐츠를 하나의 센티널로 대체합니다. 파일시스템 격리가 켜진 macOS에서는 Claude Code가 `extract` 또는 `decode`가 실행되기 전에 `mask` 항목을 `deny`로 적용합니다. [자격 증명 파일 마스크](https://code.claude.com/docs/ko/sandboxing.md#mask-credential-files)를 참조하십시오.

| 필드 | 유형 | 수행하는 작업 |
| :- | :- | :- |
| `extract` | 문자열, 최소 하나의 캡처 그룹을 포함하는 정규식 | 각 일치의 그룹 1로 캡처된 텍스트만 마스크하므로, 파일의 나머지는 파싱 가능한 상태로 유지됩니다. `decode`도 설정되면, Claude Code는 각 캡처를 즉시 대체하는 대신 가능한 JWT로 확인합니다. v2.1.221 이상이 필요합니다. |
| `onExtractNoMatch` | `"warn"`, `"deny"`, 또는 `"error"`. 기본값 `"warn"` | `extract` 또는 `decode`가 마스크할 것을 찾지 못할 때 발생하는 일. `warn`은 파일을 샌드박스 내부에서 있는 그대로 읽을 수 있게 남기고, `deny`는 읽을 수 없게 만들고, `error`는 구성을 수정할 때까지 샌드박스 설정을 중지합니다. Claude Code는 [파일시스템 격리를 비활성화](https://code.claude.com/docs/ko/sandboxing.md#disable-filesystem-isolation)하거나 [`sandbox.filesystem.allowRead`](#sandbox-filesystem-allowread) 항목이 경로를 다시 열어 읽기 차단이 적용되지 않을 때 `deny`를 `error`로 취급합니다. v2.1.221 이상이 필요합니다. `decode` 경우는 v2.1.224 이상이 필요합니다. |
| `decode` | 문자열 `"jwt"` | 기본 제공 패턴 또는 설정된 경우 `extract`를 사용하여 파일에서 JSON Web Tokens(JWT)를 찾고, 각 후보를 검증하고, 구조적으로 유효한 가짜 토큰으로 대체하므로, 샌드박스 내부에서 토큰을 디코드하는 코드는 계속 작동합니다. 검증되는 후보가 없으면, `onExtractNoMatch`가 결과를 결정합니다. v2.1.224 이상이 필요합니다. |
| `maskClaims` | 문자열의 배열, 최소 하나의 클레임 이름. `decode` 필요 | 각 검증된 JWT 내부의 명명된 최상위 페이로드 클레임만 마스크하고 수정된 페이로드를 중심으로 토큰을 다시 빌드하므로, 다른 클레임은 읽을 수 있게 유지됩니다. 명명된 클레임이 일치하지 않으면, `onExtractNoMatch`가 결과를 결정합니다. v2.1.224 이상이 필요합니다. |
| `maskDuplicates` | Boolean, 기본값 `false` | 주석에 붙여넣은 비밀과 같이 파일의 다른 곳에 있는 각 마스크된 값의 원문 그대로의 복사본도 대체합니다. Claude Code는 원시 부분 문자열을 일치시키므로, 길고 엔트로피가 높은 비밀에만 사용하십시오. `extract` 또는 `decode`가 설정될 때만 참조됩니다. v2.1.221 이상이 필요합니다. |
| `injectHosts` | 문자열의 배열, 각각 [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains)도 허용하는 호스트 | 샌드박스 프록시가 실제 값을 대체하는 호스트를 좁힙니다. 설정되지 않으면, 프록시는 `sandbox.network.allowedDomains`의 모든 호스트에 대한 요청에서 대체합니다. v2.1.221 이상이 필요합니다. |

다음은 `gh` 호스트 파일의 `oauth_token` 값만 마스크하고, 파일에 있는 해당 값의 다른 모든 복사본을 대체하고, 패턴이 아무것도 일치하지 않으면 파일을 읽을 수 없게 만들고, `api.github.com`에 대한 요청에서만 실제 토큰을 대체합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "maskDuplicates": true,
          "onExtractNoMatch": "deny",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}
```

### `sandbox.credentials.envVars`

환경 변수를 샌드박스된 명령으로부터 보호합니다. `"mode": "deny"`를 사용하면, Claude Code는 샌드박스된 명령의 환경에서 변수를 제거합니다. `"mode": "mask"`를 사용하면, 샌드박스된 명령은 세션별 센티널 값을 보고, 샌드박스 프록시는 해당 항목의 `injectHosts`에 대한 아웃바운드 요청에서 실제 값을 대체하므로, `gh` 및 `npm`과 같은 도구는 실제 자격 증명을 보유하지 않고도 계속 인증합니다.

* **범위**: [`Any file`](#scopes). Claude Code는 프로젝트 `.claude/settings.json`과 로컬 `.claude/settings.local.json`의 `mask` 항목을 무시합니다.
* **유형**: 각각 `name` 및 `"deny"` 또는 `"mask"`의 `mode`를 포함하는 객체의 배열이며, 선택적 [환경 변수용 마스크 필드](#mask-fields-for-environment-variables)도 포함합니다.
* **기본값**: 설정되지 않음. 보호되는 환경 변수가 없습니다.

다음은 샌드박스된 명령에서 `NPM_TOKEN`을 제거하고 `GITHUB_TOKEN`을 마스크하며, `api.github.com`에 대한 요청에서만 실제 값을 대체합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "credentials": {
      "envVars": [
        { "name": "NPM_TOKEN", "mode": "deny" },
        { "name": "GITHUB_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}
```

`name`은 문자 또는 밑줄로 시작해야 하며 문자, 숫자, 밑줄만 포함해야 합니다. Claude Code는 세션이 로드하는 모든 설정 범위에서 배열을 병합하고, 동일한 변수가 두 모드로 나타날 때 `deny`를 적용합니다. [자격 증명 보호](https://code.claude.com/docs/ko/sandboxing.md#protect-credentials)는 `--setting-sources`로 제외하는 소스에서 여전히 적용되는 것을 다룹니다.

`mask` 대체는 샌드박스 프록시를 통해서만 실행되므로, [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 또는 일반 HTTP 테스트 네트워크의 경우 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject)를 설정하십시오. [자격 증명 마스크](https://code.claude.com/docs/ko/sandboxing.md#mask-credentials)를 참조하십시오. Claude Code는 `deny` 항목의 `mask` 필드를 수용하지만 무시합니다.

#### 환경 변수용 마스크 필드

`mask` 항목은 이러한 선택적 필드를 수용합니다. `extract` 또는 `decode` 없이는 Claude Code가 전체 값을 하나의 센티널로 대체합니다. `extract`와 `decode`는 동일한 항목에서 함께 사용할 수 없습니다.

| 필드 | 유형 | 수행하는 작업 |
| :- | :- | :- |
| `extract` | 문자열, 최소 하나의 캡처 그룹을 포함하는 정규식 | `DATABASE_URL` 연결 문자열 내부의 비밀번호와 같이 각 일치의 그룹 1로 캡처된 텍스트만 마스크하므로, 값의 나머지는 파싱 가능한 상태로 유지됩니다. v2.1.224 이상이 필요합니다. |
| `onExtractNoMatch` | `"warn"`, `"deny"`, 또는 `"error"`. 기본값 `"warn"`. `decode`를 포함하는 항목에서는 `"warn"`만 수용됨 | `extract`가 아무것도 일치하지 않을 때 발생하는 일. `warn`은 변수를 마스크 없이 전달하고, `deny`는 샌드박스 내부에서 설정 해제하고, `error`는 구성을 수정할 때까지 샌드박스 설정을 중지합니다. v2.1.224 이상이 필요합니다. |
| `decode` | 문자열 `"jwt"` | 전체 값이 JWT인지 검증하고 구조적으로 유효한 가짜 토큰으로 대체하므로, 샌드박스 내부에서 토큰을 디코드하는 코드는 계속 작동합니다. 프록시는 송신 시 전체 실제 토큰을 대체합니다. 검증되지 않는 값은 경고와 함께 마스크 없이 전달됩니다. v2.1.224 이상이 필요합니다. |
| `maskClaims` | 문자열의 배열, 최소 하나의 클레임 이름. `decode` 필요 | 디코드된 JWT 내부의 명명된 최상위 페이로드 클레임만 마스크하고 수정된 페이로드를 중심으로 토큰을 다시 빌드하므로, 다른 클레임은 읽을 수 있게 유지됩니다. 명명된 클레임이 일치하지 않으면, 변수는 경고와 함께 마스크 없이 전달됩니다. v2.1.224 이상이 필요합니다. |
| `injectHosts` | 문자열의 배열, 각각 [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains)도 허용하는 호스트 | 샌드박스 프록시가 실제 값을 대체하는 호스트를 좁힙니다. 설정되지 않으면, 프록시는 `sandbox.network.allowedDomains`의 모든 호스트에 대한 요청에서 대체합니다. IPv6 대상은 괄호로 묶인 형식이 아니라 `"::1"`과 같이 압축된 주소 그대로 작성합니다. [`injectHosts`의 IPv6 대상](https://code.claude.com/docs/ko/sandboxing#ipv6-destinations-in-injecthosts)을 참조하십시오. |

다음은 `DATABASE_URL` 내부의 비밀번호만 마스크하고, 패턴이 아무것도 일치하지 않으면 변수를 설정 해제하고, `SERVICE_JWT`의 JWT를 마스크하면서 `api_key`를 제외한 모든 클레임을 읽을 수 있게 유지합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "credentials": {
      "envVars": [
        {
          "name": "DATABASE_URL",
          "mode": "mask",
          "extract": "://[^:]+:([^@]+)@",
          "onExtractNoMatch": "deny"
        },
        {
          "name": "SERVICE_JWT",
          "mode": "mask",
          "decode": "jwt",
          "maskClaims": ["api_key"]
        }
      ]
    }
  }
}
```

### `sandbox.credentials.allowPlaintextInject`

TLS 종료 HTTPS뿐만 아니라 일반 HTTP 요청에서도 `mask` 대체를 허용합니다. 일반 HTTP에서는 업스트림 신원이 검증되지 않으며 자격 증명이 평문으로 전송되므로, 신뢰할 수 있는 테스트 네트워크 외부에서는 이를 끈 상태로 두십시오.

* **범위**: [`User or managed`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code는 TLS 종료 HTTPS뿐만 아니라 일반 HTTP 요청에서도 `mask` 대체를 허용합니다.
  * `false`: Claude Code는 TLS 종료 HTTPS에서만 `mask` 대체를 허용합니다.
* **기본값**: `false`

```json settings.json theme={null}
{
  "sandbox": {
    "credentials": {
      "allowPlaintextInject": true
    }
  }
}
```

### `sandbox.credentials.awsPairs`

자격 증명이 비표준 이름의 변수에 있을 때, [SigV4 재서명](https://code.claude.com/docs/ko/sandboxing.md#re-sign-aws-requests)을 위해 하나의 AWS 자격 증명을 구성하는 마스크된 환경 변수를 그룹화합니다. Claude Code는 전체 값을 마스크할 때 기존 `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` 트리오를 자동으로 연결하므로, 다른 이름에 대해서만 이 키가 필요합니다. Claude Code v2.1.224 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes)
* **유형**: 각각 `accessKeyIdVar`, `secretAccessKeyVar`, 선택적 `sessionTokenVar`를 포함하는 객체의 배열이며, `sandbox.credentials.envVars` 항목을 지정합니다.
* **기본값**: 설정되지 않음. 기존 트리오만 쌍을 이룹니다.

다음은 세 개의 사용자 정의 이름 변수를 재서명을 위한 하나의 AWS 자격 증명으로 연결합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}
```

각 명명된 변수는 `extract` 또는 `decode`가 없는 [`sandbox.credentials.envVars`](#sandbox-credentials-envvars)의 전체 값 `mask` 항목이어야 하며, 모든 쌍에서 하나의 슬롯만 채울 수 있습니다. 다음 규칙도 적용됩니다:

* 프록시는 액세스 키 ID 항목의 `injectHosts`에 나열된 호스트에 대한 요청을 재서명합니다.
* `sessionTokenVar`가 설정되면, 프록시는 재서명된 요청에서 실제 토큰을 `x-amz-security-token`으로 전송합니다.
* 쌍에 기존 변수 중 하나라도 지정하면 자동 쌍 연결이 대체됩니다.

### `sandbox.credentials.sigv4`

샌드박스 프록시가 [재서명할 수 없는](https://code.claude.com/docs/ko/sandboxing.md#re-sign-aws-requests) AWS 요청 형식으로 수행할 작업을 선택합니다: `streaming`은 aws-chunked 스트리밍 업로드, `presigned`는 사전 서명된 URL, `sigv4a`는 SigV4A 비대칭 서명입니다. 이는 마스크된 쌍의 자리 표시자 액세스 키 ID로 서명된 요청에만 적용됩니다. Claude Code v2.1.224 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes)
* **유형**: `streaming`, `presigned`, `sigv4a`를 포함하는 객체이며, 각각 다음 중 하나입니다:
  * `"deny"`: 프록시가 요청을 실패시킵니다.
  * `"passthrough"`: 프록시는 마스크된 자리 표시자로 서명된 요청을 전달하므로, 도구는 AWS의 자체 거부를 받습니다.
* **기본값**: 설정되지 않음. 모든 형식이 `"deny"`입니다.

다음은 스트리밍 업로드를 프록시에서 실패시키는 대신 전달합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "credentials": {
      "sigv4": {
        "streaming": "passthrough"
      }
    }
  }
}
```

`deny`를 사용하면, 프록시가 요청을 실패시킵니다. `passthrough`를 사용하면, 프록시는 마스크된 자리 표시자에서 계산된 서명으로 요청을 전달하므로, AWS가 거부하고 호출 도구는 프록시 오류 대신 AWS의 자체 응답을 받습니다.

### `sandbox.network`

샌드박스된 명령이 도달할 수 있는 호스트, 포트, 소켓을 제어합니다. 샌드박스는 아웃바운드 트래픽을 이러한 목록을 적용하는 프록시를 통해 라우팅합니다. [네트워크 격리](https://code.claude.com/docs/ko/sandboxing.md#network-isolation)에서 프록시가 결정하는 방식 및 확인을 요청하는 시기를 참조하십시오.

* **범위**: [`Any file`](#scopes). `strictAllowlist`, `allowManagedDomainsOnly`, `tlsTerminate`는 각 항목에 설명된 대로 더 적은 소스에서 읽습니다.
* **유형**: 아래 하위 키를 포함하는 객체
* **기본값**: 설정되지 않음. 미리 허용된 도메인이 없으며, 권한 모드가 [각 새 호스트에 대해 일어나는 일](https://code.claude.com/docs/ko/sandboxing.md#hosts-outside-your-allowed-domains)을 결정합니다.

다음은 GitHub 및 npm을 미리 허용하고, `uploads.github.com`을 차단하고, 명령이 localhost에 바인드되도록 합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["uploads.github.com"],
      "allowLocalBinding": true
    }
  }
}
```

Claude Code는 배열 하위 키를 설정 범위 전체에서 병합하므로, [저장소 잠금](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox)이 적용되지 않는 한 프로젝트는 사용자 목록에 도메인을 추가할 수 있습니다. `WebFetch(domain:...)` 허용 및 거부 [권한 규칙](https://code.claude.com/docs/ko/sandboxing.md#permission-rules)은 동일한 허용 및 거부 목록에 추가됩니다.

### `sandbox.network.allowUnixSockets`

macOS에서 샌드박스된 명령이 연결할 수 있는 Unix 소켓 경로를 나열합니다. Claude Code는 seccomp 필터가 소켓 경로를 검사할 수 없는 Linux 및 WSL2에서 이 목록을 무시합니다. 해당 플랫폼에서는 대신 [`allowAllUnixSockets`](#sandbox-network-allowallunixsockets)를 사용하십시오.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: 각각 소켓 경로인 문자열의 배열
* **기본값**: 설정되지 않음. macOS 샌드박스는 모든 Unix 소켓을 차단합니다.

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"]
    }
  }
}
```

소켓 경로는 광범위한 액세스를 부여할 수 있습니다: 예를 들어 `/var/run/docker.sock`을 허용하면, 샌드박스된 명령이 Docker 데몬을 제어할 수 있습니다. [보안 제한](https://code.claude.com/docs/ko/sandboxing.md#security-limitations)을 참조하십시오.

### `sandbox.network.allowAllUnixSockets`

샌드박스된 명령이 모든 Unix 소켓에 연결하도록 합니다. Linux 및 WSL2에서 샌드박스의 [seccomp 필터](https://code.claude.com/docs/ko/sandboxing.md#set-up-linux-and-wsl2)는 `socket(AF_UNIX, ...)` 호출을 차단하므로, 이는 해당 플랫폼에서 Unix 소켓을 허용하는 유일한 방법입니다. 필터가 누락된 경우(`/sandbox`가 의존성 탭에서 보고함) 샌드박스는 Unix 소켓 호출을 차단하지 않습니다. [Linux 및 WSL2 설정](https://code.claude.com/docs/ko/sandboxing.md#set-up-linux-and-wsl2)에서 필터가 어디에서 오는지 참조하십시오.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: Boolean
  * `true`: 샌드박스 처리된 명령이 모든 Unix 소켓에 연결할 수 있습니다. Linux와 WSL2에서는 `AF_VSOCK` 주소 패밀리인 VM 소켓에도 연결할 수 있습니다
  * `false`: 샌드박스가 Unix 소켓 연결을 차단합니다. macOS에서는 `allowUnixSockets`의 경로를 제외하고, Linux와 WSL2에서는 seccomp 필터가 있는 경우 이를 통해 차단합니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "allowAllUnixSockets": true
    }
  }
}
```

WSL2에서 `true`는 또한 `cmd.exe` 및 `powershell.exe`와 같은 Windows 바이너리를 시작하는 interop 소켓을 다시 엽니다.

### `sandbox.network.allowLocalBinding`

macOS의 샌드박스된 명령이 네트워크 포트에서 수신 대기(예: 개발 서버 시작)하고 localhost의 모든 포트에 연결하도록 합니다. 루프백이 아닌 주소에서 수신 대기하는 명령은 다른 머신의 연결을 수락합니다. 이 키는 각 샌드박스된 명령이 자체 루프백 인터페이스를 가지는 Linux 및 WSL2에서는 효과가 없습니다. Linux 또는 WSL2에서 호스트의 서버에 도달하려면 [명령이 localhost의 서버에 도달하지 못함](https://code.claude.com/docs/ko/sandboxing.md#a-command-fails-to-reach-a-server-on-localhost)을 참조하십시오.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: Boolean
  * `true`: macOS의 샌드박스된 명령은 모든 로컬 주소에서 수신 대기하고 localhost의 모든 포트에 연결할 수 있습니다.
  * `false`: macOS의 샌드박스된 명령은 포트에서 수신 대기하거나 localhost의 서버에 직접 연결할 수 없습니다.
* **기본값**: `false`

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}
```

### `sandbox.network.allowMachLookup`

macOS 샌드박스가 조회할 수 있는 추가 XPC 및 Mach 서비스 이름을 나열합니다. iOS 시뮬레이터 또는 Playwright와 같이 XPC를 통해 통신하는 도구는 여기에 서비스를 나열해야 합니다.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음
* **유형**: 각각 서비스 이름인 문자열의 배열. 단일 후행 `*`는 접두사와 일치하고, `"*"` 단독으로는 모든 서비스와 일치합니다.
* **기본값**: 설정되지 않음

다음은 `com.apple.coresimulator.` 접두사 아래의 모든 서비스를 허용합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "allowMachLookup": ["com.apple.coresimulator.*"]
    }
  }
}
```

### `sandbox.network.allowedDomains`

샌드박스된 명령의 아웃바운드 트래픽에 대해 도메인을 미리 허용하므로, 샌드박스가 해당 도메인에 대해 확인을 요청하지 않습니다. `*.example.com`과 같은 와일드카드는 하위 도메인과 일치하며, 선택적 `:port` 접미사는 항목을 하나의 포트로 제한합니다. 포트 없는 항목은 모든 포트와 일치합니다.

* **범위**: [`Any file`](#scopes), [프로젝트 및 로컬 설정에 대한 제한](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox) 있음. [`allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly)가 설정된 경우 관리형 설정만 해당합니다.
* **유형**: 각각 도메인, 와일드카드 패턴, 또는 IP 리터럴이며, 선택적 `:port` 접미사를 포함하는 문자열의 배열
* **기본값**: 설정되지 않음. 권한 모드가 [각 새 호스트에 대해 일어나는 일](https://code.claude.com/docs/ko/sandboxing.md#hosts-outside-your-allowed-domains)을 결정합니다.

다음은 모든 포트의 GitHub, 모든 npm 하위 도메인, 포트 443에서만 하나의 API 호스트를 미리 허용합니다:

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "api.example.com:443"]
    }
  }
}
```

IPv6 리터럴은 괄호로 묶어 작성하며, 선택적으로 포트를 포함합니다: `"[::1]"`은 모든 포트를 허용하고 `"[::1]:443"`은 하나의 포트를 허용합니다. 괄호로 묶인 형식은 Claude Code v2.1.229 이상이 필요합니다. [도메인 목록의 IPv6 주소](https://code.claude.com/docs/ko/sandboxing.md#ipv6-addresses-in-domain-lists)를 참조하십시오.

### `sandbox.network.deniedDomains`

샌드박스된 명령의 아웃바운드 트래픽에 대해 도메인을 차단하며, [`allowedDomains`](#sandbox-network-alloweddomains)와 동일한 와일드카드, 포트, IPv6 구문을 사용합니다. 거부된 도메인은 `allowedDomains` 항목도 일치하더라도 차단된 상태로 유지됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 각각 도메인, 와일드카드 패턴, 또는 IP 리터럴이며, 선택적 `:port` 접미사를 포함하는 문자열의 배열
* **기본값**: 설정되지 않음

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "deniedDomains": ["sensitive.cloud.example.com"]
    }
  }
}
```

Claude Code는 `allowManagedDomainsOnly`가 설정되어도 세션이 로드하는 모든 설정 소스에서 이 목록을 병합하므로, 개발자는 항상 거부 목록을 강화할 수 있습니다. IPv6 리터럴은 [도메인 목록의 IPv6 주소](https://code.claude.com/docs/ko/sandboxing.md#ipv6-addresses-in-domain-lists)를 참조하십시오.

정규화된 도메인 이름을 표시하는 후행 점으로 작성된 항목(예: `example.com.`)은 `example.com`과 동일한 연결을 차단합니다.

### `sandbox.network.strictAllowlist`

승인을 요청하는 대신 허용 목록 외부의 호스트에 대한 샌드박스된 명령의 액세스를 거부합니다. 허용 목록은 [`allowedDomains`](#sandbox-network-alloweddomains)와 `WebFetch(domain:...)` 허용 규칙의 도메인을 합친 것이거나, [`allowManagedDomainsOnly`](#sandbox-network-allowmanageddomainsonly)가 설정되면 관리형 설정 항목만입니다. [관리자 필수 샌드박스 없이 적용되는 잠금](https://code.claude.com/docs/ko/sandboxing.md#locks-that-apply-without-an-admin-required-sandbox)은 저장소의 항목을 다룹니다. Claude Code v2.1.219 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes). 저장소는 이 설정을 켜거나 끌 수 없습니다.
* **유형**: Boolean
  * `true`: Claude Code는 허용 목록 외부의 호스트에 대한 샌드박스된 명령의 액세스를 거부합니다.
  * `false`: 다른 신뢰할 수 있는 설정 파일이 `true`를 설정하지 않는 한, Claude Code는 허용 목록 외부의 호스트를 즉시 거부하는 대신 권한 모드에 따라 결정합니다: 자동 모드에서는 명령의 [명령별 허용된 도메인](https://code.claude.com/docs/ko/sandboxing.md#per-command-allowed-domains-in-auto-mode)에 대해 호스트를 확인하고, `dontAsk` 모드에서는 거부하고, `bypassPermissions` 모드 및 우회가 가능한 대화형 터미널 플랜 모드 세션에서는 허용하며, 그 외에는 사용자에게 묻습니다.
* **기본값**: `false`

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "strictAllowlist": true
    }
  }
}
```

Claude Code는 샌드박스된 명령에만 이를 적용합니다. `WebFetch`와 같은 프로세스 내 도구는 여전히 [권한 규칙](https://code.claude.com/docs/ko/sandboxing.md#permission-rules)을 따릅니다. 인정된 소스 중 하나라도 `true`로 설정하면, 이는 켜진 상태로 유지됩니다. [네트워크 격리](https://code.claude.com/docs/ko/sandboxing.md#network-isolation)를 참조하십시오. Claude Code v2.1.219 이상이 필요합니다.

### `sandbox.network.allowManagedDomainsOnly`

네트워크 허용 목록을 관리형 설정이 정의하는 것으로 잠급니다. 그러면 Claude Code는 관리형 설정의 `allowedDomains` 및 `WebFetch(domain:...)` 허용 규칙만 인정하고, 사용자, 프로젝트, 로컬, `--settings` 설정의 도메인을 무시하고, 허용되지 않은 도메인을 확인을 요청하는 대신 자동으로 차단합니다.

* **범위**: [`Managed`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code는 관리형 설정의 `allowedDomains` 및 `WebFetch(domain:...)` 허용 규칙만 인정하고 허용되지 않은 도메인을 확인을 요청하는 대신 차단합니다.
  * `false`: 다른 설정 파일의 도메인이 허용 목록에 병합될 수 있습니다.
* **기본값**: `false`

다음은 허용 목록을 GitHub 및 npm으로 잠그고 개발자가 추가하는 도메인을 무시합니다:

```json managed-settings.json theme={null}
{
  "sandbox": {
    "network": {
      "allowManagedDomainsOnly": true,
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}
```

키가 `true`인 동안 샌드박스는 [관리자 필수](https://code.claude.com/docs/ko/sandboxing.md#repository-settings-under-an-admin-required-sandbox)이며, 관리형 설정만 [프록시 포트](#sandbox-network-httpproxyport)를 설정할 수 있습니다.

거부된 도메인은 여전히 세션이 로드하는 모든 소스에서 병합됩니다. [개발자가 정책을 확대하지 못하도록 유지](https://code.claude.com/docs/ko/sandboxing.md#keep-developers-from-widening-the-policy)를 참조하십시오.

### `sandbox.network.httpProxyPort`

Claude Code가 실행하는 프록시 대신 자체 HTTP 프록시를 샌드박스에 지정합니다. 조직은 HTTPS 트래픽을 검사하거나, 자체 필터링 규칙을 적용하거나, 요청을 로그에 기록하기 위해 이를 수행합니다. 해당 프록시가 필터링을 맡으며, Claude Code는 그곳으로 전송되는 트래픽에 도메인 목록과 네트워크 확인 요청을 더 이상 적용하지 않습니다. 설정되지 않으면, Claude Code는 HTTP 트래픽에 대해 자체 프록시를 시작합니다.

* **범위**: [`Any file`](#scopes). 단, [다른 샌드박스 설정이 포트를 설정할 수 있는 파일을 제한](https://code.claude.com/docs/ko/sandboxing.md#custom-proxy-configuration)하는 경우는 예외입니다
* **유형**: 숫자, 로컬 TCP 포트
* **기본값**: 설정되지 않음. Claude Code는 자체 프록시를 실행합니다.

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080
    }
  }
}
```

프록시가 SOCKS 트래픽도 전달해야 하면 [`socksProxyPort`](#sandbox-network-socksproxyport)도 설정하십시오. 둘 중 하나만 설정되면, Claude Code는 여전히 다른 프로토콜에 대해 자체 프록시를 실행합니다. [사용자 정의 프록시 구성](https://code.claude.com/docs/ko/sandboxing.md#custom-proxy-configuration)을 참조하십시오.

### `sandbox.network.socksProxyPort`

Claude Code가 실행하는 프록시 대신 자체 SOCKS5 프록시를 샌드박스에 지정합니다. 해당 프록시가 필터링을 맡으며, Claude Code는 그곳으로 전송되는 트래픽에 도메인 목록과 네트워크 확인 요청을 더 이상 적용하지 않습니다. 설정되지 않으면, Claude Code는 SOCKS 트래픽에 대해 자체 프록시를 시작합니다.

* **범위**: [`Any file`](#scopes). 단, [다른 샌드박스 설정이 포트를 설정할 수 있는 파일을 제한](https://code.claude.com/docs/ko/sandboxing.md#custom-proxy-configuration)하는 경우는 예외입니다
* **유형**: 숫자, 로컬 TCP 포트
* **기본값**: 설정되지 않음. Claude Code는 자체 프록시를 실행합니다.

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "socksProxyPort": 8081
    }
  }
}
```

[사용자 정의 프록시 구성](https://code.claude.com/docs/ko/sandboxing.md#custom-proxy-configuration)을 참조하십시오.

### `sandbox.network.tlsTerminate`

샌드박스 프록시가 TLS를 종료하도록 하여 HTTPS 요청의 콘텐츠를 읽을 수 있게 합니다. 이는 실험적 기능이며, `mask` [자격 증명 대체](https://code.claude.com/docs/ko/sandboxing.md#mask-credentials)에 필요합니다. 세션용 임시 인증 기관을 생성하려면 `{}`를 설정하고, 자체 인증 기관을 사용하려면 `caCertPath` 및 `caKeyPath`를 설정하십시오.

* **범위**: [`User or managed`](#scopes). 저장소에서는 이 설정을 활성화하거나 인증 기관을 제공할 수 없습니다.
* **유형**: 선택적 `caCertPath` 및 `caKeyPath` 문자열(각각 파일 경로)을 포함하는 객체
* **기본값**: 설정되지 않음. 프록시는 TLS를 종료하거나 검사하지 않습니다.

```json settings.json theme={null}
{
  "sandbox": {
    "network": {
      "tlsTerminate": {}
    }
  }
}
```

둘 이상의 인정된 소스가 이를 설정하면, Claude Code는 가장 높은 우선순위 소스의 값을 사용합니다: 관리형 설정, 그 다음 `--settings` 플래그, 그 다음 사용자 설정입니다.

## 메모리 및 컨텍스트

Claude Code가 컨텍스트에 로드하는 내용, 압축 방식, 메모리 및 계획 저장 위치를 제어합니다. [컨텍스트 관리](https://code.claude.com/docs/ko/context-window.md) 및 [메모리](https://code.claude.com/docs/ko/memory.md)를 참조하십시오.

### `autoCompactEnabled`

컨텍스트가 한계에 가까워질 때 Claude Code가 [대화를 자동으로 압축](https://code.claude.com/docs/ko/context-window.md#when-your-context-fills-up)하도록 합니다. `/config`에 **자동 압축**으로 표시되며, 여기서 토글하면 이 키가 사용자 설정에 기록됩니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: 컨텍스트가 한계에 가까워질 때 Claude Code가 대화를 자동으로 압축합니다
  * `false`: Claude Code가 자동으로 압축하지 않습니다
* **기본값**: `true`
* **세션별 재정의**: [`DISABLE_AUTO_COMPACT`](https://code.claude.com/docs/ko/env-vars)는 한 세션 동안 자동 압축을 끕니다. 둘 중 하나가 끄면 다른 하나는 다시 켤 수 없습니다

```json settings.json theme={null}
{
  "autoCompactEnabled": false
}
```

자동 압축이 꺼져 있는 동안에도 수동 `/compact` 명령은 계속 작동합니다. 자동 압축을 끄면 [유휴 압축](#idlecompaction)도 함께 꺼집니다.

### `autoCompactWindow`

Claude Code가 [자동으로 압축](https://code.claude.com/docs/ko/context-window.md#when-your-context-fills-up)하기 전에 컨텍스트 윈도우가 얼마나 찬지 설정합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 토큰 수, `100000`에서 `1000000` 사이. Claude Code는 값을 모델의 컨텍스트 윈도우로 제한합니다. [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)에 각 모델의 윈도우가 나열되어 있습니다
* **기본값**: 설정되지 않음. Claude Code가 모델에 맞게 조정된 윈도우를 선택합니다
* **세션별 재정의**: [`--autocompact`](https://code.claude.com/docs/ko/cli-reference#cli-flags)는 한 세션 동안 이 키보다 우선하며, [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](https://code.claude.com/docs/ko/env-vars)는 둘 다보다 우선합니다. 단, Claude Code가 [변수의 값을 무시하는](https://code.claude.com/docs/ko/model-config.md#claude_code_auto_compact_window-values) 경우는 예외입니다

```json settings.json theme={null}
{
  "autoCompactWindow": 500000
}
```

[`/autocompact`](https://code.claude.com/docs/ko/commands#all-commands) 명령은 현재 모델의 윈도우를 [`modelSettings`](#modelsettings) 아래에 저장하며, 이 값은 해당 모델에 대해 같은 파일의 이 키보다 우선합니다. [자동 압축 윈도우 설정](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)에서 명령, 플래그, 변수 및 설정이 어떻게 상호작용하는지 설명합니다.

### `autoMemoryDirectory`

[자동 메모리](https://code.claude.com/docs/ko/memory.md#storage-location)를 프로젝트별 기본값 대신 선택한 디렉토리에 저장합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열, 절대 경로 또는 `~/` 접두사가 있는 디렉토리 경로
* **기본값**: 설정되지 않음. Claude Code는 `~/.claude/projects/<project>/memory/`를 사용합니다

```json settings.json theme={null}
{
  "autoMemoryDirectory": "~/my-memory-dir"
}
```

프로젝트 또는 로컬 설정에서 Claude Code는 [훅과 동일한 워크스페이스 신뢰 규칙](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder)에 따라 이 키를 준수합니다. 복제된 저장소가 이러한 파일을 제공할 수 있기 때문입니다.

### `autoMemoryEnabled`

[자동 메모리](https://code.claude.com/docs/ko/memory.md#enable-or-disable-auto-memory)를 켜거나 끕니다. `false`일 때 Claude는 자동 메모리 디렉토리에서 읽거나 쓰지 않습니다. 세션 중에 `/memory`로 토글할 수도 있으며, 이는 이 키를 사용자 설정에 기록합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: 설정되지 않은 것과 동일합니다. 자동 메모리는 `--bare`, 안전 모드 또는 `CLAUDE_CODE_DISABLE_AUTO_MEMORY`와 같이 이 키보다 우선하는 것이 세션을 끄지 않는 한 켜져 있습니다
  * `false`: Claude는 자동 메모리 디렉토리에서 읽거나 쓰지 않습니다
* **기본값**: `true`
* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](https://code.claude.com/docs/ko/env-vars)는 한 세션 동안 이 키보다 어느 방향이든 우선합니다

```json settings.json theme={null}
{
  "autoMemoryEnabled": false
}
```

### `bashOutputMaxChars`

성공한 Bash 또는 PowerShell 명령의 [출력 중 Claude가 인라인으로 받는 문자 수](https://code.claude.com/docs/ko/tools-reference.md#output-limits)를 설정합니다. 출력이 한계를 초과하면 Claude Code는 출력을 파일에 저장하고 Claude는 짧은 미리보기와 파일의 경로를 받습니다. 자세한 빌드 또는 전체 테스트 스위트 로그와 같은 명령 출력이 기본값을 자주 초과하고 Claude가 파일을 열지 않고 읽기를 원할 때 한계를 높입니다. Claude Code v2.1.261 이상이 필요합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자 수, 양의 정수. Claude Code는 값을 `4000`에서 `128000` 범위로 제한합니다
* **기본값**: 설정되지 않음. Claude는 최대 30,000자를 인라인으로 받습니다

```json settings.json theme={null}
{
  "bashOutputMaxChars": 100000
}
```

이 키를 설정하면 Claude Code는 [`BASH_MAX_OUTPUT_LENGTH`](https://code.claude.com/docs/ko/env-vars) 환경 변수를 무시합니다.

### `claudeMd`

CLAUDE.md 스타일 지침을 별도 파일을 배포하지 않고 조직 관리 메모리로 주입합니다. Claude Code는 텍스트를 사용자 및 프로젝트 CLAUDE.md 파일보다 먼저 관리되는 메모리 항목으로 로드합니다.

* **범위**: [`관리됨`](#scopes)
* **유형**: 문자열, CLAUDE.md 파일의 텍스트. 파일처럼 작성하되 Markdown을 포함하고 줄 바꿈을 `\n`으로 표기합니다
* **기본값**: 설정되지 않음

이 예제는 두 가지 규칙을 짧은 Markdown 목록으로 배포합니다:

```json managed-settings.json theme={null}
{
  "claudeMd": "# Engineering rules\n\n- Always run make lint before committing.\n- Never push directly to main."
}
```

[조직 전체 CLAUDE.md 배포](https://code.claude.com/docs/ko/memory.md#deploy-organization-wide-claude-md)를 참조하십시오.

### `claudeMdExcludes`

Claude Code가 [메모리](https://code.claude.com/docs/ko/memory.md#exclude-specific-claude-md-files)를 로드할 때 특정 `CLAUDE.md` 파일을 건너뜁니다. 큰 모노레포에서 이를 사용하여 작업과 관련이 없는 다른 팀의 CLAUDE.md 파일을 건너뜁니다. 대규모 코드베이스 가이드의 [관련 없는 CLAUDE.md 파일 제외](https://code.claude.com/docs/ko/large-codebases.md#exclude-irrelevant-claude-md-files)에서 해당 경우를 설명합니다. 패턴은 절대 파일 경로와 일치합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열 배열, 각각 glob 패턴 또는 절대 경로
* **기본값**: 설정되지 않음. Claude Code는 찾은 모든 CLAUDE.md를 로드합니다

```json settings.json theme={null}
{
  "claudeMdExcludes": ["**/vendor/**/CLAUDE.md"]
}
```

제외는 사용자, 프로젝트 및 로컬 메모리 파일에만 적용됩니다. 관리되는 정책 CLAUDE.md 파일은 제외할 수 없습니다.

### `env`

모든 세션 및 Claude Code가 시작하는 서브프로세스에 대한 환경 변수를 설정합니다. [환경 변수 참조](https://code.claude.com/docs/ko/env-vars.md)의 대부분의 변수를 여기에 넣을 수 있으며, 이것이 모든 세션에 적용하거나 팀에 배포하는 방법입니다. 프로젝트 및 로컬 설정은 [일부 변수](#variables-claude-code-ignores-in-env)를 설정할 수 없습니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 변수 이름을 문자열 값으로 매핑하는 객체
* **기본값**: 설정되지 않음

이 예제는 자동 압축을 끄고 API 요청을 프록시를 통해 라우팅합니다:

```json settings.json theme={null}
{
  "env": {
    "DISABLE_AUTO_COMPACT": "1",
    "ANTHROPIC_BASE_URL": "https://proxy.example.com"
  }
}
```

#### `env` 값이 셸과 상호작용하는 방식

* 여기의 값은 셸에서 내보낸 동일한 변수를 덮어쓰며, 둘 이상의 설정 파일이 변수를 설정할 때 [가장 높은 우선순위](https://code.claude.com/docs/ko/settings.md#settings-precedence)가 적용됩니다. [Claude Code가 `env`에서 무시하는 변수](#variables-claude-code-ignores-in-env)는 프로젝트 및 로컬 설정의 예외를 나열합니다.
* Claude Desktop 앱 또는 [자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments) 러너가 세션을 시작할 때, 빌드하는 시작 환경이 대신 우선합니다. Claude Code는 시작 환경이 이미 설정한 변수에 대해 설정 파일의 `env` 값을 무시합니다. [디버그 로그](https://code.claude.com/docs/ko/debug-your-config.md)는 무시된 각 변수의 이름을 지정합니다.
* 셸 내보내기를 취소하려면 변수를 `""`로 설정합니다. Claude Code는 공 값을 공급자 선택에 대해 설정되지 않은 것으로 취급하며, 서브프로세스는 공 값을 상속합니다.
* `NO_COLOR` 및 `FORCE_COLOR`는 여기에서 설정하면 서브프로세스에만 도달합니다. Claude Code 자체 인터페이스 색상을 변경하려면 `claude`를 시작하기 전에 셸에서 설정합니다.
* 여기의 값은 설정 파일의 일반 텍스트이며 Claude Code가 시작하는 모든 서브프로세스에 도달합니다. 회전하는 OTLP 베어러 토큰의 경우 [`otelHeadersHelper`](#otelheadershelper)를 사용합니다. API 자격 증명의 경우 [`apiKeyHelper`](#apikeyhelper)를 사용합니다.

#### Claude Code가 `env` 값을 적용하는 시기

* 사용자 설정, `--settings` 및 관리되는 설정에서: 시작 시 및 저장된 변경이 병합된 `env`를 변경할 때 실행 중인 세션에서.
* 프로젝트 및 로컬 설정에서: 워크스페이스를 신뢰한 후 또는 신뢰 대화를 표시하지 않는 `-p` 모드에서 시작할 때, 저장된 변경이 병합된 `env`를 변경할 때 다시.
* Claude Code가 모델 선택, 타임아웃 및 한계, 기능 토글과 같은 안전한 것으로 분류하는 변수: [프로젝트 및 로컬 설정이 설정할 수 없는 변수](#variables-claude-code-ignores-in-env)를 제외하고 모든 설정 파일에서 시작할 때.
* v2.1.246 이상에서 [`/cd`로 세션을 이동](https://code.claude.com/docs/ko/permissions#move-the-session-to-another-directory)한 후: 새 디렉토리의 프로젝트 및 로컬 `env` 값, 이전 디렉토리의 위에.

#### Claude Code가 `env`에서 무시하는 변수

* 프로젝트 및 로컬 설정은 체크아웃된 저장소가 제어하지 않아야 하는 변수를 설정할 수 없습니다. 대신 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. Claude Code는 텔레메트리를 끄는 몇 가지 값을 제외하고 각각을 삭제하며, `claude --debug`로 볼 수 있는 경고를 기록합니다. 여기에는 다음이 포함됩니다:

  * Claude Code가 자신의 파일을 저장하거나 쓰는 위치를 선택하는 변수: `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_TMPDIR` 및 `HOME`, `TMPDIR`, `TMP`, `TEMP` 및 `XDG_*` 계열과 같은 운영 체제 디렉토리 변수.
  * Claude Code가 시작하는 프로세스의 프로그램과 시스템 전체 구성을 선택하는 Windows 변수, 예: `SystemRoot`, `ComSpec`, `ProgramData`, `LOCALAPPDATA`, `PATHEXT`, `PSModulePath` 및 `ProgramFiles` 계열.
  * 세션 콘텐츠를 내보내는 변수: [`OTEL_LOG_RAW_API_BODIES`](https://code.claude.com/docs/ko/env-vars#variables) 및 자세한 베타 추적 쌍 `ENABLE_BETA_TRACING_DETAILED` 및 `BETA_TRACING_ENDPOINT`.
  * [OpenTelemetry 내보내기](https://code.claude.com/docs/ko/monitoring-usage.md) 변수는 텔레메트리를 켜거나, 어디로 갈지 선택하거나, 어떤 콘텐츠를 캡처할지 선택합니다:

    * `CLAUDE_CODE_ENABLE_TELEMETRY`, 향상된 텔레메트리 베타 쌍 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 및 `ENABLE_ENHANCED_TELEMETRY_BETA`
    * 내보내기 선택기 `OTEL_LOGS_EXPORTER`, `OTEL_METRICS_EXPORTER` 및 `OTEL_TRACES_EXPORTER`
    * 콘텐츠 변수 `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_ASSISTANT_RESPONSES`, `OTEL_LOG_TOOL_CONTENT` 및 `OTEL_LOG_TOOL_DETAILS`
    * `OTEL_EXPORTER_OTLP_*` 변수는 이름이 `_ENDPOINT`, `_HEADERS`, `_PROTOCOL`, `_CERTIFICATE`, `_CLIENT_KEY` 또는 `_INSECURE`로 끝나며, 일반 및 신호별 형식으로 `OTEL_EXPORTER_OTLP_ENDPOINT` 및 `OTEL_EXPORTER_OTLP_METRICS_HEADERS`와 같습니다
    * `OTEL_EXPORTER_PROMETHEUS_HOST` 및 `OTEL_EXPORTER_PROMETHEUS_PORT`

    이 값들만 프로젝트 및 로컬 설정에서 계속 적용됩니다. 왜냐하면 그들은 뭔가를 끄기 때문입니다: 세 개의 내보내기 선택기에 대해 `none`, 그리고 `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_CONTENT` 및 `OTEL_LOG_TOOL_DETAILS`에 대해 `0`과 같은 끄기 값. 이러한 값은 사용자 설정의 동일한 변수를 재정의하지만 Claude Code를 시작하는 환경, `--settings` 파일 또는 관리되는 설정이 설정하는 것은 재정의하지 않습니다.

    프로젝트 또는 로컬 설정 파일이 이 그룹의 변수를 설정할 때 로컬 대화형 세션은 시작 시 공지를 표시합니다. `/status` 또는 `claude doctor`를 실행하여 Claude Code가 무시한 변수와 원격 측정을 끈 변수를 확인합니다. 둘 다 이름을 나열하며 값은 나열하지 않습니다. `-p`를 사용한 비대화형 실행 또는 Agent SDK 세션은 공지를 표시하지 않으므로 업그레이드 후 수집기가 여전히 데이터를 받는지 확인합니다. 그렇지 않으면 사용자 설정, 관리되는 설정, 작업의 환경 또는 `--settings`로 전달하는 파일에서 변수를 설정합니다.

    프로젝트 및 로컬 설정에서 이 그룹을 무시하려면 Claude Code v2.1.282 이상이 필요합니다.
  * Claude Code가 시작하거나 동기화하는 방식을 변경하는 변수, 예: `CLAUDE_CODE_PROCESS_WRAPPER`, `CLAUDE_CODE_SYNC_SKILLS`, `CLAUDE_CODE_SYNC_PLUGINS`, `CLAUDE_CODE_PLUGIN_CACHE_DIR` 및 `CLAUDE_CODE_PLUGIN_SEED_DIR`.
  * [화면 낭독기 모드](https://code.claude.com/docs/ko/accessibility.md) 변수 `CLAUDE_AX_SCREEN_READER` 및 [`CLAUDE_AX_STARTUP_QUIET_MS`](https://code.claude.com/docs/ko/env-vars#variables)와 같이 이름이 `CLAUDE_AX_`로 시작하는 기타 변수.
  * 응답하지 않은 대화 상자의 타이머를 설정하는 [`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`](https://code.claude.com/docs/ko/env-vars#variables).
  * 첨부 파일 처리를 끄는 [`CLAUDE_CODE_DISABLE_ATTACHMENTS`](https://code.claude.com/docs/ko/env-vars#variables).
  * Claude Code가 파일 및 디렉토리의 `@` 멘션을 확장하지 않도록 하는 [`CLAUDE_CODE_DISABLE_FILE_MENTIONS`](https://code.claude.com/docs/ko/env-vars#variables).

  v2.1.251 이전에는 프로젝트 및 로컬 설정이 Claude Code가 파일을 쓰는 위치를 선택하거나 세션 콘텐츠를 내보내는 이 목록의 변수를 설정할 수도 있었습니다. `HOME` 및 `XDG_CONFIG_HOME` 제외. v2.1.290 이전에는 대화 상자 타이머 변수와 `CLAUDE_CODE_DISABLE_ATTACHMENTS`도 설정할 수 있었습니다.
* Claude Code의 호스팅 환경이 소유하는 ID 변수, 예: `CLAUDE_CODE_REMOTE` 및 `CLAUDE_CODE_ACCOUNT_UUID`는 모든 파일에서 무시됩니다.
* [`CLAUDE_CODE_MESSAGING_SOCKET` 및 `CLAUDE_CODE_MESSAGING_TOKEN`](https://code.claude.com/docs/ko/env-vars#variables)는 Claude Code가 자체 내보내는 것이므로 모든 파일에서 무시됩니다. 소켓 변수를 무시하려면 Claude Code v2.1.224 이상이 필요하고, 토큰을 무시하려면 v2.1.228 이상이 필요합니다.
* [`CLAUDE_CODE_PROJECT_DIR_NAME`](https://code.claude.com/docs/ko/sessions#name-the-project-directory-yourself)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. v2.1.234 이상이 필요합니다.
* [`CLAUDE_CODE_RESTRICTED`](https://code.claude.com/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다.
* [`CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY`](https://code.claude.com/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. 변수는 Claude Code v2.1.283 이상이 필요합니다.
* [`CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT`, `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT`, `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` 및 `CLAUDE_CODE_DISABLE_MOUNTED_DRIVE_RM_PROMPT`](https://code.claude.com/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다.
* [`CLAUDE_CODE_WARN_DISK_FREE_GIB` 및 `CLAUDE_CODE_WARN_MEMORY_FREE_GIB`](https://code.claude.com/docs/ko/env-vars#variables)는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. 이 변수는 Claude Code v2.1.304 이상이 필요합니다.

### `fileCheckpointingEnabled`

Claude Code가 각 편집 전에 파일을 스냅샷하여 [`/rewind`](https://code.claude.com/docs/ko/checkpointing)가 파일을 복원할 수 있도록 합니다. `/config`에 \*\*코드 되감기(체크포인트)\*\*로 표시되며, 여기서 토글하면 이 키가 사용자 설정에 기록됩니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: Claude Code가 각 편집 전에 파일을 스냅샷하여 `/rewind`가 파일을 복원할 수 있습니다
  * `false`: Claude Code가 파일을 스냅샷하지 않으므로 `/rewind`가 파일을 복원할 수 없습니다
* **기본값**: `true`
* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](https://code.claude.com/docs/ko/env-vars)는 한 세션 동안 체크포인팅을 끕니다. 둘 중 하나가 끄면 다른 하나는 다시 켤 수 없습니다

```json settings.json theme={null}
{
  "fileCheckpointingEnabled": false
}
```

`-p` 실행 또는 Agent SDK 세션에서 Claude Code는 이 키를 무시합니다. SDK는 `enableFileCheckpointing` 옵션으로 체크포인팅을 켜고, 베어 `-p` 실행은 `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true`가 필요합니다. [Agent SDK의 파일 체크포인팅](https://code.claude.com/docs/ko/agent-sdk/file-checkpointing.md)을 참조하십시오.

### `idleCompaction`

유휴 압축은 사용자가 자리를 비운 긴 대화를 [압축](https://code.claude.com/docs/ko/context-window.md#what-survives-compaction)합니다. 그러면 다음 메시지는 전체 대화 대신 요약을 전송합니다. 압축이 완료되면 대화에 다음과 같은 알림이 표시됩니다:

* **터미널**: `Compacted while idle, before the prompt cache expired`로 시작하는 줄
* **[VS Code 채팅 패널](#idle-compaction-in-vs-code-and-the-desktop-app)**: `a summary written while you were away`가 포함된 알림
* **[데스크톱 앱](#idle-compaction-in-vs-code-and-the-desktop-app)**: 레이블에 `Claude Code notice`가 포함된 행 안에 표시되는 동일한 알림. 해당 행이나 텍스트가 보이지 않으면 [Verbose 보기 모드](https://code.claude.com/docs/ko/desktop.md#switch-view-modes)로 전환합니다.

유휴 압축은 다음 조건을 모두 충족하는 대화에 대해 기본적으로 켜져 있습니다:

* **세션**: 대화형 터미널 세션에 있거나, [Anthropic이 선택한 계정](#idle-compaction-in-vs-code-and-the-desktop-app)으로 VS Code 확장 프로그램의 채팅 패널 또는 데스크톱 앱의 Code 탭을 사용하고 있습니다
* **자동 압축**: [`autoCompactEnabled`](#autocompactenabled)가 켜져 있습니다
* **프롬프트 캐시**: 대화가 [1시간 프롬프트 캐시 TTL](https://code.claude.com/docs/ko/prompt-caching.md#which-ttl-each-request-gets)을 사용합니다
* **기능 플래그**: Claude Code가 [Anthropic에서 기능 플래그를 가져올](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching) 수 있습니다
* **크기**: 대화의 컨텍스트가 토큰 임계값에 도달했습니다. 이 임계값은 기본값 200,000에서 [변경](#change-the-idle-compaction-threshold)할 수 있습니다
* **유휴 시간**: 마지막 요청 이후 약 54분이 지났으며, 그 시점에 컴퓨터가 깨어 있습니다

유휴 압축을 끄려면 이 키를 `false`로 설정합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: Claude Code가 조건을 충족하는 유휴 대화를 압축합니다
  * `false`: 세션이 유휴 상태인 동안 Claude Code가 압축하지 않습니다
* **기본값**: `true`
* **세션별 재정의**: [`DISABLE_AUTO_COMPACT`](https://code.claude.com/docs/ko/env-vars)는 자동 압축과 함께 유휴 압축도 끕니다

```json settings.json theme={null}
{
  "idleCompaction": false
}
```

터미널 세션 내에서 유휴 압축을 끄거나 켜려면 `/config`를 실행하고 **유휴 압축** 행을 변경합니다. 선택한 값은 사용자 설정에 저장되며 즉시 적용됩니다. 이 행은 Claude Code v2.1.302 이상이 필요합니다. 해당 버전을 실행 중인데 `/config`에 이 행이 표시되지 않으면 다음 원인을 확인합니다:

* **다른 설정 소스가 키를 설정함**: 관리형 설정, `--settings` 플래그 또는 프로젝트나 로컬 설정 파일의 값이 사용자 설정을 재정의합니다. 대신 해당 소스에서 키를 변경합니다
* **기능 플래그를 사용할 수 없음**: Claude Code가 [Anthropic에서 기능 플래그를 가져올](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching) 수 없는 환경에서는 유휴 압축이 실행되지 않으므로 끌 대상이 없습니다

이 키는 Claude Code v2.1.290 이상이 필요합니다. 이 키를 무시하는 이전 버전에서는 유휴 압축을 중지하려면 [`autoCompactEnabled`](#autocompactenabled)를 끕니다.

#### 유휴 압축 임계값 변경

[`CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS`](https://code.claude.com/docs/ko/env-vars)를 대화의 컨텍스트가 유휴 압축 대상이 되기 위해 도달해야 하는 토큰 수로 설정합니다. 양의 정수를 사용합니다. `100000` 미만의 값은 가장 낮은 임계값인 `100000`으로 올려집니다.

기본값에서는 200K 컨텍스트 윈도우의 대화가 200,000 토큰에 도달하기 전에 자동 압축됩니다. 이 예제는 해당 대화가 조건을 충족하도록 임계값을 150,000으로 낮춥니다:

```json settings.json theme={null}
{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}
```

#### VS Code 및 데스크톱 앱의 유휴 압축

다음과 같은 알림은 Claude Code가 [이전 대화를 요약으로 대체](https://code.claude.com/docs/ko/context-window.md#what-survives-compaction)했으며, Claude가 이제 그 요약을 바탕으로 작업한다는 의미입니다:

```text theme={null}
Compacted using a summary written while you were away · turn off with "idleCompaction": false in settings.json
```

별도로 조치할 필요는 없습니다. 유휴 압축을 끄려면 `~/.claude/settings.json` 또는 다른 [설정 파일](https://code.claude.com/docs/ko/settings.md#settings-files-and-who-they-affect)에서 `idleCompaction`을 `false`로 설정합니다.

VS Code 확장 프로그램의 채팅 패널과 데스크톱 앱의 Code 탭에서는 Anthropic이 선택한 계정에 대해 유휴 압축이 실행됩니다. Claude Code는 사용자가 자리를 비운 동안 요약을 작성한 다음, 다음 메시지가 마지막 요청으로부터 1시간 이상 지나서 도착하는 경우에만 그 요약으로 압축합니다.

### `plansDirectory`

Claude Code가 [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#analyze-before-you-edit-with-plan-mode)에서 작성하는 계획 파일을 저장할 위치를 선택합니다. Claude Code는 경로를 프로젝트 루트에 상대적으로 해석합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열, 프로젝트 루트에 상대적인 경로
* **기본값**: 설정되지 않음. Claude Code는 `~/.claude/plans`를 사용합니다

```json settings.json theme={null}
{
  "plansDirectory": "./plans"
}
```

다음과 같은 경우 Claude Code는 설정한 디렉토리 대신 `~/.claude/plans`에 계획을 저장합니다:

* **프로젝트 루트 외부**: `"../plans"`처럼 경로가 프로젝트 루트 외부로 해석되는 경우.
* **macOS, Linux 및 WSL에서의 백슬래시**: Windows 스타일의 `"docs\\plans"`처럼 해석된 경로에 백슬래시가 포함된 경우. Windows에서도 작동하는 `"docs/plans"`로 작성합니다.

### `skillListingBudgetFraction`

각 턴마다 Claude는 설명과 함께 [스킬 목록](https://code.claude.com/docs/ko/skills.md#skill-descriptions-are-cut-short)을 보며, Claude Code는 해당 목록을 컨텍스트 윈도우의 일부로 제한합니다. 목록이 제한을 초과하면 Claude Code는 모든 스킬의 이름을 유지하지만 가장 적게 사용된 스킬의 설명을 삭제하므로 Claude는 여전히 해당 스킬을 호출할 수 있지만 자체적으로 선택할 가능성이 낮습니다. 더 많은 설명을 표시하려면 이 키를 높이되 턴당 더 많은 컨텍스트를 사용합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 숫자, `0`보다 크고 최대 `1`인 분수
* **기본값**: `0.01`, 컨텍스트 윈도우의 1%를 예약합니다

```json settings.json theme={null}
{
  "skillListingBudgetFraction": 0.02
}
```

목록이 사용하는 컨텍스트 양과 어떤 스킬이 가장 많이 기여하는지 확인하려면 `/doctor`를 실행합니다.

### `skillListingMaxDescChars`

각 턴마다 Claude는 각 스킬의 `description` 및 `when_to_use` 텍스트를 보여주는 [스킬 목록](https://code.claude.com/docs/ko/skills.md#skill-descriptions-are-cut-short)을 봅니다. 이 키는 Claude Code가 스킬당 해당 텍스트의 몇 문자를 표시하는지 제한합니다. 더 긴 텍스트는 제한에서 잘립니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자 수, 양의 정수
* **기본값**: `1536`

```json settings.json theme={null}
{
  "skillListingMaxDescChars": 2048
}
```

긴 설명을 유지하려면 높이되 턴당 더 많은 컨텍스트를 사용합니다. [`skillListingBudgetFraction`](#skilllistingbudgetfraction) 아래에 더 많은 스킬을 맞추려면 낮춥니다.

### `taskOutputMaxChars`

> [!WARNING]
>
> v2.1.277에서 제거되었으며, 크기를 조정한 `TaskOutput` 도구와 함께 제거되었습니다. 설정해도 현재 버전에는 영향을 주지 않습니다. Claude는 `Read`를 사용하여 백그라운드 작업의 [출력 파일](https://code.claude.com/docs/ko/tools-reference.md#background-commands)을 읽습니다.

v2.1.276까지 이 키를 설정하여 Claude가 `TaskOutput` 도구로 작업을 읽을 때 인라인으로 받은 [백그라운드 작업](https://code.claude.com/docs/ko/tools-reference.md#background-commands)의 출력 문자 수를 설정했습니다.

## 인터페이스 및 터미널

터미널에서 Claude Code의 모양과 동작을 변경합니다. 테마, 편집기 모드, 상태줄, 스피너, 세션 내 알림, 접근성을 다룹니다. [터미널 구성](https://code.claude.com/docs/ko/terminal-config.md)을 참조하십시오.

### `askUserQuestionTimeout`

응답이 없는 [`AskUserQuestion`](https://code.claude.com/docs/ko/tools-reference) 대화 상자가 일정 시간 유휴 상태가 지나면 자동으로 계속 진행되도록 하며, 이미 선택한 옵션을 제출합니다. 자리를 비운 동안 Claude가 사용자 없이 계속 진행하기를 원할 때 설정합니다. 기본값에서는 질문이 사용자가 답할 때까지 대기합니다. 타이머가 일시 중지되거나 시작되지 않는 경우는 [질문 자동 계속 타임아웃](https://code.claude.com/docs/ko/tools-reference.md#question-auto-continue-timeout)을 참조하십시오.

* **범위**: [`User or managed`](#scopes)
* **유형**: 문자열, `"60s"`, `"5m"`, `"10m"`, `"never"` 중 하나
* **기본값**: `"never"`

```json settings.json theme={null}
{
  "askUserQuestionTimeout": "5m"
}
```

`/config`에 **Question auto-continue timeout**으로 표시되며, 이 키를 사용자 설정에 기록합니다. 관리형 설정이나 `--settings` 플래그가 키를 설정하는 동안에는 Claude Code가 이 행을 숨깁니다.

### `autoContinueAtUsageLimit`

claude.ai 사용 한도로 세션이 중지된 후, 열린 세션에서 대기하다가 한도가 초기화되면 작업을 자동으로 계속합니다. [자동 계속 끄기](https://code.claude.com/docs/ko/interactive-mode.md#turn-automatic-continue-off)를 참조하십시오. Claude Code v2.1.234 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes). 사용자 설정, `--settings`, 관리형 설정에서만 읽습니다. 이 중 어느 것도 키를 설정하지 않은 경우, 프로젝트 또는 로컬 설정 파일이 이 키를 설정하면 무시되는 대신 기능이 꺼집니다.
* **유형**: Boolean
  * `true`: claude.ai 사용 한도로 세션이 중지된 후, Claude Code가 열린 세션에서 대기하다가 한도가 초기화되면 작업을 자동으로 계속합니다
  * `false`: Claude Code가 스스로 대기를 시작하지 않습니다. 사용 한도 옵션 메뉴에서 [직접 대기를 시작](https://code.claude.com/docs/ko/interactive-mode.md#start-a-wait-yourself)할 수는 있습니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "autoContinueAtUsageLimit": false
}
```

`/config`에 **Continue automatically at usage limit**으로 표시되며, 이 키를 사용자 설정에 기록합니다. 관리형 설정이나 `--settings` 플래그가 키를 설정하는 동안에는 Claude Code가 이 행을 숨깁니다.

### `autoScrollEnabled`

[전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md)에서 새 출력을 따라 대화 하단으로 이동합니다. 이 설정을 끄면 Claude가 작업을 계속하는 동안 스크롤한 위치에 머무릅니다. 권한 프롬프트는 여전히 화면에 스크롤되어 표시됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: 대화가 새 출력을 따라 하단으로 이동합니다
  * `false`: Claude가 작업을 계속하는 동안 스크롤한 위치에 머무릅니다. 권한 프롬프트는 여전히 트랜스크립트 아래에 표시됩니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "autoScrollEnabled": false
}
```

전체 화면 렌더링이 켜져 있을 때 `/config`에 **Auto-scroll**로 표시되며, 이 키를 사용자 설정에 기록합니다.

### `axScreenReader`

스크린 리더 친화적인 출력을 렌더링합니다. 장식용 테두리나 애니메이션이 없는 평문 텍스트입니다. 스크린 리더 모드는 클래식 렌더러를 사용하므로 활성화된 동안에는 `tui` 설정이 효과가 없습니다. 연결된 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)은 여전히 전체 화면으로 렌더링됩니다.

* **범위**: [`User or managed`](#scopes). `--settings`로 전달하는 파일에서도 키를 설정할 수 있습니다. Claude Code는 프로젝트 및 로컬 설정의 키를 무시하므로, 저장소나 사용자 자신의 `.claude/settings.local.json` 모두 스크린 리더 모드를 켜거나 끌 수 없습니다.
* **유형**: Boolean
  * `true`: Claude Code가 클래식 렌더러를 사용하여 장식용 테두리나 애니메이션 없이 평문 텍스트를 렌더링합니다
  * `false`: Claude Code가 일반적으로 렌더링합니다
* **기본값**: 설정되지 않음, 따라서 스크린 리더 모드가 꺼져 있습니다
* **세션별 재정의**: [`--ax-screen-reader`](https://code.claude.com/docs/ko/cli-reference#cli-flags)가 [`CLAUDE_AX_SCREEN_READER`](https://code.claude.com/docs/ko/env-vars)보다 우선하며, 둘 다 한 세션 동안 이 키보다 우선합니다

```json settings.json theme={null}
{
  "axScreenReader": true
}
```

### `bashEditDiffEnabled`

Bash 명령이 실행되는 동안 Git 저장소에서 어떤 파일이 변경되었는지 Claude Code가 기록할지 선택합니다. 기록하면 명령 실행 후 터미널에서 해당 diff를 볼 수 있고, [PostToolUse Bash 훅](https://code.claude.com/docs/ko/hooks.md#bash)이 변경된 파일 목록을 받습니다.

목록에 있는 파일이 항상 해당 명령이 변경한 파일인 것은 아닙니다. 명령이 실행되는 동안 다른 프로그램이나 다른 Bash 호출이 만든 변경도 목록에 나타날 수 있습니다.

모든 권한 모드에서 기록하려면 키를 `true`로 설정합니다. Claude Code v2.1.269 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes). `true`는 사용자 설정, `--settings`로 전달된 JSON, 또는 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서만 유효하므로, 저장소의 `.claude/settings.json`이나 `.claude/settings.local.json`에 있는 `true`로는 기록을 켤 수 없습니다. 두 저장소 파일 중 하나에 있는 `false`는 [우선순위가 더 높은](https://code.claude.com/docs/ko/settings.md#settings-precedence) 파일이 `true`를 설정하지 않는 한 여전히 기록을 끕니다.
* **유형**: Boolean
* **기본값**: 설정되지 않음, 따라서 Claude Code는 자동 모드와 `bypassPermissions` 모드에서 Claude에게 Bash를 통해 파일을 편집하도록 지시할 때 변경 사항을 기록합니다
* **세션별 재정의**: [`CLAUDE_CODE_BASH_EDIT_DIFF`](https://code.claude.com/docs/ko/env-vars)가 한 세션 동안 이 키보다 우선합니다

```json settings.json theme={null}
{
  "bashEditDiffEnabled": true
}
```

### `companyAnnouncements`

시작 시 사용자에게 조직의 공지 사항을 표시합니다. 두 개 이상을 나열하면 Claude Code가 세션마다 하나를 무작위로 선택합니다. 사용자가 처음 실행할 때는 첫 번째 항목을 표시합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열 배열
* **기본값**: 설정되지 않음, 따라서 공지 사항이 표시되지 않습니다

```json settings.json theme={null}
{
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
  ]
}
```

### `defaultShell`

입력 상자에서 [`!` 접두사](https://code.claude.com/docs/ko/interactive-mode#shell-mode-with-prefix)로 입력하는 셸 명령, 즉 Claude Code가 직접 실행하여 세션에 추가하는 명령을 Bash와 PowerShell 중 어느 것으로 실행할지 선택합니다.

`"powershell"`은 [PowerShell 도구](https://code.claude.com/docs/ko/tools-reference.md#powershell-tool)가 켜져 있을 때만 작동합니다. 이 도구는 Git Bash가 없는 Windows에서, 그리고 claude.ai 및 Console 계정의 경우 Git Bash가 있는 Windows에서 기본적으로 켜져 있습니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 세션과 macOS, Linux, WSL에서는 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`을 설정하여 도구를 켭니다. 도구를 끄려면 이 변수를 `0`으로 설정합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열, 다음 중 하나:
  * `"bash"`: Claude Code가 `!` 명령을 Bash에서 실행합니다
  * `"powershell"`: Claude Code가 `!` 명령을 PowerShell에서 실행합니다
* **기본값**: `"bash"`, Bash를 사용할 수 없는 Windows에서는 `"powershell"`

```json settings.json theme={null}
{
  "defaultShell": "powershell"
}
```

지정한 셸을 사용할 수 없으면 Claude Code는 다른 셸을 사용합니다. `"powershell"`은 PowerShell 도구가 꺼져 있을 때 Bash로 대체되고, `"bash"`는 Bash가 설치되어 있지 않을 때 PowerShell로 대체됩니다.

### `dialogExpiry`

Remote Control 또는 SDK 호스트와 같이 Claude Code가 [원격 클라이언트로 전달하는](https://code.claude.com/docs/ko/remote-control.md#limitations) 대화 상자와 [보류된 세션 간 메시지](https://code.claude.com/docs/ko/cross-session-messaging.md#control-inbound-messages)의 승인 대화 상자에 대한 기한을 설정합니다. Claude Code v2.1.236 이상에서는 터미널에 아무도 없을 수 있는 세션에서 세션 도중 표시되는 [Fable 사용량 크레딧 동의 프롬프트](https://code.claude.com/docs/ko/model-config.md#fable-and-usage-credits)에도 같은 기한이 적용됩니다. 기한 전에 응답이 없으면 Claude Code는 대화 상자를 취소하고 아무 작업도 하지 않는 기본 동작으로 계속합니다. Claude Code v2.1.224 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes)
* **유형**: 문자열, `"60s"`, `"5m"`, `"10m"`, 또는 기한을 비활성화하는 `"never"` 중 하나
* **기본값**: `"5m"`
* **세션별 재정의**: [`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`](https://code.claude.com/docs/ko/env-vars)가 한 세션 동안 이 키보다 우선합니다

```json settings.json theme={null}
{
  "dialogExpiry": "10m"
}
```

권한 프롬프트와 [`AskUserQuestion`](https://code.claude.com/docs/ko/tools-reference#askuserquestion-tool-behavior) 질문은 자체 흐름을 사용하며 이 기한의 적용을 받지 않습니다. `/config`에 **Dialog expiry**로 표시되며, 이 키를 사용자 설정에 기록합니다. 이 행은 Claude Code v2.1.232 이상이 필요하며, 관리형 설정이나 `--settings` 플래그가 키를 설정하는 동안에는 Claude Code가 이 행을 숨깁니다.

### `editorMode`

입력 프롬프트의 키 바인딩 모드를 선택합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열, 다음 중 하나:
  * `"normal"`: 프롬프트 입력의 표준 키 바인딩
  * `"vim"`: NORMAL, INSERT, VISUAL 모드를 갖춘 vim 스타일 편집
* **기본값**: `"normal"`

```json settings.json theme={null}
{
  "editorMode": "vim"
}
```

`/config`에 **Editor mode**로 표시되며, 이 키를 사용자 설정에 기록합니다.

### `emojiCompletionEnabled`

프롬프트 입력에 `:`와 단축 코드를 입력하면 이모지 제안을 표시하고, `:heart:`와 같이 완성된 단축 코드를 해당 이모지로 바꿉니다. 둘 다 끄려면 `false`로 설정합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 `:` 뒤에 이모지 제안을 표시하고 완성된 단축 코드를 해당 이모지로 바꿉니다
  * `false`: Claude Code가 이모지를 제안하지 않으며 단축 코드도 바꾸지 않습니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "emojiCompletionEnabled": false
}
```

[이모지 단축 코드](https://code.claude.com/docs/ko/interactive-mode.md#emoji-shortcodes)를 참조하십시오. Claude Code v2.1.217 이상이 필요합니다.

### `fileSuggestion`

기본 제공 파일 제안 대신 자체 명령을 실행하여 `@` 파일 경로 자동 완성을 제공합니다. 기본 제공 제안은 빠른 파일 시스템 탐색을 사용합니다. 대규모 모노레포에서는 미리 빌드된 파일 인덱스와 같은 프로젝트별 인덱싱이 더 나을 수 있습니다.

* **범위**: [`Any file`](#scopes). [상태줄 및 파일 제안 게이트](#status-line-and-file-suggestion-gates)에 따라 Claude Code는 명령을 끄거나 관리형 값만 실행하며, 사용자의 명령은 경고 없이 건너뜁니다.
* **유형**: 항상 `"command"`인 `type`과 실행할 셸 명령인 `command`가 있는 객체
* **기본값**: 설정되지 않음, 따라서 Claude Code가 기본 제공 파일 제안을 사용합니다

```json settings.json theme={null}
{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}
```

이를 저장한 후 프롬프트에 `@`와 경로의 일부를 입력하면 명령 출력에서 제안이 나옵니다.

#### 명령 입력 및 출력

Claude Code는 `CLAUDE_PROJECT_DIR`를 포함하여 [훅](https://code.claude.com/docs/ko/hooks.md)과 동일한 환경 변수로 명령을 실행하며, 5초 후에는 대기를 중단합니다. 명령은 지금까지 입력한 내용을 담은 `query` 필드가 있는 JSON을 stdin으로 받습니다.

```json theme={null}
{"query": "src/comp"}
```

줄바꿈으로 구분된 파일 경로를 stdout으로 출력합니다. Claude Code는 최대 15개를 표시합니다.

```text theme={null}
src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx
```

다음 스크립트는 쿼리를 읽어 저장소 파일 인덱스에 전달합니다.

```bash theme={null}
#!/bin/bash
query=$(cat | jq -r '.query')
# Replace your-repo-file-index with your own file search command
your-repo-file-index --query "$query" | head -20
```

### `footerLinksRegexes`

정규식이 턴 출력(파일 내용과 가져온 페이지를 포함한 도구 결과, Claude 자체의 응답)과 일치하면 입력 상자 아래 푸터에 클릭 가능한 배지를 추가로 렌더링합니다. 리뷰 도구나 이슈 트래커와 같은 프로젝트 CLI가 출력하는 ID를 세션 링크로 바꾸는 데 사용합니다.

* **범위**: [`User or managed`](#scopes)
* **유형**: 객체 배열, 각 객체에는 `"regex"`로 설정된 `type`, `pattern` 정규식, `url` 템플릿, 선택적 `label`이 있습니다. `url`과 `label`의 `{name}` 자리 표시자는 `pattern`의 명명된 캡처 그룹으로 채워집니다
* **기본값**: 설정되지 않음, 따라서 배지가 렌더링되지 않습니다

이 예시는 `PROJ-1234`와 같은 이슈 키를 일치시키고 캡처된 키로 각 링크를 만듭니다.

```json settings.json theme={null}
{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}
```

이렇게 구성하면 도구 결과나 Claude의 응답에 `PROJ-1234`가 나타날 때 `https://issues.example.com/browse/PROJ-1234`로 연결되는 `PROJ-1234` 배지가 푸터에 표시됩니다.

#### 배지 제약 조건

각 항목의 URL, 레이블, 배지 수는 다음과 같이 제한됩니다.

| 제약 조건 | 동작 |
| :- | :- |
| URL 출처 | 캡처된 값은 URL 인코딩되며, 구성된 URL은 템플릿의 리터럴 출처와 같아야 합니다. 캡처는 경로 세그먼트나 쿼리 값을 채울 수 있지만 링크가 가리키는 곳을 바꿀 수는 없습니다 |
| URL 길이 | 2048자를 초과하는 구성된 URL은 삭제됩니다 |
| URL 스킴 | `https`, `http`, 또는 인식되는 편집기나 워크스페이스 딥 링크 스킴이어야 합니다: `vscode`, `vscode-insiders`, `cursor`, `windsurf`, `zed`, `jetbrains`, `idea`, `slack`, `linear`, `notion`, `figma` |
| 레이블 | 기본값은 일치한 텍스트이며 28개 표시 열로 잘립니다 |
| 배지 수 | 최대 5개의 배지가 렌더링됩니다. 가장 오래된 배지는 새로운 일치 항목으로 대체되며 `/clear`로 제거됩니다 |

턴이 완료되면 Claude Code는 메인 스레드에서 각 항목의 `pattern` 정규식을 턴 출력과 대조하므로, 느린 정규식은 완료될 때까지 UI를 차단합니다. `(a+)+$`와 같은 중첩 수량자는 특정 입력에 대해 기하급수적으로 오래 걸려 세션을 멈추게 할 수 있으므로, 각 `pattern`을 선형으로 유지하고 `+`나 `*`를 중첩하지 마십시오.

[사용자 지정 상태줄](https://code.claude.com/docs/ko/statusline.md)이 구성되어 있으면 푸터 배지는 그 옆에 함께 렌더링되며, 어느 쪽도 다른 쪽을 대체하지 않습니다. 세션 데이터로 자체 내용을 계산하는 스크립트 기반 행에는 상태줄을 사용하고, 스크립트 없이 대화의 ID를 링크로 바꾸려면 푸터 배지를 사용합니다.

### `keybindingFlavor`

> [!WARNING]
>
> v2.1.261부터 deprecated되었으며 효과가 없습니다. 프롬프트의 단어 편집 키는 Bash에서처럼 항상 [readline 규칙을 따릅니다](https://code.claude.com/docs/ko/interactive-mode.md#make-ctrl-w-delete-back-to-whitespace). Claude Code는 여전히 `keybindingFlavor`를 허용하므로 이를 설정한 설정 파일은 계속 유효합니다.

v2.1.238부터 v2.1.260까지는 이 키를 `"readline"`으로 설정하면 `Ctrl+W`가 이전 단어만이 아니라 이전 공백까지 삭제했습니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열, `"classic"` 또는 `"readline"`
* **기본값**: 설정되지 않음

### `maxProseWidth`

넓은 터미널에서도 줄을 읽기 쉽게 유지하도록 Claude 응답의 산문 너비를 제한합니다. 단락, 제목, 목록, 인용구는 이 열 수 안에서 줄바꿈되며, 표와 코드 블록은 전체 터미널 너비를 유지합니다. Claude Code v2.1.282 이상이 필요합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 터미널 열 수, 정수, 최솟값 `40`. Claude Code는 다른 값을 무시합니다
* **기본값**: 설정되지 않음, 따라서 산문이 터미널 가장자리에서 줄바꿈됩니다

```json settings.json theme={null}
{
  "maxProseWidth": 80
}
```

### `prefersReducedMotion`

스피너, 시머, 깜박임 효과와 같은 인터페이스 애니메이션을 줄이거나 끕니다. `/config`에 **Reduce motion**으로 표시됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 스피너, 시머, 깜박임 효과와 같은 인터페이스 애니메이션을 줄이거나 끕니다
  * `false`: 설정되지 않은 경우와 같으며, Claude Code가 애니메이션을 표시합니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "prefersReducedMotion": true
}
```

### `promptSuggestionEnabled`

프롬프트 입력에 나타나는 회색 예측인 [프롬프트 제안](https://code.claude.com/docs/ko/interactive-mode.md#prompt-suggestions)을 표시하거나 숨깁니다. 숨기려면 `false`로 설정하거나 `/config`에서 **Prompt suggestions**를 끕니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: 프롬프트 입력에 프롬프트 제안이 표시됩니다
  * `false`: Claude Code가 프롬프트 제안을 숨깁니다
* **기본값**: `true`
* **세션별 재정의**: [`CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION`](https://code.claude.com/docs/ko/env-vars)이 한 세션 동안 이 키보다 우선합니다

```json settings.json theme={null}
{
  "promptSuggestionEnabled": false
}
```

프롬프트 제안에는 텔레메트리가 켜진 claude.ai 또는 Console 계정이 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서, 또는 [`DISABLE_TELEMETRY`](https://code.claude.com/docs/ko/env-vars) 등으로 텔레메트리가 꺼진 경우에는 이 키가 효과가 없으며 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1`만으로 프롬프트 제안을 켤 수 있습니다.

### `respectGitignore`

`@` 파일 선택기가 `.gitignore` 패턴과 일치하는 파일을 제외할지 제어합니다. `/config`에 **Respect .gitignore in file picker**로 표시됩니다.

* **범위**: [`Any file`](#scopes). 어떤 설정 파일도 이 키를 설정하지 않으면 Claude Code는 `/config` 토글이 기록하는 `~/.claude.json`의 `respectGitignore`를 사용합니다.
* **유형**: Boolean
  * `true`: `@` 파일 선택기가 `.gitignore` 패턴과 일치하는 파일을 제외합니다
  * `false`: `@` 파일 선택기가 `.gitignore` 패턴과 일치하는 파일을 포함합니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "respectGitignore": false
}
```

### `respondToBashCommands`

입력 상자에서 [`!` 접두사](https://code.claude.com/docs/ko/interactive-mode#shell-mode-with-prefix)로 셸 명령을 실행한 후 Claude가 응답할지 선택합니다. 기본적으로 Claude Code는 명령 출력을 대화에 추가하고 Claude가 이에 응답합니다. 응답 없이 출력을 컨텍스트에 추가하려면 이 키를 `false`로 설정합니다. 이렇게 하면 여러 명령을 실행한 후 한꺼번에 질문할 수 있습니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 명령 출력을 대화에 추가하고 Claude가 이에 응답합니다
  * `false`: Claude Code가 응답 없이 출력을 컨텍스트에 추가합니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "respondToBashCommands": false
}
```

[`!` 접두사를 사용하는 셸 모드](https://code.claude.com/docs/ko/interactive-mode#shell-mode-with-prefix)를 참조하십시오.

### `showClearContextOnPlanAccept`

Claude가 [플랜 모드](https://code.claude.com/docs/ko/permission-modes.md#review-and-approve-a-plan)에서 계획을 완료하면 승인 메뉴를 표시합니다. 계획 수립에는 많은 컨텍스트가 사용될 수 있으므로, 이 키는 해당 메뉴에 첫 번째 옵션으로 \*\*Yes, clear context and …\*\*를 추가합니다. 이 옵션은 계획을 승인하고 대화 컨텍스트를 지운 다음 계획만으로 구현을 시작합니다. 레이블의 나머지 부분에는 세션이 계속 진행될 권한 모드와 계획 수립에 사용된 컨텍스트의 양이 표시됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: 계획 승인 메뉴에 계획을 승인하고 대화 컨텍스트를 지우는 첫 번째 옵션 \*\*Yes, clear context and …\*\*가 추가됩니다
  * `false`: 계획 승인 메뉴에 컨텍스트 지우기 옵션이 표시되지 않습니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "showClearContextOnPlanAccept": true
}
```

### `showTurnDuration`

각 응답 후에 "Cooked for 1m 6s · done 6:05 PM"과 같은 턴 소요 시간 메시지를 표시하거나 숨깁니다. "done" 뒤의 시각은 턴이 끝난 시간을 나타내며, [`timeFormat`](#timeformat)과 [`timeZone`](#timezone)이 그 형식과 시간대를 제어합니다. `/config`에 **Show turn duration**으로 표시됩니다.

* **범위**: [`Any file`](#scopes). 어떤 설정 파일도 이 키를 설정하지 않으면 이전 버전의 `~/.claude.json`에 있는 값이 적용됩니다.
* **유형**: Boolean
  * `true`: 각 응답 후에 턴 소요 시간 메시지가 표시됩니다
  * `false`: Claude Code가 턴 소요 시간 메시지를 숨깁니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "showTurnDuration": false
}
```

### `spellcheck`

사용자가 설치한 맞춤법 검사기를 사용하여 입력하는 동안 프롬프트 입력에서 철자가 틀린 단어에 밑줄을 표시합니다. Claude Code는 입력 상자의 텍스트만 검사합니다. aspell, hunspell, ispell 설치 방법과 검사기가 다루는 범위는 [입력하면서 맞춤법 검사](https://code.claude.com/docs/ko/interactive-mode.md#check-spelling-as-you-type)를 참조하십시오. Claude Code v2.1.235 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes). 이 키를 설정하는 가장 높은 계층의 블록이 전체로 적용됩니다.
* **유형**: `enabled`(Boolean), `checker`(`"aspell"`, `"hunspell"`, `"ispell"`, 또는 `"auto"`), `language`(문자열, 검사기에 사전 이름으로 전달됨), `color`(문자열, 터미널 색상 이름, `#rrggbb`, `rgb(r,g,b)`, `ansi256(n)`, 또는 `ansi:<name>`)가 있는 객체
* **기본값**: 설정되지 않음, 따라서 맞춤법 검사가 꺼져 있습니다. `checker`의 기본값은 `"auto"`이며, 이는 세 검사기 중 `PATH`에서 가장 먼저 발견되는 것을 사용한다는 의미입니다. `language`의 기본값은 검사기 자체의 사전이며, `color`의 기본값은 테마의 오류 색상입니다

```json settings.json theme={null}
{
  "spellcheck": { "enabled": true, "language": "en_GB" }
}
```

### `spinnerTipsEnabled`

Claude가 작업하는 동안 스피너 줄에는 "Use Plan Mode to prepare for a complex request before making changes. Press Shift+Tab twice to enable."와 같은 Claude Code 기능에 관한 짧은 팁이 순환 표시됩니다. 이를 숨기려면 이 키를 `false`로 설정합니다. `/config`에 **Show tips**로 표시됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude가 작업하는 동안 스피너에 팁이 표시됩니다
  * `false`: Claude Code가 스피너 팁을 숨깁니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "spinnerTipsEnabled": false
}
```

### `spinnerTipsOverride`

Claude가 작업하는 동안 Claude Code가 표시하는 [스피너 팁](#spinnertipsenabled)에 자체 팁을 추가하거나, 기본 제공 팁을 자체 팁으로 대체합니다. Claude Code는 사용자의 팁을 기본 제공 팁과 같은 순환에 넣습니다.

[`spinnerTipsEnabled`](#spinnertipsenabled)를 `false`로 설정하면 Claude Code는 사용자의 팁을 포함하여 모든 팁을 숨깁니다.

* **범위**: [`Any file`](#scopes). Claude Code는 사용자 설정, `--settings` 플래그, 관리형 설정의 팁 객체, `tipsFile`, `label`, `excludeDefault`를 적용하며, 프로젝트 및 로컬 설정에서는 일반 문자열 팁만 읽습니다.
* **유형**: 각각 선택 사항인 `tips`, `tipsFile`, `label`, `excludeDefault` 필드가 있는 객체
* **기본값**: 설정되지 않음, 따라서 Claude Code가 기본 제공 팁만 표시합니다

팁 객체, `tipsFile`, `label`, 그리고 프로젝트 및 로컬 설정이 일반 문자열만 제공한다는 범위 항목의 규칙은 Claude Code v2.1.247 이상이 필요합니다.

각 `tips` 항목은 일반 문자열이거나 다음 필드가 있는 객체입니다.

| 필드 | 필수 | 설명 |
| :- | :- | :- |
| `id` | 예 | 최대 64개의 문자, 숫자, `.`, `_`, 또는 `-`. Claude Code는 이 값을 기준으로 팁의 표시 기록을 관리하므로, 목록 순서를 바꿔도 팁의 쿨다운이 유지됩니다. 같은 id를 가진 두 항목 중에서는 Claude Code가 첫 번째 항목을 사용합니다 |
| `text` | 예 | 팁 내용, 최대 500자의 한 줄. Claude Code는 ANSI 이스케이프와 제어 문자를 제거하고 공백을 축약합니다 |
| `cooldownSessions` | 아니요 | Claude Code가 팁을 다시 표시하기 전에 기다리는 세션 수, `0`부터 `1000`까지, 기본값 `0` |
| `priority` | 아니요 | 같은 기간 동안 표시되지 않은 팁 사이의 순서, 높은 값이 먼저, `-10`부터 `10`까지, 기본값 `0` |

Claude Code는 일반 문자열을 해당 기본값과 위치 기반 id를 가진 팁으로 읽으므로, 목록 순서를 바꾸면 표시 기록이 초기화됩니다. 편집 후에도 기록을 유지하려면 팁에 `id`를 지정하십시오.

Claude Code는 `tips`와 `tipsFile`을 합쳐 최대 200개의 팁을 읽으며, 유효하지 않은 항목은 설정 파일을 거부하는 대신 디버그 경고와 함께 삭제합니다.

나머지 필드를 사용하여 팁 파일을 지정하고, 접두사를 설정하고, 기본 제공 팁을 숨깁니다.

* `tipsFile`: 같은 항목의 배열 또는 `tips` 배열이 있는 객체를 담은 로컬 JSON 파일의 절대 경로 또는 `~/` 경로, 최대 256 KB. Claude Code는 프로세스당 한 번 파일을 읽으므로, 편집 내용은 다음 시작 시 로드됩니다. [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)을 통해서는 설정할 수 없습니다. 이 경우 인라인 `tips`를 배포하거나, 디스크상의 `managed-settings.json`에 경로를 배포하십시오.
* `label`: 사용자, `--settings`, 관리형 설정의 팁 앞에 Claude Code가 표시하는 접두사, 최대 40자. 기본값은 기본 제공 팁과 같은 접두사인 `Tip`이며, 프로젝트 및 로컬 설정의 팁은 항상 이 접두사를 사용합니다.
* `excludeDefault`: 기본 제공 팁을 숨기고 사용자의 팁만 표시하려면 `true`로 설정합니다. 예를 들어 `tipsFile`이 존재하지 않거나 모든 항목이 유효하지 않아 Claude Code가 사용자의 팁을 하나도 로드할 수 없으면, 빈 스피너 대신 기본 제공 순환을 유지합니다.

둘 이상의 설정 파일이 이 키를 설정하면 Claude Code는 모든 파일의 팁을 표시하며, `tipsFile`, `label`, `excludeDefault`는 각각을 설정하는 관리형 설정, `--settings` 플래그, 사용자 설정 중 우선순위가 가장 높은 것에서 가져옵니다.

사용자 설정에 있는 이 예시는 `Acme tip` 접두사로 일반 문자열 팁과 객체 팁을 순환에 추가합니다.

```json settings.json theme={null}
{
  "spinnerTipsOverride": {
    "label": "Acme tip",
    "tips": [
      "Run /review before opening a PR",
      {
        "id": "gateway-errors",
        "text": "Seeing 5xx errors? Check the gateway status page first",
        "cooldownSessions": 5,
        "priority": 2
      }
    ]
  }
}
```

예시의 각 필드는 Claude Code가 팁을 표시하는 방식의 한 가지를 바꿉니다.

* `label`: Claude Code가 두 팁을 모두 `Tip: ...` 대신 `Acme tip: ...`으로 표시합니다.
* 일반 문자열: Claude Code가 기본값을 적용하므로 바로 다음 세션에 다시 나타날 수 있습니다.
* `id`: Claude Code가 두 번째 팁의 표시 기록을 `gateway-errors` 기준으로 관리하므로, 팁을 추가하거나 순서를 바꾼 후에도 쿨다운이 계속 적용됩니다.
* `cooldownSessions`: Claude Code가 `gateway-errors` 팁을 표시한 후에는 다섯 세션이 지날 때까지 해당 팁을 다시 표시하지 않습니다.
* `priority`: `gateway-errors` 팁과 다른 팁이 같은 세션 수 동안 표시되지 않은 경우(예: 둘 다 아직 표시된 적이 없는 경우), Claude Code는 `gateway-errors`를 먼저 표시합니다. 일반 문자열은 기본 우선순위인 `0`을 가집니다.

Claude가 작업하는 동안 Claude Code는 `Acme tip: Run /review before opening a PR`과 같이 사용자의 접두사와 함께 스피너에 팁을 표시합니다.

### `spinnerVerbs`

턴이 진행되는 동안 스피너에는 "Accomplishing", "Architecting", "Baking"과 같은 동사가 순환 표시됩니다. 이 키를 사용하여 해당 순환에 자체 동사를 추가하거나 기본 제공 목록을 자체 목록으로 대체합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열 배열인 `verbs`와 다음 중 하나인 `mode`가 있는 객체:
  * `"append"`: Claude Code가 기본 제공 세트에 사용자의 동사를 추가합니다
  * `"replace"`: Claude Code가 사용자의 동사만 표시합니다
* **기본값**: 설정되지 않음, 따라서 Claude Code가 기본 제공 동사를 사용합니다

이 예시는 기본 제공 세트에 두 개의 동사를 추가합니다.

```json settings.json theme={null}
{
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["Pondering", "Crafting"]
  }
}
```

`"replace"` 모드에서 `verbs` 배열이 비어 있으면 Claude Code는 기본 제공 동사를 유지합니다.

### `statusLine`

자체 명령을 실행하여 모델, 비용, git 브랜치와 같은 컨텍스트를 담은 [상태줄](https://code.claude.com/docs/ko/statusline.md)을 프롬프트 아래에 렌더링합니다. 선택적 필드로 간격을 조정하고, 주기적 재실행을 추가하고, 스크립트가 `vim.mode`를 직접 렌더링할 때 기본 제공 vim 모드 표시기를 숨길 수 있습니다.

* **범위**: [`Any file`](#scopes). [`allowManagedHooksOnly`](#allowmanagedhooksonly)가 켜져 있거나 [`disableAllHooks`](#disableallhooks)가 관리형 설정 외부에서 설정된 경우 관리형 설정 값만 실행됩니다.
* **유형**: `"command"`로 설정된 `type`과 `command` 문자열, 그리고 선택적으로 문자 수인 `padding`, 초 단위(최솟값 `1`)인 `refreshInterval`, Boolean인 `hideVimModeIndicator`가 있는 객체
* **기본값**: 설정되지 않음, 따라서 상태줄이 없습니다

이 예시는 모델 이름과 컨텍스트 사용량을 출력하고 수평 간격 2자를 추가합니다.

```json settings.json theme={null}
{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
    "padding": 2
  }
}
```

이 예시는 [`jq`](https://jqlang.org/)가 설치되어 있어야 하며 셸에서 실행됩니다. PowerShell 및 Git Bash용 동등한 예시는 [Windows 구성](https://code.claude.com/docs/ko/statusline.md#windows-configuration)을, 전체 설정 방법은 [상태줄 수동 구성](https://code.claude.com/docs/ko/statusline.md#manually-configure-a-status-line)을 참조하십시오.

### `subagentStatusLine`

Claude가 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)를 실행하면 Claude Code는 프롬프트 아래의 작업 표시에 서브에이전트당 한 행씩 `name · description · token count`를 표시하여 나열합니다. 이 키를 사용하면 자체 명령을 실행하여 이러한 행을 다시 작성할 수 있습니다. 예를 들어 각 서브에이전트의 컨텍스트 사용량을 백분율로 표시할 수 있습니다. 새로 고칠 때마다 Claude Code는 각 서브에이전트의 `id`, `name`, `status`, `model`, `tokenCount` 등을 담은 `tasks` 배열이 포함된 하나의 JSON 객체로 표시된 행을 stdin에 보내고, `{"id", "content"}` 줄로 다시 작성한 각 `id`의 행을 대체합니다. 다시 작성하지 않은 행은 기본 렌더링을 유지합니다.

* **범위**: [`Any file`](#scopes). [`allowManagedHooksOnly`](#allowmanagedhooksonly)가 켜져 있거나 [`disableAllHooks`](#disableallhooks)가 관리형 설정 외부에서 설정된 경우 관리형 설정 값만 실행됩니다.
* **유형**: `"command"`로 설정된 `type`과 `command` 문자열이 있는 객체
* **기본값**: 설정되지 않음, 따라서 Claude Code가 기본 행을 렌더링합니다

```json settings.json theme={null}
{
  "subagentStatusLine": {
    "type": "command",
    "command": "jq -c '.tasks[] | {id, content: \"\\(.name): \\(.tokenCount) tokens\"}'"
  }
}
```

[서브에이전트 상태줄](https://code.claude.com/docs/ko/statusline.md#subagent-status-lines)을 참조하십시오.

### `syntaxHighlightingDisabled`

Claude Code는 터미널에 표시하는 diff, 코드 블록, 파일 미리 보기의 코드를 기본 제공 하이라이터로 언어별로 색상을 입힙니다. 플러그인이나 언어 서버는 관여하지 않습니다. 색상이 터미널 테마와 어울리지 않거나 스크린 리더를 느리게 하는 경우 등에는 이 키를 `true`로 설정하여 일반 텍스트로 표시합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 diff, 코드 블록, 파일 미리 보기에서 구문 강조를 끕니다
  * `false`: Claude Code가 구문을 강조합니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "syntaxHighlightingDisabled": true
}
```

### `terminalProgressBarEnabled`

일부 터미널은 터미널에서 실행 중인 프로그램에 대한 진행률 표시기를 탭이나 작업 표시줄에 표시할 수 있습니다. Claude가 작업하는 동안 Claude Code는 터미널에 진행 중 상태를 보고하므로, 다른 탭이나 창에서 세션이 아직 바쁜지 확인할 수 있습니다. 턴이 끝난 후에도 [백그라운드 서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#run-subagents-in-foreground-or-background)나 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)가 아직 실행 중이면 표시기가 계속 보이며, 세션이 유휴 상태가 되면 사라집니다.

Claude Code는 표시기를 지원하는 터미널(ConEmu, Ghostty 1.2.0 이상, iTerm2 3.6.6 이상)에서만 이를 보고합니다. Claude Code가 보고하지 않도록 하려면 이 키를 `false`로 설정합니다. `/config`에 **Terminal progress bar**로 표시됩니다.

* **범위**: [`Any file`](#scopes). 어떤 설정 파일도 이 키를 설정하지 않으면 이전 버전의 `~/.claude.json`에 있는 값이 적용됩니다.
* **유형**: Boolean
  * `true`: 지원하는 터미널에서 터미널 진행률 표시줄이 표시됩니다
  * `false`: Claude Code가 터미널 진행률 표시줄을 숨깁니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "terminalProgressBarEnabled": false
}
```

### `terminalTitleFromRename`

Claude Code는 터미널 탭의 제목을 설정합니다. 기본적으로 대화에서 생성한 제목을 사용하며, `/rename` 또는 `--name`으로 세션에 [이름](https://code.claude.com/docs/ko/sessions.md#name-your-sessions)을 지정하면 탭에 그 이름이 대신 표시됩니다. 세션에 이름을 지정한 후에도 탭에 생성된 제목을 유지하려면 이 키를 `false`로 설정합니다. 이름 자체는 여전히 적용되므로 `/resume <name>`과 세션 선택기에서 찾을 수 있습니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: 터미널 탭 제목에 설정한 세션 이름이 표시됩니다
  * `false`: 탭이 대화에서 Claude Code가 생성한 제목을 유지합니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "terminalTitleFromRename": false
}
```

Claude Code가 터미널 제목을 아예 업데이트하지 않도록 하려면 대신 [`CLAUDE_CODE_DISABLE_TERMINAL_TITLE`](https://code.claude.com/docs/ko/env-vars)를 `1`로 설정합니다.

### `theme`

인터페이스의 색상 테마를 선택합니다. `/config`에 **Theme**으로 표시됩니다.

* **범위**: [`Any file`](#scopes). 어떤 설정 파일도 이 키를 설정하지 않으면 이전 버전의 `~/.claude.json`에 있는 값이 적용됩니다.
* **유형**: 문자열, 다음 중 하나:
  * `"auto"`: 터미널의 밝은 배경 또는 어두운 배경에 맞춥니다
  * `"dark"`: 어두운 테마
  * `"light"`: 밝은 테마
  * `"dark-daltonized"`: 색각 이상자 친화적인 색상의 어두운 테마
  * `"light-daltonized"`: 색각 이상자 친화적인 색상의 밝은 테마
  * `"dark-ansi"`: 터미널의 ANSI 색상 팔레트만 사용하는 어두운 테마
  * `"light-ansi"`: 터미널의 ANSI 색상 팔레트만 사용하는 밝은 테마
  * `"custom:<slug>"` 또는 `"custom:<plugin-name>:<slug>"`: `~/.claude/themes/` 또는 플러그인의 사용자 지정 테마
* **기본값**: `"dark"`

```json settings.json theme={null}
{
  "theme": "light-daltonized"
}
```

[사용자 지정 테마 만들기](https://code.claude.com/docs/ko/terminal-config.md#create-a-custom-theme)를 참조하십시오.

### `timeFormat`

각 턴 소요 시간 메시지 끝의 `done 6:05 PM`이나 [트랜스크립트 뷰어](https://code.claude.com/docs/ko/interactive-mode.md#transcript-viewer)의 타임스탬프와 같이 Claude Code가 인터페이스에 표시하는 시간의 표기 방식을 선택합니다. 프리셋을 선택하려면 `/config`를 실행하고 **Time format**을 설정합니다. Claude Code v2.1.257 이상이 필요합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열, 다음 중 하나:
  * `"auto"`: 설정되지 않은 경우와 같으며, 각 시간은 기본 제공 형식을 유지합니다. 턴 소요 시간 메시지에서는 로캘을 따릅니다
  * `"12-hour"`: 12시간제
  * `"24-hour"`: 24시간제
  * `"24-hour-utc"`: `18:05Z`와 같이 분 뒤에 `Z`가 붙는 UTC 기준 24시간제. 이 프리셋에서는 Claude Code가 [`timeZone`](#timezone)을 무시합니다
  * `"%H:%M"`과 같은 strftime 패턴: Claude Code가 각 시간을 패턴으로 표기합니다. `%`가 포함된 값은 모두 패턴이며, 프리셋이 아닌 그 밖의 값은 `"auto"`로 간주됩니다
* **기본값**: `"auto"`

```json settings.json theme={null}
{
  "timeFormat": "24-hour"
}
```

`/config`는 프리셋만 제공하므로, strftime 패턴을 사용하려면 설정 파일에 키를 추가하십시오. 이 예시는 각 시간을 두 자리 24시간제로 표시합니다.

```json settings.json theme={null}
{
  "timeFormat": "%H:%M"
}
```

그러면 턴 소요 시간 메시지와 트랜스크립트 뷰어에 `18:05`와 같은 시간이 표시됩니다. 트랜스크립트 뷰어에서는 패턴이 타임스탬프 전체이므로, 날짜를 표시하려면 날짜 지시어를 추가하십시오. 이 예시는 시각 앞에 날짜를 넣습니다.

```json settings.json theme={null}
{
  "timeFormat": "%Y-%m-%d %H:%M"
}
```

그러면 같은 위치에 `2026-09-01 18:05`와 같은 시간이 표시됩니다.

### `timeZone`

인터페이스의 시간을 시스템과 다른 시간대로 표시합니다. `"UTC"` 또는 `"Europe/Dublin"`과 같은 [IANA 시간대 이름](https://www.iana.org/time-zones)으로 설정합니다. 그러면 [`timeFormat`](#timeformat)이 제어하는 시간이 이 시간대로 표시됩니다. `timeFormat`이 `"24-hour-utc"`이면 시간은 UTC로 유지되며 Claude Code는 이 키를 무시합니다. `/config`에는 이 키에 대한 행이 없으므로 설정 파일에서 설정하십시오. Claude Code v2.1.257 이상이 필요합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열, IANA 시간대 이름. Claude Code가 이름을 인식하지 못하면 시스템 시간대를 사용합니다
* **기본값**: 설정되지 않음, 따라서 시간이 시스템 시간대로 표시됩니다

```json settings.json theme={null}
{
  "timeZone": "Europe/Dublin"
}
```

### `tui`

터미널 UI 렌더러를 선택합니다. 가상화된 스크롤백을 갖춘 깜박임 없는 [대체 화면 렌더러](https://code.claude.com/docs/ko/fullscreen.md)에는 `"fullscreen"`을, 클래식 메인 화면 렌더러에는 `"default"`를 사용합니다. `/tui fullscreen` 또는 `/tui default`를 실행하면 이 키가 자동으로 기록됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열, 다음 중 하나:
  * `"default"`: 클래식 메인 화면 렌더러
  * `"fullscreen"`: 가상화된 스크롤백을 갖춘 깜박임 없는 대체 화면 렌더러
* **기본값**: 설정되지 않음, 따라서 Claude Code가 [렌더러를 자동으로 선택합니다](https://code.claude.com/docs/ko/fullscreen.md#fullscreen-by-default)
* **세션별 재정의**: [`CLAUDE_CODE_NO_FLICKER`](https://code.claude.com/docs/ko/env-vars)와 [`CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN`](https://code.claude.com/docs/ko/env-vars)이 한 세션 동안 이 키보다 우선합니다. `CLAUDE_CODE_NO_FLICKER=1`은 전체 화면을 켜고, `CLAUDE_CODE_NO_FLICKER=0` 또는 `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`은 끕니다. 둘 다 설정된 경우 Claude Code는 전체 화면을 끕니다

```json settings.json theme={null}
{
  "tui": "fullscreen"
}
```

tmux `-CC`에서 또는 Windows로의 SSH 연결에서는 `CLAUDE_CODE_NO_FLICKER=1`을 설정하지 않는 한 Claude Code가 클래식 렌더러를 유지합니다. [에이전트 뷰](https://code.claude.com/docs/ko/agent-view.md)에서 연 백그라운드 세션은 이 설정과 관계없이 항상 전체 화면 렌더러를 사용합니다.

### `verbose`

기본적으로 트랜스크립트는 각 도구 호출을 Claude가 실행한 명령과 출력의 줄 수 같은 짧은 요약으로 접으며, 세부 정보를 보려면 `Ctrl+O`를 눌러 트랜스크립트 전체를 확장 보기로 전환합니다. 이 키를 `true`로 설정하면 모든 도구 호출의 전체 입력과 출력이 발생하는 즉시 인라인으로 표시되며, 훅, MCP 서버, 또는 긴 셸 명령을 디버깅할 때 유용합니다. `/config`에 **Verbose output**으로 표시됩니다.

* **범위**: [`Any file`](#scopes). 어떤 설정 파일도 이 키를 설정하지 않으면 이전 버전의 `~/.claude.json`에 있는 값이 적용됩니다.
* **유형**: Boolean
  * `true`: 전체 도구 출력이 표시됩니다
  * `false`: 도구 출력의 잘린 요약이 표시됩니다
* **기본값**: `false`
* **세션별 재정의**: [`--verbose`](https://code.claude.com/docs/ko/cli-reference#cli-flags)가 한 세션 동안 이 키보다 우선합니다

```json settings.json theme={null}
{
  "verbose": true
}
```

[`viewMode`](#viewmode) 값이나 유지되는 `/focus` 선택은 모든 세션에서 이 키를 재정의합니다.

### `viewMode`

Claude Code가 시작할 때의 트랜스크립트 보기를 `"default"`, `"verbose"`, `"focus"` 중에서 설정합니다. 설정하면 유지되는 `/focus` 선택과 [`verbose`](#verbose) 설정을 모두 재정의합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열, 다음 중 하나:
  * `"default"`: 도구 출력이 잘린 일반 트랜스크립트
  * `"verbose"`: 전체 도구 출력이 포함된 트랜스크립트
  * `"focus"`: 마지막 프롬프트, 편집 diffstat이 포함된 도구 호출의 한 줄 요약, 최종 응답만 표시합니다. 포커스 보기에는 [전체 화면 렌더러](#tui)가 필요합니다
* **기본값**: 설정되지 않음, 따라서 `verbose` 설정과 마지막 `/focus` 선택이 적용됩니다
* **세션별 재정의**: [`--verbose`](https://code.claude.com/docs/ko/cli-reference#cli-flags)가 한 세션 동안 이 키보다 우선합니다

```json settings.json theme={null}
{
  "viewMode": "focus"
}
```

### `vimInsertModeRemaps`

[vim 편집기 모드](https://code.claude.com/docs/ko/interactive-mode.md#vim-editor-mode)에서 두 키로 된 INSERT 모드 시퀀스를 Escape에 매핑합니다. 각 키는 순서대로 입력하는 정확히 두 개의 인쇄 가능한 문자이며, 지원되는 대상은 `"<Esc>"`뿐입니다. Claude Code는 다른 항목을 무시합니다.

* **범위**: [`User or managed`](#scopes). 저장소는 사용자의 키 입력을 다시 매핑할 수 없습니다.
* **유형**: 두 문자 시퀀스를 `"<Esc>"`에 매핑하는 객체
* **기본값**: 설정되지 않음

```json settings.json theme={null}
{
  "vimInsertModeRemaps": {
    "jj": "<Esc>"
  }
}
```

`editorMode`가 `"vim"`이 아니면 효과가 없습니다. [INSERT 모드 키 시퀀스 다시 매핑](https://code.claude.com/docs/ko/interactive-mode.md#remap-insert-mode-key-sequences)을 참조하십시오.

### `voice`

[음성 받아쓰기](https://code.claude.com/docs/ko/voice-dictation.md)를 켜고 받아쓰기 키의 동작 방식을 선택합니다. `/voice`를 실행하면 Claude Code가 이 객체를 자동으로 기록합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean인 `enabled`, 홀드 모드에서만 적용되는 Boolean인 `autoSubmit`, 그리고 다음 중 하나인 `mode`가 있는 객체:
  * `"hold"`: 말하는 동안 받아쓰기 키를 누르고 있다가 떼면 중지됩니다
  * `"tap"`: 키를 한 번 눌러 녹음을 시작하고 다시 눌러 전송합니다
* **기본값**: 설정되지 않음, 따라서 받아쓰기가 꺼져 있습니다. `enabled`가 `true`이고 `mode`가 설정되지 않은 경우 Claude Code는 `"hold"`를 사용합니다

이 예시는 받아쓰기를 켜고, 키를 한 번 눌러 녹음을 시작하고 다시 눌러 전송하도록 합니다.

```json settings.json theme={null}
{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}
```

`autoSubmit`은 홀드 모드에서 키를 뗄 때 프롬프트를 전송합니다. 음성 받아쓰기에는 claude.ai 계정이 필요합니다.

### `voiceEnabled`

> [!WARNING]
>
> v2.1.92에서 [`voice`](#voice) 객체로 대체되면서 deprecated되었습니다. 이전 설정 파일이 계속 작동하도록 Claude Code가 여전히 이 키를 읽지만, 새 구성에서는 `voice.enabled`를 설정해야 합니다.

`voice` 객체 이전에 사용되던 단일 Boolean 형식으로 음성 받아쓰기를 켭니다. 둘 다 설정된 경우 `voice.enabled`가 적용됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: `voice.enabled`가 설정되지 않은 한, claude.ai 계정으로 로그인되어 있고 조직의 정책이 음성을 허용하면 음성 받아쓰기가 켜집니다
  * `false`: `voice.enabled`가 설정되지 않은 한 음성 받아쓰기가 꺼집니다
* **기본값**: 설정되지 않음

```json settings.json theme={null}
{
  "voiceEnabled": true
}
```

### `wheelScrollAccelerationEnabled`

[전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md#mouse-wheel-scrolling)에서 빠르게 스크롤할 때 마우스 휠 스크롤 속도를 가속합니다. 휠 한 칸당 일정한 스크롤 속도를 원하면 `false`로 설정합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 빠르게 스크롤할 때 마우스 휠 스크롤 속도를 가속합니다
  * `false`: Claude Code가 휠 한 칸당 일정한 속도로 스크롤합니다
* **기본값**: `true`

```json settings.json theme={null}
{
  "wheelScrollAccelerationEnabled": false
}
```

## Git 및 속성

Claude Code가 커밋 및 풀 요청에 추가하는 속성을 제어하고 git과 어떻게 작동하는지 관리합니다.

### `attribution`

Claude Code가 git 커밋 및 풀 요청에 추가하는 속성을 사용자 정의합니다. 커밋은 기본적으로 `Co-Authored-By`와 같은 [git 트레일러](https://git-scm.com/docs/git-interpret-trailers)를 받습니다. 풀 요청 설명은 일반 텍스트를 받습니다. 아래의 하위 키를 사용하여 각 부분을 별도로 설정합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: `commit` 및 `pr` 문자열과 `sessionUrl` 부울을 포함하는 객체, 또는 모든 속성을 숨기려면 `false`. `false` 값은 Claude Code v2.1.281 이상이 필요합니다. 이전 버전은 이를 거부하고 [이를 포함하는 전체 사용자, 프로젝트 또는 로컬 설정 파일을 건너뜁니다](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file).
* **기본값**: 설정되지 않음. 따라서 Claude Code는 각 하위 키 아래에 표시된 표준 속성을 사용합니다.

모든 속성을 숨기려면 `attribution`을 `false`로 설정합니다. 이전 버전도 읽는 설정 파일에서는 [`commit`](#attribution-commit) 및 [`pr`](#attribution-pr)을 빈 문자열로 설정하고 [`sessionUrl`](#attribution-sessionurl)을 `false`로 설정합니다.

이 예제는 커밋 속성을 바꾸고, 풀 요청 속성을 제거하며, 세션 링크를 삭제합니다:

```json settings.json theme={null}
{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": "",
    "sessionUrl": false
  }
}
```

`commit` 또는 `pr`을 설정하면 Claude Code는 더 이상 사용되지 않는 `includeCoAuthoredBy` 설정을 무시하고 설정하지 않은 두 항목에 대해 기본 텍스트를 사용합니다.

Claude Code는 Claude에게 속성에 대한 사용자 정의 지침(예: CLAUDE.md 또는 [메모리](https://code.claude.com/docs/ko/memory.md) 규칙)이 이러한 커밋 및 PR 라인보다 우선한다고 알립니다. 단, 라인이 [관리되는 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 설정된 경우는 제외합니다.

### `includeCoAuthoredBy`

> [!WARNING]
>
> v2.0.62 이후 더 이상 사용되지 않음. [`attribution`](#attribution)이 이를 대체했습니다. Claude Code는 여전히 이를 읽지만, 새로운 구성은 `attribution`을 설정해야 합니다.

이 키를 대체하는 [`attribution`](#attribution)을 대신 사용하십시오. 이를 통해 커밋 트레일러, 풀 요청 텍스트 및 세션 링크를 별도로 변경하거나 숨길 수 있습니다. Claude Code는 여전히 `attribution`이 존재하기 이전의 설정 파일에서 `includeCoAuthoredBy: false`를 준수하지만, `attribution.commit` 또는 `attribution.pr`을 설정하면 이를 무시합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: 설정되지 않은 것과 동일합니다. Claude Code는 커밋 트레일러 및 풀 요청 속성 텍스트를 추가합니다.
  * `false`: Claude Code는 커밋 트레일러 및 풀 요청 속성 텍스트를 모두 생략합니다. 단, `attribution`이 `commit` 또는 `pr`을 설정하는 경우 [`attribution`](#attribution) 규칙이 적용됩니다.
* **기본값**: `true`

```json settings.json theme={null}
{
  "includeCoAuthoredBy": false
}
```

모든 속성을 숨기려면 [`attribution`](#attribution)을 참조하십시오.

### `includeGitInstructions`

Claude Code는 Claude에게 두 가지 git 관련 컨텍스트를 제공합니다. Bash 도구의 설명에 있는 커밋 및 풀 요청 작성 방법에 대한 기본 제공 지침과 저장소의 git 상태 스냅샷입니다. 스냅샷은 현재 분기, 주 분기, `git status` 출력 및 최근 커밋을 포함합니다. Claude Code는 대화가 시작될 때 이를 읽습니다.

예를 들어 자신의 git 워크플로우 스킬을 사용할 때 이 키를 `false`로 설정하여 둘 다 제외합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: Claude Code는 기본 제공 커밋 및 풀 요청 워크플로우 지침과 git 상태 스냅샷을 포함합니다. 클라우드 세션은 스냅샷을 포함하지 않습니다.
  * `false`: Claude Code는 둘 다 제외합니다.
* **기본값**: `true`
* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS`](https://code.claude.com/docs/ko/env-vars)는 한 세션에 대해 이 키보다 우선합니다.

```json settings.json theme={null}
{
  "includeGitInstructions": false
}
```

[비대화형 모드](https://code.claude.com/docs/ko/headless.md) 또는 Agent SDK에서 시스템 프롬프트를 대체하면 이 키가 `true`인 경우에도 세션이 스냅샷 없이 시작됩니다:

* **`-p` 실행**: [`--system-prompt`](https://code.claude.com/docs/ko/cli-reference#system-prompt-flags) 또는 `--system-prompt-file`을 전달하면 프롬프트가 대체됩니다. [`--agent`](https://code.claude.com/docs/ko/sub-agents#invoke-subagents-explicitly) 또는 [`agent`](#agent) 설정으로 선택한, 자체 프롬프트가 있는 사용자 정의 에이전트를 실행하는 경우에도 프롬프트가 대체됩니다. [bare 모드](https://code.claude.com/docs/ko/headless.md#start-faster-with-bare-mode) 외부에서 스냅샷을 유지하려면 사용자 정의 에이전트 없이 실행하고, 프롬프트를 대체하는 대신 [`--append-system-prompt`](https://code.claude.com/docs/ko/cli-reference#system-prompt-flags)로 지침을 추가합니다.
* **[Agent SDK](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md)**: 사용자 정의 시스템 프롬프트 또는 사용자 정의 메인 스레드 에이전트를 사용하면 프롬프트가 대체됩니다. 시스템 프롬프트를 설정하지 않으면 SDK는 최소 기본값을 사용하며, 이 경우에도 세션이 스냅샷 없이 시작됩니다. [bare 모드](https://code.claude.com/docs/ko/headless.md#start-faster-with-bare-mode) 외부에서 스냅샷을 유지하려면 사용자 정의 `agent` 없이 `claude_code` 프리셋을 사용합니다.

### `prUrlTemplate`

Claude Code가 렌더링하는 PR 링크(바닥글 배지 및 도구 결과 요약)를 `github.com` 대신 내부 코드 검토 도구로 지정합니다. Claude Code는 PR URL에서 `{host}`, `{owner}`, `{repo}`, `{number}` 및 `{url}`을 대체합니다. [GitLab 병합 요청](https://code.claude.com/docs/ko/interactive-mode.md#gitlab-merge-requests) 링크는 두 표면 모두에서 GitLab URL을 유지합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열, 5개의 자리 표시자 중 하나를 사용하는 URL 템플릿
* **기본값**: 설정되지 않음

```json settings.json theme={null}
{
  "prUrlTemplate": "https://reviews.example.com/{owner}/{repo}/pull/{number}"
}
```

Claude Code는 자신이 직접 렌더링하는 링크에만 템플릿을 적용합니다. Claude가 메시지에 작성한 PR 번호(예: `#123`)는 Claude가 작성한 대로 유지됩니다. `/pull/<number>` 형태가 아닌 URL은 변경되지 않습니다.

### `attribution.commit`

Claude Code가 git 커밋에 추가하는 속성 텍스트(모든 트레일러 포함)를 설정합니다. 커밋 속성을 숨기려면 빈 문자열로 설정합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열
* **기본값**: 설정되지 않음. 따라서 Claude Code는 `Co-Authored-By: <name> <noreply@anthropic.com>`을 추가합니다. 이름은 `Claude Sonnet 5`와 같은 커밋이 만들어질 때 사용 중인 모델입니다. [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)가 커밋을 만들 때 트레일러는 서브에이전트의 모델을 이름으로 지정합니다.
  * Claude Code가 모델을 Claude 모델로 인식하지만 정확한 버전을 확인할 수 없는 경우 `Claude`만 작성합니다.
  * 모델 ID를 Claude 모델과 일치시킬 수 없는 경우(예: 사용자 정의 [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/env-vars)을 통해 제공되는 타사 모델) `Claude Code`를 작성합니다.

이 예제는 기본 트레일러를 사용자 정의 라인 및 사용자 정의 `Co-Authored-By` 트레일러로 바꿉니다:

```json settings.json theme={null}
{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>"
  }
}
```

### `attribution.pr`

Claude Code가 풀 요청 설명에 추가하는 속성 텍스트를 설정합니다. 풀 요청 속성을 숨기려면 빈 문자열로 설정합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열
* **기본값**: 설정되지 않음. 따라서 Claude Code는 `🤖 Generated with [Claude Code](https://claude.com/claude-code)`를 추가합니다.

```json settings.json theme={null}
{
  "attribution": {
    "pr": ""
  }
}
```

### `attribution.sessionUrl`

Claude Code가 [클라우드](https://code.claude.com/docs/ko/claude-code-on-the-web.md) 또는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 세션에서 커밋하거나 풀 요청을 열 때 claude.ai 세션 링크를 추가할지 여부를 선택합니다. Claude Code는 커밋에 `Claude-Session` 트레일러로 링크를 추가하고 풀 요청 설명에 링크로 추가합니다. 링크를 생략하려면 `false`로 설정합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: Claude Code는 클라우드 또는 Remote Control 세션에서 커밋하거나 풀 요청을 열 때 claude.ai 세션 링크를 추가합니다.
  * `false`: Claude Code는 링크를 생략합니다.
* **기본값**: `true`

```json settings.json theme={null}
{
  "attribution": {
    "sessionUrl": false
  }
}
```

## 훅과 자동화

훅을 등록하고, 실행할 훅을 제한하며, 워크플로를 제어합니다. 훅 이벤트 및 페이로드는 [훅 참조](https://code.claude.com/docs/ko/hooks.md)를 참조하십시오.

### `allowedHttpHookUrls`

[HTTP 훅](https://code.claude.com/docs/ko/hooks.md#http-hook-fields)이 대상으로 할 수 있는 URL을 제한합니다. 이 키를 정의하면 Claude Code는 URL이 패턴 중 하나와 일치하는 경우에만 HTTP 훅을 실행하고 나머지는 실행하지 않고 차단합니다. 빈 배열은 모든 HTTP 훅을 차단합니다.

* **범위**: [`모든 파일`](#scopes). 배열은 설정 파일 전체에서 병합됩니다.
* **유형**: URL 패턴 배열, `*`를 와일드카드로 사용
* **기본값**: 설정되지 않음, 따라서 모든 URL이 허용됨

이 예제는 `https://hooks.example.com/` 아래의 모든 URL과 모든 `http://localhost` URL을 허용합니다:

```json settings.json theme={null}
{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}
```

호스트명 일치는 대소문자를 구분하지 않으며 정규화된 도메인 이름을 표시하는 후행 점이 있는 `hooks.example.com.`을 DNS가 처리하는 방식과 동일하게 `hooks.example.com`으로 취급합니다. 허용 목록은 관리형 설정을 포함한 모든 소스의 훅에 적용됩니다.

Agent SDK의 `managedSettings` 옵션에서는 목록에 항목이 있으면 Claude Code가 이 키를 무시하므로, 대신 SDK의 [`settings` 옵션](https://code.claude.com/docs/ko/agent-sdk/typescript#options)에 목록을 전달하십시오. [상위 설정에서 빈 목록이 수행하는 작업](https://code.claude.com/docs/ko/claude-apps-gateway#how-hook-and-skill-keys-in-parent-settings-take-effect)을 참조하십시오.

### `allowManagedHooksOnly`

훅 실행을 조직이 배포하는 훅으로 제한합니다.

* **범위**: [`관리됨`](#scopes)
* **유형**: 부울
  * `true`: 관리형 훅만 실행되며, Agent SDK 훅 및 관리형 설정이 강제로 활성화하는 플러그인의 훅도 실행됩니다. [`allowManagedHooksOnly`에서 실행되는 항목](#what-runs-under-allowmanagedhooksonly)을 참조하십시오.
  * `false`: 모든 설정 범위 및 플러그인의 훅이 실행됨
* **기본값**: 설정되지 않음, 따라서 모든 설정 범위 및 플러그인의 훅이 실행됨

```json managed-settings.json theme={null}
{
  "allowManagedHooksOnly": true
}
```

#### `allowManagedHooksOnly`에서 실행되는 항목

이를 `true`로 설정하면 Claude Code는 로드되는 훅 및 훅과 유사한 명령을 변경합니다:

* **관리형 훅 및 SDK 훅 실행**: 관리형 설정의 훅 및 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)가 프로세스에 등록하는 훅
* **강제 활성화된 플러그인 훅 실행**: 관리형 설정이 [`enabledPlugins`](#enabledplugins)를 통해 강제로 활성화하는 플러그인의 훅. Claude Code는 전체 `plugin@marketplace` ID와 일치하므로 다른 마켓플레이스의 동일한 이름의 플러그인은 차단된 상태로 유지됩니다. 이를 통해 조직 마켓플레이스를 통해 검증된 훅을 배포하면서 다른 모든 것을 차단할 수 있습니다. 이러한 플러그인의 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)는 [조직의 것으로 계산될 때](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods)만 로드됩니다.
* **다른 플러그인의 모니터 차단**: 플러그인이 강제로 활성화되지 않는 한 플러그인의 [모니터](https://code.claude.com/docs/ko/plugins/components.md#monitors)는 시작되지 않습니다. Claude Code v2.1.310 이상이 필요합니다.
* **다른 모든 것은 차단됨**: 사용자, 프로젝트 및 로컬 훅, 다른 설치된 플러그인의 훅 및 mod, 에이전트 frontmatter에 선언된 훅. [Claude Code에 내장된 mod](https://code.claude.com/docs/ko/plugins/mods/overview.md#mods-built-into-claude-code)는 계속 실행됩니다. 사용자의 mod만 차단하려면 [`allowManagedModsOnly`](https://code.claude.com/docs/ko/plugins/mods/admin#set-options-on-the-built-in-guard)를 대신 설정합니다.
* **명령 소스 플러그인 비활성화**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)를 명시적으로 `false`로 설정하지 않는 한 [`command` 소스](https://code.claude.com/docs/ko/plugins/marketplace-reference#command-plugin-source)가 있는 플러그인(관리형 `enabledPlugins`에서 강제로 활성화된 플러그인 포함)을 비활성화합니다.
* **마켓플레이스 `headersHelper` 명령 차단**: Claude Code는 또한 [`disableCommandPluginSources`](#disablecommandpluginsources)가 명시적으로 `false`로 설정되지 않는 한 마켓플레이스 [`headersHelper` 명령](https://code.claude.com/docs/ko/plugins/host-marketplace#authenticate-archive-downloads)을 차단합니다. 단, 관리형 설정 자체가 선언하는 마켓플레이스는 제외됩니다. Claude Code v2.1.238 이상이 필요합니다.
* **상태줄 및 파일 제안이 관리형 설정으로 좁혀짐**: Claude Code는 [상태줄 및 파일 제안 게이트](#status-line-and-file-suggestion-gates)를 따르면서 관리형 설정에서만 [`statusLine`](https://code.claude.com/docs/ko/statusline), [`fileSuggestion`](#filesuggestion), [`subagentStatusLine`](https://code.claude.com/docs/ko/statusline#subagent-status-lines)을 읽습니다.

[`/goal`](https://code.claude.com/docs/ko/goal) 명령은 이 키가 설정된 동안 실행할 수 없습니다. 훅에 따라 달라지기 때문입니다.

### `disableAllHooks`

[훅](https://code.claude.com/docs/ko/hooks.md#disable-or-remove-hooks), 모든 사용자 정의 [상태줄](https://code.claude.com/docs/ko/statusline.md), 모든 사용자 정의 [파일 제안](#filesuggestion) 명령을 끕니다. 설정에서 삭제하지 않고 이 모든 것을 일시적으로 끄는 데 사용합니다.

* **범위**: [`모든 파일`](#scopes). 관리형 설정만 관리형 훅을 비활성화할 수 있습니다.
* **유형**: 부울
  * `true`: Claude Code는 훅, 모든 사용자 정의 상태줄, 모든 사용자 정의 파일 제안 명령을 끕니다.
  * `false`: 훅, 상태줄, 파일 제안 명령이 실행됨
* **기본값**: 설정되지 않음, 따라서 훅이 실행됨

```json settings.json theme={null}
{
  "disableAllHooks": true
}
```

범위는 키를 포함하는 파일에 따라 달라집니다:

* **관리형 설정에서**: Claude Code는 관리형 훅을 포함한 모든 구성된 훅을 비활성화하고 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)가 프로세스에 등록하는 훅을 계속 실행합니다.
* **Agent SDK의 `managedSettings` 옵션에서**: 관리자가 관리형 설정을 배포하는 머신에서는 관리자가 [임베딩 호스트가 정책을 추가하도록 허용](https://code.claude.com/docs/ko/managed-settings.md#let-an-embedding-host-add-policy)하지 않는 한 Claude Code가 이 키를 무시합니다. 키가 적용되는 경우 사용자, 프로젝트, 로컬 및 플러그인 훅이 중지되며, SDK의 `settings` 옵션에 있는 훅도 중지됩니다. 관리자의 관리형 훅, [강제 활성화된](#enabledplugins) 플러그인의 훅, [SDK 훅 콜백](https://code.claude.com/docs/ko/agent-sdk/hooks.md)은 계속 실행됩니다. Claude Code v2.1.309 이상이 필요합니다.
* **다른 설정 파일에서**: Claude Code는 사용자, 프로젝트, 로컬 및 플러그인 훅을 비활성화합니다. 관리형 훅, Agent SDK 훅, 관리형 [`enabledPlugins`](#enabledplugins)에서 강제로 활성화된 플러그인의 훅은 계속 실행됩니다.

이 키는 코드가 훅을 등록하는 플러그인인 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)도 중지합니다:

* **관리형 설정에서**: 조직의 mod를 포함하여 설치된 모든 플러그인의 mod가 중지됩니다.
* **다른 설정 파일에서**: 사용자가 설치한 mod는 중지되고, [조직의 mod](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods)는 계속 실행됩니다.

Claude Code에 내장된 mod는 두 경우 모두 계속 실행됩니다. 각 mod에는 [자체 스위치](https://code.claude.com/docs/ko/plugins/mods/overview.md#mods-built-into-claude-code)가 있습니다.

관리형 설정이 이 키를 설정할 때 Agent SDK 훅을 실행 상태로 유지하려면 Claude Code v2.1.242 이상이 필요합니다.

[`/goal`](https://code.claude.com/docs/ko/goal) 명령은 훅이 비활성화된 동안 실행할 수 없으며, `/hooks` 메뉴는 훅 대신 공지를 표시합니다.

#### 상태줄 및 파일 제안 게이트

Claude Code는 `statusLine`, `fileSuggestion`, `subagentStatusLine`에 대해 다음 순서로 두 가지 결정을 내립니다:

* **완전히 끔**: 관리형 설정이 `disableAllHooks`를 설정하거나, 폴더가 [설정 파일의 훅과 동일한 워크스페이스 신뢰 규칙](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder) 아래에서 신뢰되지 않을 때
* **관리형 설정으로 좁혀짐**: [`allowManagedHooksOnly`](#allowmanagedhooksonly)가 설정되었을 때, `disableAllHooks`가 [설정 우선순위](https://code.claude.com/docs/ko/hooks.md#disable-or-remove-hooks)가 적용된 후 관리형 설정 외부에서 `true`일 때, 또는 `--safe-mode`로 Claude Code를 시작할 때

좁혀짐 상태에서 Claude Code는 배포된 관리형 값이 있으면 실행합니다. 그렇지 않으면 경고 없이 값을 건너뜁니다: 상태줄이 비활성화되고 `@` 자동 완성은 기본 제공 파일 제안으로 돌아갑니다.

### `disableWorkflows`

[동적 워크플로](https://code.claude.com/docs/ko/workflows.md#turn-workflows-off)와 관리형 설정을 통한 조직과 같이 설정이 도달하는 모든 사람을 위한 번들 워크플로 명령을 끕니다. 자신을 위해서만 워크플로를 켜거나 끄려면 [`enableWorkflows`](#enableworkflows)를 대신 사용하십시오. `/config`의 **동적 워크플로** 토글이 사용자 설정에 기록합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: Claude Code는 설정이 도달하는 모든 사람을 위해 동적 워크플로와 번들 워크플로 명령을 끕니다.
  * `false`: 설정되지 않은 것과 동일합니다. 워크플로가 켜져 있는지 여부는 [`enableWorkflows`](#enableworkflows)와 계획의 기본값을 따릅니다.
* **기본값**: `false`
* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](https://code.claude.com/docs/ko/env-vars)는 한 세션 동안 워크플로를 끕니다. 둘 중 하나가 워크플로를 끄면 다른 하나는 다시 켤 수 없습니다.

```json settings.json theme={null}
{
  "disableWorkflows": true
}
```

### `enableWorkflows`

계획의 기본값이 원하는 것이 아닐 때 자신을 위해 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md)를 켜거나 끕니다. `/config`에 **동적 워크플로**로 나타나며, 이는 이 키를 사용자 설정에 기록하고 계획의 기본값으로 다시 토글할 때 제거합니다. 관리형 설정에서 모든 사람을 위해 워크플로를 끄려면 [`disableWorkflows`](#disableworkflows)를 대신 사용하십시오.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: Claude Code는 자신을 위해 동적 워크플로를 켭니다.
  * `false`: Claude Code는 자신을 위해 동적 워크플로를 끕니다.
* **기본값**: 설정되지 않음, 따라서 워크플로는 켜져 있습니다. Pro 계획에서는 꺼져 있습니다.
* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_WORKFLOWS`](https://code.claude.com/docs/ko/env-vars)는 한 세션 동안 워크플로를 끕니다. `true`는 설정된 동안 워크플로를 다시 켤 수 없습니다.

```json settings.json theme={null}
{
  "enableWorkflows": true
}
```

[`disableWorkflows`](#disableworkflows)와 조직의 워크플로 정책도 우선순위를 가집니다: `enableWorkflows: true`는 어떤 소스가 워크플로를 끄는 동안 워크플로를 다시 켤 수 없습니다. Claude Code는 사용자 설정 이외의 소스가 `enableWorkflows`를 설정하거나 `disableWorkflows`를 `true`로 설정하는 동안 `/config` 행을 숨깁니다.

### `hooks`

Claude Code의 수명 주기의 특정 지점(예: 도구 호출 전 또는 세션 시작 시)에서 [훅](https://code.claude.com/docs/ko/hooks.md)으로 자신의 명령, 프롬프트, 에이전트, HTTP 요청 또는 MCP 도구를 실행합니다. [훅 참조](https://code.claude.com/docs/ko/hooks.md#hook-events)는 모든 이벤트, 페이로드 및 종료 코드를 나열합니다. 각 이벤트는 매처 그룹 목록에 매핑되고, 각 그룹은 매처가 적용될 때 실행할 핸들러를 나열합니다.

* **범위**: [`모든 파일`](#scopes). 훅은 서로 대체하지 않고 파일 전체에서 병합되며, 관리형 설정의 훅은 다른 파일에서 제거할 수 없습니다.
* **유형**: [훅 이벤트](https://code.claude.com/docs/ko/hooks.md#hook-events)로 키가 지정된 객체. 각 값은 `"command"`, `"prompt"`, `"agent"`, `"http"` 또는 `"mcp_tool"`의 `type`을 가진 `hooks` 항목이 있는 `{ "matcher", "hooks" }` 그룹의 배열입니다.
* **기본값**: 설정되지 않음, 따라서 훅이 실행되지 않음

이 예제는 모든 Bash 도구 호출 전에 스크립트를 실행합니다:

```json settings.json theme={null}
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/check-bash.sh" }
        ]
      }
    ]
  }
}
```

모든 이벤트, 매처 패턴 및 핸들러 필드는 [훅 참조](https://code.claude.com/docs/ko/hooks.md#configuration)를 참조하십시오. 훅을 끄려면 [`disableAllHooks`](#disableallhooks)를 참조하십시오. 훅을 조직이 배포하는 것으로 제한하려면 [`allowManagedHooksOnly`](#allowmanagedhooksonly)를 참조하십시오.

### `httpHookAllowedEnvVars`

[HTTP 훅](https://code.claude.com/docs/ko/hooks.md#http-hook-fields)은 환경 변수의 값을 요청 헤더(예: `Authorization: Bearer $HOOK_TOKEN` 헤더)에 넣을 수 있지만, 훅이 자신의 `allowedEnvVars`에 나열하는 변수에만 해당됩니다. 이 키는 모든 HTTP 훅에 대해 해당 목록에 외부 제한을 설정합니다: 훅은 자신의 `allowedEnvVars`와 이 키 모두에서 이름을 지정한 경우에만 변수를 사용할 수 있습니다. 훅의 정의가 요청하더라도 훅이 읽으면 안 되는 비밀을 읽지 못하도록 하는 데 사용합니다.

* **범위**: [`모든 파일`](#scopes). 배열은 설정 파일 전체에서 병합됩니다.
* **유형**: 환경 변수 이름 배열
* **기본값**: 설정되지 않음, 따라서 각 훅의 자신의 `allowedEnvVars` 목록이 적용됨

이 예제는 헤더 보간을 `MY_TOKEN` 및 `HOOK_SECRET`으로 제한합니다:

```json settings.json theme={null}
{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}
```

허용 목록은 관리형 설정을 포함한 모든 소스의 훅에 적용됩니다.

Agent SDK의 `managedSettings` 옵션에서는 목록에 항목이 있으면 Claude Code가 이 키를 무시하므로, 대신 SDK의 [`settings` 옵션](https://code.claude.com/docs/ko/agent-sdk/typescript#options)에 목록을 전달하십시오. [상위 설정에서 빈 목록이 수행하는 작업](https://code.claude.com/docs/ko/claude-apps-gateway#how-hook-and-skill-keys-in-parent-settings-take-effect)을 참조하십시오.

### `workflowKeywordTriggerEnabled`

프롬프트에서 키워드 `ultracode`를 입력하면 [동적 워크플로](https://code.claude.com/docs/ko/workflows.md#ask-for-a-workflow-in-your-prompt)가 트리거되는지 선택합니다. 워크플로를 트리거하지 않고 이 단어를 입력하려면 `false`로 설정합니다.

* **범위**: [`모든 파일`](#scopes). `/config`에 **Ultracode 키워드 트리거**로 나타납니다.
* **유형**: 부울
  * `true`: 프롬프트에서 `ultracode`를 입력하면 동적 워크플로가 트리거됨
  * `false`: 워크플로를 트리거하지 않고 이 단어를 입력할 수 있음
* **기본값**: `true`

```json settings.json theme={null}
{
  "workflowKeywordTriggerEnabled": false
}
```

`ultracode` 노력 설정, `/workflows`, 저장된 워크플로 명령은 영향을 받지 않습니다.

### `workflowSizeGuideline`

작성하는 동적 워크플로에서 Claude가 목표로 하는 [에이전트 수](https://code.claude.com/docs/ko/workflows.md#set-a-size-guideline)를 설정합니다. Claude Code는 값을 Claude에 조언으로 보냅니다. 강제 상한이 아닙니다: `"small"`은 5개 미만의 에이전트를 요청하고, `"medium"`은 10개 미만, `"large"`는 50개 미만입니다. 워크플로가 소비하는 것을 제한하려면 `"small"`을 선택합니다. Claude Code v2.1.219 이상이 필요합니다.

* **범위**: [`모든 파일`](#scopes). 여기의 값은 `/config`의 **동적 워크플로 크기** 선택보다 우선순위를 가집니다. Claude Code는 이를 `~/.claude.json`에 저장하고, 설정 파일이 키를 설정하는 동안 해당 행을 숨깁니다.
* **유형**: 문자열, 다음 중 하나:
  * `"unrestricted"`: 지침 없음, 따라서 Claude는 워크플로를 작업에 맞게 크기 조정
  * `"small"`: Claude는 5개 미만의 에이전트를 목표로 함
  * `"medium"`: Claude는 10개 미만의 에이전트를 목표로 함
  * `"large"`: Claude는 50개 미만의 에이전트를 목표로 함
* **기본값**: `"medium"`, 또는 Claude Code v2.1.271 이상에서 Pro 계획에 로그인했을 때 `"small"`

```json settings.json theme={null}
{
  "workflowSizeGuideline": "small"
}
```

Claude Code v2.1.219 이상이 필요합니다. v2.1.202부터 v2.1.218까지는 대신 `/config`에서 지침을 설정합니다.

## 플러그인과 스킬

플러그인을 활성화하고, 마켓플레이스를 등록하고, 조직에서 허용하는 플러그인 소스를 제한하고, 로드할 스킬을 제어합니다. 플러그인 설치 및 빌드에 대해서는 [플러그인](https://code.claude.com/docs/ko/plugins/overview.md)을 참조하세요.

### `disableBundledSkills`

Claude Code에 포함된 [스킬](https://code.claude.com/docs/ko/skills.md)과 워크플로를 끕니다. Claude Code는 번들 스킬과 워크플로를 완전히 제거하며, `/init` 같은 기본 제공 명령은 계속 입력할 수 있지만 모델에는 숨겨집니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 번들 스킬과 워크플로를 제거하고 `/init` 같은 기본 제공 명령을 모델에서 숨깁니다
  * `false`: 번들 스킬이 로드됩니다
* **기본값**: 설정되지 않음. 따라서 번들 스킬이 로드됩니다
* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_BUNDLED_SKILLS`](https://code.claude.com/docs/ko/env-vars)를 `1`로 설정하면 한 세션 동안 번들 스킬이 꺼집니다. 둘 중 어느 쪽이 번들 스킬을 끄든, 다른 쪽으로 다시 켤 수는 없습니다

```json settings.json theme={null}
{
  "disableBundledSkills": true
}
```

플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. `/doctor`는 기본 제공 명령과 마찬가지로 계속 입력할 수 있습니다. 이를 숨기려면 대신 [`DISABLE_DOCTOR_COMMAND`](https://code.claude.com/docs/ko/env-vars)를 설정하세요.

### `disableSkillShellExecution`

사용자, 프로젝트, 플러그인 또는 추가 디렉터리 소스의 [스킬](https://code.claude.com/docs/ko/skills.md)과 사용자 지정 명령에서 `` !`...` `` 및 ` ```! ` 블록의 인라인 셸 실행을 끕니다. Claude Code는 각 명령을 실행하는 대신 `[shell command execution disabled by policy]`로 대체합니다.

* **범위**: [`모든 파일`](#scopes). 관리형 설정의 `true`는 다른 곳의 `false`로 재정의할 수 없습니다.
* **유형**: Boolean
  * `true`: Claude Code가 각 인라인 셸 명령을 실행하는 대신 `[shell command execution disabled by policy]`로 대체합니다
  * `false`: 인라인 셸이 실행됩니다
* **기본값**: 설정되지 않음. 따라서 인라인 셸이 실행됩니다

```json settings.json theme={null}
{
  "disableSkillShellExecution": true
}
```

번들 스킬과 관리형 설정을 통해 배포된 스킬은 영향을 받지 않습니다.

### `skillOverrides`

`SKILL.md`를 편집하지 않고 [스킬](https://code.claude.com/docs/ko/skills.md#override-skill-visibility-from-settings)을 숨기거나 축소합니다. Claude Code는 각 스킬 이름 아래의 값을 Claude가 보는 스킬 목록과 사용자의 `/` 자동 완성에 적용합니다.

* **범위**: [`모든 파일`](#scopes). `/skills` 메뉴는 `.claude/settings.local.json`에 기록합니다.
* **유형**: 스킬 이름을 다음 중 하나에 매핑하는 객체:
  * `"on"`: Claude가 스킬을 보고 사용자가 `/name`을 입력할 수 있습니다
  * `"name-only"`: Claude가 설명 없이 이름으로만 스킬을 봅니다
  * `"user-invocable-only"`: Claude는 스킬을 보지 못하지만 사용자는 여전히 `/name`을 입력할 수 있습니다
  * `"off"`: Claude가 스킬을 보지 못하고 `/name`이 자동 완성에서 숨겨집니다
* **기본값**: 설정되지 않음. 따라서 모든 스킬이 `"on"`입니다

다음 예시는 `legacy-context`를 Claude에게 이름으로만 표시하고 `deploy`를 Claude와 `/` 자동 완성에서 숨깁니다.

```json settings.json theme={null}
{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}
```

재정의는 플러그인 스킬에는 적용되지 않으며, 플러그인 스킬은 `/plugin`을 통해 관리합니다.

관리형 설정과 `--settings`로 전달된 파일에서는 번들 스킬의 별칭(예: `/doctor`의 `checkup`)에 대한 키도 해당 스킬에 적용됩니다. [별칭 키가 스킬 자체 이름의 키와 결합되는 방식](https://code.claude.com/docs/ko/skills.md#override-skill-visibility-from-settings)을 참조하세요.

### `syncClaudeAiSkills`

[claude.ai 계정에 활성화된 스킬](https://code.claude.com/docs/ko/skills.md#how-synced-skills-behave)의 다운로드를 끕니다. Claude Code는 [claude.ai 계정으로 로그인한 터미널 세션](https://code.claude.com/docs/ko/skills.md#where-synced-skills-load)(대화형 또는 비대화형)과 Cowork 및 클라우드 세션에서 이 스킬을 `~/.claude/skills/synced/`로 다운로드합니다. `false`로 설정하면 해당 다운로드가 중지되고 이미 동기화된 스킬의 로드도 중지됩니다. Claude Code는 `false`만 인식합니다. `true`는 설정하지 않은 것과 같으며, 다른 이유로 꺼져 있는 곳에서 동기화를 켜지 않습니다.

* **범위**: [`사용자, 로컬 또는 관리형`](#scopes) 및 `--settings`로 전달된 파일. 저장소가 사용자 대신 이를 끌 수는 없습니다.
* **유형**: Boolean
  * `false`: Claude Code가 동기화된 스킬의 다운로드를 중지하고 이미 `~/.claude/skills/synced/`에 있는 스킬의 로드를 중지합니다. 사용자 또는 관리형 설정에서는 해당 스킬을 `~/.claude/skills/.trash/`로 이동하기도 합니다
  * `true`: 설정하지 않은 것과 같습니다
* **기본값**: 설정되지 않음. 따라서 claude.ai 계정으로 로그인한 세션은 스킬을 동기화합니다

다음 예시는 어떤 세션에서도 머신이 계정의 스킬을 다운로드하지 않도록 합니다.

```json settings.json theme={null}
{
  "syncClaudeAiSkills": false
}
```

### `syncClaudeAiPlugins`

[claude.ai 계정에 활성화된 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#synced-plugins)의 다운로드를 끕니다. Claude Code는 claude.ai 계정으로 로그인한 터미널 세션의 시작 시점과 Cowork 세션에서 이 플러그인을 `~/.claude/plugins/synced/`로 다운로드하고, 각각을 `<name>@synced`로 로드합니다. `false`로 설정하면 해당 다운로드가 중지되고 이미 동기화된 플러그인의 로드도 중지됩니다. Claude Code는 `false`만 인식합니다. `true`는 설정하지 않은 것과 같으며, 다른 이유로 꺼져 있는 곳에서 동기화를 켜지 않습니다. Claude Code v2.1.273 이상이 필요합니다.

* **범위**: [`사용자, 로컬 또는 관리형`](#scopes) 및 `--settings`로 전달된 파일. 저장소가 사용자 대신 이를 끌 수는 없습니다.
* **유형**: Boolean
  * `false`: Claude Code가 동기화된 플러그인의 다운로드를 중지하고 이미 `~/.claude/plugins/synced/`에 있는 플러그인의 로드를 중지합니다. 사용자 또는 관리형 설정에서는 해당 플러그인을 `~/.claude/plugins/.trash/`로 이동하기도 합니다
  * `true`: 설정하지 않은 것과 같습니다
* **기본값**: 설정되지 않음. 따라서 claude.ai 계정으로 로그인한 세션은 플러그인을 동기화합니다

동기화된 플러그인 전체가 아닌 하나만 끄려면 [`enabledPlugins`](#enabledplugins)에 `"<name>@synced": false`를 설정하세요.

다음 예시는 어떤 세션에서도 머신이 계정의 플러그인을 다운로드하지 않도록 합니다.

```json settings.json theme={null}
{
  "syncClaudeAiPlugins": false
}
```

### `allowedChannelPlugins`

조직의 세션에 메시지를 푸시할 수 있는 [채널](https://code.claude.com/docs/ko/channels.md) 플러그인을 선택합니다. 이 키를 설정하면 Claude Code는 기본 Anthropic 허용 목록 대신 사용자의 목록을 사용합니다. 각 항목은 플러그인과 해당 플러그인이 속한 마켓플레이스를 지정합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: 각각 `marketplace`와 `plugin` 문자열을 가진 객체의 배열. 항목은 대신 `"telegram@claude-plugins-official"`과 같은 `"plugin@marketplace"` 문자열일 수도 있으며, Claude Code는 이를 동등한 객체로 취급합니다. 문자열 형식에는 Claude Code v2.1.267 이상이 필요합니다. 이전 버전은 문자열 형식이 포함된 경우 `allowedChannelPlugins` 값 전체를 거부합니다
* **기본값**: 설정되지 않음. 따라서 Claude Code는 기본 Anthropic 허용 목록을 사용합니다

다음 예시는 채널을 켜고 공식 Anthropic 마켓플레이스의 Telegram 플러그인만 허용합니다.

```json managed-settings.json theme={null}
{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "claude-plugins-official", "plugin": "telegram" }
  ]
}
```

빈 배열은 모든 채널 플러그인을 차단합니다.

이 키는 계정에 대해 채널이 [`channelsEnabled`](#channelsenabled) 게이트를 통과한 후에 적용됩니다. Team 및 Enterprise 플랜과 관리형 설정이 있는 Console 계정에서는 `channelsEnabled: true`를 의미합니다. [실행할 수 있는 채널 플러그인 제한](https://code.claude.com/docs/ko/channels.md#restrict-which-channel-plugins-can-run)을 참조하세요.

### `blockedMarketplaces`

조직의 플러그인 마켓플레이스 소스를 차단합니다. Claude Code는 마켓플레이스 추가 시와 플러그인 설치, 업데이트, 새로 고침, 자동 업데이트 시 차단 목록을 확인하므로, 정책을 설정하기 전에 누군가 추가한 마켓플레이스도 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 소스는 다운로드 전에 확인되므로 파일 시스템에 전혀 닿지 않습니다.

[claude.ai 관리 콘솔](https://code.claude.com/docs/ko/server-managed-settings.md)에서 이 키를 설정하면, [제한 작동 방식](https://code.claude.com/docs/ko/plugins/org.md#restrict-what-users-can-install)에 설명된 대로 조직의 누군가가 claude.ai에서 git 저장소로부터 마켓플레이스를 추가할 때도 claude.ai가 이를 적용합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: [`strictKnownMarketplaces`](#allowed-source-types)와 동일한 형식의 마켓플레이스 소스 객체 배열
* **기본값**: 설정되지 않음. 따라서 어떤 마켓플레이스도 차단되지 않습니다

다음 예시는 하나의 GitHub 저장소를 마켓플레이스 소스로 차단합니다.

```json managed-settings.json theme={null}
{
  "blockedMarketplaces": [
    { "source": "github", "repo": "untrusted/plugins" }
  ]
}
```

`github` 항목은 [소유자 와일드카드 형식](#owner-wildcards) `"owner/*"`를 사용하여 해당 GitHub 소유자 아래의 모든 저장소를 차단할 수 있으며, 이를 위해서는 Claude Code v2.1.223 이상이 필요합니다. 마켓플레이스를 제한하지 않고 Claude Code가 `~/.claude/skills/`와 프로젝트의 `.claude/skills/` 양쪽에서 [`@skills-dir` 플러그인](https://code.claude.com/docs/ko/plugins/loading#plugins-shared-through-a-repository)을 로드하지 않도록 하려면 `{ "source": "skills-dir" }`를 추가하세요. [관리형 마켓플레이스 제한](https://code.claude.com/docs/ko/plugins/org.md#restrict-what-users-can-install)을 참조하세요.

### `channelsEnabled`

조직에서 [채널](https://code.claude.com/docs/ko/channels.md)을 허용합니다. claude.ai Team 및 Enterprise 플랜에서는 이 값을 `true`로 설정할 때까지 Claude Code가 채널을 차단합니다. API 키로 인증하는 [Anthropic Console](https://code.claude.com/docs/ko/authentication.md#claude-console-authentication) 계정에서는 기본적으로 채널이 허용됩니다. 조직에서 관리형 설정을 배포하는 경우, 이 키를 `true`로 설정할 때까지 Claude Code는 해당 계정에서도 채널을 차단합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 조직에서 채널을 허용합니다
  * `false`: 설정하지 않은 것과 같습니다. 기본값에 설명된 대로 채널 차단 여부는 플랜에 따라 다릅니다
* **기본값**: 설정되지 않음. Team 및 Enterprise 플랜과 관리형 설정이 있는 Console 계정에서는 채널이 차단되고, Pro 및 Max 플랜과 관리형 설정이 없는 Console 계정에서는 허용됩니다

```json managed-settings.json theme={null}
{
  "channelsEnabled": true
}
```

채널이 활성화된 후 채널로 등록할 수 있는 플러그인을 제한하려면 [`allowedChannelPlugins`](#allowedchannelplugins)를 설정하세요. [엔터프라이즈 제어](https://code.claude.com/docs/ko/channels.md#enterprise-controls)를 참조하세요.

### `disableCommandPluginSources`

마켓플레이스가 선언한 명령을 사용자 머신에서 실행하여 플러그인을 설치하는 [`command` 플러그인 소스](https://code.claude.com/docs/ko/plugins/marketplace-reference#command-plugin-source)를 차단합니다. `true`로 설정하면 Claude Code는 해당 명령을 절대 실행하지 않고, command 소스 플러그인을 설치하거나 업데이트하지 않으며, 이미 설치된 플러그인의 로드를 중지합니다. 명시적으로 허용하려면 `false`로 설정하세요. `true`로 설정했든 [`allowManagedHooksOnly`](#allowmanagedhooksonly) 하에서 설정하지 않은 채로 두었든, command 소스를 차단할 때마다 마켓플레이스 [`headersHelper` 명령](https://code.claude.com/docs/ko/plugins/host-marketplace#authenticate-archive-downloads)도 차단합니다. 단, 관리형 설정 자체가 선언한 마켓플레이스는 예외입니다. Claude Code v2.1.229 이상이 필요하며, `headersHelper` 차단에는 v2.1.238 이상이 필요합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 마켓플레이스가 선언한 명령을 절대 실행하지 않고, command 소스 플러그인을 설치하거나 업데이트하지 않으며, 이미 설치된 플러그인의 로드를 중지합니다
  * `false`: Claude Code가 command 소스 플러그인을 명시적으로 허용합니다
* **기본값**: 설정되지 않음. 따라서 Claude Code는 [`allowManagedHooksOnly`](#allowmanagedhooksonly)를 따릅니다. 훅 실행을 관리형 설정으로 제한하는 조직에서는 command 소스도 비활성화됩니다. Agent SDK의 `managedSettings` 옵션에서 [`disableAllHooks: true`](#disableallhooks)를 전달하는 애플리케이션은 그것만으로는 command 소스를 비활성화하지 않습니다.

```json managed-settings.json theme={null}
{
  "disableCommandPluginSources": true
}
```

Claude Code v2.1.229 이상이 필요합니다.

### `pluginSuggestionMarketplaces`

스피너 팁과 `/plugin` **Discover** 탭 상단 고정 영역에서 상황에 맞는 설치 제안으로 플러그인이 표시될 수 있는 마켓플레이스를 지정합니다. 기본 제공되는 퍼스트 파티 frontend-design 팁은 영향을 받지 않습니다. 제안은 마켓플레이스 항목에 있는 각 플러그인의 `relevance` 선언에서 나옵니다.

* **범위**: [`관리형`](#scopes)
* **유형**: 마켓플레이스 이름의 배열
* **기본값**: 설정되지 않음. 따라서 마켓플레이스가 선언한 제안은 표시되지 않습니다

```json managed-settings.json theme={null}
{
  "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}
```

이름은 해당 마켓플레이스가 머신에 등록되어 있고, 등록된 소스가 같은 관리형 설정에서 해당 이름의 [`extraKnownMarketplaces`](#extraknownmarketplaces) 항목 또는 [`strictKnownMarketplaces`](#strictknownmarketplaces)의 항목으로 선언되어 있을 때만 적용됩니다. Claude Code는 허용 목록에 있는 이름으로 다른 소스에서 등록된 마켓플레이스를 무시합니다. 공식 마켓플레이스는 소스 요구 사항에서 면제됩니다. 해당 이름은 공식 Anthropic 소스에서만 등록될 수 있으므로 이름만 허용 목록에 추가하면 충분합니다. [상황에 따라 플러그인 제안](https://code.claude.com/docs/ko/plugins/relevance.md)을 참조하세요.

### `pluginTrustMessage`

Claude Code가 설치 전에 표시하는 플러그인 신뢰 경고에 조직 자체의 문구를 추가합니다. 예를 들어 내부 마켓플레이스의 플러그인이 검증되었음을 확인하는 데 사용할 수 있습니다.

* **범위**: [`관리형`](#scopes)
* **유형**: 문자열
* **기본값**: 설정되지 않음. 따라서 Claude Code는 표준 경고만 표시합니다

```json managed-settings.json theme={null}
{
  "pluginTrustMessage": "All plugins from our marketplace are approved by IT"
}
```

### `strictKnownMarketplaces`

조직 구성원이 추가하고 플러그인을 설치할 수 있는 플러그인 마켓플레이스 소스를 제한합니다. Claude Code는 마켓플레이스 추가 시와 플러그인 설치, 업데이트, 새로 고침, 자동 업데이트 시 네트워크 또는 파일 시스템 작업 전에 허용 목록을 적용하므로, 정책을 설정하기 전에 누군가 추가한 마켓플레이스라도 소스가 더 이상 일치하지 않으면 플러그인을 가져오는 데 사용할 수 없습니다. 차단된 사용자에게는 관리형 정책을 명시하는 오류가 표시됩니다.

[claude.ai 관리 콘솔](https://code.claude.com/docs/ko/server-managed-settings.md)에서 이 키를 설정하면, [제한 작동 방식](https://code.claude.com/docs/ko/plugins/org.md#restrict-what-users-can-install)에 설명된 대로 조직의 누군가가 claude.ai에서 git 저장소로부터 마켓플레이스를 추가할 때도 claude.ai가 이를 적용합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: 마켓플레이스 소스 객체의 배열. [허용되는 소스 유형](#allowed-source-types)을 참조하세요
* **기본값**: 설정되지 않음. 따라서 사용자는 모든 마켓플레이스를 추가할 수 있습니다. 빈 배열은 공식 Anthropic 마켓플레이스를 포함한 모든 마켓플레이스 소스를 차단하는 완전한 잠금입니다

다음 예시는 두 개의 GitHub 저장소(하나는 `v2.0` ref에 고정)와 하나의 호스팅된 `marketplace.json` URL을 허용합니다.

```json managed-settings.json theme={null}
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/approved-plugins" },
    { "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" },
    { "source": "url", "url": "https://plugins.example.com/marketplace.json" }
  ]
}
```

이 키를 `allowedMarketplaces`로 작성할 수도 있습니다. Claude Code가 별칭을 처리하는 방식과 별칭을 허용하는 버전은 [마켓플레이스 키 별칭](#marketplace-key-aliases)에 설명되어 있습니다. 이 키는 정책 게이트입니다. 사용자가 추가할 수 있는 항목을 제어하지만 아무것도 등록하지 않습니다. 하나의 파일에서 제한과 사전 등록을 함께 하려면 [`extraKnownMarketplaces`와 결합](#combine-with-extraknownmarketplaces)을 참조하세요. 사용자 관점의 설명은 [관리형 마켓플레이스 제한](https://code.claude.com/docs/ko/plugins/org.md#restrict-what-users-can-install)을 참조하세요.

#### 허용되는 소스 유형

아래 각 항목은 소스 유형별 허용 목록 항목 하나와 해당 항목이 허용하는 필드를 보여 줍니다. 대부분의 유형은 정확히 일치해야 합니다. `hostPattern`과 `pathPattern`은 정규식으로 일치시키며, `github` 항목은 [소유자 와일드카드](#owner-wildcards)를 사용할 수 있습니다.

| 소스 | 예시 항목 | 필드 |
| :- | :- | :- |
| `github` | `{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }` | `repo` 필수. `ref`는 브랜치 또는 태그. `path`는 하위 디렉터리 |
| `git` | `{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git", "ref": "production" }` | `url` 필수. `ref`와 `path`는 `github`와 동일 |
| `url` | `{ "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }` | `url` 필수. `headers`는 인증된 액세스를 위한 HTTP 헤더를 추가 |
| `file` | `{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }` | `path` 필수. `marketplace.json` 파일의 절대 경로 |
| `directory` | `{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }` | `path` 필수. `.claude-plugin/marketplace.json`을 포함하는 디렉터리의 절대 경로 |
| `hostPattern` | `{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }` | `hostPattern` 필수. 마켓플레이스 호스트의 어느 위치에서든 일치하는 정규식. 호스트 전체와 일치시키려면 `^`와 `$`로 고정 |
| `pathPattern` | `{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }` | `pathPattern` 필수. `file` 및 `directory` 소스의 `path` 어느 위치에서든 일치하는 정규식. 접두사를 고정하려면 `^`로 시작 |
| `skills-dir` | `{ "source": "skills-dir" }` | 필드 없음 |

일부 소스 유형에는 표 외에 추가 규칙이 있습니다.

* **`url`**: URL 마켓플레이스는 `marketplace.json` 파일만 다운로드하며, Claude Code는 해당 서버에서 상대 경로로 플러그인 파일을 가져오지 않습니다. 따라서 해당 플러그인은 상대 경로가 아닌 [플러그인 소스](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#plugin-sources)(예: 같은 호스트에 있을 수도 있는 아카이브 URL)를 사용해야 합니다. 상대 경로를 사용하는 플러그인의 경우 대신 Git 기반 마켓플레이스를 사용하세요. [URL 기반 마켓플레이스에서 상대 경로 플러그인이 실패함](https://code.claude.com/docs/ko/plugins/troubleshooting.md#plugins-with-relative-paths-fail-in-url-based-marketplaces)을 참조하세요.
* **`hostPattern`**: 각 저장소를 나열하지 않고 내부 GitHub Enterprise 또는 GitLab 서버의 모든 마켓플레이스를 허용할 때 사용합니다. Claude Code는 `github` 소스를 `github.com`과 대조하고, `url` 소스에서는 호스트 이름을 가져오며, `git` 소스에서는 [git URL](https://git-scm.com/docs/git-clone#_git_urls)의 형식에 따라 호스트 이름을 가져옵니다.

  * `https://` 또는 `ssh://` 같은 스킴이 있는 URL: URL의 호스트 이름.
  * git의 `user@host:path` 형식으로 된 스킴 없는 SSH 주소(예: `git@git.example.com:tools/plugins.git`): `@`와 `:` 사이의 호스트로, git이 연결하는 호스트입니다.
  * 스킴이 없는 그 밖의 형식: 호스트가 없으므로 어떤 `strictKnownMarketplaces` `hostPattern` 항목과도 일치하지 않습니다. `blockedMarketplaces` `hostPattern`의 경우 Claude Code가 더 넓은 범위의 형식에서 호스트를 가져오므로, 차단 목록 항목은 이러한 형식과 여전히 일치할 수 있습니다. v2.1.234 이전에는 `strictKnownMarketplaces` `hostPattern`이 git이 SSH 주소로 취급하지 않는 일부 형식과도 일치했습니다.

  `file` 및 `directory` 소스에는 호스트가 없으므로 `hostPattern` 항목과 절대 일치하지 않습니다.
* **`pathPattern`**: 네트워크 소스에 대한 `hostPattern` 항목과 함께 파일 시스템 마켓플레이스를 허용할 때 사용합니다. `".*"`는 모든 로컬 경로를 허용하며, `"^/opt/approved/"`와 같은 더 좁은 패턴은 특정 디렉터리로 제한합니다.
* **`skills-dir`**: 빈 목록을 포함한 모든 허용 목록은 Claude Code가 `~/.claude/skills/`와 프로젝트의 `.claude/skills/` 양쪽에서 [`@skills-dir` 플러그인](https://code.claude.com/docs/ko/plugins/loading#plugins-shared-through-a-repository)을 로드하는 것을 중지시킵니다. 계속 로드하려면 `{ "source": "skills-dir" }` 항목을 추가하고 [`strictPluginOnlyCustomization`](#strictpluginonlycustomization)은 설정하지 않은 채로 두세요. 이 항목은 이 키와 `blockedMarketplaces` 외에서는 의미가 없습니다.

#### 소유자 와일드카드

`repo` 값이 `"<owner>/*"`인 `github` 항목은 해당 GitHub 소유자 아래의 모든 저장소와 일치합니다. 소유자 와일드카드에는 Claude Code v2.1.223 이상이 필요하며 `strictKnownMarketplaces`와 `blockedMarketplaces`에서만 작동합니다. `extraKnownMarketplaces`나 `/plugin marketplace add`처럼 `github` 소스가 나타나는 다른 모든 곳에서는 `repo` 값이 단일 저장소를 지정해야 합니다. v2.1.223 이전에는 Claude Code가 항목을 문자 그대로 비교했기 때문에 허용 목록 항목은 어떤 저장소와도 일치하지 않았고 차단 목록 항목은 아무것도 차단하지 않았습니다. 단일 저장소 항목은 모든 버전에서 적용됩니다.

다음 항목은 `acme-corp` 조직의 모든 마켓플레이스 저장소를 허용합니다.

```json managed-settings.json theme={null}
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/*" }
  ]
}
```

저장소 이름 위치 전체만 와일드카드가 될 수 있습니다. Claude Code는 `*`, `*/plugins`, `acme-corp/tools-*` 같은 항목을 잘못된 항목으로 간주하여 무시하므로, 이러한 항목은 어떤 저장소와도 일치하지 않습니다.

일치 규칙은 두 설정 간에 다릅니다.

| 규칙 | `strictKnownMarketplaces` | `blockedMarketplaces` |
| - | - | - |
| 일치하는 소스 표기 | `owner/repo` 형식만. 같은 저장소를 복제하는 git URL은 일치하지 않음 | 같은 github.com 저장소로 확인되는 git URL을 포함한 모든 표기 |
| 소유자 대소문자 | 대소문자 구분 | 대소문자 구분 안 함 |
| `ref` | 정확한 항목 규칙을 따름: `ref`가 있는 항목은 정확히 해당 ref를 가진 소스와만 일치하고, ref가 없는 항목은 ref를 지정하지 않은 소스와만 일치 | `ref`가 없는 항목은 일치하는 저장소의 모든 ref를 차단 |
| `path` | 정확한 항목 규칙보다 느슨함: `path`가 있는 항목은 정확히 해당 값이 필요하지만, path가 없는 항목은 저장소 내의 모든 경로와 일치 | `path`가 없는 항목은 일치하는 저장소의 모든 경로를 차단 |

#### 정확한 일치

소유자 와일드카드 `github` 항목과 정규식으로 일치시키는 `hostPattern` 및 `pathPattern` 항목을 제외한 모든 소스 유형에서, Claude Code는 마켓플레이스 소스가 항목과 정확히 일치할 때만 사용자의 추가를 허용합니다. git 기반 소스인 `github`와 `git`의 경우 정확한 일치에는 선택적 필드도 포함됩니다.

* `repo` 또는 `url`이 정확히 일치해야 합니다
* `ref` 필드가 정확히 일치하거나 둘 다 정의되지 않아야 합니다
* `path` 필드가 정확히 일치하거나 둘 다 정의되지 않아야 합니다

예를 들어 Claude Code는 아래의 각 쌍을 서로 다른 두 소스로 취급합니다.

* `{ "source": "github", "repo": "acme-corp/plugins" }`와 `{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }`
* `{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }`와 `{ "source": "github", "repo": "acme-corp/plugins" }`

#### 공식 마켓플레이스만 허용

공식 Anthropic 마켓플레이스만 허용하고 다른 것은 허용하지 않으려면 해당 저장소를 나열하세요.

```json managed-settings.json theme={null}
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" }
  ]
}
```

이 항목이 있으면 Claude Code는 이미 등록된 공식 마켓플레이스를 계속 사용할 수 있게 유지하고, 새 머신에서는 처음으로 대화형 터미널 세션을 시작할 때 마켓플레이스를 자동으로 등록합니다. 자동 등록이 가장 흔히 누락되는 경우는 다음과 같습니다.

* 머신의 첫 번째 대화형 터미널 세션 전에 실행되는 비대화형 환경.
* Claude Code가 VS Code 확장을 통해서만 실행된 머신.
* 빈 배열 잠금처럼 마켓플레이스를 차단한 정책 하에서 Claude Code가 이미 대화형 터미널 세션을 실행한 머신. Claude Code는 차단된 시도를 기록하며 정책이 변경된 후 재시도하지 않습니다.

이러한 머신에서는 같은 `managed-settings.json`의 [`extraKnownMarketplaces`](#extraknownmarketplaces)에 마켓플레이스를 추가하여 Claude Code가 자동으로 등록하도록 하거나, `claude plugin marketplace add anthropics/claude-plugins-official`을 실행하세요.

#### `extraKnownMarketplaces`와 결합

두 키는 서로 다른 역할을 합니다. 다음 표에서 둘을 비교합니다.

| 측면 | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
| - | - | - |
| 목적 | 조직 정책 적용 | 팀 편의 |
| 설정 파일 | 관리형 설정만 | 모든 설정 파일 |
| 동작 | 허용 목록에 없는 추가를 차단 | 누락된 마켓플레이스를 등록 |
| 적용 시점 | 네트워크 및 파일 시스템 작업 전 | 사용자 또는 관리형 설정에서는 즉시, 저장소 파일의 경우 워크스페이스 신뢰 대화 상자 이후 |
| 재정의 가능 여부 | 아니요, 최고 우선순위 | 예, 우선순위가 더 높은 설정으로 재정의 가능 |
| 소스 형식 | 직접 소스 객체 | 중첩된 `source` 객체가 있는 이름이 지정된 마켓플레이스 |

모든 사용자에 대해 마켓플레이스를 제한하는 동시에 사전 등록하려면 `managed-settings.json`에 둘 다 설정하세요.

```json managed-settings.json theme={null}
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}
```

`strictKnownMarketplaces`만 설정하면 사용자는 여전히 `/plugin marketplace add`로 허용된 마켓플레이스를 직접 추가할 수 있습니다. Claude Code가 자동으로 등록하는 마켓플레이스는 공식 Anthropic 마켓플레이스뿐이며, 이는 허용 목록이 이를 허용하는 경우에만 해당합니다. 자동 등록이 누락되는 머신은 [공식 마켓플레이스만 허용](#allow-only-the-official-marketplace)에 나열되어 있습니다.

### `strictPluginOnlyCustomization`

사용자 및 프로젝트 소스의 스킬, 에이전트, 훅, MCP 서버를 차단하여 플러그인이나 관리형 설정에서만 제공되도록 합니다. [`strictKnownMarketplaces`](#strictknownmarketplaces)와 결합하면 전체 사용자 지정 공급망을 제어할 수 있습니다. 마켓플레이스 허용 목록은 사용자가 설치할 수 있는 플러그인을 제어합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: 네 가지 사용자 지정 유형을 모두 잠그려면 `true`, 또는 `"skills"`, `"agents"`, `"hooks"`, `"mcp"` 중에서 잠글 유형을 지정하는 배열
* **기본값**: 설정되지 않음. 따라서 아무것도 잠기지 않습니다

다음 예시는 스킬과 훅을 잠그고 에이전트와 MCP 서버는 잠그지 않습니다.

```json managed-settings.json theme={null}
{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}
```

어떤 사용 환경이든 잠그면 Claude Code는 사용자가 `~/.claude/skills/` 또는 `.claude/skills/` 아래에 두는 플러그인 폴더인 [skills-directory 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)의 로드도 중지합니다. 사용자는 이러한 폴더를 마켓플레이스에서 설치하지 않고 직접 배치하므로, Claude Code는 이 설정에서 이를 사용자 사용자 지정으로 취급합니다.

아래의 네 가지 하위 키 항목은 각 사용 환경이 그 밖에 차단하는 것과 계속 로드되는 것을 나열합니다. Claude Code는 인식하지 못하는 사용 환경 이름을 설정 파일 실패로 처리하지 않고 무시하므로, 모든 클라이언트가 업데이트되기 전에 새 사용 환경 이름을 추가할 수 있습니다.

### `strictPluginOnlyCustomization.skills`

`skills` 사용 환경을 잠급니다. Claude Code는 `~/.claude/skills/`와 `.claude/skills/`의 스킬, `~/.claude/commands/`와 `.claude/commands/`의 사용자 지정 명령, `--add-dir` 디렉터리 아래의 스킬과 명령, claude.ai 계정에서 동기화된 스킬의 로드를 중지합니다. 번들 스킬, 관리형 정책 디렉터리의 스킬, [skills-directory 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)을 제외한 플러그인의 스킬은 계속 로드합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"skills"`
* **기본값**: 잠기지 않음

```json managed-settings.json theme={null}
{
  "strictPluginOnlyCustomization": ["skills"]
}
```

### `strictPluginOnlyCustomization.agents`

`agents` 사용 환경을 잠급니다. Claude Code는 `~/.claude/agents/`, `.claude/agents/`, `--add-dir` 디렉터리의 에이전트 로드를 중지합니다. 기본 제공 에이전트, 관리형 정책 디렉터리의 에이전트, [skills-directory 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)을 제외한 플러그인의 에이전트는 계속 로드합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"agents"`
* **기본값**: 잠기지 않음

```json managed-settings.json theme={null}
{
  "strictPluginOnlyCustomization": ["agents"]
}
```

### `strictPluginOnlyCustomization.hooks`

`hooks` 사용 환경을 잠급니다.

* **실행 중지**:
  * 사용자, 프로젝트, 로컬 `settings.json`의 훅
  * [`skills`](#strictpluginonlycustomization-skills) 또는 [`agents`](#strictpluginonlycustomization-agents) 잠금이 차단하는 소스에 있는 스킬, 사용자 지정 명령, 에이전트의 frontmatter 훅
* **계속 실행**: 관리형 설정의 훅과 [skills-directory 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)을 제외한 플러그인의 훅

frontmatter 훅의 실행이 중지된 스킬, 사용자 지정 명령, 에이전트는 자체 사용 환경이 잠기지 않은 동안에는 계속 로드됩니다.

frontmatter에 `hooks`를 선언한 개인 또는 프로젝트 [스킬](https://code.claude.com/docs/ko/skills.md#where-skills-live)은 [`allowed-tools`](https://code.claude.com/docs/ko/skills#pre-approve-tools-for-a-skill) 사전 승인도 잃게 되므로, 사용자는 해당 필드에 나열된 도구에 대해 권한 프롬프트를 받게 됩니다. 이러한 스킬이 [`context: fork`](https://code.claude.com/docs/ko/skills#run-skills-in-a-subagent)를 통해 서브에이전트에서 실행될 때는 사전 승인이 유지됩니다. `hooks`를 선언하지 않은 스킬도 사전 승인을 유지합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"hooks"`
* **기본값**: 잠기지 않음

```json managed-settings.json theme={null}
{
  "strictPluginOnlyCustomization": ["hooks"]
}
```

### `strictPluginOnlyCustomization.mcp`

`mcp` 사용 환경을 잠급니다. Claude Code는 `~/.claude.json`과 `.mcp.json`의 MCP 서버 로드를 중지합니다. [`managed-mcp.json`](https://code.claude.com/docs/ko/managed-mcp) 서버, [`managedMcpServers`](#managedmcpservers)의 서버, [skills-directory 플러그인](https://code.claude.com/docs/ko/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings)을 제외한 플러그인의 MCP 서버는 계속 로드합니다.

* **범위**: [`관리형`](#scopes)
* **유형**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 배열의 문자열 `"mcp"`
* **기본값**: 잠기지 않음

```json managed-settings.json theme={null}
{
  "strictPluginOnlyCustomization": ["mcp"]
}
```

### `enabledPlugins`

`plugin-name@marketplace-name`을 키로 사용하여 개별 [플러그인](https://code.claude.com/docs/ko/plugins/overview.md)을 켜거나 끕니다. 어떤 범위에도 항목이 없는 플러그인은 해당 플러그인의 [`defaultEnabled`](https://code.claude.com/docs/ko/plugins/manifest-reference#fields) 값을 따릅니다. `/plugin` 또는 `claude plugin enable`로 플러그인을 활성화하거나 비활성화하면 Claude Code가 이 키를 대신 기록합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: `plugin-name@marketplace-name`을 Boolean에 매핑하는 객체
* **기본값**: 설정되지 않음. 따라서 각 플러그인은 자체 `defaultEnabled` 값을 따릅니다

다음 예시는 `team-tools` 마켓플레이스의 플러그인 두 개를 활성화하고 `personal`의 플러그인 하나를 비활성화합니다.

```json settings.json theme={null}
{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}
```

각 범위는 서로 다른 용도로 사용됩니다.

* **사용자 설정**: 개인 플러그인 기본 설정
* **프로젝트 설정**: 저장소의 모든 사람과 공유하는 플러그인
* **로컬 설정**: 머신별 재정의. Claude Code가 여기에 설정을 저장할 때 gitignore 처리됩니다
* **관리형 설정**: 조직 전체 정책. 여기서 `false`로 설정된 플러그인은 모든 범위에서 설치가 차단되고 마켓플레이스에서 숨겨집니다

프로젝트 설정이 사용자 설정보다 우선하므로, `~/.claude/settings.json`에서 플러그인을 `false`로 설정해도 프로젝트의 `.claude/settings.json`이 활성화한 플러그인은 비활성화되지 않습니다. 프로젝트에서 활성화한 플러그인을 자신의 머신에서 제외하려면 대신 `.claude/settings.local.json`에서 `false`로 설정하세요. 관리형 설정은 로컬 설정을 재정의하므로, 관리형 설정에서 강제로 활성화된 플러그인은 이 방법으로 비활성화할 수 없습니다.

프로젝트의 `.claude/settings.json`에서 GitHub 저장소나 npm 패키지 같은 외부 소스의 플러그인을 활성화해도 다른 사람에게 설치되지는 않습니다. 플러그인을 로드하는 모든 경로에서, 각 사용자가 [직접 설치](https://code.claude.com/docs/ko/plugins/org.md#require-plugins-per-repository)할 때까지 Claude Code는 해당 플러그인을 설치되지 않은 것으로 보고합니다.

### `extraKnownMarketplaces`

추가 플러그인 마켓플레이스를 이름으로 등록하여, 저장소를 여는 사람이나 관리형 설정이 적용되는 모든 사람이 직접 추가하지 않아도 마켓플레이스를 사용할 수 있게 합니다. Claude Code는 아직 알지 못하는 각 마켓플레이스를 등록합니다. [`enabledPlugins`](#enabledplugins)가 해당 마켓플레이스에서 지정하는 플러그인이 설치되는지 여부는 플러그인의 소스와 어떤 파일이 이를 활성화하는지에 따라 달라지며, 해당 항목에 규칙이 설명되어 있습니다.

* **범위**: [`모든 파일`](#scopes). Claude Code는 저장소의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 항목을 해당 폴더의 워크스페이스 신뢰 대화 상자를 수락한 후에만 인식합니다. 신뢰하지 않은 폴더에서는, 그곳에서의 `-p` 실행을 포함하여, 메시지 없이 해당 항목을 무시합니다.
* **유형**: 마켓플레이스 이름을 `source` 객체와 선택적 `autoUpdate` Boolean을 가진 객체에 매핑하는 객체
* **기본값**: 설정되지 않음

다음 예시는 GitHub 마켓플레이스와 자체 호스팅 git URL의 마켓플레이스를 등록합니다.

```json settings.json theme={null}
{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}
```

[폴더를 신뢰하기 전에 실행되는 항목](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder)에서 신뢰 게이트를 저장소가 제공할 수 있는 다른 콘텐츠와 비교합니다. 이 키를 `additionalMarketplaces`로 작성할 수도 있습니다. [마켓플레이스 키 별칭](#marketplace-key-aliases)을 참조하세요.

`source`와 함께 `"autoUpdate": true`를 설정하면 Claude Code가 시작 후 백그라운드에서 해당 마켓플레이스를 새로 고치고 설치된 플러그인을 업데이트합니다. 생략하면 `claude-plugins-official`과 대부분의 다른 공식 Anthropic 마켓플레이스는 기본값이 `true`이고, 서드 파티 마켓플레이스는 기본값이 `false`입니다. [자동 업데이트 구성](https://code.claude.com/docs/ko/plugins/install.md#keep-plugins-updated)을 참조하세요.

둘 이상의 설정 파일이 같은 이름으로 마켓플레이스 항목을 정의하면, Claude Code는 [우선순위가 가장 높은 파일](https://code.claude.com/docs/ko/settings.md#settings-precedence)의 항목을 통째로 사용합니다. 해당 항목은 우선순위가 낮은 항목을 대체하며 그 필드를 전혀 상속하지 않으므로, 재정의를 통해 한 파일의 `source.headers` 자격 증명을 다른 파일이 제어하는 URL과 결합할 수 없습니다. v2.1.228 이전에는 Claude Code가 같은 이름의 항목을 필드별로 병합했기 때문에, 우선순위가 높은 파일의 항목이 다른 파일의 `headers`를 포함하여 자신이 설정하지 않은 필드를 상속할 수 있었습니다.

#### 마켓플레이스 소스 유형

`source` 객체는 다음 형식 중 하나를 사용합니다.

* **`github`**: `repo`를 지정하는 GitHub 저장소
* **`git`**: `url`을 지정하는 모든 git URL
* **`url`**: `marketplace.json` 파일에 대한 직접 URL로, `url`과 인증된 액세스를 위한 선택적 `headers` 및 `headersHelper`를 지정합니다. `headersHelper`는 `headers`에 나열하기에는 수명이 너무 짧은 값을 가진 헤더를 출력하는 명령을 지정하며, Claude Code v2.1.238 이상이 필요합니다
* **`file`**: `path`를 지정하는 `marketplace.json` 파일의 로컬 경로
* **`directory`**: `path`를 지정하는 로컬 파일 시스템 경로. 개발용으로 사용하거나, 조직이 [각 머신에 배포](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods)하는 마켓플레이스에 사용합니다.
* **`settings`**: 호스팅된 저장소 없이 설정 파일에 직접 선언된 인라인 마켓플레이스로, `name`과 `plugins`를 지정합니다

`git` 소스 유형은 자체 호스팅 GitLab과 Bitbucket을 포함한 모든 git 호스팅 서비스에서 작동합니다. Claude Code는 해당 머신에서 `git clone`이 사용할 것과 동일한 인증, 즉 구성된 자격 증명 도우미나 SSH 키로 저장소를 복제합니다. `GITHUB_TOKEN` 같은 공급자 토큰은 이를 읽는 자격 증명 도우미를 통해 적용됩니다. 설정 세부 사항은 [비공개 저장소](https://code.claude.com/docs/ko/plugins/host-marketplace.md#grant-access-to-a-private-marketplace)를 참조하세요.

`github` 및 `git` 소스의 경우, Claude Code는 마켓플레이스 저장소를 추가하거나 업데이트하기 위해 복제할 때 [Git LFS](https://git-lfs.com) 콘텐츠를 절대 다운로드하지 않습니다. LFS로 추적되는 파일은 포인터 파일로 체크아웃되며, 추가 또는 업데이트 출력에 그 개수가 보고됩니다.

`source` 객체 내의 `skipLfs` 필드는 허용되지만 아무 효과가 없습니다. v2.1.274 이전에는 `"skipLfs": true`를 설정하지 않는 한 Claude Code가 LFS 콘텐츠를 다운로드했습니다.

`url` 소스의 경우, `headers`의 자격 증명이 만료되어 명령으로 새 자격 증명을 생성해야 할 때 `source` 객체 내에 `headersHelper`를 설정하세요. Claude Code v2.1.238 이상이 필요합니다. 명령이 출력해야 하는 내용과 Claude Code가 명령을 실행하는 위치는 [headersHelper 명령 작성](https://code.claude.com/docs/ko/plugins/host-marketplace.md#write-the-headershelper-command)을, Claude Code가 명령을 실행하지 않는 경우는 [Claude Code가 headersHelper 명령을 건너뛰는 경우](https://code.claude.com/docs/ko/plugins/host-marketplace.md#when-claude-code-skips-a-headershelper-command-or-drops-its-output)를 참조하세요. `https://` 마켓플레이스 URL에 `headersHelper`를 설정하면 Claude Code는 두 시점에 명령을 실행하며, 한 번 실행한 출력을 최대 60초 동안 재사용합니다.

* 나중의 새로 고침을 포함하여 해당 마켓플레이스의 `marketplace.json`을 가져오기 전마다. Claude Code는 출력된 헤더를 해당 가져오기와 함께 보냅니다.
* 마켓플레이스 URL의 오리진(동일한 스킴, 호스트, 포트)에서 플러그인 아카이브를 다운로드하기 전마다. Claude Code는 출력을 해당 다운로드와 함께 보내며, 다른 다운로드에는 헤더가 전달되지 않습니다.

Claude Code는 [`--add-dir`](https://code.claude.com/docs/ko/permissions#what-runs-before-you-trust-a-folder)로 추가한 디렉터리의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 설정된 `headersHelper`를 `url` 소스와 인라인 플러그인 항목 모두에서 무시하고, 해당 파일에 설정된 고정 `headers`만 보냅니다. 다른 설정 파일에 대해서는 [사용자가 headersHelper 명령을 수락하는 방법](https://code.claude.com/docs/ko/plugins/host-marketplace.md#how-users-accept-a-headershelper-command)에서 다룹니다.

`settings` 소스에 나열된 플러그인은 GitHub나 npm 같은 외부 소스를 참조해야 하며, `name`은 마켓플레이스 키와 일치해야 합니다. 각 플러그인은 여전히 `enabledPlugins`에서 별도로 활성화해야 합니다. 다음 예시는 플러그인 하나를 인라인으로 선언합니다.

```json settings.json theme={null}
{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}
```

`source: 'settings'` 아래에서 자체 `source`가 [`archive`](https://code.claude.com/docs/ko/plugins/marketplace-reference#archive-plugin-source)인 플러그인 항목은 아카이브 다운로드를 위한 `headers`를 설정할 수 있습니다. 레지스트리가 요청 시 발급하는 토큰처럼 `headers`에 넣을 값의 수명이 짧다면 대신 `headersHelper` 명령을 설정하세요. 항목에 둘 다 설정할 수도 있습니다. 두 필드 모두 Claude Code v2.1.238 이상이 필요합니다.

Claude Code는 항목의 `headers`와 명령이 출력하는 내용을 해당 플러그인의 아카이브 다운로드와 함께 보내며, 다른 다운로드에는 보내지 않습니다. Claude Code는 사용자가 [해당 플러그인 하나만 단독으로 설치하거나 업데이트](https://code.claude.com/docs/ko/plugins/host-marketplace.md#how-users-accept-a-headershelper-command)할 때만 명령을 실행합니다. 항목이 어느 파일에 있는지에 따라 세 가지 추가 규칙이 적용됩니다.

* **`strict`**: 마켓플레이스의 `marketplace.json`에 있는 항목과 달리, 설정의 항목은 `"strict": false`가 필요하지 않습니다. 설정 파일에는 인라인할 매니페스트 필드가 없기 때문입니다. [Strict 모드](https://code.claude.com/docs/ko/plugins/marketplace-reference.md#strict-mode)를 참조하세요.
* **폴더 신뢰**: 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 항목의 경우, Claude Code는 사용자가 [해당 폴더도 신뢰](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder)한 후에만 명령을 실행합니다.
* **헤더 필터**: 저장소가 해당 파일을 제공할 수 있으므로, Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 항목에서 [요청 라우팅 및 클라이언트 식별 헤더 이름](https://code.claude.com/docs/ko/plugins/host-marketplace.md#when-claude-code-skips-a-headershelper-command-or-drops-its-output)을 제거합니다. Claude Code는 카탈로그 항목과 `--add-dir` 디렉터리 설정의 항목에도 같은 필터를 적용하며, 사용자 설정, `--settings` 파일 또는 관리형 설정의 항목에는 필터를 적용하지 않습니다.

#### 마켓플레이스 키 별칭

Claude Code v2.1.232 이상에서는 `extraKnownMarketplaces`를 `additionalMarketplaces`로, `strictKnownMarketplaces`를 `allowedMarketplaces`로 작성할 수 있습니다. Claude Code는 각 별칭을 다음과 같이 처리합니다.

* 이전 버전은 별칭을 무시하므로, 여러 Claude Code 버전이 섞인 머신 집합용 관리형 설정 파일처럼 이전 버전도 읽는 파일에는 정식 표기를 유지하세요.
* 정식 키를 허용하는 모든 설정 파일에서 Claude Code는 별칭을 정식 키와 똑같이 읽습니다.
* Claude Code는 파일을 업데이트할 때 `additionalMarketplaces`를 `extraKnownMarketplaces`로 다시 쓸 수 있습니다.
* 한 파일에 두 표기를 모두 설정하면 Claude Code는 정식 값을 사용하고 별칭을 무시합니다.

### `pluginConfigs`

플러그인의 [`userConfig`](https://code.claude.com/docs/ko/plugins/manifest-reference#user-configuration) 구성 대화 상자에 입력한 민감하지 않은 응답을 플러그인 ID를 키로 하여 저장합니다. 대화 상자를 작성하면 Claude Code가 이 키를 사용자 설정에 기록하므로 직접 편집할 필요가 없습니다. Claude Code는 민감한 옵션을 대신 macOS Keychain에 저장하며, Keychain이 쓰기를 거부하면 `~/.claude/.credentials.json`으로 대체합니다. 지원되는 키체인이 없는 플랫폼에서는 `~/.claude/.credentials.json`에 저장합니다.

* **범위**: [`사용자 또는 관리형`](#scopes)
* **유형**: 플러그인 ID를 객체에 매핑하는 객체. 해당 객체에는 각 옵션 이름을 문자열, 숫자, Boolean 또는 문자열 배열에 매핑하는 `options` 필드와, 같은 형태로 서버별 사용자 구성 값을 담는 선택적 `mcpServers` 필드가 있습니다
* **기본값**: 설정되지 않음

다음 예시는 `acme-tools`의 `deployer` 플러그인에 대한 `api_endpoint` 옵션을 저장합니다.

```json settings.json theme={null}
{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}
```

기본 제공 플러그인은 같은 키 아래에 `@builtin` 접미사를 붙여 옵션을 저장합니다. 예를 들어 Claude Code가 `AGENTS.md` 파일을 읽을지 여부를 제어하는 [**Project instructions**](https://code.claude.com/docs/ko/memory.md#choose-which-instruction-files-load) 설정은 `pluginConfigs["cc-plugin-agents-md@builtin"].options.instructionFiles`입니다. v2.1.285 이전에는 플러그인의 ID가 `agents-md@builtin`이었습니다. 이후 버전은 두 ID 중 어느 쪽 아래의 항목이든 읽습니다.

Claude Code는 이 값을 플러그인 훅, MCP, LSP 구성에 대입하므로 복제된 저장소가 이 값을 제공할 수 없어야 합니다. 따라서 프로젝트 및 로컬 항목은 무시합니다.

### `prependPlugins`

사용자가 설치한 모든 mod보다 먼저, 나열된 순서대로 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 실행되는 관리형 플러그인을 나열합니다. 관리형 설정에서 이 키를 설정할 때는 기본 제공 가드를 유지하려면 목록에 `sec-default@builtin`을 포함하세요. 관리형 설정에서 Claude Code는 플러그인이 조직의 것으로 간주되지 않는 id를 건너뜁니다. 해당 조건과 두 순서 지정 키가 함께 작동하는 방식은 [조직의 mod 설치 및 순서 설정](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods)을 참조하세요.

* **범위**: [`사용자 또는 관리형`](#scopes). Claude Code는 관리형 설정에서 이 키를 읽습니다. 사용자 설정에서는 관리형 설정이 없는 머신에서 자격 증명이 Team 또는 Enterprise `/login`이 아닌 세션에서만 이 키를 읽습니다. 프로젝트 및 로컬 설정과 `--settings` 파일에서는 이 키를 무시합니다.
* **유형**: `plugin-name@marketplace-name` 문자열의 배열
* **기본값**: 설정되지 않음

```json managed-settings.json theme={null}
{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]
}
```

### `appendPlugins`

사용자가 설치한 모든 mod 다음에, 나열된 순서대로 [mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 실행되는 관리형 플러그인을 나열합니다. `prependPlugins`와 `appendPlugins` 모두에 나열된 id는 앞에 추가됩니다. 관리형 설정에서 Claude Code는 플러그인이 [조직의 것으로 간주](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods)되지 않는 id를 건너뜁니다.

* **범위**: [`사용자 또는 관리형`](#scopes). Claude Code는 관리형 설정에서 이 키를 읽습니다. 사용자 설정에서는 관리형 설정이 없는 머신에서 자격 증명이 Team 또는 Enterprise `/login`이 아닌 세션에서만 이 키를 읽습니다. 프로젝트 및 로컬 설정과 `--settings` 파일에서는 이 키를 무시합니다.
* **유형**: `plugin-name@marketplace-name` 문자열의 배열
* **기본값**: 설정되지 않음

```json managed-settings.json theme={null}
{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-audit@acme-tools": true },
  "appendPlugins": ["acme-audit@acme-tools"]
}
```

## MCP

Claude Code가 연결하는 MCP 서버와 조직이 허용하는 서버를 제어합니다. [MCP를 사용하여 외부 도구에 연결](https://code.claude.com/docs/ko/mcp.md) 및 [관리형 MCP 구성](https://code.claude.com/docs/ko/managed-mcp.md)을 참조하세요.

### `allowAllClaudeAiMcps`

Claude Code가 배포된 `managed-mcp.json`과 함께 자체적으로 가져오는 [claude.ai 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 로드합니다. 이 키가 없으면 `managed-mcp.json`이 MCP 서버를 독점적으로 제어하고 해당 커넥터를 억제합니다.

* **범위**: [`Managed`](#scopes). 사용자는 독점적 제어가 억제한 커넥터를 다시 활성화할 수 없습니다.
* **유형**: Boolean
  * `true`: Claude Code는 배포된 `managed-mcp.json`과 함께 claude.ai 커넥터를 로드합니다
  * `false`: 배포된 `managed-mcp.json`이 MCP 서버를 독점적으로 제어하고 [Claude Code가 자체적으로 가져오는](https://code.claude.com/docs/ko/mcp.md#how-connectors-reach-claude-code) claude.ai 커넥터를 억제합니다
* **기본값**: `false`이므로 배포된 `managed-mcp.json`이 Claude Code가 자체적으로 가져오는 claude.ai 커넥터를 억제합니다

```json managed-settings.json theme={null}
{
  "allowAllClaudeAiMcps": true
}
```

[`allowedMcpServers`](#allowedmcpservers) 및 [`deniedMcpServers`](#deniedmcpservers)는 여전히 이 키가 로드하는 커넥터에 적용됩니다. `managed-mcp.json`을 포함하는 호스트(예: 자체 호스팅 러너)의 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에 전달된 커넥터는 억제된 상태로 유지됩니다. [관리형 세트와 함께 claude.ai 커넥터 허용](https://code.claude.com/docs/ko/managed-mcp.md#allow-claude-ai-connectors-alongside-the-managed-set)을 참조하세요.

### `allowClaudeInChromeWithManagedMcp`

배포된 `managed-mcp.json`과 함께 기본 제공 [Claude in Chrome](https://code.claude.com/docs/ko/chrome.md) 서버를 실행합니다. 이 키가 없으면 배포된 `managed-mcp.json`이 터미널 세션에서 Claude in Chrome을 차단합니다. Claude Code v2.1.282 이상이 필요합니다.

* **범위**: [`Managed`](#scopes), 기기의 자체 관리형 설정에서만: MDM 배포 plist 또는 HKLM 레지스트리 키, 또는 시스템 `managed-settings.json` 파일. Claude Code는 서버 관리형 설정, 사용자 쓰기 가능 HKCU 레지스트리, 사용자 또는 프로젝트 설정에서는 무시합니다.
* **유형**: Boolean
  * `true`: 기본 제공 Claude in Chrome 서버는 배포된 `managed-mcp.json`과 함께 실행할 수 있습니다
  * `false`: 배포된 `managed-mcp.json`이 터미널 세션에서 Claude in Chrome을 차단합니다
* **기본값**: `false`이므로 배포된 `managed-mcp.json`이 터미널 세션에서 Claude in Chrome을 차단합니다

```json managed-settings.json theme={null}
{
  "allowClaudeInChromeWithManagedMcp": true
}
```

`claude-in-chrome`에 대한 [`deniedMcpServers`](#deniedmcpservers) 항목은 이 키가 켜져 있어도 여전히 서버를 차단합니다. [관리형 세트와 함께 Claude in Chrome 허용](https://code.claude.com/docs/ko/managed-mcp.md#allow-claude-in-chrome-alongside-the-managed-set)을 참조하세요.

### `allowedMcpServers`

사용자가 추가할 수 있는 MCP 서버를 허용 목록에 추가합니다. Claude Code는 플러그인 서버, `--mcp-config`로 전달된 서버, claude.ai의 서버를 포함하여 정의된 모든 위치에서 항목과 일치하지 않는 모든 서버를 차단합니다.

Chrome의 Claude, Claude Code가 실행 중인 [VS Code](https://code.claude.com/docs/ko/vs-code.md#the-built-in-ide-mcp-server) 또는 [JetBrains](https://code.claude.com/docs/ko/jetbrains.md#the-built-in-ide-mcp-server) IDE에 연결하는 `ide` 서버, CLI 자체가 구성하는 서버와 같은 기본 제공 서버는 허용 목록에서 제외되며, 거부 목록은 여전히 이들에게 적용됩니다. Claude Code v2.1.268 이상에서 [Claude Tag](https://code.claude.com/docs/ko/claude-tag.md) 세션의 Slack 도구도 허용 목록에서 제외되며, 거부 목록은 여전히 이들에게 적용됩니다. 프로세스 내 `type: "sdk"` 서버는 두 목록 모두에서 제외됩니다. [세션을 시작한 앱](https://code.claude.com/docs/ko/mcp.md#how-connectors-reach-claude-code)이 이들을 등록합니다.

조직이 제공하는 서버도 허용 목록에서 제외되며, 거부 목록은 여전히 이들에게 적용됩니다. 이 제외는 모든 [`managedMcpServers`](#managedmcpservers) 항목과, 값이 [`env` 외부에서 `${VAR}` 확장을 사용하지 않는](https://code.claude.com/docs/ko/managed-mcp#how-allowlists-and-denylists-apply-to-the-managed-set) 모든 [`managed-mcp.json`](https://code.claude.com/docs/ko/managed-mcp#exclusive-control-with-managed-mcp-json) 항목을 포함합니다. 전체 확인 순서는 [서버 평가 방법](https://code.claude.com/docs/ko/managed-mcp.md#how-a-server-is-evaluated)을 참조하세요. v2.1.259 이전에는 `managed-mcp.json`의 서버도 일치해야 했습니다.

* **범위**: [`Any file`](#scopes). 모든 파일의 항목이 하나의 허용 목록으로 병합됩니다. [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly)가 설정되지 않은 경우입니다. 관리형 설정에 배포하여 적용합니다.
* **타입**: 각각 정확히 하나의 키를 가진 객체 배열입니다. 문자, 숫자, 하이픈, 밑줄로 제한된 문자열인 `serverName`, 정확히 일치하는 명령과 해당 인수의 배열인 `serverCommand`, 또는 `*` 와일드카드를 사용하는 URL 패턴인 `serverUrl` 중 하나를 사용합니다
* **기본값**: 설정되지 않음, 따라서 모든 서버가 허용됩니다. 빈 배열은 사용자가 추가하는 모든 서버를 차단합니다

이 예제는 나열된 `npx` 명령이 시작하는 stdio 서버만 허용합니다:

```json settings.json theme={null}
{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] }
  ]
}
```

[`deniedMcpServers`](#deniedmcpservers) 항목이 우선하므로 두 목록에 있는 서버는 차단됩니다. 목록에 `serverCommand` 항목이 포함되면 stdio 서버는 `serverCommand` 항목과 일치해야 하고, `serverUrl` 항목이 포함되면 원격 서버는 `serverUrl` 항목과 일치해야 합니다. `serverName` 일치는 더 이상 해당 종류의 서버를 허용하지 않습니다. [허용 목록 및 거부 목록을 사용한 정책 기반 제어](https://code.claude.com/docs/ko/managed-mcp.md#policy-based-control-with-allowlists-and-denylists)를 참조하세요.

### `allowManagedMcpServersOnly`

관리형 허용 목록을 적용되는 유일한 목록으로 만듭니다. Claude Code는 [`allowedMcpServers`](#allowedmcpservers)를 관리형 설정에서만 읽고 사용자, 프로젝트, 로컬 설정의 허용 목록을 무시합니다. [`deniedMcpServers`](#deniedmcpservers)는 여전히 모든 설정 범위에서 병합되므로 사용자는 자신을 위해 서버를 차단할 수 있습니다. 관리자는 사용자의 자체 설정이 관리형 허용 목록이 허용하는 것을 확대할 수 없도록 설정합니다.

* **범위**: [`Managed`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code는 `allowedMcpServers`를 관리형 설정에서만 읽고 사용자, 프로젝트, 로컬 설정의 허용 목록을 무시합니다
  * `false`: 모든 설정 범위의 허용 목록이 병합됩니다
* **기본값**: `false`이므로 모든 설정 범위의 허용 목록이 병합됩니다

이 예제는 허용 목록을 관리형 설정으로 잠그고 `github`라는 서버만 허용합니다:

```json managed-settings.json theme={null}
{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverName": "github" }
  ]
}
```

사용자는 여전히 자신의 MCP 서버를 추가할 수 있습니다. 관리형 허용 목록과 일치하는 서버만 로드됩니다. [허용 목록을 관리형 설정만으로 제한](https://code.claude.com/docs/ko/managed-mcp.md#restrict-the-allowlist-to-managed-settings-only)을 참조하세요.

### `deniedMcpServers`

특정 MCP 서버를 차단합니다. Claude Code는 플러그인 서버, `--mcp-config`로 전달된 서버, `managed-mcp.json`의 서버, [`managedMcpServers`](#managedmcpservers)의 서버, [자체적으로 가져오는](https://code.claude.com/docs/ko/mcp.md#how-connectors-reach-claude-code) claude.ai 커넥터를 포함하여 정의된 모든 위치에서 일치하는 서버를 로드하기를 거부합니다. 프로세스 내 `type: "sdk"` 서버는 제외됩니다. 세션을 시작한 앱이 이들을 등록합니다.

* **범위**: [`Any file`](#scopes). 모든 파일의 항목이 하나의 거부 목록으로 병합되며, [`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly)는 이를 변경하지 않습니다. 관리형 설정에 배포하여 적용합니다.
* **유형**: 객체 배열, 각각 정확히 하나의 키: `"claude.ai Slack"`과 같은 claude.ai 커넥터의 표시 이름인 문자열인 `serverName`; 정확히 일치하는 명령 및 해당 인수의 배열인 `serverCommand`; 또는 `*` 와일드카드가 있는 URL 패턴인 `serverUrl`
* **기본값**: 설정되지 않음, 따라서 서버가 차단되지 않습니다. 빈 배열도 아무것도 차단하지 않습니다

```json settings.json theme={null}
{
  "deniedMcpServers": [
    { "serverName": "filesystem" }
  ]
}
```

거부 목록이 [`allowedMcpServers`](#allowedmcpservers)보다 우선하므로 두 목록에 있는 서버는 차단됩니다. [허용 목록 및 거부 목록을 사용한 정책 기반 제어](https://code.claude.com/docs/ko/managed-mcp.md#policy-based-control-with-allowlists-and-denylists)를 참조하세요.

### `disableClaudeAiConnectors`

[Claude Code가 자체적으로 가져오는](https://code.claude.com/docs/ko/mcp.md#how-connectors-reach-claude-code) [claude.ai MCP 커넥터](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)를 끕니다. 따라서 이들을 가져오거나 연결하지 않습니다. 모든 설정 파일의 `true`가 적용됩니다. 체크인된 프로젝트 `.claude/settings.json`은 저장소를 해당 커넥터에서 제외할 수 있지만, 프로젝트 수준의 `false`는 사용자 또는 관리형 수준의 `true`를 재정의할 수 없습니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code는 해당 커넥터를 가져오거나 연결하지 않습니다
  * `false`: 설정되지 않은 것과 동일합니다. Claude Code는 다른 설정 파일이나 `ENABLE_CLAUDEAI_MCP_SERVERS`가 이들을 끄지 않는 한 커넥터를 가져옵니다
* **기본값**: `false`이므로 Claude Code는 커넥터를 가져옵니다
* **세션별 재정의**: [`ENABLE_CLAUDEAI_MCP_SERVERS`](https://code.claude.com/docs/ko/env-vars)를 `false`로 설정하면 한 세션 동안 커넥터가 꺼집니다. 둘 중 어느 것이 이들을 끄든 다른 하나는 이들을 다시 켤 수 없습니다

```json settings.json theme={null}
{
  "disableClaudeAiConnectors": true
}
```

`--mcp-config`로 명시적으로 전달하는 서버는 영향을 받지 않습니다. 모든 커넥터를 차단하는 대신 개별 커넥터를 차단하려면 [`deniedMcpServers`](#deniedmcpservers)를 사용하세요. [claude.ai 커넥터 비활성화](https://code.claude.com/docs/ko/mcp.md#disable-claude-ai-connectors)를 참조하세요.

### `disabledMcpjsonServers`

프로젝트의 `.mcp.json` 파일에 정의된 특정 서버를 거부하여 Claude Code가 이들을 연결하거나 승인을 요청하지 않도록 합니다. 모든 설정 파일의 거부가 적용되며, 저장소에 체크인된 프로젝트 `.claude/settings.json`도 포함됩니다.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열 배열, `.mcp.json`에 나타나는 서버 이름
* **기본값**: 설정되지 않음

```json settings.json theme={null}
{
  "disabledMcpjsonServers": ["filesystem"]
}
```

Claude Code는 승인 대화에서 서버를 거부할 때 이 키를 `.claude/settings.local.json`에 씁니다. `claude mcp get <name>`은 거부된 서버를 `✘ Rejected (see disabledMcpjsonServers in settings)`로 표시합니다. 거부는 [`enabledMcpjsonServers`](#enabledmcpjsonservers) 및 [`enableAllProjectMcpServers`](#enableallprojectmcpservers)보다 우선합니다.

### `enableAllProjectMcpServers`

프로젝트 `.mcp.json` 파일에 정의된 모든 MCP 서버를 프롬프트 없이 승인합니다. Claude Code는 승인 대화에서 모든 서버를 승인하도록 선택할 때 이 키를 `.claude/settings.local.json`에 씁니다.

* **범위**: [`Any file`](#scopes). 신뢰 대화를 수락하지 않은 폴더에서 Claude Code는 사용자 설정, 관리형 설정, `--settings`에서 이를 준수하고 공유 프로젝트 파일에서는 무시합니다. 세션 및 `claude mcp list`와 `claude mcp get`에서 모두 [프로젝트 서버 승인 및 작업 영역 신뢰](https://code.claude.com/docs/ko/mcp.md#project-server-approvals-and-workspace-trust)는 추적되지 않은 `.claude/settings.local.json`이 언제 계산되는지 말합니다.
* **유형**: Boolean
  * `true`: Claude Code는 프로젝트 `.mcp.json` 파일에 정의된 모든 MCP 서버를 프롬프트 없이 승인합니다
  * `false`: Claude Code는 각 서버를 승인하도록 요청합니다. 신뢰된 폴더에서 더 높은 우선순위 파일의 `false`는 더 낮은 우선순위 파일의 `true`를 재정의합니다. 신뢰하지 않은 폴더에서 준수되는 모든 파일의 `true`는 충분합니다
* **기본값**: 설정되지 않음, 따라서 Claude Code는 각 서버를 승인하도록 요청합니다

```json settings.json theme={null}
{
  "enableAllProjectMcpServers": true
}
```

[`disabledMcpjsonServers`](#disabledmcpjsonservers) 항목은 여전히 서버를 거부합니다.

### `enabledMcpjsonServers`

프로젝트 `.mcp.json` 파일에 정의된 특정 서버를 승인하여 Claude Code가 묻지 않고 이들을 연결하도록 합니다. Claude Code는 승인 대화에서 서버를 승인할 때 이 키를 `.claude/settings.local.json`에 씁니다.

* **범위**: [`Any file`](#scopes). 신뢰 대화를 수락하지 않은 폴더에서 Claude Code는 사용자 설정, 관리형 설정, `--settings`에서 이를 준수하고 공유 프로젝트 파일에서는 무시합니다. 세션 및 `claude mcp list`와 `claude mcp get`에서 모두 [프로젝트 서버 승인 및 작업 영역 신뢰](https://code.claude.com/docs/ko/mcp.md#project-server-approvals-and-workspace-trust)는 추적되지 않은 `.claude/settings.local.json`이 언제 계산되는지 말합니다.
* **유형**: 문자열 배열, `.mcp.json`에 나타나는 서버 이름
* **기본값**: 설정되지 않음

이 예제는 프로젝트의 `.mcp.json`에서 `memory` 및 `github` 서버를 승인합니다:

```json settings.json theme={null}
{
  "enabledMcpjsonServers": ["memory", "github"]
}
```

[`disabledMcpjsonServers`](#disabledmcpjsonservers) 항목은 여전히 서버를 거부합니다.

### `managedMcpServers`

관리형 설정에서 모든 사용자에게 원격 MCP 서버를 제공합니다. 사용자는 자신이 추가한 서버를 유지하고 제공하는 서버를 편집하거나 제거할 수 없습니다. Claude Code v2.1.259 이상이 필요합니다.

* **범위**: [`Managed`](#scopes). Claude Code는 사용자, 프로젝트, 로컬 설정에서 키를 경고와 함께 삭제하고, 타사 배포의 Claude Desktop 앱의 Code 탭이나 앱의 Cowork 세션에서는 읽지 않습니다. Claude Desktop이 해당 세션의 MCP 서버를 공급하고 잠급니다.
* **유형**: 서버 이름으로 키가 지정된 객체. 각 항목은 `http` 또는 `sse` 서버에 대한 `.mcp.json` 형태입니다. 필수 `https://` `url`, 그리고 선택적으로 `headers`, `oauth`, 기타 HTTP 및 SSE 옵션. Claude Code는 유효성 검사에 실패한 항목을 삭제하고, [항목이 포함할 수 있는 것](https://code.claude.com/docs/ko/managed-mcp.md#what-an-entry-can-contain)은 조건을 나열합니다
* **기본값**: 설정되지 않음, 따라서 관리형 설정은 서버를 제공하지 않습니다

이 예제는 `search`라는 HTTP 서버 하나를 제공합니다:

```json managed-settings.json theme={null}
{
  "managedMcpServers": {
    "search": {
      "type": "http",
      "url": "https://search.example.com/mcp"
    }
  }
}
```

우선순위, 제공된 서버가 `managed-mcp.json` 및 허용 및 거부 목록과 결합되는 방식, 사용자가 보는 것에 대해서는 [관리형 설정을 통해 서버 제공](https://code.claude.com/docs/ko/managed-mcp.md#provide-servers-through-managed-settings)을 참조하세요.

## 에이전트, 세션, 및 worktrees

기본 에이전트를 설정하고, 팀원을 제어하며 세션 간 메시징을 구성하고, worktrees를 설정합니다. [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md) 및 [Worktrees](https://code.claude.com/docs/ko/worktrees.md)를 참조하세요.

### `agent`

명명된 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#invoke-subagents-explicitly)로 메인 스레드를 실행하여 Claude Code가 해당 서브에이전트의 시스템 프롬프트, 도구 제한 사항 및 모델을 세션에 적용하도록 합니다. 동일한 키는 `claude agents`에서 디스패치하는 세션의 기본 에이전트를 설정합니다.

* **Scope**: [`Any file`](#scopes)
* **Type**: string, 기본 제공 또는 사용자 정의 에이전트의 이름
* **Default**: 설정되지 않음. 메인 스레드는 Claude Code의 기본 에이전트로 실행됩니다
* **Per-session overrides**: `--agent`는 한 세션에 대해 이 키보다 우선합니다

```json settings.json theme={null}
{
  "agent": "code-reviewer"
}
```

플러그인의 자체 `settings.json`도 이 키를 제공할 수 있습니다. [플러그인과 함께 기본 설정 제공](https://code.claude.com/docs/ko/plugins/components.md#default-settings)을 참조하세요.

### `crossSessionInbound`

이 세션이 [다른 Claude Code 세션에서 도착하는 메시지](https://code.claude.com/docs/ko/cross-session-messaging.md#control-inbound-messages)로 수행할 작업을 선택합니다. 적용되는 값이 없으면 Claude Code는 두 세션의 권한 모드 클래스에서 메시지별로 결정합니다. Claude Code v2.1.224 이상이 필요합니다.

* **Scope**: [`Any file`](#scopes). 프로젝트 또는 로컬 값은 관리형 설정, `--settings` 플래그 또는 사용자 설정이 제공하는 값보다 더 엄격할 때만 적용됩니다.
* **Type**: string, 다음 중 하나:
  * `"accept"`: Claude Code가 메시지를 Claude에 전달합니다
  * `"hold"`: Claude Code가 메시지를 전달하지 않고 알림을 표시합니다
  * `"refuse"`: Claude Code가 메시지를 삭제합니다
* **Default**: 설정되지 않음. Claude Code는 메시지별로 결정합니다

```json settings.json theme={null}
{
  "crossSessionInbound": "hold"
}
```

Claude Code는 관리형 설정을 먼저 읽은 다음 `--settings` 플래그, 그 다음 사용자 설정을 읽고 찾은 첫 번째 값을 적용합니다. `refuse`는 `hold`보다 더 엄격하고, `hold`는 `accept`보다 더 엄격합니다. 신뢰할 수 있는 소스 중 어느 것도 값을 설정하지 않으면 프로젝트 또는 로컬 `hold` 또는 `refuse`가 여전히 적용되어 메시지별 기본값을 대체합니다. 세션 간 메시징이 있는 세션에서 이 키는 `/config`에 **다른 세션의 메시지**로 나타나며, 이는 사용자 설정에 기록됩니다. 행에는 Claude Code v2.1.232 이상이 필요하며, Claude Code는 `--settings` 플래그 또는 관리형 설정이 키를 설정하는 동안 이를 숨깁니다.

Claude Code는 인식하지 못하는 값을 설정할 때 [경고](https://code.claude.com/docs/ko/errors.md#crosssessioninbound-must-be-one-of-accept-hold-refuse)합니다. 해당 값이 사용자, 프로젝트, 로컬 또는 `--settings` 파일에 있는 동안 Claude Code는 인바운드 메시지를 보류합니다. 우선순위를 갖는 소스가 `accept`를 설정하더라도 마찬가지입니다. 다른 소스가 설정한 `refuse`는 여전히 적용됩니다. 값을 수정하거나 제거하여 보류를 해제합니다.

인식하지 못하는 값이 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에 있으면 Claude Code는 대신 관리자가 수정할 때까지 이를 `refuse`로 처리합니다. v2.1.248 이전에는 Claude Code가 경고 없이 인식하지 못하는 값을 무시했습니다.

### `disableAgentView`

[배경 에이전트 및 에이전트 보기](https://code.claude.com/docs/ko/agent-view.md)를 끕니다: `claude agents`, `--bg`, `/background` 및 온디맨드 감독자. [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에서 설정하여 조직에 대해 적용합니다.

* **Scope**: [`Any file`](#scopes)
* **Type**: Boolean
  * `true`: Claude Code가 `claude agents`, `--bg`, `/background` 및 온디맨드 감독자를 끕니다
  * `false`: 에이전트 보기를 사용할 수 있습니다
* **Default**: 설정되지 않음. 에이전트 보기를 사용할 수 있습니다
* **Per-session overrides**: [`CLAUDE_CODE_DISABLE_AGENT_VIEW`](https://code.claude.com/docs/ko/env-vars)는 한 세션에 대해 에이전트 보기를 끕니다. 둘 중 하나가 이를 끄면 다른 하나는 다시 켤 수 없습니다

```json settings.json theme={null}
{
  "disableAgentView": true
}
```

### `isolatePeerMachines`

Claude의 `SendMessage`가 이 머신을 넘어 세션 중 하나에 도달하기 전에 명시적 승인을 요구합니다. [크로스 머신 메시지에 대한 승인 요구](https://code.claude.com/docs/ko/cross-session-messaging.md#require-approval-for-cross-machine-messages)를 참조하세요. 승인 프롬프트는 [`bypassPermissions` 모드](https://code.claude.com/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)에서도 나타납니다.

* **Scope**: [`Any file`](#scopes). 모든 범위의 `true`가 적용되므로 체크인된 프로젝트 파일이 요구 사항을 켤 수 있지만 끌 수는 없습니다.
* **Type**: Boolean
  * `true`: Claude Code는 Claude의 `SendMessage`가 이 머신을 넘어 세션 중 하나에 도달하기 전에 승인을 요청합니다
  * `false`: 크로스 머신 메시지는 프롬프트를 표시하지 않습니다
* **Default**: 설정되지 않음. 크로스 머신 메시지는 프롬프트를 표시하지 않습니다

```json settings.json theme={null}
{
  "isolatePeerMachines": true
}
```

크로스 머신 `SendMessage` 승인에는 Claude Code v2.1.224 이상이 필요합니다.

### `processWrapper`

macOS 및 Linux에서 [Claude Code가 시작하는 배경 프로세스](https://code.claude.com/docs/ko/corporate-launcher.md#what-the-launcher-covers) 앞에 회사 런처 명령을 배치합니다. Claude Code는 자체 명령줄이 추가된 런처를 실행하므로 런처는 Claude Code로 exec해야 합니다. [회사 런처 뒤에서 Claude Code 실행](https://code.claude.com/docs/ko/corporate-launcher.md)에서 런처 계약을 참조하세요. Claude Code v2.1.210 이상이 필요합니다.

* **Scope**: [`User or managed`](#scopes)
* **Type**: string, argv 접두사로서의 런처 명령(예: 선택적 인수가 있는 절대 경로)
* **Default**: 설정되지 않음. 배경 프로세스는 래핑되지 않은 상태로 시작됩니다
* **Per-session overrides**: [`CLAUDE_CODE_PROCESS_WRAPPER`](https://code.claude.com/docs/ko/env-vars)는 한 세션에 대해 이 키보다 우선합니다

```json settings.json theme={null}
{
  "processWrapper": "/opt/corp/launcher --profile claude"
}
```

Claude Code는 Windows에서 런처를 무시하고 모든 프로세스를 래핑되지 않은 상태로 시작합니다. Claude Code v2.1.210 이상이 필요합니다.

### `teammateMode`

Claude Code가 [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md) 팀원을 표시할 위치를 선택합니다: 메인 터미널 창 내부 또는 터미널이 지원할 때 분할 창에서. [디스플레이 모드 선택](https://code.claude.com/docs/ko/agent-teams.md#choose-a-display-mode)을 참조하세요.

* **Scope**: [`Any file`](#scopes). Claude Code는 또한 이전 버전에서 `~/.claude.json`에 남겨진 값을 읽습니다.
* **Type**: string, 다음 중 하나:
  * `"in-process"`: 팀원은 메인 터미널 창 내부에서 실행됩니다
  * `"auto"`: tmux 내부에서 실행 중이거나 `PATH`에 `it2`가 있거나 tmux가 설치된 iTerm2 내부에서 분할 창을 사용합니다. 그 외에는 인프로세스입니다
  * `"tmux"`: 터미널에서 감지된 tmux 또는 iTerm2를 사용하여 분할 창을 만듭니다
  * `"iterm2"`: iTerm2 네이티브 분할 창을 `it2` CLI를 통해 사용합니다
* **Default**: `"in-process"`
* **Per-session overrides**: `--teammate-mode`는 한 세션에 대해 이 키보다 우선합니다

```json settings.json theme={null}
{
  "teammateMode": "auto"
}
```

### `worktree`

Claude Code가 `--worktree`, `EnterWorktree` 도구 및 격리된 서브에이전트 및 배경 세션에 대해 [git worktrees](https://code.claude.com/docs/ko/worktrees.md)를 생성하고 관리하는 방식을 구성합니다.

* **Scope**: [`Any file`](#scopes)
* **Type**: `baseRef`, `symlinkDirectories`, `sparsePaths` 및 `bgIsolation`을 포함하는 객체
* **Default**: 설정되지 않음

이 예제는 현재 `HEAD`에서 새 worktree의 브랜치를 만들고 각 worktree에 `node_modules`의 심볼릭 링크를 만듭니다:

```json settings.json theme={null}
{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules"]
  }
}
```

`.env`와 같은 gitignored 파일을 새 worktrees에 복사하려면 설정 대신 프로젝트 루트에 [`.worktreeinclude` 파일](https://code.claude.com/docs/ko/worktrees#copy-gitignored-files-into-worktrees)을 추가합니다.

### `worktree.baseRef`

새 worktree의 브랜치가 시작될 ref를 선택합니다. `"fresh"`는 원격과 일치하는 깨끗한 트리를 위해 `origin/<default-branch>`에서 브랜치를 만듭니다. `"head"`는 현재 로컬 `HEAD`에서 브랜치를 만들므로 푸시되지 않은 커밋 및 기능 브랜치 상태가 worktree에 있습니다.

* **Scope**: [`Any file`](#scopes)
* **Type**: string, 다음 중 하나:
  * `"fresh"`: 새 worktree는 `origin/<default-branch>`에서 브랜치를 만듭니다
  * `"head"`: 새 worktree는 푸시되지 않은 커밋을 포함하여 현재 로컬 `HEAD`에서 브랜치를 만듭니다
* **Default**: `"fresh"`

```json settings.json theme={null}
{
  "worktree": {
    "baseRef": "head"
  }
}
```

연결된 worktree 내부에서 `"head"`는 메인 체크아웃이 아닌 해당 worktree의 `HEAD`로 확인됩니다.

### `worktree.symlinkDirectories`

메인 저장소의 디렉터리를 각 worktree에 심볼릭 링크로 연결하여 디스크에 큰 디렉터리를 복제하지 않습니다.

* **Scope**: [`Any file`](#scopes)
* **Type**: 문자열 배열, 저장소 루트에 상대적인 디렉터리 경로
* **Default**: 설정되지 않음. Claude Code는 디렉터리를 심볼릭 링크로 연결하지 않습니다

이 예제는 메인 저장소의 `node_modules` 및 `.cache`를 모든 새 worktree에 심볼릭 링크로 연결합니다:

```json settings.json theme={null}
{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}
```

### `worktree.sparsePaths`

git sparse-checkout를 통해 각 worktree에서 나열된 디렉터리만 체크아웃합니다. Claude Code는 해당 디렉터리와 루트 수준 파일만 디스크에 기록하므로 대규모 monorepos에서 더 빠릅니다. [필요한 디렉터리만 체크아웃](https://code.claude.com/docs/ko/large-codebases.md#check-out-only-the-directories-you-need)을 참조하세요.

* **Scope**: [`Any file`](#scopes)
* **Type**: 문자열 배열, 저장소 루트에 상대적인 디렉터리 경로
* **Default**: 설정되지 않음. 각 worktree는 전체 트리를 체크아웃합니다

이 예제는 각 worktree에서 `packages/my-app` 및 `shared/utils`와 루트 수준 파일만 체크아웃합니다:

```json settings.json theme={null}
{
  "worktree": {
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}
```

sparse worktree가 존재하는 동안 git은 저장소의 공유 `.git/config`에서 `extensions.worktreeConfig`를 활성화합니다.

### `worktree.bgIsolation`

[배경 세션](https://code.claude.com/docs/ko/agent-view.md#how-file-edits-are-isolated)이 파일 편집을 격리하는 방식을 선택합니다. `←` 또는 `/background`로 세션을 배경으로 옮긴 경우, 해당 세션은 이 키의 값과 관계없이 파일을 제자리에서 편집합니다. `"worktree"`를 사용하면 Claude Code는 세션이 `EnterWorktree`를 호출할 때까지 메인 체크아웃에서 `Edit` 및 `Write`를 차단합니다. `"none"`을 사용하면 배경 작업이 작업 복사본을 직접 편집합니다. git worktrees가 비실용적인 저장소의 경우 `"none"`을 설정합니다.

* **Scope**: [`Any file`](#scopes)
* **Type**: string, 다음 중 하나:
  * `"worktree"`: Claude Code는 세션이 `EnterWorktree`를 호출할 때까지 메인 체크아웃에서 `Edit` 및 `Write`를 차단합니다
  * `"none"`: 배경 작업이 작업 복사본을 직접 편집합니다
* **Default**: `"worktree"`

```json settings.json theme={null}
{
  "worktree": {
    "bgIsolation": "none"
  }
}
```

git 저장소 외부에서 실패하는 [`WorktreeCreate` 훅](https://code.claude.com/docs/ko/worktrees#non-git-version-control)은 차단을 해제하여 세션이 작업 디렉터리를 제자리에서 편집할 수 있도록 합니다.

### `worktree.location`

[Desktop SSH 세션](https://code.claude.com/docs/ko/desktop.md#choose-where-ssh-session-worktrees-go)이 `<project-root>/.claude/worktrees/` 대신 worktree를 생성할 원격 머신의 폴더를 선택합니다. 이 키는 데스크톱 앱만 읽습니다. `--worktree`, `EnterWorktree` 도구, 격리된 서브에이전트 및 배경 세션은 이 키를 무시합니다. Claude Desktop v1.44121.0 이상이 필요합니다.

* **Scope**: [`User`](#scopes), 원격 머신의 `~/.claude/settings.json`에서 설정
* **Type**: string, 절대 경로 또는 `~/`로 시작하는 경로
* **Default**: 설정되지 않음. worktree는 프로젝트 내부에 생성됩니다

이 예제는 폴더를 `~/worktrees`로 설정합니다:

```json settings.json theme={null}
{
  "worktree": {
    "location": "~/worktrees"
  }
}
```

Desktop에서 SSH 연결에 설정한 **Worktree folder**가 우선합니다. 조직에서 세션이 사용할 수 있는 폴더를 제한하는 경우 Desktop은 worktree를 프로젝트 내부에 유지합니다.

## 원격, 데스크톱 및 알림

Remote Control, 클라우드 환경, 데스크톱 앱, 그리고 Claude Code가 사용자의 응답이 필요할 때 보내는 알림을 구성합니다. [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 참조하십시오.

### `agentPushNotifEnabled`

긴 작업이 끝났을 때처럼 Claude가 보낼 가치가 있다고 판단하면 휴대폰으로 푸시 알림을 보낼 수 있도록 허용합니다. Claude는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)이 연결되어 있는 동안 알림을 보낼 수 있습니다. `/config`에는 **Push when Claude decides**로 표시됩니다. 그곳에서 값을 변경하면 Claude Code는 해당 값을 사용자의 계정에도 저장합니다.

* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전이 `~/.claude.json`에 남긴 값도 읽습니다.
* **유형**: Boolean
  * `true`: Claude가 보낼 가치가 있다고 판단하면 휴대폰으로 푸시 알림을 보낼 수 있습니다
  * `false`: Claude가 해당 알림을 보내지 않습니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "agentPushNotifEnabled": true
}
```

[`claude remote-control`](https://code.claude.com/docs/ko/remote-control#start-a-remote-control-session) 서버에서 세션을 실행하는 경우, 해당 세션은 이 키가 아니라 계정에 저장된 값을 따릅니다. 그 값을 변경하려면 터미널의 Claude Code 세션에서 `/config`를 실행하고 **Push when Claude decides**를 켜거나 끕니다. 토글이 이미 원하는 값을 표시하고 있다면, 값을 한 번 바꿨다가 다시 되돌려 Claude Code가 해당 값을 계정에 저장하도록 합니다.

[모바일 푸시 알림](https://code.claude.com/docs/ko/remote-control.md#mobile-push-notifications)을 참조하십시오.

### `awaySummaryEnabled`

몇 분간 자리를 비운 후 터미널로 돌아오면 한 줄짜리 세션 요약을 표시합니다. 요약을 중지하려면 `false`로 설정하거나 `/config`에서 **Session recap**을 끕니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: 몇 분간 자리를 비운 후 돌아오면 한 줄짜리 세션 요약이 표시됩니다
  * `false`: Claude Code가 요약을 표시하지 않습니다
* **기본값**: 설정되지 않음, 따라서 요약이 켜져 있습니다
* **세션별 재정의**: [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](https://code.claude.com/docs/ko/env-vars)는 한 세션에 대해 어느 방향으로든 이 키보다 우선합니다

```json settings.json theme={null}
{
  "awaySummaryEnabled": false
}
```

Claude Code는 비대화형 모드에서는 요약을 표시하지 않습니다.

### `disableArtifact`

> [!WARNING]
>
> Deprecated되었으며 [`enableArtifact`](#enableartifact)로 대체되었습니다. Claude Code는 여전히 `disableArtifact: true`를 `enableArtifact: false`와 동일하게 처리하며, `disableArtifact: false`는 무시합니다.

세션 출력을 claude.ai의 비공개 웹 페이지로 게시하는 [Artifact](https://code.claude.com/docs/ko/artifacts.md) 도구를 끄려면 대신 [`enableArtifact`](#enableartifact)를 사용하십시오. `/config`에서 **Artifacts** 행을 끄면 Claude Code는 사용자 설정에 `enableArtifact`를 기록하고 이 키를 제거합니다.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 해당 파일이 적용되는 모든 세션에서 Artifact 도구를 끄며, 다른 어떤 파일도 이를 다시 켤 수 없습니다
  * `false`: 무시됩니다. 도구를 켜 두려면 키를 제거합니다
* **기본값**: 설정되지 않음, 따라서 도구는 계정의 [사용 가능 여부](https://code.claude.com/docs/ko/artifacts.md#availability)를 따릅니다
* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_ARTIFACT`](https://code.claude.com/docs/ko/env-vars)를 `1`로 설정하면 한 세션에 대해 도구가 꺼집니다

```json settings.json theme={null}
{
  "disableArtifact": true
}
```

[아티팩트 비활성화](https://code.claude.com/docs/ko/artifacts.md#disable-artifacts)에는 도구를 끄는 모든 방법이 나와 있습니다.

### `disableDeepLinkRegistration`

Claude Code가 운영 체제에 `claude-cli://` 프로토콜 핸들러를 등록하지 않도록 합니다. 이 설정이 없으면 Claude Code는 대화형 세션의 첫 번째 프롬프트를 보낸 후 핸들러를 등록합니다. [딥 링크](https://code.claude.com/docs/ko/deep-links.md)를 사용하면 외부 도구가 미리 채워진 프롬프트로 Claude Code 세션을 열 수 있습니다. 프로토콜 핸들러 등록이 제한되거나 별도로 관리되는 환경에서 이 값을 설정하십시오.

* **범위**: [`Any file`](#scopes)
* **유형**: 문자열 `"disable"`
* **기본값**: 설정되지 않음, 따라서 Claude Code가 핸들러를 등록합니다

```json settings.json theme={null}
{
  "disableDeepLinkRegistration": "disable"
}
```

### `disableDesktopLocalSessions`

개발자가 SSH를 통해 원격 머신에서 작업해야 하는 배포 환경을 위해, [데스크톱 앱](https://code.claude.com/docs/ko/desktop.md#local-sessions-on-managed-devices)에서 기기 자체에서 실행되는 Code 세션을 끕니다. 키를 `true`로 설정하면 사용자는 Code 탭에서 다음과 같은 내용을 보게 됩니다.

* **환경 선택기**: 사용자의 컴퓨터 항목이 회색으로 표시되어 선택할 수 없으며, **Disabled by your organization**이라는 툴팁이 표시됩니다. Windows에서는 WSL 항목도 같은 방식으로 회색으로 표시되지만, 관리형 기기에서 WSL 세션이 실행될 수 있는지 여부는 [별도로 관리됩니다](https://code.claude.com/docs/ko/admin-setup.md#wsl-sessions-in-claude-code-desktop).
* **새 세션**: 구성된 [SSH 연결](https://code.claude.com/docs/ko/desktop.md#ssh-sessions)이 있으면 첫 번째 연결이 기본값이 됩니다
* **기기에서의 세션**: 앱이 기기에서 세션을 시작하거나 재개하는 것을 거부하며, 같은 머신으로 다시 연결하는 SSH 연결도 포함됩니다
* **다른 호스트로의 SSH 세션 및 클라우드 세션**: 영향을 받지 않습니다

이 키는 데스크톱 앱이 읽으며, 터미널 CLI는 무시합니다. Claude Desktop v1.37937.0 이상이 필요합니다.

* **범위**: [`Managed`](#scopes). 기본적으로 데스크톱 앱은 [하나의 관리형 소스](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)에서 키를 읽습니다.
* **유형**: Boolean. JSON Boolean `true`만 효력이 있습니다
  * `true`: 데스크톱 앱이 기기 내 Code 세션을 제공하지 않습니다. 기존 로컬 세션은 목록에 남아 있지만 계속할 수 없습니다
  * `false`: 로컬 세션을 계속 사용할 수 있습니다
* **기본값**: 설정되지 않음, 따라서 로컬 세션을 사용할 수 있습니다

```json managed-settings.json theme={null}
{
  "disableDesktopLocalSessions": true
}
```

데스크톱 앱은 다른 값은 무시하며, 문자열 `"true"`나 `1`처럼 Boolean이 아닌 값은 경고도 로그에 기록합니다. 사용자가 작동하는 연결로 바로 이동할 수 있도록 [`sshConfigs`](#sshconfigs)와 함께 사용하고, 접근할 수 있는 호스트를 제한하려면 [`sshHostAllowlist`](#sshhostallowlist)와 함께 사용하십시오. [관리형 기기의 로컬 세션](https://code.claude.com/docs/ko/desktop.md#local-sessions-on-managed-devices)을 참조하십시오.

Claude Desktop은 데스크톱 구성에서 파생된 정책(예: 서드파티 배포의 송신 허용 목록, 파일 시스템 샌드박스, MCP 제한)을 Code 세션에 제공합니다. Claude Code는 서버 관리형 설정, MDM 또는 OS 수준 정책, 관리형 설정 파일 등 [관리자 소스](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)가 있을 때마다 이러한 상위 설정을 무시합니다. 따라서 서드파티 배포에서처럼 이전에 관리자 소스가 없던 기기에 이러한 관리자 소스 중 하나를 통해 이 키를 배포하면, 데스크톱에서 파생된 정책이 더 이상 적용되지 않습니다. 상위 설정이 여전히 병합될 수 있는 경우는 [임베딩 호스트가 정책을 추가하도록 허용](https://code.claude.com/docs/ko/managed-settings.md#let-an-embedding-host-add-policy)에서 다룹니다. 이는 이 키뿐만 아니라 그런 방식으로 배포하는 모든 키에 해당합니다.

### `disableRemoteControl`

[Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 끕니다. 그러면 Claude Code는 `claude remote-control`, `--remote-control` 플래그, 자동 시작, 세션 내 토글을 거부하고 조직의 정책에 의해 비활성화되었다고 알립니다. 기기별 MDM 적용을 위해 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)에 배치하십시오.

* **범위**: [`Any file`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 `claude remote-control`, `--remote-control` 플래그, 자동 시작, 세션 내 토글을 거부합니다
  * `false`: Remote Control을 계속 사용할 수 있습니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "disableRemoteControl": true
}
```

### `enableArtifact`

세션 출력을 claude.ai의 비공개 웹 페이지로 게시하는 [Artifact](https://code.claude.com/docs/ko/artifacts.md) 도구를 끕니다. `/config`에서 **Artifacts** 행을 끄면 Claude Code가 이 키를 사용자 설정에 기록하므로, 일반적으로 직접 편집할 필요는 없습니다.

* **범위**: [`Any file`](#scopes). 모든 파일이 도구를 끌 수 있지만, 어떤 파일도 다시 켤 수는 없습니다.
* **유형**: Boolean
  * `false`: Claude Code가 해당 파일이 적용되는 모든 세션에서 Artifact 도구를 끕니다
  * `true`: 키를 설정하지 않은 것과 같습니다. 다른 파일, [`CLAUDE_CODE_DISABLE_ARTIFACT`](https://code.claude.com/docs/ko/env-vars), 또는 조직의 [관리자 설정](https://code.claude.com/docs/ko/artifacts.md#manage-artifacts-for-your-organization)에서 온 `false`를 절대 재정의하지 않기 때문입니다
* **기본값**: 설정되지 않음, 따라서 도구는 계정의 [사용 가능 여부](https://code.claude.com/docs/ko/artifacts.md#availability)를 따릅니다

```json settings.json theme={null}
{
  "enableArtifact": false
}
```

사용자 본인의 사용자 설정이 아닌 다른 소스가 도구를 꺼 둔 상태로 유지하는 동안에는, `/config`에서 켜더라도 아무것도 바뀌지 않으므로 Claude Code가 `/config`의 **Artifacts** 행을 숨깁니다. [아티팩트 비활성화](https://code.claude.com/docs/ko/artifacts.md#disable-artifacts)에는 도구를 끄는 모든 방법이 나와 있습니다.

### `inputNeededNotifEnabled`

권한 프롬프트나 질문이 사용자의 입력을 기다리고 있을 때 휴대폰으로 푸시 알림을 받습니다. Claude Code는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)이 연결되어 있는 동안에만 이 알림을 보냅니다. `/config`에는 **Push when actions required**로 표시됩니다.

* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전이 `~/.claude.json`에 남긴 값도 읽습니다.
* **유형**: Boolean
  * `true`: Remote Control이 연결되어 있는 동안 권한 프롬프트나 질문이 대기 중이면 휴대폰으로 푸시 알림을 받습니다
  * `false`: Claude Code가 이러한 알림을 보내지 않습니다
* **기본값**: `false`

```json settings.json theme={null}
{
  "inputNeededNotifEnabled": true
}
```

[모바일 푸시 알림](https://code.claude.com/docs/ko/remote-control.md#mobile-push-notifications)을 참조하십시오.

### `preferredNotifChannel`

작업이 완료되거나 권한 프롬프트가 대기 중일 때 Claude Code가 알림을 보내는 방식을 선택합니다. [mod의 알림](https://code.claude.com/docs/ko/plugins/mods/api.md#show-something-without-starting-a-turn)도 같은 설정을 사용합니다. `/config`에는 **Local notifications**로 표시됩니다.

* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전이 `~/.claude.json`에 남긴 값도 읽습니다.
* **유형**: 문자열, 다음 중 하나:
  * `"auto"`: Claude Code가 iTerm2, Ghostty, Kitty에서는 데스크톱 알림을 보내고, Terminal.app에서는 가청 벨이 꺼져 있을 때만 벨을 울리며, 그 외에서는 아무것도 하지 않습니다
  * `"terminal_bell"`: Claude Code가 모든 터미널에서 벨 문자를 울립니다
  * `"iterm2"`: Claude Code가 iTerm2 데스크톱 알림을 보냅니다
  * `"iterm2_with_bell"`: Claude Code가 iTerm2 데스크톱 알림을 보내고 벨을 울립니다
  * `"kitty"`: Claude Code가 Kitty 데스크톱 알림을 보냅니다
  * `"ghostty"`: Claude Code가 Ghostty 데스크톱 알림을 보냅니다
  * `"notifications_disabled"`: Claude Code가 알림을 보내지 않습니다
* **기본값**: `"auto"`

```json settings.json theme={null}
{
  "preferredNotifChannel": "terminal_bell"
}
```

`"auto"`를 사용하면 Claude Code는 iTerm2, Ghostty, Kitty에서 데스크톱 알림을 보냅니다. Terminal.app에서는 Terminal의 가청 벨을 꺼 둔 경우에만 벨 문자를 울리며, 다른 터미널에서는 아무것도 하지 않습니다. 모든 터미널에서 벨 문자를 울리려면 `"terminal_bell"`로 설정하십시오. [터미널 벨 또는 알림 받기](https://code.claude.com/docs/ko/terminal-config.md#get-a-terminal-bell-or-notification)를 참조하십시오.

### `remote.defaultEnvironmentId`

`claude --cloud` 등으로 CLI에서 생성하는 클라우드 세션의 기본 [클라우드 환경](https://code.claude.com/docs/ko/cloud-environments.md)을 선택합니다. [`/remote-env`](https://code.claude.com/docs/ko/cloud-environments#select-an-environment-from-the-cli)로 환경을 선택하면 Claude Code가 이 키를 사용자 설정에 기록합니다.

* **범위**: [`Any file`](#scopes). 자체 호스팅 환경 ID의 경우 사용자 설정 또는 관리형 설정, 또는 `--settings` 플래그에서만 적용됩니다.
* **유형**: 문자열, `env_...` 또는 `ccpool_...`과 같은 환경 ID
* **기본값**: 설정되지 않음, 따라서 Claude Code는 목록에 Anthropic 호스팅 환경이 있으면 이를 사용하고, 없으면 목록에서 [Remote Control 브리지 환경](https://code.claude.com/docs/ko/cloud-environments.md#the-default-environment)이 아닌 첫 번째 환경을, 모든 환경이 브리지 환경이면 첫 번째 환경을 사용합니다
* **세션별 재정의**: `--environment`는 해당 플래그가 생성하는 하나의 클라우드 세션에 대해 이 키보다 우선합니다

```json settings.json theme={null}
{
  "remote": {
    "defaultEnvironmentId": "env_0123abcd"
  }
}
```

`env_`로 시작하는 Anthropic 호스팅 환경 ID는 표준 설정 우선순위를 따르므로, 저장소의 프로젝트 설정에 있는 값이 사용자 수준에서 선택한 값을 재정의합니다. `ccpool_`로 시작하는 [자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments) ID는 사용자 설정, 관리형 설정, `--settings` 플래그에서만 적용됩니다. Claude Code는 저장소의 프로젝트 설정이나 로컬 설정에 있는 해당 ID를 무시하고 `/remote-env`는 어떤 값이 무시되었는지 표시하므로, 체크인된 파일이 사용자가 선택하지 않은 자체 호스팅 환경으로 세션을 유도할 수 없습니다.

### `remoteControlAtStartup`

`/remote-control`을 기다리지 않고 각 대화형 세션이 시작될 때 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 자동으로 연결합니다. 자동 연결을 켜려면 `true`로, 끄려면 `false`로 설정하십시오. `/config`에는 **Enable Remote Control for all sessions**로 표시됩니다.

* **범위**: [`Any file`](#scopes). Claude Code는 이전 버전이 `~/.claude.json`에 남긴 값도 읽습니다.
* **유형**: Boolean
  * `true`: Claude Code가 각 대화형 세션이 시작될 때 Remote Control을 자동으로 연결합니다
  * `false`: Claude Code가 `/remote-control`을 기다립니다
* **기본값**: 설정되지 않음, 따라서 [자동 연결 기본값](https://code.claude.com/docs/ko/remote-control.md#enable-remote-control-for-all-sessions)이 적용됩니다
* **세션별 재정의**: `--remote-control`은 이 키가 `false`인 경우에도 한 세션에 대해 Remote Control을 켜며, 한 세션에 대해 이를 끄는 플래그는 없습니다

```json settings.json theme={null}
{
  "remoteControlAtStartup": true
}
```

Claude Code는 프로젝트 설정이나 로컬 설정의 `true`를 무시하므로, 저장소는 자신의 체크아웃에 대해 자동 연결을 끌 수는 있지만 켤 수는 없습니다. 범위별 전체 동작은 [모든 세션에 Remote Control 활성화](https://code.claude.com/docs/ko/remote-control.md#enable-remote-control-for-all-sessions) 및 [더 엄격한 값이 적용되는 보안 키](https://code.claude.com/docs/ko/settings.md#security-keys-where-the-stricter-value-applies)를 참조하십시오.

### `sshConfigs`

[Desktop](https://code.claude.com/docs/ko/desktop.md#pre-configure-ssh-connections-for-your-team) 환경 선택기에 SSH 연결을 추가합니다. 관리자는 `sshConfigs`를 사용하여 팀에 공유 연결을 배포합니다. 사용자는 관리형 연결을 선택하고 해당 연결에 대해 [자신만의 **Worktree folder**를 설정](https://code.claude.com/docs/ko/desktop.md#set-the-worktree-folder-on-an-existing-connection)할 수 있습니다. 앱에서 다른 필드를 편집하거나 연결을 삭제할 수는 없습니다.

* **범위**: [`User or managed`](#scopes). 이 키는 데스크톱 앱이 읽습니다. 기본적으로 데스크톱 앱은 [하나의 관리형 소스](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)에서 관리형 연결을 읽습니다.
* **유형**: 객체 배열. 각 객체에는 필수 항목 `id`, `name`, `sshHost`와 선택 항목 `sshPort`, `sshIdentityFile`이 있습니다
* **기본값**: 설정되지 않음

다음 예시는 `user@dev.example.com`에 연결하는 `Dev VM`이라는 연결 하나를 추가합니다.

```json settings.json theme={null}
{
  "sshConfigs": [
    {
      "id": "dev-vm",
      "name": "Dev VM",
      "sshHost": "user@dev.example.com"
    }
  ]
}
```

### `sshHostAllowlist`

[Desktop SSH 세션](https://code.claude.com/docs/ko/desktop.md#restrict-which-ssh-hosts-users-can-connect-to)이 연결할 수 있는 호스트를 제한합니다. 이 키는 Desktop 앱만 읽으며, CLI는 읽지 않습니다. 패턴은 대소문자를 구분하지 않습니다. `*`는 모든 호스트와 일치하고, `*.example.com`은 `example.com` 및 모든 하위 도메인과 일치하며, 그 밖의 값은 `~/.ssh/config` 해석 후의 호스트 이름과 정확히 일치해야 합니다. 빈 배열은 SSH 세션을 끕니다.

Claude Desktop v3.1623.0 이상에서는 세션의 [점프 호스트](https://code.claude.com/docs/ko/desktop.md#allow-jump-hosts)도 패턴과 일치해야 합니다.

* **범위**: [`Managed`](#scopes). 기본적으로 Desktop은 [하나의 관리형 소스](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)에서 키를 읽습니다.
* **유형**: 호스트 이름 패턴 배열
* **기본값**: 설정되지 않음, 따라서 모든 호스트가 허용됩니다

다음 예시는 `devboxes.example.com`과 그 하위 도메인, 그리고 정확한 호스트 `bastion.example.com`을 허용합니다.

```json managed-settings.json theme={null}
{
  "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"]
}
```

`true`나 객체처럼 Desktop이 호스트 목록으로 읽을 수 없는 값은 수정하기 전까지 빈 배열로 간주되며, 단 `null`은 설정되지 않은 것으로 간주됩니다. Claude Desktop v2.26454.0 이상이 필요합니다.

가장 높은 순위의 소스에서 [`managedSourcesBehavior`](#managedsourcesbehavior)를 `"merge"`로 설정하면, Desktop은 모든 [관리자 소스](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)의 목록을 결합하고 그중 하나라도 일치하는 호스트를 허용합니다. 한 소스에서 빈 배열을 설정하더라도 다른 소스에 나열된 호스트에 대해서는 SSH 세션이 계속 켜져 있습니다.

### `sshHostCommands`

호스트를 명령에서 가져오는 SSH 연결을 [Desktop](https://code.claude.com/docs/ko/desktop.md#create-an-ssh-connection-from-a-command) 환경 선택기에 추가합니다. 연결을 생성하거나 연결의 호스트를 교체하면 Desktop은 사용자의 컴퓨터에서 해당 항목의 명령을 실행하고, 명령이 출력하는 호스트에 연결합니다. macOS 또는 Linux에서 Claude 계정으로 로그인한 Claude Desktop v3.6556.0 이상이 필요합니다.

* **범위**: [`User or managed`](#scopes). 이 키는 데스크톱 앱만 읽습니다. 관리형 항목은 컴퓨터의 [하나의 관리형 설정 파일 또는 MDM 정책](https://code.claude.com/docs/ko/desktop.md#distribute-commands-to-your-team)에서 읽으며, [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)에 있는 키는 무시합니다.
* **유형**: 객체 배열. 각 객체에는 필수 항목 `id`, `name`, `command`와 선택 항목 `sshIdentityFile`, `startDirectory`가 있습니다. Desktop은 셸 없이 `command`를 시작하므로, [프로그램과 일반 인수 형태로 작성](https://code.claude.com/docs/ko/desktop.md#write-the-command)하십시오.
* **기본값**: 설정되지 않음

다음 예시는 `Dev box`라는 연결 하나를 추가하며, 여기서 `acme-dev create`는 사용자 자신의 도구를 나타냅니다.

```json settings.json theme={null}
{
  "sshHostCommands": [
    {
      "id": "devbox",
      "name": "Dev box",
      "command": "acme-dev create"
    }
  ]
}
```

Claude Code v2.1.307 이전에는 Edit 도구가 유효한 설정 파일에 이 키를 추가하는 변경을 `Unrecognized field: sshHostCommands` 오류와 함께 거부했습니다. 해당 버전에서는 대신 텍스트 편집기에서 키를 추가하십시오. Claude Code는 이 키가 포함된 파일을 정상적으로 로드합니다. Desktop에서는 터미널의 버전이 아니라 [Code 탭의 Claude Code 버전](https://code.claude.com/docs/ko/desktop.md#claude-code-version-in-the-code-tab)이 기준이 됩니다.

## 인증 및 공급자

도우미 스크립트를 통해 자격 증명을 제공하고, 조직의 경우 로그인 방법이나 조직을 강제합니다. [인증](https://code.claude.com/docs/ko/authentication.md)을 참조하세요.

### `allowedProviders`

머신이 Claude에 도달할 수 있는 서비스를 나열합니다. 예를 들어 Anthropic API, Amazon Bedrock, 또는 LLM 게이트웨이입니다. 나열되지 않은 공급자의 세션은 시작 시, 로그인 시, API에 다음으로 연락할 때 거부되므로 세션 중간에 나열되지 않은 공급자로 전환하는 것도 거부됩니다. [거부 메시지](https://code.claude.com/docs/ko/errors.md#managed-settings-dont-allow-this-api-provider)는 공급자를 선택한 것과 계속하는 단계를 이름 지정합니다. Claude Code v2.1.285 이상이 필요합니다.

* **범위**: [`관리됨`](#scopes). 머신 자신의 관리자 소스인 MDM 정책 및 관리형 설정 파일이 설정한 목록은 서버 관리형 설정도 하나를 전달할 때 계속 적용됩니다: 세션은 두 목록 모두에 있는 공급자만 사용할 수 있으므로 서버 관리형 목록은 머신이 허용하는 것을 좁힐 수 있지만 절대 확장할 수 없습니다. 어느 머신 소스의 `allowedProviders`가 계산되는지는 [Claude Code가 관리 소스를 결합하는 방법](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)을 따릅니다. 서버 관리형 설정만을 통해 전달된 목록은 [서버 관리형 설정을 가져오는](https://code.claude.com/docs/ko/server-managed-settings.md#platform-availability) 세션에만 도달합니다.
* **유형**: 문자열 배열, 각각 다음 중 하나:
  * `"anthropic"`: Anthropic의 자체 호스트의 Anthropic API, claude.ai 또는 Console 로그인 또는 API 키를 통해. [`forceLoginMethod`](#forceloginmethod) 또는 [`forceLoginOrgUUID`](#forceloginorguuid)와 쌍을 이루어 로그인도 제한합니다.
  * `"bedrock"`: [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md)
  * `"vertex"`: [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md), 이전의 Vertex AI
  * `"foundry"`: [Microsoft Foundry](https://code.claude.com/docs/ko/microsoft-foundry.md)
  * `"anthropicAws"`: [AWS의 Claude Platform](https://code.claude.com/docs/ko/claude-platform-on-aws.md)
  * `"mantle"`: Amazon Bedrock [Mantle 엔드포인트](https://code.claude.com/docs/ko/amazon-bedrock.md#use-the-mantle-endpoint). [Mantle을 Invoke API와 함께 실행](https://code.claude.com/docs/ko/amazon-bedrock.md#run-mantle-alongside-the-invoke-api)하는 세션은 두 공급자를 모두 사용하므로 `"bedrock"`과 `"mantle"`을 함께 나열합니다.
  * `"customEndpoint"`: Anthropic API 또는 클라우드 공급자의 API를 다른 호스트로 보냅니다. 예를 들어 `ANTHROPIC_BASE_URL` 또는 `ANTHROPIC_BEDROCK_BASE_URL`과 같은 공급자의 엔드포인트 변수로 이름 지정된 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)입니다. Claude Code는 관리 [`env`](#env) 블록이 고정한 정확한 값에 대해서만 이를 허용합니다.
  * `"gateway"`: [클라우드 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway) 로그인
* **기본값**: 설정되지 않음, 따라서 모든 공급자를 사용할 수 있습니다.

```json managed-settings.json theme={null}
{
  "allowedProviders": ["anthropic", "bedrock"]
}
```

각 클라우드 공급자의 항목은 해당 공급자의 자체 서비스를 의미합니다. 지역, FIPS, 및 개인 엔드포인트를 포함합니다.

Claude Code가 공급자 이름으로 인식하지 않는 항목은 삭제되고 보고되며, 목록의 나머지는 강제됩니다. 빈 목록이거나 모든 항목이 인식되지 않는 목록의 경우, Claude Code는 모든 공급자를 거부하고 머신에서 시작하지 않습니다.

#### 관리 `env`에서 핀이 필요한 엔드포인트

핀은 관리 [`env`](#env) 블록에 설정된 엔드포인트 변수의 값입니다. 세션이 공급자의 트래픽을 해당 공급자의 자체 서비스 이외의 곳으로 보낼 때, Claude Code는 세션의 값이 핀과 동일한 경우에만 이를 허용합니다. 이러한 엔드포인트에는 하나가 필요합니다:

* **`"customEndpoint"` 세션**: 호스트를 이름 지정하는 변수, 예를 들어 `ANTHROPIC_BASE_URL`
* **Amazon Bedrock**: AWS SDK의 `AWS_ENDPOINT_URL`, `AWS_ENDPOINT_URL_BEDROCK`, 및 `AWS_ENDPOINT_URL_BEDROCK_RUNTIME` 변수는 Bedrock의 자체 서비스 외부를 가리킬 때입니다. 세션은 `"customEndpoint"` 대신 `"bedrock"` 아래에 머물러 있습니다.
* **게이트웨이 로그인의 URL**: 세션은 `"gateway"` 아래에 머물러 있으며, [`forceLoginGatewayUrl`](#forcelogingatewayurl)도 핀으로 계산됩니다.

어느 `env` 블록이 핀으로 계산되는지는 목록이 설정된 위치에 따라 다릅니다:

* **머신의 관리자 소스가 목록을 설정합니다**: 머신의 자체 관리자 소스의 `env` 블록만 계산됩니다.
* **서버 관리형 설정만 목록을 설정합니다**: 해당 서버 관리형 설정의 `env` 값도 계산됩니다.

목록은 클라우드 공급자의 자격 증명 및 테넌시 변수 또는 `HTTPS_PROXY` 및 인증서 설정과 같은 네트워크 경로를 판단하지 않습니다. 관리 `env` 블록에서 플릿에 대해 이를 설정합니다.

### `apiKeyHelper`

Claude Code가 모델 요청과 함께 보내는 자격 증명을 생성하기 위해 자신의 명령을 실행합니다. Claude Code는 macOS 및 Linux에서는 `/bin/sh`를, Windows에서는 `cmd`를 통해 시스템 셸을 통해 명령을 실행하고, 그 출력을 `X-Api-Key` 및 `Authorization: Bearer` 헤더 모두로 보냅니다. 자격 증명 모음에서 가져온 단기 토큰과 같은 동적 또는 회전하는 자격 증명에 사용합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열, 셸 명령줄
* **기본값**: 설정되지 않음, 따라서 Claude Code는 도우미를 실행하지 않습니다.

```json settings.json theme={null}
{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh"
}
```

Claude Code는 값을 캐시하고 다음 경우에 명령을 다시 실행합니다:

* 캐시 수명 후, 기본값은 5분이거나 [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](https://code.claude.com/docs/ko/env-vars)로 설정한 간격입니다.
* Anthropic API에 대한 요청이 직접 또는 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 통해 `401` 또는 `403`으로 실패할 때입니다.
* Anthropic API에 요청을 보내기 전에, 직접 또는 LLM 게이트웨이를 통해, 캐시된 출력이 도우미가 생성한 후 만료된 JWT일 때입니다. Claude Code v2.1.246 이상이 필요합니다.

마지막 두 경우는 도우미의 출력이 Claude Code가 보내는 자격 증명이고 `ANTHROPIC_AUTH_TOKEN`이 설정되지 않았을 때만 적용됩니다.

대화형 세션에서, 명령이 프로젝트 또는 로컬 설정에서 올 때, Claude Code는 워크스페이스 신뢰 프롬프트를 수락할 때까지 실행하지 않습니다. [자격 증명 관리](https://code.claude.com/docs/ko/authentication.md#credential-management)를 참조하세요.

### `awsAuthRefresh`

Claude Code가 [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md)에 대해 가진 자격 증명이 작동을 멈출 때 `.aws` 디렉토리의 자격 증명을 새로 고치기 위해 `aws sso login`과 같은 자신의 명령을 실행합니다. Claude Code는 먼저 현재 자격 증명을 STS에 대해 확인하고 해당 확인이 실패할 때만 명령을 실행한 다음 새로 고쳐진 `.aws` 디렉토리를 읽습니다.

별도의 터미널이나 IDE 창과 같이 동일한 명령과 자격 증명을 사용하는 여러 Claude Code 프로세스에서 동시에 확인이 실패하면, 한 프로세스가 명령을 실행하고 나머지는 각자 실행을 시작하는 대신 해당 실행을 기다립니다. 요청이 대기 중인 상태로 60초 동안 기다린 프로세스는 직접 명령을 실행합니다. 이를 끄려면 [`CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK`](https://code.claude.com/docs/ko/env-vars)을 `1`로 설정하세요.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열, 셸 명령줄
* **기본값**: 설정되지 않음, 따라서 Claude Code는 AWS 자격 증명을 새로 고치지 않습니다.

```json settings.json theme={null}
{
  "awsAuthRefresh": "aws sso login --profile myprofile"
}
```

새로 고침 흐름이 `.aws`에 쓸 때 이 키를 사용하세요. 대신 자격 증명을 인쇄할 때는 [`awsCredentialExport`](#awscredentialexport)를 사용하세요. [고급 자격 증명 구성](https://code.claude.com/docs/ko/amazon-bedrock.md#advanced-credential-configuration)을 참조하세요.

### `awsCredentialExport`

Claude Code가 `.aws` 디렉토리에 없는 자격 증명으로 [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md)을 호출할 수 있도록 AWS 자격 증명을 JSON으로 인쇄하는 자신의 명령을 실행합니다. Claude Code는 `aws sts` 출력 형태와 평면 `aws configure export-credentials` 형태를 수락하고, 자격 증명을 자신의 Bedrock 클라이언트로 범위를 지정하므로 Claude가 실행하는 셸 명령은 여전히 주변 자격 증명을 봅니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열, 셸 명령줄
* **기본값**: 설정되지 않음, 따라서 Claude Code는 주변 AWS 자격 증명 체인을 사용합니다.

```json settings.json theme={null}
{
  "awsCredentialExport": "/bin/generate_aws_grant.sh"
}
```

[`awsAuthRefresh`](#awsauthrefresh)와 달리, Claude Code는 이 명령이 설정되면 먼저 주변 자격 증명을 확인하지 않고 항상 실행합니다. [고급 자격 증명 구성](https://code.claude.com/docs/ko/amazon-bedrock.md#advanced-credential-configuration)을 참조하세요.

### `forceLoginMethod`

사람들이 로그인할 수 있는 계정 종류를 제한합니다. `"claudeai"`로 설정하여 claude.ai 계정만 허용하거나, `"console"`로 설정하여 Claude Console 계정만 허용하거나, `"gateway"`로 설정하여 사람들을 첫 번째 당사자 로그인 대신 [클라우드 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)로 보냅니다. 관리자는 관리형 설정에서 설정하고 [`forceLoginOrgUUID`](#forceloginorguuid)와 쌍을 이루어 개발자의 claude.ai 로그인을 한 조직 내에 유지합니다. 설정 파일에서 `"claudeai"` 또는 `"console"`로 설정하면, Claude Code는 해당 파일이 적용되는 세션에서 [키 없는 Console 로그인](https://code.claude.com/docs/ko/authentication.md#sign-in-without-an-api-key)도 제공하지 않습니다.

* **범위**: [`모든 파일`](#scopes). Claude Code는 [`forceLoginGatewayUrl`](#forcelogingatewayurl)과 동일한 소스에서만 `"gateway"`를 인정하며, 그 외의 모든 곳에서는 설정되지 않은 것으로 취급합니다.
* **유형**: 문자열, 다음 중 하나:
  * `"claudeai"`: claude.ai 계정만 로그인할 수 있습니다.
  * `"console"`: Claude Console 계정만 로그인할 수 있습니다.
  * `"gateway"`: Claude Code는 사람들을 첫 번째 당사자 로그인 대신 클라우드 게이트웨이로 보냅니다.
* **기본값**: 설정되지 않음, 따라서 사람들이 로그인 방법을 선택합니다.

```json settings.json theme={null}
{
  "forceLoginMethod": "claudeai"
}
```

모든 첫 번째 당사자 로그인 경로는 [VS Code 확장](https://code.claude.com/docs/ko/vs-code.md), Agent SDK, `claude setup-token`, 및 `/install-github-app`을 포함한 제한을 적용하며, 터미널의 대화형 로그인 화면은 제외하고, `/login` 또는 첫 실행 온보딩으로 도달하며, 이는 강제하지 않고 방법을 미리 선택합니다. v2.1.212 이전에는 터미널 로그인만 적용했습니다. [조직에 로그인 제한](https://code.claude.com/docs/ko/authentication.md#restrict-login-to-your-organization)을 참조하여 각 로그인 경로, 환경 자격 증명, 및 제3자 공급자가 어떻게 처리되는지 확인하세요.

머신의 관리 소스가 `"gateway"`를 설정하면, Claude Code는 남은 로그인, API 키, 또는 `apiKeyHelper` 자격 증명을 사용하지 않습니다. [관리자 정책이 클라우드 게이트웨이 로그인을 요구합니다](https://code.claude.com/docs/ko/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)를 참조하여 각각이 생성하는 메시지를 확인하세요. `CLAUDE_CODE_USE_BEDROCK` 또는 유사한 환경 변수를 통해 클라우드 공급자를 선택하면, 세션은 게이트웨이 로그인이 필요하지 않습니다. v2.1.261 이전에는 Claude Code가 이러한 머신에서 남은 로그인을 사용했습니다.

### `forceLoginGatewayUrl`

`/login` 클라우드 게이트웨이 화면이 연결하는 게이트웨이 URL을 설정하여 사람들이 주소를 입력하지 않고 [클라우드 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)에 도달하도록 합니다. 화면에는 URL 필드가 없습니다: 이 키가 설정되면, 게이트웨이 URL을 표시하고 사람이 Enter를 누르면 연결합니다. 없으면, IT 관리자에게 문의하도록 알립니다.

관리형 설정에서는 이 키 또는 `forceLoginMethod: "gateway"` 중 하나가 `CLAUDE_CODE_USE_*`로 클라우드 공급자를 선택하는 세션을 제외하고 머신을 게이트웨이 전용으로 만듭니다. 그러면 `/login`은 로그인 방법 선택기 없이 클라우드 게이트웨이 화면에서 열립니다. [관리자 정책이 클라우드 게이트웨이 로그인을 요구합니다](https://code.claude.com/docs/ko/errors.md#administrator-policy-requires-a-cloud-gateway-sign-in)를 참조하여 남은 첫 번째 당사자 로그인 또는 API 키에 어떤 일이 발생하는지 확인하세요. 화면이 오류를 표시하는 대신 연결하도록 두 키를 모두 설정하세요.

* **범위**: [`사용자 또는 관리됨`](#scopes). 머신의 관리 소스에서 읽습니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 도우미. 이 중 어느 것도 없는 머신에서는 Claude Code v2.1.295 이상이 [사용자 설정](https://code.claude.com/docs/ko/claude-apps-gateway#set-the-gateway-url-in-user-settings)에서도 이 키를 읽습니다. Claude Code는 HKCU 및 서버 관리형 설정에서 무시합니다.
* **유형**: 문자열, 스키마를 포함한 전체 URL
* **기본값**: 설정되지 않음, 따라서 클라우드 게이트웨이 화면은 IT 관리자에게 문의하도록 알리는 오류를 표시합니다.

```json managed-settings.json theme={null}
{
  "forceLoginGatewayUrl": "https://claude-gateway.example.com"
}
```

값이 유효한 URL이 아니면, 로그인 화면이 보고하고, 관리형 설정 파일의 나머지는 여전히 적용됩니다. [게이트웨이 URL 설정](https://code.claude.com/docs/ko/claude-apps-gateway#set-the-gateway-url)을 참조하세요.

### `forceLoginOrgUUID`

관리 소스에서, claude.ai 계정 로그인이 단일 UUID로 지정된 하나의 Anthropic 조직에 속하거나 배열로 지정된 여러 조직 중 하나에 속하도록 요구합니다. 모든 설정 파일에서, Claude Code는 또한 단일 UUID를 사용하여 claude.ai 또는 Claude Console 로그인 중에 해당 조직을 미리 선택하고, 배열의 경우 아무것도 미리 선택하지 않습니다. 설정 파일에서 키를 설정하면, Claude Code는 또한 해당 파일이 적용되는 세션에서 [키 없는 Console 로그인](https://code.claude.com/docs/ko/authentication.md#sign-in-without-an-api-key)을 제공하지 않고 대신 API 키를 생성합니다.

* **범위**: [`모든 파일`](#scopes). 관리 소스만 제한을 강제합니다. 다른 설정 파일의 단일 UUID는 제한하지 않고 로그인 중에 조직을 미리 선택합니다.
* **유형**: 문자열, 하나의 UUID, 또는 문자열 배열, 여러 UUID
* **기본값**: 설정되지 않음, 따라서 모든 조직이 로그인할 수 있습니다.

이 예제는 하나를 미리 선택하지 않고 두 조직 중 하나에서 로그인을 수락합니다:

```json managed-settings.json theme={null}
{
  "forceLoginOrgUUID": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]
}
```

관리 소스가 빈 배열 또는 문자열이나 문자열 배열이 아닌 값을 설정하면, Anthropic 계정으로 로그인하는 사용자는 Claude Code를 시작하거나 로그인을 완료할 수 없습니다. 이 경우 `forceLoginOrgUUID`를 명시하고 관리자에게 문의하도록 안내하는 메시지가 표시됩니다. 잘못된 유형의 값을 내보내는 [`policyHelper`](#policyhelper)는 대신 [실행에 실패합니다](#helper-failures).

[조직에 로그인 제한](https://code.claude.com/docs/ko/authentication.md#restrict-login-to-your-organization)을 참조하여 Claude Code가 Claude Console 로그인, 다른 로그인 경로, 및 환경 자격 증명을 어떻게 취급하는지 확인하세요.

### `gatewayInternalNetworks`

조직이 내부 네트워크를 번호 매기는 공개 IPv4 블록을 선언하여 `/login`이 [클라우드 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway)를 그곳에서 수락하도록 합니다. Claude Code v2.1.268 이상이 필요합니다.

이 키가 없으면, `/login`은 개인 주소의 모든 게이트웨이에 연결하고 다른 것은 없습니다. 이 키가 있으면, `/login`은 또한 나열된 블록 내의 게이트웨이를 직접 연결을 통해서만 수락합니다. 해당 연결의 머신 자신의 주소도 동일한 블록 내에 있어야 합니다.

* **범위**: [`관리됨`](#scopes). 머신의 소스에서만 읽습니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 도우미. Claude Code는 HKCU 및 서버 관리형 설정에서 무시합니다.
* **유형**: 문자열 배열, 최대 4개의 IPv4 CIDR 블록, 각각 `/8`에서 `/32`, 서로 겹치지 않음, 그리고 개인 공간과 겹치지 않음.
* **기본값**: 설정되지 않음, 따라서 `/login`은 개인 주소의 게이트웨이만 수락합니다.

```json managed-settings.json theme={null}
{
  "gatewayInternalNetworks": ["203.0.113.0/24"]
}
```

예제의 설명서 범위를 자신의 블록으로 바꾸세요. Claude Code는 설명서 범위, VPN 및 NAT64 클라이언트가 로컬로 사용하는 범위, 그리고 멀티캐스트와 같이 어떤 네트워크도 번호 매기지 않는 예약된 공간을 거부합니다.

항목이 유효하지 않거나 값이 문자열 목록이 아니면, `/login`은 문제를 이름 지정하고 값을 수정할 때까지 머신의 모든 새로운 게이트웨이 로그인을 거부합니다. 기존 로그인은 계속 작동합니다. [공개 주소 공간에서 소유한 게이트웨이 허용](https://code.claude.com/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)을 참조하여 전체 규칙과 개발자가 보는 것을 확인하세요.

### `gcpAuthRefresh`

Claude Code가 Google Cloud Application Default Credentials가 만료되었거나 로드할 수 없음을 발견할 때 새로 고치기 위해 자신의 명령을 실행하여 [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md) 요청이 손으로 다시 인증하지 않고도 계속 작동하도록 합니다.

별도의 터미널이나 IDE 창과 같이 동일한 명령과 자격 증명을 사용하는 여러 Claude Code 프로세스가 동시에 자격 증명이 만료되었음을 발견하면, 한 프로세스가 명령을 실행하고 나머지는 각자 실행을 시작하는 대신 해당 실행을 기다립니다. 요청이 대기 중인 상태로 60초 동안 기다린 프로세스는 직접 명령을 실행합니다. 이를 끄려면 [`CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK`](https://code.claude.com/docs/ko/env-vars)을 `1`로 설정하세요.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열, 셸 명령줄
* **기본값**: 설정되지 않음, 따라서 Claude Code의 자격 증명 오류는 `gcloud auth application-default login`을 직접 실행하도록 알립니다.

```json settings.json theme={null}
{
  "gcpAuthRefresh": "gcloud auth application-default login"
}
```

[고급 자격 증명 구성](https://code.claude.com/docs/ko/google-vertex-ai.md#advanced-credential-configuration)을 참조하세요.

### `otelHeadersHelper`

Claude Code가 OpenTelemetry 내보내기와 함께 보내는 헤더를 생성하기 위해 자신의 명령을 실행하여, 토큰이 회전하는 백엔드의 경우입니다. Claude Code는 시작 시 및 그 후 주기적으로 실행하고, stdout에서 문자열 헤더 값의 JSON 객체를 예상합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 문자열, 실행 가능한 경로 또는 셸 명령줄
* **기본값**: 설정되지 않음, 따라서 Claude Code는 도우미 생성 헤더를 추가하지 않습니다.

```json settings.json theme={null}
{
  "otelHeadersHelper": "/bin/generate_otel_headers.sh"
}
```

[`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](https://code.claude.com/docs/ko/env-vars)로 새로 고침 간격을 설정하세요. [동적 헤더](https://code.claude.com/docs/ko/monitoring-usage.md#dynamic-headers)를 참조하여 스크립트 요구 사항과 도우미가 실패할 때 어떤 일이 발생하는지 확인하세요.

## 업데이트 및 버전 관리

업데이트 채널을 선택하고, 조직의 경우 사용자가 실행할 수 있는 버전을 고정합니다. [Claude Code 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)를 참조하십시오.

### `autoUpdatesChannel`

백그라운드 자동 업데이트 및 `claude update`가 따르는 [릴리스 채널](https://code.claude.com/docs/ko/setup.md#configure-release-channel)을 선택합니다. 일반적으로 약 1주일 된 버전이며 주요 회귀가 있는 릴리스를 건너뛰는 `"stable"`을 설정하거나, 가장 최근 릴리스를 위해 `"latest"`를 설정합니다.

* **범위**: [`모든 파일`](#scopes). 조직 전체에 하나의 채널을 적용하려면 관리 설정에서 설정합니다.
* **유형**: 문자열, 다음 중 하나:
  * `"latest"`: 업데이트가 가장 최근 릴리스를 따릅니다
  * `"stable"`: 업데이트가 일반적으로 약 1주일 된 버전을 따르며 주요 회귀가 있는 릴리스를 건너뜁니다
* **기본값**: 설정되지 않음, Claude Code는 `"latest"`를 따릅니다

```json settings.json theme={null}
{
  "autoUpdatesChannel": "stable"
}
```

Claude Code는 `/config`의 **자동 업데이트 채널**에서 선택할 때 사용자 설정에 `"stable"`을 기록하고, 거기서 최신으로 다시 전환할 때 키를 제거합니다. `claude install stable` 및 `claude install latest`도 명명한 채널을 저장합니다. `/config`에서 `"latest"`에서 `"stable"`로 전환하면 다운그레이드를 허용할지 또는 현재 버전에 머물지 묻습니다. 머물기를 선택하면 [`minimumVersion`](#minimumversion)을 설정합니다. Homebrew 설치는 이 키를 무시합니다: `claude-code` cask는 stable을 추적하고 `claude-code@latest`는 latest를 추적하며, `claude update`는 `brew upgrade`로 연기됩니다. 자동 업데이트를 완전히 끄려면 `env`에서 [`DISABLE_AUTOUPDATER`](https://code.claude.com/docs/ko/setup#disable-auto-updates)를 설정합니다.

### `minimumVersion`

백그라운드 자동 업데이트 및 `claude update`가 이 버전 아래의 버전을 설치하지 않도록 하여, `"stable"` 채널로 이동해도 최신 `"latest"` 빌드에서 다운그레이드되지 않습니다. Claude Code는 `/config`에서 채널을 전환하면서 현재 버전에 머물기를 선택할 때 이 키를 기록하고, `"latest"`로 다시 전환할 때 지웁니다.

* **범위**: [`모든 파일`](#scopes). 조직 전체 최소값을 고정하려면 관리 설정에서 설정하여 사용자 및 프로젝트 설정이 낮출 수 없도록 합니다.
* **유형**: 문자열, `"2.1.100"`과 같은 버전 번호; 유효한 버전이 아닌 값은 무시됩니다
* **기본값**: 설정되지 않음, 업데이트는 채널이 제공하는 모든 버전을 설치할 수 있습니다

이 예제는 stable 채널을 따르고 2.1.100 아래의 버전 설치를 거부합니다:

```json settings.json theme={null}
{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}
```

이 키는 업데이트만 제한합니다. Claude Code가 버전 아래에서 시작하지 않도록 하려면 대신 [`requiredMinimumVersion`](#requiredminimumversion)을 사용합니다. [최소 버전 고정](https://code.claude.com/docs/ko/setup.md#pin-a-minimum-version)을 참조하십시오.

### `requiredMaximumVersion`

조직이 시작할 수 있는 가장 최신 Claude Code 버전을 설정합니다. 실행 중인 버전이 더 최신이면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 승인된 버전을 설치하도록 지시합니다. `claude install <version>`도 작동할 수 있습니다. Claude Code v2.1.163 이상이 필요합니다.

* **범위**: [`관리됨`](#scopes). Claude Code는 다른 곳에서 키를 무시할 때 경고를 제공하지 않습니다.
* **유형**: 문자열, `"2.1.150"`과 같은 버전 번호; 유효한 버전이 아닌 값은 무시됩니다
* **기본값**: 설정되지 않음, 상한이 적용되지 않습니다

```json managed-settings.json theme={null}
{
  "requiredMaximumVersion": "2.1.150"
}
```

백그라운드 자동 업데이트 및 `claude update`는 상한 위의 버전을 건너뛰므로 범위 내의 설치는 범위 내에 머물러 있습니다. `claude update`, `claude install`, 및 `claude doctor`는 사용자가 복구할 수 있도록 상한 위에서 계속 작동합니다. [`requiredMinimumVersion`](#requiredminimumversion)과 쌍을 이루어 범위를 적용합니다.

### `requiredMinimumVersion`

조직이 시작할 수 있는 가장 오래된 Claude Code 버전을 설정합니다. 실행 중인 버전이 더 오래되면 Claude Code는 시작 시 종료되고 사용자에게 조직의 승인된 방법을 통해 업데이트하도록 지시합니다. 검사는 시작 시에만 실행되므로 이미 실행 중인 세션은 계속됩니다. Claude Code v2.1.163 이상이 필요합니다.

* **범위**: [`관리됨`](#scopes). Claude Code는 다른 곳에서 키를 무시할 때 경고를 제공하지 않습니다.
* **유형**: 문자열, `"2.1.150"`과 같은 버전 번호; 유효한 버전이 아닌 값은 무시됩니다
* **기본값**: 설정되지 않음, 하한이 적용되지 않습니다

```json managed-settings.json theme={null}
{
  "requiredMinimumVersion": "2.1.150"
}
```

`claude update`, `claude install`, 및 `claude doctor`는 사용자가 복구할 수 있도록 하한 아래에서 계속 작동합니다. 다운그레이드만 방지하는 [`minimumVersion`](#minimumversion)과 달리, 이 키는 시작을 차단합니다. [`requiredMaximumVersion`](#requiredmaximumversion)과 쌍을 이루어 범위를 적용합니다.

## 도구

[Claude Code 데스크톱 앱](https://code.claude.com/docs/ko/desktop.md)에서 특정 도구를 끕니다. 터미널 CLI는 이 키를 무시합니다. 도구 자체에 대해서는 [Claude에서 사용 가능한 도구](https://code.claude.com/docs/ko/tools-reference.md)를 참조하세요.

### `browserExternalPageTools`

Claude가 데스크톱 앱의 [브라우저 창](https://code.claude.com/docs/ko/desktop.md#browse-external-sites)에서 외부 페이지를 읽거나 작동하는 도구를 사용하지 못하도록 합니다. 조직의 사용자는 여전히 외부 사이트를 직접 열 수 있으며, 로컬 개발 서버 미리보기는 Claude의 도구와 함께 계속 작동합니다. 데스크톱 앱이 이 키를 읽습니다. 터미널 CLI는 무시합니다.

* **범위**: [`Managed`](#scopes)
* **유형**: 문자열, `"disabled"`; 데스크톱 앱은 `"disable"`도 허용하며, 어느 경우든
* **기본값**: 설정되지 않음, 따라서 Claude의 도구는 외부 페이지에서 작동합니다

```json managed-settings.json theme={null}
{
  "browserExternalPageTools": "disabled"
}
```

다른 값은 Claude의 도구를 켜진 상태로 두며, 허용된 두 값 중 하나가 아닌 비어있지 않은 문자열은 경고를 기록합니다. 사용자와 Claude 모두에 대해 외부 사이트를 차단하려면 대신 [`disableBrowserExternalNavigation`](#disablebrowserexternalnavigation)을 설정하세요. [조직의 외부 브라우징 제한](https://code.claude.com/docs/ko/desktop.md#restrict-external-browsing-for-your-organization)을 참조하세요.

### `disableBrowserExternalNavigation`

데스크톱 앱의 [브라우저 창](https://code.claude.com/docs/ko/desktop.md#browse-external-sites)에서 사용자와 Claude 모두에 대해 외부 브라우징을 끕니다. Localhost 개발 서버 미리보기는 계속 작동합니다. 데스크톱 앱이 이 키를 읽습니다. 터미널 CLI는 무시합니다.

* **범위**: [`Managed`](#scopes)
* **유형**: 부울; JSON 부울 `true`만 적용됩니다
  * `true`: 데스크톱 앱이 브라우저 창에서 사용자와 Claude 모두에 대해 외부 브라우징을 끕니다. localhost 미리보기는 계속 작동합니다
  * `false`: 외부 브라우징이 켜진 상태로 유지됩니다
* **기본값**: 설정되지 않음, 따라서 외부 브라우징이 켜져 있습니다

```json managed-settings.json theme={null}
{
  "disableBrowserExternalNavigation": true
}
```

데스크톱 앱은 다른 값을 무시하며, 문자열 `"true"` 또는 `1`과 같이 부울이 아닌 값도 경고를 기록합니다. 외부 브라우징은 켜진 상태로 두되 Claude의 도구를 외부 페이지에서 끄려면 대신 [`browserExternalPageTools`](#browserexternalpagetools)를 설정하세요. [조직의 외부 브라우징 제한](https://code.claude.com/docs/ko/desktop.md#restrict-external-browsing-for-your-organization)을 참조하세요.

### `disableMobileSimulatorTools`

데스크톱 앱의 [iOS 시뮬레이터 창](https://code.claude.com/docs/ko/desktop-ios-simulator.md#turn-off-simulator-access)에 대해 Claude의 도구를 차단합니다. 사용자는 창을 수동으로 사용할 수 있습니다. Claude의 접근만 제거되며, 아무도 앱 내에서 이를 다시 켤 수 없습니다. 데스크톱 앱이 이 키를 읽습니다. 터미널 CLI는 무시합니다.

* **범위**: [`Managed`](#scopes)
* **유형**: 부울; JSON 부울 `true`만 적용됩니다
  * `true`: 데스크톱 앱이 iOS 시뮬레이터 창에 대해 Claude의 도구를 차단합니다
  * `false`: Claude의 시뮬레이터 도구는 데스크톱 앱의 각 사용자 설정 토글을 따릅니다
* **기본값**: 설정되지 않음, 따라서 Claude의 시뮬레이터 도구는 데스크톱 앱의 각 사용자 설정 토글을 따릅니다

```json managed-settings.json theme={null}
{
  "disableMobileSimulatorTools": true
}
```

데스크톱 앱은 다른 값을 무시하며, 문자열 `"true"` 또는 `1`과 같이 부울이 아닌 값도 경고를 기록합니다.

## 개인정보 보호 및 원격 측정

Claude Code가 세션 데이터를 얼마나 오래 보관하고 무엇을 전송하는지 제어합니다. 사용 지표 및 오류 보고를 끄는 스위치는 설정 키가 아니라 환경 변수입니다. [`env`](#env) 키 또는 셸에서 `DISABLE_TELEMETRY`, `DISABLE_ERROR_REPORTING` 또는 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`을 설정합니다. [원격 측정 서비스](https://code.claude.com/docs/ko/data-usage.md#telemetry-services)에서 각각이 무엇을 중지하는지 설명합니다. 두 가지 예외는 설정 파일에서 끕니다. 아래의 [`feedbackDrafts`](#feedbackdrafts)는 Claude가 작성한 피드백용이고, 아래의 [`feedbackSurveyRate`](#feedbacksurveyrate)는 세션 설문조사용입니다.

### `cleanupPeriodDays`

Claude Code가 [세션 기록 및 기타 애플리케이션 데이터](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)를 삭제하기 전에 보관하는 일 수를 설정합니다. Claude Code는 세션이 시작된 후 백그라운드 스윕으로 삭제를 실행하며, 보관 기간을 안전하게 결정할 수 있는 한 실행합니다. 스윕은 메시지를 표시하지 않고 기록을 삭제하므로, 보관 기간보다 오래 사용하지 않은 세션은 더 이상 [`/resume`](https://code.claude.com/docs/ko/sessions#resume-a-session) 선택기에 나타나지 않습니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 일 수, 정수, 최소값 `1`
* **기본값**: `30`

```json settings.json theme={null}
{
  "cleanupPeriodDays": 20
}
```

`0`을 설정하면 유효성 검사에 실패하므로 장기 보관을 위해 `3650`과 같은 큰 값을 선택합니다. Claude Code가 기록을 전혀 작성하지 않도록 하려면 [일반 텍스트 저장소](https://code.claude.com/docs/ko/claude-directory.md#plaintext-storage)를 참조합니다.

### `desktopSessionCleanupPeriodDays`

Claude Desktop 또는 Cowork에서 시작하거나 가장 최근에 계속한 세션의 트랜스크립트에 대한 나이 제한을 일 수로 설정합니다. 이 키가 없으면 Claude Code는 [해당 트랜스크립트를 나이와 관계없이 유지합니다](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically). Claude Code는 각 트랜스크립트가 이 제한과 [`cleanupPeriodDays`](#cleanupperioddays) 모두보다 오래되면 삭제하므로, `cleanupPeriodDays`가 기본값 30일 때 `7` 값은 여전히 30일 동안 유지합니다. [자동으로 정리되는 항목](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)에는 `cleanupPeriodDays`가 대신 적용되고 Claude Code가 이 키를 무시하는 경우가 나열되어 있습니다. Claude Code v2.1.248 이상이 필요합니다.

* **범위**: [`사용자 또는 관리됨`](#scopes). Claude Code는 `--settings`로 전달하는 파일에서도 키를 읽고 프로젝트 및 로컬 설정에서는 무시합니다.
* **유형**: 일 수, 정수, 최소값 `0`
* **기본값**: `0`, 나이 제한을 설정하지 않음

```json settings.json theme={null}
{
  "desktopSessionCleanupPeriodDays": 90
}
```

### `feedbackDrafts`

[Claude가 작성한 피드백](https://code.claude.com/docs/ko/tools-reference.md#sendfeedback-tool-behavior) 제어: Claude가 검토할 피드백 초안을 대기열에 넣을 수 있는지 여부, 그리고 Claude Code가 Claude가 초안을 대기열에 넣을 때 카드를 표시하는지 여부입니다.

* **범위**: [`사용자 또는 관리됨`](#scopes)
* **유형**: 문자열, `"notify"`, `"quiet"` 또는 `"off"` 중 하나
  * `"notify"`: Claude Code는 Claude가 초안을 대기열에 넣을 때 프롬프트 위에 카드를 표시하며, 기본적으로 [세션당 최대 3개의 카드](https://code.claude.com/docs/ko/tools-reference.md#what-you-see-when-claude-drafts)
  * `"quiet"`: Claude는 카드 없이 초안을 작성합니다. 프롬프트 바닥글에서 대기열에 있는 초안의 개수를 보고 `/feedback`에서 검토합니다.
  * `"off"`: Claude Code는 SendFeedback 도구를 제거하므로 Claude는 초안을 대기열에 넣을 수 없습니다.
* **기본값**: `"notify"`
* **세션별 재정의**: [`CLAUDE_CODE_SEND_FEEDBACK`](https://code.claude.com/docs/ko/env-vars)을 `0`으로 설정하면 한 세션 동안 기능을 끕니다.

```json settings.json theme={null}
{
  "feedbackDrafts": "quiet"
}
```

`/config`에 **Claude가 작성한 피드백**으로 나타나며, 이 키를 사용자 설정에 씁니다. `/config` 행은 [Claude가 피드백을 작성할 수 있는 세션](https://code.claude.com/docs/ko/tools-reference.md#sessions-without-claude-drafted-feedback)에서만 표시됩니다. `"off"`를 설정해도 숨기지 않으므로 같은 행에서 기능을 다시 켤 수 있습니다. 관리되는 설정의 값은 사용자 설정보다 우선하므로, 관리자가 이 키를 설정하면 행에 관리되는 값이 표시되고 변경해도 효과가 없습니다. Claude Code는 프로젝트 및 로컬 설정에서 이 키를 무시합니다.

### `feedbackSurveyRate`

[세션 품질 설문조사](https://code.claude.com/docs/ko/data-usage.md#session-quality-surveys)가 세션이 적격일 때 나타날 확률을 설정합니다. 설문조사가 나타나지 않도록 하려면 `0`으로 설정합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: `0`과 `1` 사이의 숫자
* **기본값**: 설정되지 않음, Claude Code는 Anthropic이 원격으로 설정한 비율을 사용하거나, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 기본 제공 비율 `0.005`를 사용합니다. 이들은 원격 구성을 받지 않습니다.
* **세션별 재정의**: [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](https://code.claude.com/docs/ko/env-vars)을 `1`로 설정하면 이 키가 설정한 비율과 관계없이 한 세션 동안 설문조사를 끕니다.

```json settings.json theme={null}
{
  "feedbackSurveyRate": 0.05
}
```

같은 비율이 VS Code 확장 프로그램의 설문조사에도 적용됩니다.

### `skipWebFetchPreflight`

[WebFetch 도메인 안전 검사](https://code.claude.com/docs/ko/data-usage.md#webfetch-domain-safety-check)를 건너뜁니다. 이 검사는 가져오기 전에 요청된 각 호스트명을 `api.anthropic.com`으로 보냅니다. Amazon Bedrock, Google Cloud의 Agent Platform 또는 제한적인 송신이 있는 Microsoft Foundry 배포와 같이 Anthropic으로의 트래픽을 차단하는 환경에서 `true`로 설정합니다.

* **범위**: [`모든 파일`](#scopes)
* **유형**: 부울
  * `true`: Claude Code는 WebFetch 도메인 안전 검사를 건너뜁니다.
  * `false`: 검사는 세션의 각 호스트명으로의 첫 번째 가져오기 전에 실행되며, 이전 검사가 차단되거나 실패한 호스트명에 대해 다시 실행됩니다.
* **기본값**: 설정되지 않음, 검사는 세션의 각 호스트명으로의 첫 번째 가져오기 전에 실행됩니다.

```json settings.json theme={null}
{
  "skipWebFetchPreflight": true
}
```

검사를 건너뛰면 WebFetch는 차단 목록을 참조하지 않고 모든 URL을 시도하므로, Claude가 도달할 수 있는 도메인을 제한해야 하는 경우 [`WebFetch` 권한 규칙](https://code.claude.com/docs/ko/permissions#webfetch)과 함께 사용합니다.

## 엔터프라이즈 및 관리형 설정

조직이 관리형 설정을 계산, 새로고침 및 결합하는 데 사용하는 키입니다. [관리형 설정 설정](https://code.claude.com/docs/ko/admin-setup.md)을 참조하세요.

### `disableSideloadFlags`

`--plugin-dir`, `--plugin-url`, `--agents`, `--mcp-config` CLI 플래그를 시작 시 거부하여 사용자가 [`strictKnownMarketplaces`](#strictknownmarketplaces)를 단일 실행으로 우회하는 데 사용할 수 없도록 합니다. Claude Code는 거부된 플래그의 이름을 지정하는 오류로 종료됩니다. [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)에서 Claude Code는 세션을 시작하고 인프로세스 `type: "sdk"` 항목 및 [Claude Tag](https://code.claude.com/docs/ko/claude-tag.md) 세션의 Slack 도구를 제외한 모든 서버 제공 `--mcp-config` 항목을 삭제합니다. Claude Code v2.1.193 이상이 필요합니다.

* **범위**: [`Managed`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code는 시작 시 `--plugin-dir`, `--plugin-url`, `--agents`, `--mcp-config`를 거부하고 이름을 지정하는 오류로 종료됩니다. 클라우드 세션에서는 세션을 시작하고 인프로세스 `type: "sdk"` 항목 및 Claude Tag 세션의 Slack 도구를 제외한 모든 서버 제공 `--mcp-config` 항목을 삭제합니다.
  * `false`: Claude Code는 해당 플래그를 수락합니다.
* **기본값**: `false`

```json managed-settings.json theme={null}
{
  "disableSideloadFlags": true
}
```

Claude Code는 여전히 서버가 모두 인프로세스 `type: "sdk"` 항목인 `--mcp-config`를 수락하므로 Agent SDK 및 VS Code 확장이 계속 작동합니다. 사용자는 여전히 `claude mcp add` 또는 `.mcp.json` 파일로 서버를 추가할 수 있습니다. 서버별 제어의 경우 [`allowedMcpServers`](https://code.claude.com/docs/ko/managed-mcp)도 설정하세요. Claude Code v2.1.193 이상이 필요합니다.

동일한 검사는 [`CLAUDE_CODE_PLUGIN_DIRS`](https://code.claude.com/docs/ko/env-vars#variables) 환경 변수에 명명된 플러그인 폴더를 포함합니다. 이는 Claude Code v2.1.280 이상이 필요합니다. 변수가 폴더의 이름을 지정하면 Claude Code는 동일한 오류로 종료되며, 오류는 변수를 설정 해제하도록 지시합니다.

클라우드 세션에서 Claude Code는 또한 서버 제공 중간 세션 MCP 업데이트를 무시합니다. 이는 클라우드 세션 구성 및 SDK `setMcpServers()` 호출 뒤의 경로이며, 이러한 세션에 도달합니다. 인프로세스 `type: "sdk"` 항목 및 Claude Tag 세션의 Slack 도구는 거기서도 면제됩니다. v2.1.268 이전에는 이 삭제와 시작 삭제 모두 Claude Tag 세션의 Slack 도구를 제거했습니다. v2.1.239 이전에는 서버 제공 `--mcp-config`가 클라우드 세션이 시작되는 것을 차단했습니다.

데스크톱 앱은 claude.ai에서 동기화된 플러그인 및 조직이 앱을 통해 배포하는 플러그인을 포함하여 일부 플러그인을 자체적으로 관리합니다. MDM, OS 수준 정책 또는 관리형 설정 파일을 통해 이 키를 디바이스에 배포하면 데스크톱 앱은 해당 디바이스의 다음 세션에 해당 플러그인을 전달하지 않습니다:

* **[사용자 머신의 Code 세션](https://code.claude.com/docs/ko/desktop.md#environment-configuration)**: 사용자의 claude.ai 계정에 대해 활성화된 스킬 없이도 시작됩니다. Claude Code가 관리형 설정의 마켓플레이스에서 설치하는 플러그인은 여전히 로드됩니다. [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)에서 디바이스의 `org-plugins` 디렉터리에 배포하는 플러그인의 MCP 서버는 데스크톱 앱이 자체적으로 연결하기 때문에 사용 가능한 상태로 유지됩니다. Claude Desktop v1.37937.0 이전에는 이러한 세션이 시작 시 실패했습니다.
* **[사용자 머신의 Cowork 세션](https://code.claude.com/docs/ko/managed-settings.md#where-and-when-a-policy-applies)**: 해당 플러그인 내의 스킬 및 사용자의 claude.ai 계정에 대해 활성화된 스킬은 사용 가능한 상태로 유지됩니다. [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)에서 디바이스의 `org-plugins` 디렉터리에 배포하는 플러그인의 MCP 서버는 데스크톱 앱이 자체적으로 연결하기 때문에 사용 가능한 상태로 유지됩니다. Claude Desktop v1.44121.0 이전에는 이러한 세션이 시작 시 실패했습니다.

### `forceRemoteSettingsRefresh`

Claude Code가 [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)을 새로 가져올 때까지 CLI 시작을 차단합니다. 가져오기가 실패하면 Claude Code는 캐시된 설정이나 설정 없이 계속하지 않고 종료합니다. 환경이 관리형 정책 없이 세션이 실행되는 짧은 기간도 허용할 수 없을 때 설정하세요.

키가 설정되지 않으면 Claude Code는 가져오기에서 시작을 차단하지 않지만, 개발자가 시작 시 로그인할 때 가져오기를 위해 최대 5초를 기다립니다. Cloud 게이트웨이 세션은 항상 기다리며, 게이트웨이에 도달할 수 없으면 종료됩니다.

* **범위**: [`Managed`](#scopes). Claude Code는 최우선 소스가 아닌 경우에도 모든 관리자 제어 관리형 소스에서 `true`를 인정합니다.
* **유형**: Boolean
  * `true`: Claude Code는 서버 관리형 설정을 새로 가져올 때까지 시작을 차단하고, 가져오기가 실패하면 종료합니다.
  * `false`: Claude Code는 가져오기에서 시작을 차단하지 않지만, 로그인 시작 시 가져오기를 위해 최대 5초를 기다립니다.
* **기본값**: `false`

```json managed-settings.json theme={null}
{
  "forceRemoteSettingsRefresh": true
}
```

MDM 프로필 또는 관리형 설정 파일에 설정하여 첫 번째 서버 페이로드가 도착하기 전에 실패 폐쇄 시작을 적용합니다. Claude Code는 서버 관리형 설정을 가져오는 세션에서만 검사를 적용하므로, [가져오지 않는](https://code.claude.com/docs/ko/server-managed-settings.md#platform-availability) 세션은 기다리지 않고 시작됩니다. `claude auth` 부명령은 면제되므로 사용자는 만료된 자격 증명이 가져오기 실패의 원인일 때 다시 인증할 수 있습니다. [실패 폐쇄 시작 적용](https://code.claude.com/docs/ko/server-managed-settings.md#enforce-fail-closed-startup)을 참조하세요.

### `managedSourcesBehavior`

Claude Code가 조직이 제공하는 최우선 [관리형 소스](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)만 적용할지, 아니면 제공하는 모든 관리자 소스를 결합할지 선택합니다. 기본적으로 Claude Code는 [정책 키](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)를 전달하는 최우선 소스를 가져가고 나머지는 무시합니다. 정책 키는 이 키와 `wslInheritsWindowsSettings`를 제외한 모든 설정 키입니다. 해당 기본값에서 서버 관리형 설정 또는 MDM 정책이 정책 키를 제공하면 `managed-settings.json` 파일은 [Claude Code가 모든 관리자 소스에서 읽는 키](https://code.claude.com/docs/ko/managed-settings.md#keys-read-from-every-admin-source)만 제공합니다. `"merge"`를 사용하면 제공하는 모든 관리자 소스가 결합된 정책에 키를 제공합니다. Claude Code v2.1.242 이상이 필요합니다.

최우선 소스 아래에 [순위가 지정된](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources) 모든 소스가 관리자의 제어 하에 있는 경우에만 `"merge"`를 설정하세요. Claude Code는 `permissions.allow` 규칙과 같은 하위 소스의 항목을 정책에 추가하기 때문입니다.

* **범위**: [`Managed`](#scopes). Claude Code는 이 키 또는 정책 키를 전달하는 최우선 소스에서 이 키를 읽고, 순위가 낮은 모든 소스에서 이 키를 무시합니다. 따라서 하위 소스는 위의 소스와 결합하도록 자신을 선택할 수 없습니다. Windows HKCU 레지스트리 또는 [포함 호스트의 부모 설정](https://code.claude.com/docs/ko/managed-settings.md#let-an-embedding-host-add-policy)은 병합에 참여하지 않습니다.
* **유형**: string, 다음 중 하나:
  * `"first-wins"`: 정책 키를 전달하는 최우선 소스가 정책을 제공하고, 하위 소스는 [Claude Code가 모든 관리자 소스에서 읽는 키](https://code.claude.com/docs/ko/managed-settings.md#keys-read-from-every-admin-source)만 제공합니다.
  * `"merge"`: 제공하는 모든 관리자 소스가 키를 제공하며, 아래 규칙에 따라 결합됩니다.
* **기본값**: `"first-wins"`

배포하는 최우선 소스에서 키를 제공합니다. 서버 관리형 설정을 받지 않는 머신은 Claude Code가 이 키 또는 정책 키를 전달하는 최우선 소스에서 키를 읽기 때문에 MDM 프로필에도 키가 필요합니다. `managed-settings.json` 파일은 최하위 순위 관리자 소스이므로, 거기에 설정된 `"merge"`는 결합할 아래 소스가 없습니다. 서버 관리형 설정에서 키는 다음과 같습니다:

```json theme={null}
{
  "managedSourcesBehavior": "merge"
}
```

`"merge"` 아래에서 Claude Code는 각 키를 종류별로 결합합니다. 이 표는 각 종류에 대한 규칙을 제공합니다. 제한 허용 목록, 값 전체 및 최우선 소스 전용 행은 포함하는 모든 키의 이름을 지정하고, 다른 행은 예를 제공합니다:

| 키의 종류 | Claude Code가 결합하는 방법 | 키 |
| :- | :- | :- |
| 목록 | 모든 소스의 항목을 결합합니다. | [`permissions.allow`](#permissions-allow), [`sandbox.network.allowedDomains`](#sandbox-network-alloweddomains) 및 기타 목록 키 |
| 잠금 | 모든 소스가 설정하는 가장 엄격한 값을 적용합니다. 어떤 소스도 엄격한 값을 설정하지 않으면 최우선 소스에서만 더 느슨한 값을 적용합니다. | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly), [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 및 기타 boolean 또는 enum 잠금 |
| 제한 허용 목록 | 하위 소스의 항목을 추가하지 않고 설정하는 최우선 소스에서 목록 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`availableModels`](#availablemodels), [`allowedMcpServers`](#allowedmcpservers), [`allowedProviders`](#allowedproviders), [`strictKnownMarketplaces`](#strictknownmarketplaces), [`allowedChannelPlugins`](#allowedchannelplugins) 및 [`fallbackModel`](#fallbackmodel) 체인 |
| 값 전체 | 하위 소스의 항목이나 필드를 결합하지 않고 설정하는 최우선 소스에서 값 전체를 가져옵니다. 최우선 소스가 설정하지 않으면 다음 소스에서 전체를 가져옵니다. | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs), [`sandbox.ripgrep`](#sandbox-ripgrep) |
| 제공된 MCP 서버 | 모든 소스의 서버 이름을 결합합니다. 두 소스가 동일한 이름을 설정하면 상위 소스의 전체 항목을 적용합니다. | [`managedMcpServers`](#managedmcpservers) |
| 최우선 소스에서만 읽기 | 정책 키를 전달하는 최우선 소스에서만 키를 읽으므로, 최우선 소스가 설정하지 않을 때에도 하위 소스의 값은 무시됩니다. | [`apiKeyHelper`](#apikeyhelper), [`awsAuthRefresh`](#awsauthrefresh), [`awsCredentialExport`](#awscredentialexport), [`gcpAuthRefresh`](#gcpauthrefresh), [`otelHeadersHelper`](#otelheadershelper), `proxyAuthHelper`, [`forceLoginOrgUUID`](#forceloginorguuid), [`forceLoginMethod`](#forceloginmethod)의 `"claudeai"` 및 `"console"` 값, [`parentSettingsBehavior`](#parentsettingsbehavior), [`modelPicker`](#modelpicker), [`policyHelper`](#policyhelper), [`permissions.defaultMode`](#permissions-defaultmode) |
| `env` | [관리자 소스 전체에서 변수별로 병합합니다](https://code.claude.com/docs/ko/managed-settings.md#keys-read-from-every-admin-source). `"first-wins"` 및 `"merge"` 모두에서 | [`env`](#env) |
| 다른 모든 키 | 설정하는 최우선 소스에서 값을 가져옵니다. | [`cleanupPeriodDays`](#cleanupperioddays), [`model`](#model) |

`sandbox.credentials.awsPairs` 및 `sandbox.ripgrep`을 전체로 가져오려면 Claude Code v2.1.257 이상이 필요합니다.

몇 가지 키는 표에 표시되지 않는 조건을 추가합니다:

* **[`policyHelper`](#policyhelper)**: Claude Code는 정책 키를 전달하는 최우선 소스가 MDM 정책 또는 관리형 설정 파일일 때만 인정하므로, 서버 관리형 설정에서는 적용되지 않습니다.
* **[`modelOverrides`](#modeloverrides)**: `availableModels`와 쌍을 이룹니다. Claude Code는 설정하는 최우선 소스에서 `modelOverrides`를 가져옵니다. 단, 상위 소스가 `modelOverrides` 없이 `availableModels`를 설정하는 경우는 제외됩니다. 이 경우 모든 소스에서 `modelOverrides`를 무시합니다.
* **[`forceLoginGatewayUrl`](#forcelogingatewayurl), [`gatewayInternalNetworks`](#gatewayinternalnetworks) 및 [`forceLoginMethod`](#forceloginmethod)의 `"gateway"` 값**: Claude Code는 서버 관리형 설정에서 이들 중 어느 것도 읽지 않으므로, 거기의 값은 MDM 정책 또는 관리형 설정 파일에 설정된 값을 적용하거나 숨기지 않습니다. 머신의 관리자 소스 중에서 정책 키를 전달하는 최우선 순위 소스만 서버 관리형 설정도 있는지 여부와 관계없이 이들을 제공합니다.
* **[`allowedProviders`](#allowedproviders)**: 표의 규칙 이후에도 머신 자체의 목록이 결과를 제한하며, 해당 항목의 범위 참고 사항에 명시되어 있습니다.

머신에서 결합된 소스를 확인하려면 `/status`를 실행하고 [`Setting sources` 행을 읽으세요](https://code.claude.com/docs/ko/managed-settings#read-the-source-in-/status).

### `parentSettingsBehavior`

Claude Code가 Agent SDK 또는 IDE 확장과 같은 포함 호스트 프로세스에서 제공하는 관리형 설정을 적용할지 선택합니다. 관리자 배포 관리형 계층도 있을 때. `"first-wins"`를 사용하면 Claude Code는 호스트 제공 설정을 삭제합니다. `"merge"`를 사용하면 제한 전용 필터를 통해 관리자 계층 아래에 적용합니다. 호스트가 자신의 제한을 시작하는 세션에 전달해야 할 때 `"merge"`를 설정하세요. 예를 들어 Claude Desktop이 게이트웨이의 송신 허용 목록을 제공합니다.

* **범위**: [`Managed`](#scopes). Claude Code는 최우선 관리자 제어 관리형 소스에서 읽습니다.
* **유형**: string, 다음 중 하나:
  * `"first-wins"`: Claude Code는 관리자 배포 관리형 계층이 있을 때 호스트 제공 설정을 삭제합니다.
  * `"merge"`: Claude Code는 제한 전용 필터를 통해 관리자 계층 아래에 호스트 제공 설정을 적용합니다.
* **기본값**: `"first-wins"`

```json managed-settings.json theme={null}
{
  "parentSettingsBehavior": "merge"
}
```

관리자 배포 관리형 계층이 없을 때 이 키는 효과가 없습니다. 호스트의 설정은 유일한 관리형 계층으로 적용되며, 여전히 제한 값으로 필터링됩니다. 필터의 제한 및 관리형 소스가 상호 작용하는 방식에 대해서는 [포함 호스트의 부모 설정](https://code.claude.com/docs/ko/managed-settings.md#parent-settings-from-embedding-hosts) 및 [부모 설정 제한](https://code.claude.com/docs/ko/claude-apps-gateway#restrict-parent-settings)을 참조하세요.

### `policyHelper`

배포하는 실행 파일을 실행하여 시작 시 관리형 설정을 계산하므로 정적 파일 대신 디바이스 상태, ID 또는 원격 서비스에서 정책을 파생할 수 있습니다. Claude Code는 첫 번째 프롬프트를 수락하기 전에 도우미를 실행하고 내보내는 설정을 세션의 관리형 설정으로 처리합니다.

* **범위**: [`Managed`](#scopes). macOS plist, Windows HKLM 레지스트리 또는 관리형 설정 파일에서 읽습니다. Claude Code는 [정책 키](https://code.claude.com/docs/ko/managed-settings.md#how-claude-code-combines-managed-sources)를 전달하는 최우선 관리형 소스에서 키를 읽고, 해당 소스가 이 세 가지 중 하나일 때만 도우미를 실행합니다. 서버 관리형 설정, HKCU 레지스트리 및 호스트 제공 부모 설정에서 키를 무시합니다.
* **유형**: `path`, `timeoutMs` 및 `refreshIntervalMs`가 있는 object
* **기본값**: 설정 해제되어 도우미가 실행되지 않습니다.

서버 관리형 설정이 시작 시 정책을 제공하면 도우미의 소스보다 우선하고 도우미는 실행되지 않습니다.

나중에 설정 가져오기가 서버 관리형 설정이 제거되었음을 보고하면 Claude Code는 다음 시작을 기다리지 않고 그 시점에서 도우미를 실행합니다. 출력은 세션의 나머지를 관리하고, 실패한 실행은 [실패한 시작 실행](#helper-failures)과 동일한 메시지로 세션을 종료합니다.

이 예제는 5초 시간 초과로 도우미를 실행하고 5분마다 다시 실행합니다:

```json managed-settings.json theme={null}
{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy",
    "timeoutMs": 5000,
    "refreshIntervalMs": 300000
  }
}
```

#### 도우미 출력 작성

Claude Code는 인수 없이 도우미를 실행하고, 환경에서 `CLAUDE_CODE_VERSION`을 설정하고, stdout에서 JSON 봉투를 읽으며, 1 MiB로 제한됩니다.

`managedSettings` 키 아래에 설정을 배치합니다. `managedSettings` 키가 없는 베어 설정 객체는 `managedSettings` undefined로 구문 분석되고 아무것도 적용하지 않으며, Claude Code는 오류를 보고하지 않습니다:

```json theme={null}
{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  }
}
```

도우미가 `managedSettings`를 내보내면 해당 객체는 실행의 유일한 관리형 설정 소스가 됩니다. Claude Code는 MDM, 파일 및 HKCU 소스를 무시하고, 도우미의 출력에서만 [교차 소스 키](https://code.claude.com/docs/ko/managed-settings.md#keys-read-from-every-admin-source)를 읽고, [부모 설정](https://code.claude.com/docs/ko/managed-settings.md#parent-settings-from-embedding-hosts)을 병합하지 않습니다.

시작 `forceRemoteSettingsRefresh` 검사는 도우미 전에 실행되고 모든 관리자 소스를 읽습니다. 도우미가 `managedSettings`를 생략하는 봉투로 0을 종료하면 관리형 설정을 제공하지 않으며, 다른 소스는 평소대로 적용됩니다.

#### 도우미 실패

도우미 실행은 다음과 같은 경우 실패합니다:

* `path`가 [`policyHelper.path`](#policyhelper-path)의 규칙을 위반합니다.
* `path`에 일반 파일이 없습니다. Claude Code는 도우미를 시작하기 전에 동일한 `timeoutMs` 예산 내에서 파일을 확인하므로, 응답하지 않는 네트워크 마운트로 인해 실행이 실패할 수 있습니다.
* 도우미가 0이 아닌 값으로 종료되거나, `timeoutMs`가 경과할 때 여전히 실행 중이거나, 예를 들어 실행 가능하지 않기 때문에 전혀 시작되지 않습니다.
* 도우미가 stdout 또는 stderr에 1 MiB 이상을 씁니다.
* stdout이 단일 JSON 객체가 아니거나, `managedSettings`에 [Claude Code가 복구할 수 없는 스키마 위반](https://code.claude.com/docs/ko/managed-settings.md#find-entries-claude-code-dropped)이 있습니다.

시작 실행이 실패하면 Claude Code는 이유를 인쇄하고 시작을 거부합니다. 0이 아닌 종료 후 이유에는 도우미의 stderr 또는 stderr가 비어 있을 때 stdout이 포함됩니다. 시간 초과 후 이유는 `timeoutMs` 제한의 이름을 지정하고 도우미의 출력을 포함하지 않습니다. 거부는 대화형 세션, `claude -p`, Agent SDK 세션, [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md) 및 대부분의 부명령을 포함합니다.

거부는 의도적이므로 중단 복원력이 필요한 도우미는 자신의 캐시에서 제공하고 0을 종료해야 합니다.

백그라운드 새로고침이 실패하면 Claude Code는 마지막 성공한 정책을 유지하고, `/status`는 새로고침이 성공할 때까지 이유와 함께 실패한 새로고침을 표시합니다. 각 새로고침은 시작 실행과 동일한 `timeoutMs` 및 실패 규칙에서 실행됩니다.

`--debug`를 사용하면 Claude Code는 모든 실행에서 도우미의 stderr을 [디버그 로그](https://code.claude.com/docs/ko/debug-your-config.md)에 씁니다.

Claude Code는 잘못된 `policyHelper` 값을 [삭제된 항목](https://code.claude.com/docs/ko/managed-settings.md#find-entries-claude-code-dropped)으로 보고하고 도우미를 실행하지 않고 나머지 관리형 설정에서 세션을 시작합니다. 잘못된 값에는 베어 경로 문자열 및 [최소값](#policyhelper-timeoutms) 아래의 `timeoutMs`가 포함됩니다.

도우미를 끄려면 설정하는 소스에서 키를 제거합니다.

### `policyHelper.path`

Claude Code가 실행하는 도우미 실행 파일의 이름을 지정합니다. 경로가 아래 규칙을 위반할 때 발생하는 일은 [도우미 실패](#helper-failures)를 참조하세요.

* **범위**: [`Managed`](#scopes). [`policyHelper`](#policyhelper)가 읽히는 macOS plist, Windows HKLM 레지스트리 또는 관리형 설정 파일에서 읽습니다.
* **유형**: string, `.` 또는 `..` 세그먼트 없이 정규화된 형식의 절대 경로. Windows에서는 `.exe`로 끝나는 드라이브 문자 또는 UNC 경로
* **기본값**: 없음. `policyHelper`가 설정되면 필수

```json managed-settings.json theme={null}
{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy"
  }
}
```

### `policyHelper.timeoutMs`

Claude Code가 도우미를 기다리는 시간을 설정하고, 실행을 실패로 처리합니다. 시간 초과 실행은 0이 아닌 종료와 동일한 방식으로 실패하므로 시작 시 Claude Code는 시작을 거부합니다.

* **범위**: [`Managed`](#scopes). [`policyHelper`](#policyhelper)가 읽히는 macOS plist, Windows HKLM 레지스트리 또는 관리형 설정 파일에서 읽습니다.
* **유형**: integer, 밀리초, 최소 `1000`
* **기본값**: `10000`

```json managed-settings.json theme={null}
{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy",
    "timeoutMs": 5000
  }
}
```

### `policyHelper.refreshIntervalMs`

Claude Code가 백그라운드에서 간격으로 도우미를 다시 실행하여 정책 변경이 실행 중인 세션에 도달하도록 합니다. 새로고침이 성공하면 출력이 이전 관리형 설정을 다시 시작 없이 대체합니다. 새로고침이 실패하면 Claude Code는 이미 있는 정책을 유지합니다.

* **범위**: [`Managed`](#scopes). [`policyHelper`](#policyhelper)가 읽히는 macOS plist, Windows HKLM 레지스트리 또는 관리형 설정 파일에서 읽습니다.
* **유형**: integer, 밀리초: 새로고침을 비활성화하려면 `0`, 그렇지 않으면 최소 `60000`
* **기본값**: 설정 해제되어 Claude Code가 시작 시 도우미를 한 번 실행합니다.

이 예제는 5분마다 도우미를 다시 실행합니다:

```json managed-settings.json theme={null}
{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy",
    "refreshIntervalMs": 300000
  }
}
```

### `wslInheritsWindowsSettings`

Claude Code on WSL이 Windows 정책 체인에서 관리형 설정을 읽도록 하여 HKLM 및 Windows 관리형 설정 파일이 `/etc/claude-code` 및 아래의 HKCU보다 우선하도록 합니다. 체인이 켜져 있는 동안 Claude Code는 [HKLM 레지스트리 값 또는 `C:\Program Files\ClaudeCode\` 폴더에 Windows 관리자 문서가 없을 때](https://code.claude.com/docs/ko/managed-settings#present-admin-documents)만 `/etc/claude-code`를 읽습니다. Windows에 이미 배포한 정책을 WSL 세션으로 확장하도록 설정하여 호스트 세션과 동일한 규칙을 따르도록 합니다. Claude Code는 HKLM 레지스트리 키 또는 `C:\Program Files\ClaudeCode\` 아래의 관리형 설정 파일 또는 드롭인에 설정된 경우에만 인정하며, 둘 다 Windows 관리자가 작성해야 합니다.

* **범위**: [`Managed`](#scopes). 관리자 제어 Windows 소스에서.
* **유형**: Boolean
  * `true`: Claude Code on WSL은 Windows 정책 체인에서 관리형 설정을 읽고, Windows 관리자 문서가 없을 때만 `/etc/claude-code`를 읽습니다.
  * `false`: WSL은 `/etc/claude-code`만 읽습니다.
* **기본값**: `false`, WSL은 `/etc/claude-code`만 읽습니다.

```json managed-settings.json theme={null}
{
  "wslInheritsWindowsSettings": true
}
```

관리자 소스가 체인을 켜면 HKCU 정책은 HKCU도 키를 `true`로 설정할 때만 WSL에서 체인에 참여합니다. 해당 복사본은 체인을 자체적으로 켜지 않습니다. 이 키만 포함하고 `true` 또는 `false`로 설정된 Windows 소스는 정책 소스로 계산되지 않으므로 하위 우선 소스는 여전히 정책을 제공합니다. 이 키는 네이티브 Windows에 영향을 주지 않습니다.

Claude Code는 따옴표 있음 또는 없음으로 `true` 및 `false`를 읽고 `null`을 키 제거로 읽습니다. 다른 값을 보유하는 관리자 제어 Windows 소스는 체인이 켜져 있는 [현재 관리자 문서](https://code.claude.com/docs/ko/managed-settings.md#present-admin-documents)로 계산됩니다. `/etc/claude-code` 또는 HKCU는 적용되지 않으며, 시작 경고는 키의 이름을 지정합니다. 존재하지만 읽을 수 없는 HKLM 값 또는 Windows 폴더 파일도 체인이 켜져 있는지 여부와 관계없이 `/etc/claude-code`가 적용되는 것을 방지합니다. Claude Code v2.1.282 이상이 필요합니다.

## 전역 설정

이 키들을 `~/.claude.json`에 저장하세요. 설정 파일에는 저장하지 마세요. Claude Code는 다른 곳의 설정을 무시합니다. Claude Code와 `/config`가 대부분의 설정을 자동으로 작성하며, 수동으로 편집할 수도 있습니다.

### `autoConnectIde`

외부 터미널에서 Claude Code를 시작할 때 실행 중인 IDE에 자동으로 연결합니다. VS Code 또는 JetBrains 터미널 외부에서 Claude Code를 실행할 때 `/config`에 \*\*IDE에 자동 연결(외부 터미널)\*\*로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 외부 터미널에서 시작할 때 실행 중인 IDE에 자동으로 연결됩니다
  * `false`: Claude Code가 외부 터미널에서 자동으로 연결되지 않습니다. VS Code 또는 JetBrains 터미널 내부에서 또는 `--ide`를 사용하면 여전히 연결됩니다
* **기본값**: `false`
* **세션별 재정의**: [`CLAUDE_CODE_AUTO_CONNECT_IDE`](https://code.claude.com/docs/ko/env-vars)가 이 키보다 우선하며, 한 세션 동안 어느 방향이든 적용됩니다

```json ~/.claude.json theme={null}
{
  "autoConnectIde": true
}
```

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `autoInstallIdeExtension`

VS Code 터미널에서 Claude Code를 실행할 때 Claude Code IDE 확장을 자동으로 설치합니다. VS Code 또는 JetBrains 터미널 내부에서 Claude Code를 실행할 때 `/config`에 **IDE 확장 자동 설치**로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 VS Code 터미널에서 실행될 때 IDE 확장을 자동으로 설치합니다
  * `false`: Claude Code가 확장을 자동으로 설치하지 않습니다
* **기본값**: `true`
* **세션별 재정의**: [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](https://code.claude.com/docs/ko/env-vars)을 `1`로 설정하면 이 키가 `true`일 때도 한 세션 동안 설치를 건너뜁니다

```json ~/.claude.json theme={null}
{
  "autoInstallIdeExtension": false
}
```

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `claudeInChromeDefaultEnabled`

매번 `--chrome`을 전달하지 않고도 모든 대화형 CLI 세션을 [Chrome 통합](https://code.claude.com/docs/ko/chrome.md)이 켜진 상태로 시작합니다. [`claude remote-control`](https://code.claude.com/docs/ko/remote-control)을 실행하면 `bypassPermissions` 모드를 제외하고 시작하는 [프로젝트](https://code.claude.com/docs/ko/claude-projects.md) 스레드의 세션도 이 키를 따릅니다. Claude Code v2.1.287 이상에서는 이 키가 [VS Code 확장](https://code.claude.com/docs/ko/vs-code.md#automate-browser-tasks-with-chrome)의 세션에도 적용됩니다. [Chrome 기본적으로 활성화](https://code.claude.com/docs/ko/chrome.md#enable-chrome-by-default)를 참조하세요.

`/chrome`을 실행하고 **기본적으로 활성화됨**을 선택하면 이 키가 설정됩니다. `/config`에 **Chrome에서 Claude 기본적으로 활성화됨**으로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 대화형 CLI 세션이 시작될 때 Chrome 통합을 켭니다. `--chrome`을 전달할 때처럼 작동합니다. VS Code 확장에서는 세션이 시작될 때 브라우저에 연결됩니다
  * `false`: 대화형 CLI 세션이 Chrome 통합이 꺼진 상태로 시작되며, Claude Code는 [설정을 제안하는 것을 중단](https://code.claude.com/docs/ko/chrome.md#install-the-extension-when-claude-asks)합니다. 한 대화형 세션에 대해 켜려면 `--chrome`을 전달하세요. VS Code 확장에서는 키가 설정되지 않은 경우와 마찬가지로 `@browser`를 입력할 때 세션이 연결됩니다
* **기본값**: 설정되지 않음. Chrome 통합이 꺼져 있고 Claude Code는 여전히 설정을 제안할 수 있습니다
* **세션별 재정의**: `--chrome` 및 [`--no-chrome`](https://code.claude.com/docs/ko/cli-reference)이 한 대화형 세션에 대해 이 키보다 우선합니다

```json ~/.claude.json theme={null}
{
  "claudeInChromeDefaultEnabled": true
}
```

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `copyFullResponse`

선택기를 표시하지 않고 [`/copy`](https://code.claude.com/docs/ko/commands)가 매번 전체 응답을 복사하도록 합니다. 해당 선택기에서 **항상 전체 응답 복사**를 선택하면 이 키가 `true`로 설정됩니다. `/config`에 **/copy 선택기 건너뛰기**로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: Boolean
  * `true`: `/copy`가 선택기를 표시하지 않고 전체 응답을 복사합니다
  * `false`: 응답에 코드 블록이나 인용 블록이 포함되어 있을 때 `/copy`가 한 블록 또는 전체 응답을 선택하는 선택기를 표시합니다
* **기본값**: `false`

```json ~/.claude.json theme={null}
{
  "copyFullResponse": true
}
```

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `copyOnSelect`

[전체 화면 렌더링](https://code.claude.com/docs/ko/fullscreen.md#use-the-mouse) 또는 [에이전트 보기](https://code.claude.com/docs/ko/agent-view.md)에서 마우스로 텍스트 선택을 완료할 때 자동으로 클립보드에 복사합니다. 전체 화면 렌더링이 켜져 있을 때 `/config`에 **선택 시 복사**로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: Boolean
  * `true`: Claude Code가 텍스트 선택을 완료할 때 클립보드에 복사합니다
  * `false`: 텍스트 선택이 클립보드를 변경하지 않으며, 대신 [키보드 단축키로 선택 항목을 복사](https://code.claude.com/docs/ko/fullscreen.md#use-the-mouse)합니다
* **기본값**: `true`

```json ~/.claude.json theme={null}
{
  "copyOnSelect": false
}
```

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `defaultToAgentsView`

인수 없이 `claude`를 실행할 때 새 대화 대신 [에이전트 보기](https://code.claude.com/docs/ko/agent-view.md)를 엽니다. 에이전트 보기가 [꺼져 있지](#disableagentview) 않은 한 `/config`에 **기본적으로 에이전트 보기 열기**로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: Boolean
  * `true`: 인수 없는 `claude`가 에이전트 보기를 열며, 에이전트 보기가 [꺼져 있지](#disableagentview) 않은 경우입니다
  * `false`: 인수 없는 `claude`가 새 대화를 시작합니다
* **기본값**: `false`

```json ~/.claude.json theme={null}
{
  "defaultToAgentsView": true
}
```

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `diffTool`

[VS Code](https://code.claude.com/docs/ko/vs-code.md) 또는 [JetBrains](https://code.claude.com/docs/ko/jetbrains.md#features) IDE가 연결되어 있을 때 Claude Code가 제안하는 `Edit` 또는 `Write` 변경 사항의 diff를 표시할 위치를 선택합니다. `"auto"`는 IDE의 diff 뷰어에서 열고, `"terminal"`은 터미널에 유지합니다. Claude Code가 VS Code 또는 JetBrains IDE에 연결되어 있을 때만 `/config`에 **Diff 도구**로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: 문자열, 다음 중 하나:
  * `"auto"`: Claude Code가 VS Code 또는 JetBrains IDE에 연결되어 있을 때 IDE의 diff 뷰어에서 diff를 엽니다
  * `"terminal"`: Claude Code가 터미널에 diff를 유지합니다
* **기본값**: `"auto"`

```json ~/.claude.json theme={null}
{
  "diffTool": "terminal"
}
```

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `externalEditorContext`

`Ctrl+G`를 누르면 Claude Code가 입력 중인 프롬프트를 [외부 편집기](https://code.claude.com/docs/ko/interactive-mode.md#general-controls)에서 엽니다. 이 키를 켜면 편집기 버퍼가 Claude의 이전 응답으로 시작되며 `#` 주석 줄로 표시되므로 작성하는 동안 읽을 수 있고, Claude Code는 저장할 때 이 줄들을 제거합니다. `/config`에 **외부 편집기에서 마지막 응답 표시**로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: Boolean
  * `true`: 편집기 버퍼가 Claude의 이전 응답으로 시작되며 `#` 주석 줄로 표시되고, Claude Code는 저장할 때 이를 제거합니다
  * `false`: 편집기 버퍼가 프롬프트만으로 열립니다
* **기본값**: `false`

```json ~/.claude.json theme={null}
{
  "externalEditorContext": true
}
```

켜져 있을 때 Claude Code가 열 버퍼는 다음과 같으며, 마커 줄 아래의 텍스트만 프롬프트로 전송됩니다:

```text theme={null}
# ─── Claude's last response (for reference; removed on save) ───
# I added the retry loop to fetchUser in src/api.ts and a test
# for the timeout case. Want me to wire the same retry into
# fetchOrders?
# ─── Write your reply below this line ──────────────────────────

Yes, and cap it at three attempts.
```

Claude Code는 응답의 마지막 50줄을 유지하고 `# … (earlier output truncated)`로 자르기를 표시합니다.

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `leftArrowOpensAgents`

빈 프롬프트에서 `←`를 눌러 [세션을 백그라운드로 보내고 에이전트 보기를 엽니다](https://code.claude.com/docs/ko/agent-view.md#switch-sessions-without-leaving-the-terminal). 이 키를 `false`로 설정하여 단축키를 끕니다. 에이전트 보기를 사용할 수 있을 때 `/config`에 **← 에이전트 보기 열기**로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: Boolean
  * `true`: 터미널에서 시작한 세션의 빈 프롬프트에서 `←`를 누르면 세션을 백그라운드로 보내고 에이전트 보기를 엽니다
  * `false`: Claude Code가 단축키를 끕니다. [에이전트 보기에서 연결한](https://code.claude.com/docs/ko/agent-view.md#attach-to-a-session) 세션에서 빈 프롬프트의 `←`는 여전히 분리됩니다
* **기본값**: `true`

```json ~/.claude.json theme={null}
{
  "leftArrowOpensAgents": false
}
```

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `permissionExplainerEnabled`

> [!WARNING]
>
> v2.1.257에서 제거되었으며, Bash 및 PowerShell 권한 프롬프트의 `Ctrl+E` 명령 설명도 함께 제거되었습니다. 현재 버전에서 이를 설정해도 효과가 없습니다.

v2.1.256까지는 Bash 또는 PowerShell 권한 프롬프트에서 `Ctrl+E`를 눌러 모델이 생성한 명령 설명을 볼 수 있었으며, 이 키를 `false`로 설정하여 해당 단축키를 끌 수 있었습니다.

* **범위**: [`전역 설정`](#scopes). v2.1.256 이전 버전에서.
* **유형**: Boolean
* **기본값**: `true`

### `prStatusFooterEnabled`

현재 브랜치의 열린 풀 요청 또는 병합 요청에 대한 배지를 프롬프트 바닥글에 표시하며, 색상이 지정된 밑줄이 [상태](https://code.claude.com/docs/ko/interactive-mode.md#pr-review-status)를 표시합니다. `/config`에 **PR 상태 바닥글 표시**로 표시됩니다.

* **범위**: [`전역 설정`](#scopes)
* **유형**: Boolean
  * `true`: 바닥글이 [PR 검토 상태](https://code.claude.com/docs/ko/interactive-mode.md#pr-review-status)의 조건에서 배지를 표시합니다
  * `false`: Claude Code가 바닥글의 풀 요청 및 병합 요청 확인을 건너뛰고 해당 배지를 표시하지 않습니다. [에이전트 보기에서 연결한](https://code.claude.com/docs/ko/agent-view.md#attach-to-a-session) 세션은 여전히 [연결된](https://code.claude.com/docs/ko/agent-view.md#pull-request-status) 풀 요청에 대한 일반 링크를 표시할 수 있습니다
* **기본값**: `true`

```json ~/.claude.json theme={null}
{
  "prStatusFooterEnabled": false
}
```

Claude Code는 `settings.json`에서 이 키를 무시합니다.

### `teammateDefaultModel`

> [!WARNING]
>
> v2.1.234에서 제거되었으며, `/config` 행 **기본 팀원 모델**도 함께 제거되었습니다. 현재 버전에서 이를 설정해도 효과가 없습니다.

v2.1.233까지는 이 키를 [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md#specify-teammates-and-models) 팀원의 모델로 설정했으며, 프롬프트가 모델을 지정하지 않은 경우: `"sonnet"`과 같은 별칭 또는 리드의 모델을 따르려면 `null`. Claude Code가 현재 이러한 팀원을 위해 선택하는 모델은 [팀원 및 모델 지정](https://code.claude.com/docs/ko/agent-teams.md#specify-teammates-and-models)을 참조하세요.

* **범위**: [`전역 설정`](#scopes). v2.1.233 이전 버전에서.
* **유형**: 문자열, 모델 별칭 또는 전체 모델 ID, 또는 `null`
* **기본값**: 설정되지 않음

## 참고 항목

* [권한 구성](https://code.claude.com/docs/ko/permissions.md): 규칙 구문, 권한 모드 및 작업 영역 신뢰
* [환경 변수](https://code.claude.com/docs/ko/env-vars.md): Claude Code가 읽는 모든 `CLAUDE_*`, `ANTHROPIC_*` 및 공급자 변수
* [Claude에서 사용 가능한 도구](https://code.claude.com/docs/ko/tools-reference.md): 기본 제공 도구 및 승인이 필요한 도구
* [설정 파일 예제](https://code.claude.com/docs/ko/settings-example.md): 개인 파일, 팀 파일 및 조직의 관리 파일
* [관리 설정 설정](https://code.claude.com/docs/ko/admin-setup.md): 조직이 적용할 항목을 결정하는 방법
* [관리 설정 배포](https://code.claude.com/docs/ko/managed-settings.md): 전달 메커니즘, 관리 계층 내 우선순위 및 관리 설정의 잘못된 항목
* [구성 디버그](https://code.claude.com/docs/ko/debug-your-config.md): `claude doctor` 및 설정 오류 대화 상자