605 편집이 적용되는 시기605 편집이 적용되는 시기
606</h3>606</h3>
607 607
608Claude Code는 설정 파일을 감시하고 변경될 때 다시 로드하므로 대부분의 편집이 재시작 없이 실행 중인 세션에 적용됩니다. 여기에는 `permissions`, `hooks`, `apiKeyHelper`와 같은 자격 증명 도우미에 대한 편집이 포함됩니다. 다시 로드는 사용자, 프로젝트, 로컬, 관리되는 설정을 다룹니다. Claude Code는 감지된 각 설정 파일 변경에 대해 [`ConfigChange` hook](/docs/ko/hooks#configchange)을 실행하며, MDM 또는 claude.ai 콘솔에서 도착하는 관리되는 설정에 대해서는 실행하지 않습니다. MDM 또는 claude.ai 콘솔에서 도착하는 관리되는 설정은 일정에 따라 실행 중인 세션에 도달합니다. [전달 테이블](/docs/ko/managed-settings#choose-a-delivery-mechanism)은 소스별로 제공합니다.608Claude Code는 설정 파일을 감시하고 변경될 때 다시 로드하므로 대부분의 편집이 재시작 없이 실행 중인 세션에 적용됩니다. 여기에는 `permissions`, `hooks`, `apiKeyHelper`와 같은 자격 증명 도우미에 대한 편집이 포함됩니다. Claude Code는 또한 세션 중에 생성한 설정 파일을 로드합니다. 해당 폴더가 세션 시작 시 존재했다면 말입니다. 프로젝트의 `.claude/` 폴더의 경우 같은 세션에서 폴더를 생성할 때도 파일을 로드합니다.
609
610다시 로드는 사용자, 프로젝트, 로컬, 관리되는 설정을 다룹니다. Claude Code는 감지된 각 설정 파일 변경에 대해 [`ConfigChange` hook](/docs/ko/hooks#configchange)을 실행하며, MDM 또는 claude.ai 콘솔에서 도착하는 관리되는 설정에 대해서는 실행하지 않습니다. MDM 또는 claude.ai 콘솔에서 도착하는 관리되는 설정은 일정에 따라 실행 중인 세션에 도달합니다. [전달 테이블](/docs/ko/managed-settings#choose-a-delivery-mechanism)은 소스별로 제공합니다.
609 611
610Claude Code는 일부 키를 세션 시작 시에만 한 번 읽으므로 편집이 실행 중인 세션에 도달하지 않습니다. 관리자 측 키도 `requiredMinimumVersion`과 같이 재시작을 기다립니다. [정책이 적용되는 위치와 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)에 나열됩니다. 세션 중에 편집할 가능성이 가장 높은 것:612Claude Code는 일부 키를 세션 시작 시에만 한 번 읽으므로 편집이 실행 중인 세션에 도달하지 않습니다. 관리자 측 키도 `requiredMinimumVersion`과 같이 재시작을 기다립니다. [정책이 적용되는 위치와 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)에 나열됩니다. 세션 중에 편집할 가능성이 가장 높은 것:
611 613
651 설정 우선순위653 설정 우선순위
652</h2>654</h2>
653 655
654동일한 키가 여러 위치에 나타나면 Claude Code는 가장 높은 수준에서 값을 사용합니다. 아래 스택은 수준을 보여줍니다. 맨 위가 가장 높습니다. 높은 수준의 키는 아래 어디든 동일한 키를 재정의합니다.656동일한 키가 여러 위치에 나타나면 Claude Code는 가장 높은 수준에서 설정한 값을 사용합니다. 아래 스택은 수준을 보여주며, 맨 위가 가장 높습니다. 더 높은 수준의 키는 아래의 동일한 키를 재정의합니다.
655 657
656<SettingsPrecedence />658<SettingsPrecedence />
657 659
658순서대로, 가장 높은 우선순위 먼저:660순서대로, 가장 높은 우선순위부터:
659 661
6601. **관리되는 설정**: 조직이 배포하는 설정. `managed-settings.json` 파일, MDM 정책, 또는 claude.ai 콘솔의 [서버 관리 설정](/docs/ko/server-managed-settings). 아무것도 재정의하지 않습니다: `--settings`로 전달하는 키는 동일한 관리되는 키를 재정의하지 않으며, `--model`과 같은 플래그는 조직이 허용하는 모델에서만 선택합니다. 관리되는 `model`은 각 세션이 시작하는 모델을 설정하고, 여전히 `/model`로 전환할 수 있습니다. 잠금은 [`availableModels`](/docs/ko/settings-reference#availablemodels)이며, `/model`, `--model`, 자신의 파일의 `model` 키를 제한합니다. 조직이 여러 관리되는 소스를 전달하면 [관리되는 계층 내 우선순위](/docs/ko/managed-settings#precedence-within-the-managed-tier)의 규칙이 Claude Code가 각각에서 읽는 것을 설명합니다.6621. **관리되는 설정**: 조직이 배포하는 설정으로, `managed-settings.json` 파일, MDM 정책, 또는 claude.ai 콘솔의 [서버 관리 설정](/docs/ko/server-managed-settings)입니다. 사용자가 설정한 것은 이를 재정의할 수 없습니다. `--settings`로 전달한 키는 동일한 관리되는 키를 재정의하지 않으며, `--model`과 같은 플래그는 조직이 허용하는 모델에서만 선택합니다. 관리되는 `model`은 각 세션이 시작되는 모델을 설정하며, `/model`로 전환할 수 있습니다. 잠금은 [`availableModels`](/docs/ko/settings-reference#availablemodels)이며, 이는 `/model`, `--model`, 및 자신의 파일의 `model` 키를 제한합니다. 조직이 둘 이상의 관리되는 소스를 제공할 때, [관리되는 계층 내 우선순위](/docs/ko/managed-settings#precedence-within-the-managed-tier)의 규칙은 Claude Code가 각각에서 읽는 것을 나타냅니다.
6612. **명령줄 인수**: 터미널에서 `claude`를 시작할 때 전달하는 플래그. 한 세션용입니다. [한 세션에 대해 설정 변경](#change-a-setting-for-one-session)을 참조하세요. Claude Code는 `--settings <file-or-json>`으로 전달하는 JSON을 다른 수준과 동일한 규칙으로 병합합니다: 여기에 설정하는 키는 로컬, 프로젝트 또는 사용자 설정의 동일한 키를 가져가고, 생략하는 키는 낮은 수준 값을 유지합니다.6632. **명령줄 인수**: 터미널에서 `claude`를 시작할 때 전달하는 플래그로, 한 세션 동안 적용됩니다. [한 세션 동안 설정 변경](#change-a-setting-for-one-session)을 참조하세요. Claude Code는 `--settings <file-or-json>`으로 전달한 JSON을 다른 수준과 동일한 규칙으로 설정 파일과 병합합니다. 여기서 설정한 키를 로컬, 프로젝트 또는 사용자 설정의 동일한 키보다 우선하며, 생략한 키에 대해서는 낮은 수준의 값을 유지합니다.
6623. **프로젝트 로컬 설정** (`.claude/settings.local.json`): 이 프로젝트에 대한 개인 설정.6643. **프로젝트 로컬 설정** (`.claude/settings.local.json`): 이 프로젝트에 대한 개인 설정입니다.
6634. **공유 프로젝트 설정** (`.claude/settings.json`): 팀이 소스 제어에 체크인하는 설정.6654. **공유 프로젝트 설정** (`.claude/settings.json`): 팀이 소스 제어에 체크인하는 설정입니다.
6645. **사용자 설정** (`~/.claude/settings.json`): 모든 프로젝트에 대한 개인 설정.6665. **사용자 설정** (`~/.claude/settings.json`): 모든 프로젝트에 대한 개인 설정입니다.
665 667
666환경 변수는 이 스택의 수준이 아닙니다. 동작에 셸 변수와 설정 키가 모두 있으면 어느 것이 적용되는지는 수준별이 아니라 쌍별로 결정됩니다: `ANTHROPIC_MODEL`을 셸에서 내보내면 모든 파일의 `model` 키 위에 적용되는 반면, `ANTHROPIC_DEFAULT_MODEL`은 파일이 `model`을 설정하지 않을 때만 적용됩니다. [환경 변수 참조](/docs/ko/env-vars#precedence)는 어떤 키에 쌍이 있고 Claude Code가 먼저 읽는 것을 설명합니다. 설정 파일 내부의 `env` 블록은 일반 키이며 위의 수준을 따릅니다.668환경 변수는 이 스택의 수준이 아닙니다. 동작에 셸 변수와 설정 키가 모두 있을 때, 어느 것이 적용되는지는 수준이 아닌 쌍별로 결정됩니다. 셸에서 내보낸 `ANTHROPIC_MODEL`은 모든 파일의 `model` 키보다 우선하지만, `ANTHROPIC_DEFAULT_MODEL`은 파일이 `model`을 설정하지 않을 때만 적용됩니다. [환경 변수 참조](/docs/ko/env-vars#precedence)는 어느 키가 쌍을 가지고 있으며 Claude Code가 먼저 읽는 것을 나타냅니다. 설정 파일 내의 `env` 블록은 일반 키이며 위의 수준을 따릅니다.
667 669
668몇 가지 보안 민감 키의 경우 Claude Code는 낮은 수준의 더 엄격한 값을 관리되는 값보다 우선합니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)가 나열합니다.670몇 가지 보안에 민감한 키의 경우, Claude Code는 관리되는 값보다 낮은 수준의 더 엄격한 값을 준수합니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)에 이를 나열합니다.
669 671
670<h3 id="lists-merge-instead-of-overriding">672<h3 id="lists-merge-instead-of-overriding">
671 목록은 재정의하지 않고 병합합니다673 목록은 재정의 대신 병합됩니다
672</h3>674</h3>
673 675
674동일한 목록 키 (예: `permissions.allow`)를 여러 파일에 설정하면 Claude Code는 하나를 선택하지 않고 목록을 결합합니다. 따라서 각 파일은 다른 파일을 제거하지 않고 항목을 추가할 수 있습니다. 4개 키는 모델 목록 또는 모델별 항목을 보유하며 자체 규칙을 따릅니다:676`permissions.allow`와 같은 동일한 목록 키를 둘 이상의 파일에서 설정할 때, Claude Code는 하나를 선택하는 대신 목록을 결합하므로 각 파일은 다른 파일의 항목을 제거하지 않고 항목을 추가할 수 있습니다. 모델 목록 또는 모델별 항목을 보유하는 네 가지 키는 자신의 규칙을 따릅니다.
675 677
676* [`fallbackModel`](/docs/ko/settings-reference#fallbackmodel)은 위치가 의미를 가지는 순서가 지정된 체인이므로 Claude Code는 이를 정의하는 가장 높은 우선순위 파일에서 전체 값을 가져갑니다.678* [`fallbackModel`](/docs/ko/settings-reference#fallbackmodel)은 위치가 의미를 갖는 정렬된 체인이므로, Claude Code는 이를 정의하는 가장 높은 우선순위 파일의 전체 값을 사용합니다.
677* [`modelPicker`](/docs/ko/settings-reference#modelpicker)는 행의 하나의 순서가 지정된 목록과 바꾸기 플래그를 보유하므로 Claude Code는 두 소스의 행을 병합하지 않습니다. 관리되는 설정, `--settings`, 사용자 설정 중 가장 높은 것에서 전체 값을 가져가고 프로젝트 및 로컬 설정의 키를 무시합니다. Claude Code v2.1.242 이상이 필요합니다.679* [`modelPicker`](/docs/ko/settings-reference#modelpicker)는 하나의 정렬된 행 목록과 교체 플래그를 보유하므로, Claude Code는 두 소스의 행을 병합하지 않습니다. 이를 정의하는 관리되는 설정, `--settings`, 및 사용자 설정 중 가장 높은 것의 전체 값을 사용하며, 프로젝트 및 로컬 설정의 키를 무시합니다. Claude Code v2.1.242 이상이 필요합니다.
678* [`availableModels`](/docs/ko/settings-reference#availablemodels): Claude Code가 적용하는 관리되는 설정이 이를 정의할 때 Claude Code는 해당 목록을 그대로 적용하고 사용자, 프로젝트 또는 로컬 설정에 추가하는 항목을 무시합니다. embedding host가 자체 모델 목록을 제공하지 않으면 [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요. 관리되는 소스 전체에서 목록도 병합되지 않습니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 어느 소스의 목록이 적용되는지 설명합니다. 비 관리되는 범위 전체에서 Claude Code는 평소대로 배열을 병합합니다.680* [`availableModels`](/docs/ko/settings-reference#availablemodels): Claude Code가 적용하는 관리되는 설정이 이를 정의할 때, Claude Code는 해당 목록을 그대로 적용하고 사용자, 프로젝트 또는 로컬 설정에서 추가하는 항목을 무시합니다. 단, Claude Code를 포함하는 앱이 자신의 모델 목록을 제공하는 경우는 제외합니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요. 관리되는 소스 전체에서 목록은 병합되지 않습니다. [Claude Code가 관리되는 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 어느 소스의 목록이 적용되는지 나타냅니다. 관리되지 않는 범위 전체에서 Claude Code는 일반적으로 배열을 병합합니다.
679* [`modelSettings`](/docs/ko/settings-reference#modelsettings): Claude Code는 [`effortLevel`](/docs/ko/settings-reference#effortlevel)과 함께 한 번에 하나의 모델로 해결합니다. `modelSettings` 항목은 어느 파일의 값이 모델에 적용되는지 설명합니다.681* [`modelSettings`](/docs/ko/settings-reference#modelsettings): Claude Code는 [`effortLevel`](/docs/ko/settings-reference#effortlevel)과 함께 한 번에 하나의 모델로 이를 해결합니다. `modelSettings` 항목은 어느 파일의 값이 모델에 적용되는지 나타냅니다.
680 682
681<span id="examples" />683<span id="examples" />
682 684
684 우선순위 예제686 우선순위 예제
685</h3>687</h3>
686 688
687Claude가 작업하는 동안 Claude Code는 스피너 아래에 한 줄 팁을 표시합니다. 예: "권한 모드 기본값을 변경하려면 /config를 사용합니다 (Plan Mode 포함)". 팁을 끄고 싶어서 `~/.claude/settings.json`에서 [`spinnerTipsEnabled`](/docs/ko/settings-reference#spinnertipsenabled)를 `false`로 설정한다고 가정합니다. 아래의 각 시나리오는 팁을 다시 켤 수 있는 것과 할 수 있는 것입니다.689Claude가 작동하는 동안, Claude Code는 스피너 아래에 한 줄 팁을 표시합니다. 예를 들어 "Use /config to change your default permission mode (including Plan Mode)". 이러한 팁을 끄고 싶어서 `~/.claude/settings.json`에서 [`spinnerTipsEnabled`](/docs/ko/settings-reference#spinnertipsenabled)를 `false`로 설정했다고 가정합니다. 아래의 각 시나리오는 이를 다시 켤 수 있는 것과 이에 대해 할 수 있는 것입니다.
688 690
689<h4 id="team-settings-override-personal-settings">691<h4 id="team-settings-override-personal-settings">
690 팀 설정이 개인 설정을 재정의합니다692 팀 설정이 개인 설정을 재정의합니다
691</h4>693</h4>
692 694
693팀의 `.claude/settings.json`이 이를 `true`로 설정합니다. Claude Code는 공유 프로젝트가 사용자 위에 있으므로 프로젝트 값을 사용합니다. 해당 프로젝트에서 팁을 보고 다른 곳에서는 보지 않습니다.695팀의 `.claude/settings.json`이 이를 `true`로 설정합니다. Claude Code는 공유 프로젝트가 사용자 위에 있기 때문에 프로젝트 값을 사용하므로, 해당 프로젝트에서만 팁을 보고 다른 곳에서는 보지 않습니다.
694 696
695값을 다시 얻을 수 있습니다: 해당 프로젝트의 `.claude/settings.local.json`에 `"spinnerTipsEnabled": false`를 추가합니다. 프로젝트 로컬이 공유 프로젝트 위에 있으므로 세션이 팁을 표시하지 않고 팀원의 세션은 변경되지 않습니다.697값을 다시 얻을 수 있습니다. 해당 프로젝트의 `.claude/settings.local.json`에 `"spinnerTipsEnabled": false`를 추가합니다. 프로젝트 로컬이 공유 프로젝트 위에 있으므로, 해당 세션은 팁을 표시하지 않고 팀원의 세션은 변경되지 않습니다.
696 698
697<h4 id="organization-settings-override-everything">699<h4 id="organization-settings-override-everything">
698 조직 설정이 모든 것을 재정의합니다700 조직 설정이 모든 것을 재정의합니다
699</h4>701</h4>
700 702
701조직의 관리되는 설정이 이를 `true`로 설정합니다. 사용자, 프로젝트 또는 로컬 설정에 넣은 것도 팁을 끄지 않으며, `--settings`도 끄지 않습니다. 관리됨이 최고 수준입니다.703조직의 관리되는 설정이 이를 `true`로 설정합니다. 사용자, 프로젝트 또는 로컬 설정에 넣은 것도 팁을 끌 수 없으며, `--settings`도 마찬가지입니다. 관리되는 것이 최상위 수준입니다.
702 704
703값을 다시 얻을 수 없습니다. `/status`를 실행하여 어느 관리되는 소스가 적용되는지 확인하고 정책이 변경되어야 하는지 관리자에게 문의합니다.705값을 다시 얻을 수 없습니다. `/status`를 실행하여 어느 관리되는 소스가 적용되는지 확인하고, 정책을 변경해야 하는지 관리자에게 문의합니다.
704 706
705<h4 id="the-command-line-overrides-your-files-for-one-session">707<h4 id="the-command-line-overrides-your-files-for-one-session">
706 명령줄이 한 세션에 대해 파일을 재정의합니다708 명령줄이 한 세션 동안 파일을 재정의합니다
707</h4>709</h4>
708 710
709`claude --settings '{"spinnerTipsEnabled": true}'`로 세션을 시작했습니다. 명령줄이 관리됨을 제외한 모든 파일 위에 있으므로 해당 세션은 파일이 `false`라고 말해도 팁을 표시합니다.711`claude --settings '{"spinnerTipsEnabled": true}'`로 세션을 시작했습니다. 명령줄은 관리되는 것을 제외한 모든 파일 위에 있으므로, 파일이 `false`라고 말해도 해당 세션은 팁을 표시합니다.
710 712
711다음 세션에서 값을 다시 얻습니다. `--settings`는 한 세션 동안 지속되고 파일에 작성하지 않습니다.713다음 세션에서 값을 다시 얻습니다. `--settings`는 한 세션 동안만 지속되며 파일에 쓰지 않습니다.
712 714
713<h4 id="a-flag-or-environment-variable-sets-the-same-thing">715<h4 id="a-flag-or-environment-variable-sets-the-same-thing">
714 플래그 또는 환경 변수가 동일한 것을 설정합니다716 플래그 또는 환경 변수가 동일한 것을 설정합니다
715</h4>717</h4>
716 718
717일부 키에는 설정 값이 어느 파일에서 왔든 재정의하는 명령줄 플래그 또는 환경 변수가 있습니다: `ANTHROPIC_MODEL`은 [`model`](/docs/ko/settings-reference#model) 설정을 재정의하고, `--model`은 한 세션에 대해 둘 다 재정의합니다.719일부 키에는 설정 값을 재정의하는 명령줄 플래그 또는 환경 변수가 있으며, 이는 어느 파일이 설정했는지와 관계없이 적용됩니다. `ANTHROPIC_MODEL`은 [`model`](/docs/ko/settings-reference#model) 설정을 재정의하고, `--model`은 한 세션 동안 둘 다 재정의합니다.
718 720
719값을 다시 얻을 수 있는지는 키에 따라 다릅니다: 변수를 설정 해제하거나 플래그를 제거하고, [설정 참조](/docs/ko/settings-reference)의 키 항목과 [환경 변수 참조](/docs/ko/env-vars)의 변수 행을 확인하여 Claude Code가 어느 것을 사용하는지 확인합니다.721값을 다시 얻을 수 있는지는 키에 따라 다릅니다. 변수를 설정 해제하거나 플래그를 제거하고, [설정 참조](/docs/ko/settings-reference)의 키 항목과 [환경 변수 참조](/docs/ko/env-vars)의 변수 행을 확인하여 Claude Code가 어느 것을 사용하는지 확인합니다.
720 722
721<span id="keys-ignored-in-a-repository-file" />723<span id="keys-ignored-in-a-repository-file" />
722 724
730 적용되지 않는 설정 문제 해결732 적용되지 않는 설정 문제 해결
731</h3>733</h3>
732 734
733설정을 설정했는데 Claude Code가 설정한 것처럼 동작하지 않으면 `/status`로 시작하여 로드된 파일을 확인한 다음 아래에서 증상을 찾습니다. [구성 디버깅](/docs/ko/debug-your-config)은 깨끗한 구성 테스트를 포함한 더 넓은 검사를 다룹니다.735키를 설정했는데 Claude Code가 그렇게 동작하지 않으면, `/status`로 시작하여 로드한 파일을 확인한 다음 아래에서 증상을 찾습니다. [구성 디버그](/docs/ko/debug-your-config)는 깨끗한 구성 테스트를 포함한 더 넓은 검사를 다룹니다.
734 736
735<h4 id="a-value-you-set-is-ignored">737<h4 id="a-value-you-set-is-ignored">
736 설정한 값이 무시됩니다738 설정한 값이 무시됩니다
737</h4>739</h4>
738 740
739다른 것이 동일한 키를 설정하거나, 파일이 해당 값을 설정할 수 없거나, 파일이 로드되지 않았습니다:741다른 것이 동일한 키를 설정하거나, 파일이 해당 값을 설정할 수 없거나, 파일이 로드되지 않았습니다.
740 742
741* **더 높은 수준이 설정합니다.** 다른 설정 파일, `--settings` 플래그, 또는 관리되는 소스가 당신의 위에 키를 설정합니다. [스택](#settings-precedence)은 어느 것을 설명합니다. 플래그 또는 환경 변수도 자체적으로 키를 재정의할 수 있습니다. 쌍별로 결정됩니다. [설정 참조](/docs/ko/settings-reference)의 키 항목은 Claude Code가 어느 것을 사용하는지 설명하고, [`env` 항목](/docs/ko/settings-reference#env)은 관리되는 `env` 값 대 셸 내보내기를 다룹니다.743* **더 높은 수준이 이를 설정합니다.** 다른 설정 파일, `--settings` 플래그, 또는 관리되는 소스가 키를 위에서 설정합니다. [스택](#settings-precedence)은 어느 것인지 나타냅니다. 플래그 또는 환경 변수도 키별로 결정되는 키를 자체적으로 재정의할 수 있습니다. [설정 참조](/docs/ko/settings-reference)의 키 항목은 Claude Code가 어느 것을 사용하는지 나타내며, [`env` 항목](/docs/ko/settings-reference#env)은 관리되는 `env` 값 대 셸 내보내기를 다룹니다.
742* **보안 키가 엄격한 값을 유지합니다.** 몇 가지 키의 경우 Claude Code는 모든 파일에서 제한적 값을 우선합니다. 예: 프로젝트 `true`는 [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors)에 대해 유지됩니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요.744* **보안 키가 엄격한 값을 유지합니다.** 몇 가지 키의 경우 Claude Code는 모든 파일의 제한적인 값을 준수하므로, 프로젝트 `true`는 [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors)에 대해 켜진 상태로 유지됩니다. [관리되는 설정 우선순위의 예외](#exceptions-to-managed-settings-precedence)를 참조하세요.
743* **파일이 해당 값을 설정할 수 없습니다.** [`permissions.defaultMode`](/docs/ko/settings-reference#permissions-defaultmode) 값 `auto` 및 `bypassPermissions`은 프로젝트 또는 로컬 설정에서 적용되지 않습니다. 대신 사용자 또는 관리되는 설정에서 설정하거나 한 세션에 대해 `--permission-mode`를 전달합니다. v2.1.257 이전에 `bypassPermissions`은 모든 파일에서 적용되었습니다.745* **파일이 해당 값을 설정할 수 없습니다.** [`permissions.defaultMode`](/docs/ko/settings-reference#permissions-defaultmode) 값 `auto`와 `bypassPermissions`은 프로젝트 또는 로컬 설정에서 적용되지 않습니다. 대신 사용자 또는 관리되는 설정에서 설정하거나, 한 세션 동안 `--permission-mode`를 전달합니다. v2.1.257 이전에는 `bypassPermissions`이 모든 파일에서 적용되었습니다.
744* **파일이 손상되었습니다.** 유효하지 않은 JSON 또는 거부된 값은 Claude Code가 파일이나 항목을 건너뛰게 합니다. [손상된 설정 파일 수정](#fix-a-broken-settings-file)을 참조하세요.746* **파일이 손상되었습니다.** 잘못된 JSON 또는 거부된 값은 Claude Code가 파일 또는 항목을 건너뜁니다. [손상된 설정 파일 수정](#fix-a-broken-settings-file)을 참조하세요.
745 747
746<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">748<h4 id="a-change-you-made-in-claude-code-is-lost-in-new-sessions">
747 Claude Code에서 만든 변경이 새 세션에서 손실됩니다749 Claude Code에서 만든 변경 사항이 새 세션에서 손실됩니다
748</h4>750</h4>
749 751
750Claude Code 내에서 `/model`로 기본 모델을 설정하는 것과 같이 새 세션에 대한 선택을 저장하면 Claude Code가 사용자 설정 파일 `~/.claude/settings.json`에 작성합니다. 해당 파일에 쓸 수 없으면 (예: 다른 도구가 생성하거나 읽기 전용 복사본에 연결), 변경이 현재 세션에 적용되고 다음 세션에서 사라집니다. 파일을 생성하는 도구에서 키를 설정하거나 파일을 쓸 수 있는 것으로 바꿉니다.752Claude Code 내에서 새 세션을 위한 선택을 저장할 때, 예를 들어 `/model`로 기본 모델을 저장할 때, Claude Code는 사용자 설정 파일 `~/.claude/settings.json`에 씁니다. 해당 파일에 쓸 수 없으면, 예를 들어 다른 도구가 생성하거나 읽기 전용 복사본에 연결하면, 변경 사항은 현재 세션에 적용되고 다음 세션에서 손실됩니다. 파일을 생성하는 도구에서 키를 설정하거나, 파일을 쓸 수 있는 파일로 바꿉니다.
751 753
752파일에 쓸 수 있고 변경이 여전히 지속되지 않으면 변경이 [한 세션만](#change-a-setting-for-one-session) 또는 [더 높은 수준이 동일한 키를 설정](#a-value-you-set-is-ignored)하는지 확인합니다. `model` 키의 경우 [새 세션이 선택한 것과 다른 모델에서 시작합니다](/docs/ko/model-config#a-new-session-starts-on-a-different-model-than-you-picked)가 더 많은 원인을 나열합니다.754파일에 쓸 수 있고 변경 사항이 여전히 지속되지 않으면, 변경 사항이 [한 세션 동안만](#change-a-setting-for-one-session) 또는 [더 높은 수준이 동일한 키를 설정](#a-value-you-set-is-ignored)했는지 확인합니다. `model` 키의 경우, [새 세션이 선택한 것과 다른 모델에서 시작됩니다](/docs/ko/model-config#a-new-session-starts-on-a-different-model-than-you-picked)는 더 많은 원인을 나열합니다.
753 755
754<h4 id="a-managed-change-hasn’t-reached-you">756<h4 id="a-managed-change-hasn’t-reached-you">
755 관리되는 변경이 당신에게 도달하지 않았습니다757 관리되는 변경 사항이 도달하지 않았습니다
756</h4>758</h4>
757 759
758관리되는 소스는 [전달 테이블](/docs/ko/managed-settings#choose-a-delivery-mechanism)의 일정에 따라 실행 중인 세션에 도달하므로 먼저 세션을 다시 시작합니다. `/status`가 관리자가 변경한 것과 다른 소스의 이름을 지정하면 더 높은 우선순위 소스가 적용됩니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 순서를 제공합니다.760관리되는 소스는 [전달 테이블](/docs/ko/managed-settings#choose-a-delivery-mechanism)의 일정에 따라 실행 중인 세션에 도달하므로, 먼저 세션을 다시 시작합니다. `/status`가 관리자가 변경한 것과 다른 소스를 나타내면, 더 높은 우선순위 소스가 적용됩니다. [Claude Code가 관리되는 소스를 결합하는 방법](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 순서를 제공합니다.
759 761
760<h4 id="a-committed-key-doesn’t-reach-teammates">762<h4 id="a-committed-key-doesn’t-reach-teammates">
761 커밋된 키가 팀원에게 도달하지 않습니다763 커밋된 키가 팀원에게 도달하지 않습니다
762</h4>764</h4>
763 765
7642가지가 `.claude/settings.json`의 키가 복제하는 모든 사람에게 적용되는 것을 방지합니다:766두 가지가 `.claude/settings.json`의 키가 이를 복제하는 모든 사람에게 적용되는 것을 방지합니다.
765 767
766* **Claude Code가 저장소 파일의 키를 무시합니다.** [설정 인덱스](/docs/ko/settings-reference#settings-index)의 범위 열에서 `User, local, or managed`, `User or managed`, `Managed`, 또는 `Global config`를 찾습니다. 해당 키는 공유 파일에서 적용되지 않습니다. [`autoContinueAtUsageLimit`](/docs/ko/settings-reference#autocontinueatusagelimit) 제외. 저장소 파일은 여전히 키를 끌 수 있습니다: 파일이 키를 설정하고 사용자, `--settings`, 또는 관리되는 값이 하지 않으면 Claude Code는 설정을 끈 것으로 읽습니다. `Global config` 키는 `~/.claude.json`에서만 적용됩니다.768* **Claude Code는 저장소 파일의 키를 무시합니다.** [설정 인덱스](/docs/ko/settings-reference#settings-index)의 범위 열에서 `User, local, or managed`, `User or managed`, `Managed`, 또는 `Global config`를 찾습니다. 이러한 키는 [`autoContinueAtUsageLimit`](/docs/ko/settings-reference#autocontinueatusagelimit)를 제외하고 공유 파일에서 적용되지 않습니다. 저장소 파일은 여전히 키를 끌 수 있습니다. 파일이 키를 설정하고 사용자, `--settings`, 또는 관리되는 값이 없으면, Claude Code는 설정을 끈 것으로 읽습니다. `Global config` 키는 `~/.claude.json`에서만 적용됩니다.
767* **키가 신뢰를 기다립니다.** `permissions.allow` 규칙, `permissions.additionalDirectories`, `extraKnownMarketplaces`, 대부분의 [`env`](/docs/ko/settings-reference#env) 값은 각 팀원이 [폴더를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 후에만 적용됩니다. 그때까지 여전히 프롬프트를 보고 파일이 선언하는 마켓플레이스에서 플러그인을 받지 않습니다. `deny` 및 `ask` 규칙은 즉시 적용됩니다.769* **키가 신뢰를 기다립니다.** `permissions.allow` 규칙, `permissions.additionalDirectories`, `extraKnownMarketplaces`, 및 대부분의 [`env`](/docs/ko/settings-reference#env) 값은 각 팀원이 [폴더를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)한 후에만 적용됩니다. 그때까지 그들은 여전히 프롬프트를 보고 파일이 선언하는 마켓플레이스에서 플러그인을 얻지 못합니다. `deny`와 `ask` 규칙은 즉시 적용됩니다.
768 770
769<h4 id="permission-rules-combine-differently-than-you-expected">771<h4 id="permission-rules-combine-differently-than-you-expected">
770 권한 규칙이 예상과 다르게 결합됩니다772 권한 규칙이 예상과 다르게 결합됩니다
771</h4>773</h4>
772 774
773* **권한 프롬프트에서 "예, 다시 묻지 마세요"를 선택했지만 여전히 동일한 도구에 대해 프롬프트를 받습니다.** 해당 선택이 로컬 파일에 `allow` 규칙을 저장했고, `allow` 규칙은 프로젝트 또는 관리되는 파일의 `ask` 규칙을 능가하지 않습니다. [권한 규칙이 결합되는 방식](/docs/ko/permissions#settings-precedence)은 순서를 설명합니다. VS Code 확장에서 승인 카드는 프로젝트의 공유 파일을 포함한 대상 파일을 선택할 수 있으므로 모든 사람의 규칙을 변경합니다. CLI에서 Claude Code는 로컬 파일에만 작성합니다.775* **권한 프롬프트에서 "Yes, and don't ask again"을 선택했지만 여전히 동일한 도구에 대해 프롬프트를 받습니다.** 해당 선택은 `allow` 규칙을 로컬 파일에 저장했으며, 로컬 파일의 `allow` 규칙은 프로젝트 또는 관리되는 파일의 `ask` 규칙을 능가하지 않습니다. [권한 규칙이 결합되는 방법](/docs/ko/permissions#settings-precedence)은 순서를 설명합니다. VS Code 확장에서 승인 카드는 프로젝트의 공유 파일을 포함한 대상 파일을 선택할 수 있으며, 이는 모든 사람을 위한 규칙을 변경합니다. CLI에서 Claude Code는 로컬 파일에만 씁니다.
774* **조직의 allow 규칙이 당신의 것과 함께 적용됩니다.** 예상됩니다: Claude Code는 [`permissions.allow`](/docs/ko/settings-reference#permissions-allow)를 범위 전체에서 병합합니다. [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)를 설정하지 않으면.776* **조직의 허용 규칙이 여전히 사용자의 규칙과 함께 적용됩니다.** 이는 예상된 것입니다. Claude Code는 조직이 [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly)를 설정하지 않는 한 범위 전체에서 [`permissions.allow`](/docs/ko/settings-reference#permissions-allow)를 병합합니다.
775 777
776<span id="security-keys-where-the-stricter-value-applies" />778<span id="security-keys-where-the-stricter-value-applies" />
777 779
779 관리되는 설정 우선순위의 예외781 관리되는 설정 우선순위의 예외
780</h3>782</h3>
781 783
782몇 가지 보안 민감 키의 경우 Claude Code는 다른 경우 관리되는 설정을 재정의할 수 없는 범위에서 제한적 값을 우선합니다. 이 테이블에서 키를 찾아 우선하는 값과 어디서 오는지 확인합니다.784값이 세션을 제한하는 몇 가지 키의 경우, Claude Code는 관리되는 설정을 재정의할 수 없는 범위의 제한적인 값을 준수합니다. 이 표에서 키를 찾아 어느 값을 준수하는지 그리고 어디서 준수하는지 확인합니다.
783 785
784| 키 | Claude Code가 우선하는 값 | 참고 |786| 키 | Claude Code가 준수하는 값 | 참고 |
785| :------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |787| :------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |
786| [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors) | 모든 범위의 `true` | 관리되는 소스가 `false`를 설정해도 우선합니다 |788| [`disableClaudeAiConnectors`](/docs/ko/settings-reference#disableclaudeaiconnectors) | 모든 범위의 `true` | 관리되는 소스가 `false`를 설정할 때도 준수됩니다 |
787| [`enableArtifact`](/docs/ko/settings-reference#enableartifact) | 모든 범위의 `false`, 모든 범위의 `disableArtifact: true` | 관리되는 소스가 `true`를 설정해도 우선합니다. 아무것도 [Artifact 도구](/docs/ko/artifacts#disable-artifacts)를 다시 켜지 않습니다. Claude Code v2.1.242 이상이 필요합니다 |789| [`enableArtifact`](/docs/ko/settings-reference#enableartifact) | 모든 범위의 `false`, 그리고 모든 범위의 `disableArtifact: true` | 관리되는 소스가 `true`를 설정할 때도 준수됩니다. 아무것도 [Artifact 도구](/docs/ko/artifacts#disable-artifacts)를 다시 켤 수 없습니다. Claude Code v2.1.242 이상이 필요합니다 |
788| [`isolatePeerMachines`](/docs/ko/settings-reference#isolatepeermachines) | 모든 범위의 `true` | 관리되는 소스가 `false`를 설정해도 우선합니다 |790| [`isolatePeerMachines`](/docs/ko/settings-reference#isolatepeermachines) | 모든 범위의 `true` | 관리되는 소스가 `false`를 설정할 때도 준수됩니다 |
789| [`remoteControlAtStartup`](/docs/ko/settings-reference#remotecontrolatstartup) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 `false` | 관리되는 소스가 `true`를 설정해도 우선합니다. 프로젝트 또는 로컬 `true`는 무시됩니다 |791| [`remoteControlAtStartup`](/docs/ko/settings-reference#remotecontrolatstartup) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 `false` | 관리되는 소스가 `true`를 설정할 때도 준수됩니다. 프로젝트 또는 로컬 `true`는 무시됩니다 |
790| [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 더 엄격한 값. `accept` \< `hold` \< `refuse` 사다리 | 관리되는, `--settings`, 사용자 값보다 우선합니다. 프로젝트 또는 로컬 값이 더 엄격하지 않으면 무시됩니다 |792| [`crossSessionInbound`](/docs/ko/settings-reference#crosssessioninbound) | `.claude/settings.json` 또는 `.claude/settings.local.json`의 더 엄격한 값, `accept` \< `hold` \< `refuse` 사다리에서 | 관리되는, `--settings`, 및 사용자 값보다 준수됩니다. 더 엄격하지 않은 프로젝트 또는 로컬 값은 무시됩니다 |
791| [`useAutoModeDuringPlan`](/docs/ko/settings-reference#useautomodeduringplan) | 모든 관리되는 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 우승 관리되는 소스가 `true`를 설정해도 우선합니다. `.claude/settings.json`의 `false`는 무시됩니다 |793| [`useAutoModeDuringPlan`](/docs/ko/settings-reference#useautomodeduringplan) | 모든 관리되는 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리되는 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |
792| [`syncClaudeAiSkills`](/docs/ko/settings-reference#syncclaudeaiskills) | 모든 관리되는 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 우승 관리되는 소스가 `true`를 설정해도 우선합니다. `.claude/settings.json`의 `false`는 무시됩니다 |794| [`syncClaudeAiSkills`](/docs/ko/settings-reference#syncclaudeaiskills) | 모든 관리되는 소스, `--settings`, `~/.claude/settings.json`, 또는 `.claude/settings.local.json`의 `false` | 승리한 관리되는 소스가 `true`를 설정할 때도 준수됩니다. `.claude/settings.json`의 `false`는 무시됩니다 |
795| [`maxEffortLevel`](/docs/ko/settings-reference#maxeffortlevel) | `--settings`를 포함한 모든 범위의 더 낮은 상한 | Claude Code가 적용하는 관리되는 설정이 더 높은 상한을 설정할 때도 준수됩니다. 가장 낮은 상한이 적용됩니다. Claude Code v2.1.267 이상이 필요합니다 |
793 796
794Claude Code를 자체 내부에서 실행하고 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정하는 앱도 예외입니다. Claude Code는 모든 관리되는 소스의 `model`, `fallbackModel`, `modelOverrides` 키 위에 해당 앱의 모델 구성을 가져가고, 관리되는 `env` 블록의 `ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_*_MODEL` 패밀리와 같은 모델 선택 변수를 가져갑니다. Claude Code는 앱이 자체를 제공하지 않으면 관리되는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록을 적용합니다.797[`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ko/env-vars)를 설정하고 Claude Code를 자신 내부에서 실행하는 앱도 예외입니다. Claude Code는 모든 관리되는 소스의 `model`, `fallbackModel`, `modelPicker`, 및 `modelOverrides` 키보다, 그리고 관리되는 `env` 블록의 모델 선택 변수(예: `ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_*_MODEL` 계열)보다 해당 앱의 모델 구성을 사용합니다. Claude Code는 앱이 자신의 것을 제공하지 않는 한 관리되는 [`availableModels`](/docs/ko/settings-reference#availablemodels) 허용 목록을 적용 중으로 유지합니다.
795 798
796<h2 id="settings-in-cloud-sessions">799<h2 id="settings-in-cloud-sessions">
797 클라우드 세션의 설정800 클라우드 세션의 설정