397<span id="where-settings-live" />397<span id="where-settings-live" />
398 398
399<h2 id="settings-files-and-who-they-affect">399<h2 id="settings-files-and-who-they-affect">
400 설정 파일 및 영향을 받는 대상400 설정 파일 및 영향을 받는 사용자
401</h2>401</h2>
402 402
403Claude Code는 네 개의 파일에서 설정을 읽으며, 조직은 claude.ai 콘솔에서 관리되는 설정을 제공할 수도 있습니다. 각 소스는 범위를 가지고 있습니다. 즉, 설정이 적용되는 사람과 프로젝트의 집합으로, 개인, 프로젝트의 모든 사람, 또는 조직의 모든 사람일 수 있습니다.403Claude Code는 네 개의 파일에서 설정을 읽으며, 조직은 claude.ai 콘솔에서 관리되는 설정을 제공할 수도 있습니다. 각 소스는 범위를 가지고 있습니다. 즉, 설정이 적용되는 사람과 프로젝트의 집합으로, 개인 사용자, 프로젝트의 모든 사람, 또는 조직의 모든 사람일 수 있습니다.
404 404
405| 범위 | 파일 | 영향을 받는 대상 | 용도 |405| 범위 | 파일 | 영향을 받는 사용자 | 용도 |
406| :------ | :------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- | :------------------------------------ |406| :------ | :------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :------------------------------------- |
407| 사용자 | `~/.claude/settings.json` | 이 머신의 모든 프로젝트에서 사용자 | 개인 설정: 테마, 편집기 모드, 기본 모델, 자신의 권한 규칙 |407| 사용자 | `~/.claude/settings.json` | 이 머신의 모든 프로젝트에서 사용자 | 개인 설정: 테마, 편집기 모드, 기본 모델, 사용자 정의 권한 규칙 |
408| 공유 프로젝트 | `.claude/settings.json` | 이를 포함하는 폴더에서 작업하는 모든 사람. Git 저장소에서는 커밋하여 팀원이 받도록 함 | 팀 권한, hooks, plugins, 프로젝트에 필요한 환경 변수 |408| 공유 프로젝트 | `.claude/settings.json` | 이를 포함하는 폴더에서 작업하는 모든 사람. Git 저장소에서는 커밋하여 팀원이 받도록 함 | 팀 권한, 훅, 플러그인, 프로젝트에 필요한 환경 변수 |
409| 프로젝트 로컬 | `.claude/settings.local.json` | 이 프로젝트에서만 사용자. Claude Code는 파일을 생성할 때 git에서 제외함. 직접 생성한 경우 `.gitignore`에 추가 | 한 프로젝트에 대한 개인 설정 재정의 및 공유 전 테스트 |409| 프로젝트 로컬 | `.claude/settings.local.json` | 이 프로젝트에서만 사용자. Claude Code는 파일을 생성할 때 git에서 제외함. 수동으로 생성한 경우 `.gitignore`에 직접 추가 | 한 프로젝트에 대한 개인 설정 재정의 및 공유 전 테스트 |
410| 관리됨 | `managed-settings.json` 및 기타 [관리되는 소스](/docs/ko/managed-settings#delivery-mechanisms) | 조직이 배포하는 모든 대상. 몇 가지 [보안 관련 예외](#exceptions-to-managed-settings-precedence)를 제외하고 설정한 것이 이를 재정의하지 않음 | 보안 정책 및 규정 준수 요구사항 |410| 관리됨 | `managed-settings.json` 및 기타 [관리되는 소스](/docs/ko/managed-settings#delivery-mechanisms) | 조직이 배포하는 모든 사용자. 몇 가지 [보안 관련 예외](#exceptions-to-managed-settings-precedence)를 제외하고 설정한 것이 이를 재정의하지 않음 | 보안 정책 및 규정 준수 요구사항 |
411 411
412파일 열에서 `~/.claude`는 홈 디렉토리의 `.claude` 폴더이고, 단순 `.claude`는 프로젝트 내부의 `.claude` 폴더입니다.412파일 열에서 `~/.claude`는 홈 디렉토리의 `.claude` 폴더이고, 단순 `.claude`는 프로젝트 내부의 `.claude` 폴더입니다.
413 413
421 421
422머신에 `website/`, `api/`, `acme-app/` 세 개의 프로젝트가 있고, 팀원이 `acme-app/`의 자신의 클론을 가지고 있으며, `acme-app/`에서 [클라우드 세션](#settings-in-cloud-sessions)을 시작한다고 가정합니다.422머신에 `website/`, `api/`, `acme-app/` 세 개의 프로젝트가 있고, 팀원이 `acme-app/`의 자신의 클론을 가지고 있으며, `acme-app/`에서 [클라우드 세션](#settings-in-cloud-sessions)을 시작한다고 가정합니다.
423 423
424아래 그래픽은 이들 폴더에서 Claude Code를 시작할 때 설정이 적용되는 폴더를 보여줍니다. 설정 파일을 클릭하여 도달하는 폴더를 확인합니다.424아래 그래픽은 이러한 폴더에서 Claude Code를 시작할 때 설정이 적용되는 폴더를 보여줍니다. 설정 파일을 클릭하여 도달하는 폴더를 확인합니다.
425 425
426<SettingsScope />426<SettingsScope />
427 427
428* **`~/.claude/settings.json`**: 머신의 모든 프로젝트, 팀원의 것이나 클라우드 세션의 것은 제외428* **`~/.claude/settings.json`**: 머신의 모든 프로젝트, 팀원의 것이나 클라우드 세션의 것은 제외
429* **`acme-app/.claude/settings.json`**: 사용자의 `acme-app/`. 파일을 버전 제어에 커밋한 경우에만 팀원의 클론과 클라우드 세션에 도달합니다. 그 전까지는 다른 파일처럼 디스크의 파일이며 다른 사람은 가지고 있지 않습니다429* **`acme-app/.claude/settings.json`**: 사용자의 `acme-app/`. 파일을 버전 제어에 커밋한 경우에만 팀원의 클론과 클라우드 세션에 도달합니다. 커밋하기 전까지는 다른 파일처럼 디스크의 파일이며 다른 사람은 이를 가지지 않습니다.
430* **`acme-app/.claude/settings.local.json`**: 사용자의 `acme-app/`만. Claude Code는 파일을 처음 쓸 때 전역 git 제외에 추가하므로 커밋에서 제외됩니다. 파일을 직접 생성한 경우 [`.gitignore`에 직접 추가](#keep-personal-settings-out-of-a-repository)합니다430* **`acme-app/.claude/settings.local.json`**: 사용자의 `acme-app/`만. Claude Code는 파일을 처음 작성할 때 전역 git 제외에 추가하므로 커밋에서 제외됩니다. 수동으로 파일을 생성한 경우 [`.gitignore`에 직접 추가](#keep-personal-settings-out-of-a-repository)합니다.
431* **관리되는 설정**, `managed-settings.json` 파일, MDM 정책, 또는 claude.ai 콘솔의 [서버 관리 설정](/docs/ko/server-managed-settings)인지 여부: 조직이 배포하는 모든 머신의 모든 프로젝트, 또는 조직 계정으로 로그인하는 모든 머신. 서버 관리 설정만 클라우드 세션에 도달합니다431* **관리되는 설정**, `managed-settings.json` 파일, MDM 정책, 또는 claude.ai 콘솔의 [서버 관리 설정](/docs/ko/server-managed-settings): 조직이 배포하는 모든 머신의 모든 프로젝트, 또는 조직 계정으로 로그인한 모든 머신. 서버 관리 설정만 클라우드 세션에 도달합니다.
432 432
433<span id="which-files-you-have" />433<span id="which-files-you-have" />
434 434
438 438
439Claude Code를 설치해도 설정 파일이 생성되지 않습니다. 머신이나 프로젝트에 이미 파일이 있다면 다음 중 하나에서 온 것입니다:439Claude Code를 설치해도 설정 파일이 생성되지 않습니다. 머신이나 프로젝트에 이미 파일이 있다면 다음 중 하나에서 온 것입니다:
440 440
441* **관리됨**: 조직이 배포합니다. 생성하거나 편집하지 않습니다.441* **관리됨**: 조직이 배포합니다. 사용자가 생성하거나 편집하지 않습니다.
442* **공유 프로젝트**: Claude Code를 이미 사용하는 프로젝트에 커밋된 파일이 있을 수 있습니다. 없으면 프로젝트 폴더에 `.claude/settings.json`을 생성합니다.442* **공유 프로젝트**: Claude Code를 이미 사용하는 프로젝트에 커밋된 파일이 있을 수 있습니다. 없으면 프로젝트 폴더에 `.claude/settings.json`을 생성합니다.
443* **사용자** 및 **프로젝트 로컬**: 직접 생성하거나 Claude Code가 생성하도록 합니다. 테마와 같이 사용자 설정에 저장하는 `/config` 메뉴의 옵션을 처음 변경할 때 `~/.claude/settings.json`을 쓰고, Bash 명령에 대해 "Yes, and don't ask again"과 같은 권한 프롬프트에서 처음 승인을 할 때 `.claude/settings.local.json`을 씁니다. **Show tips**를 포함한 몇 가지 `/config` 옵션은 사용자 파일 대신 `.claude/settings.local.json`에 저장됩니다.443* **사용자** 및 **프로젝트 로컬**: 직접 생성하거나 Claude Code가 생성하도록 합니다. 테마와 같이 사용자 설정에 저장되는 `/config` 메뉴의 옵션을 처음 변경할 때 `~/.claude/settings.json`을 작성하고, Bash 명령에 대해 "Yes, and don't ask again"과 같은 권한 프롬프트에서 처음 승인을 할 때 `.claude/settings.local.json`을 작성합니다. **Show tips**를 포함한 몇 가지 `/config` 옵션은 사용자 파일 대신 `.claude/settings.local.json`에 저장됩니다.
444 444
445<Info>445<Info>
446 Windows에서 `~/.claude`는 `%USERPROFILE%\.claude`를 의미합니다. 홈 디렉토리 파일을 다른 곳에 보관하려면 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정합니다. Claude Code는 설정, 세션 기록, plugins을 대신 저장합니다.446 Windows에서 `~/.claude`는 `%USERPROFILE%\.claude`를 의미합니다. 홈 디렉토리 파일을 다른 곳에 보관하려면 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 설정합니다. Claude Code는 설정, 세션 기록, 플러그인을 대신 그곳에 저장합니다.
447</Info>447</Info>
448 448
449Claude Code는 또한 다섯 번째 파일인 [`~/.claude.json`](/docs/ko/claude-directory#ce-claude-json)을 유지합니다. 이는 자신을 위해 쓰는 파일이므로 편집할 필요가 없습니다. 로그인 세션, [MCP server](/docs/ko/mcp) 구성, 신뢰 결정과 같은 프로젝트별 상태, 그리고 `/config`가 사용자를 위해 쓰는 [전역 구성 키](/docs/ko/settings-reference#global-config-settings)를 보유합니다.449Claude Code는 또한 다섯 번째 파일인 [`~/.claude.json`](/docs/ko/claude-directory#ce-claude-json)을 유지합니다. 이는 Claude Code가 자신을 위해 작성하는 파일이므로 편집할 필요가 없습니다. 로그인 세션, [MCP 서버](/docs/ko/mcp) 구성, 신뢰 결정과 같은 프로젝트별 상태, `/config`가 사용자를 위해 작성하는 [전역 구성 키](/docs/ko/settings-reference#global-config-settings)를 보유합니다.
450 450
451<h3 id="share-settings-with-your-team">451<h3 id="share-settings-with-your-team">
452 팀과 설정 공유452 팀과 설정 공유
453</h3>453</h3>
454 454
455`.claude/settings.json`을 커밋하여 저장소를 클론하는 모든 사람이 동일한 권한, hooks, 원격 측정, plugins을 받도록 합니다. 각 팀원은 자신의 `.claude/settings.local.json`에서 자신을 위해 재정의할 수 있으므로 개인 예외는 커밋이 필요하지 않습니다. 완전한 팀 파일은 [팀의 공유 설정](/docs/ko/settings-example#a-teams-shared-settings)을 참조합니다.455`.claude/settings.json`을 커밋하여 저장소를 클론하는 모든 사람이 동일한 권한, 훅, 원격 측정, 플러그인을 받도록 합니다. 각 팀원은 여전히 자신의 `.claude/settings.local.json`에서 이를 재정의할 수 있으므로 개인 예외는 커밋할 필요가 없습니다. 완전한 팀 파일은 [팀의 공유 설정](/docs/ko/settings-example#a-teams-shared-settings)을 참조합니다.
456 456
457커밋하는 것 중 일부는 각 팀원이 [폴더를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)할 때까지 기다리며, 몇 가지 키는 저장소 파일에서 적용되지 않습니다. [적용되지 않는 설정 문제 해결](#common-cases)은 둘 다 다룹니다.457커밋하는 일부 항목은 각 팀원이 [폴더를 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust)할 때까지 기다리며, 몇 가지 키는 저장소 파일에서 적용되지 않습니다. [적용되지 않는 설정 문제 해결](#common-cases)은 둘 다 다룹니다.
458 458
459<span id="local-settings-file" />459<span id="local-settings-file" />
460 460
468 저장소에서 개인 설정 제외468 저장소에서 개인 설정 제외
469</h3>469</h3>
470 470
471팀원을 위해 변경하지 않고 한 프로젝트에서 자신을 위해 설정을 변경하려면 프로젝트 내부의 `.claude/settings.local.json`에 저장합니다. Claude Code는 커밋된 `.claude/settings.json` 위에 해당 파일을 적용하므로, 팀의 파일이 `"model": "claude-sonnet-5"`를 설정하고 Opus를 원하면 로컬 파일에 `"model": "claude-opus-4-8"`을 넣으면 세션만 변경됩니다.471한 프로젝트에서 팀원을 변경하지 않고 자신을 위해 설정을 변경하려면 프로젝트 내부의 `.claude/settings.local.json`에 저장합니다. Claude Code는 커밋된 `.claude/settings.json`에 해당 파일을 적용하므로, 팀의 파일이 `"model": "claude-sonnet-5"`를 설정하고 Opus를 원하면 로컬 파일에 `"model": "claude-opus-5-5"`를 입력하고 세션만 변경됩니다.
472 472
473Claude Code는 또한 이 파일에 쓰고, 커밋에서 제외하며, 신뢰 단계 없이 allow 규칙을 적용합니다:473Claude Code는 또한 이 파일에 작성하고, 커밋에서 제외하며, 신뢰 단계 없이 허용 규칙을 적용합니다:
474 474
475* **Claude Code도 이를 씁니다.** Claude가 Bash 명령을 실행할 권한을 요청하고 "Yes, and don't ask again"을 선택하면, Claude Code는 해당 [권한 승인](/docs/ko/permissions#permission-system)을 `allow` 규칙으로 여기에 저장합니다.475* **Claude Code도 작성합니다.** Claude가 Bash 명령을 실행할 권한을 요청하고 "Yes, and don't ask again"을 선택하면, Claude Code는 해당 [권한 승인](/docs/ko/permissions#permission-system)을 `allow` 규칙으로 여기에 저장합니다.
476* **직접 생성한 경우가 아니면 gitignore할 필요가 없습니다.** Claude Code가 이미 무시하지 않는 git 저장소에서 파일을 처음 쓸 때, 전역 git 제외 파일에 `**/.claude/settings.local.json`을 추가하므로 모든 저장소의 커밋에서 파일이 제외됩니다. 해당 파일은 전역 git 구성이 절대 경로 또는 `~` 접두사 경로로 설정할 때 `core.excludesFile`입니다. 그렇지 않으면 `$XDG_CONFIG_HOME/git/ignore` 또는 `XDG_CONFIG_HOME`이 설정되지 않을 때 `~/.config/git/ignore`입니다. 파일을 직접 생성했고 Claude Code가 아직 쓰지 않았다면 `.gitignore`에 직접 추가합니다.476* **수동으로 생성한 경우를 제외하고 직접 gitignore할 필요가 없습니다.** Claude Code가 이미 무시하지 않는 git 저장소에서 파일을 처음 작성할 때, 전역 git 제외 파일에 `**/.claude/settings.local.json`을 추가하므로 모든 저장소에서 파일이 커밋에서 제외됩니다. 해당 파일은 전역 git 구성이 절대 경로 또는 `~` 접두사 경로로 설정할 때 `core.excludesFile`입니다. 그렇지 않으면 `$XDG_CONFIG_HOME/git/ignore` 또는 `XDG_CONFIG_HOME`이 설정되지 않을 때 `~/.config/git/ignore`입니다. 수동으로 파일을 생성했고 Claude Code가 아직 작성하지 않았다면 `.gitignore`에 직접 추가합니다.
477* **파일이 추적되지 않는 동안 allow 규칙은 신뢰를 기다리지 않습니다.** 파일이 저장소의 것이 아니라 사용자의 것이므로, Claude Code는 커밋된 파일에 필요한 [workspace trust](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 단계 없이 `allow` 규칙을 적용합니다. 파일이 git으로 추적되면 신뢰 단계도 적용됩니다. [로컬 설정 파일이 신뢰가 필요한 경우](/docs/ko/permissions#when-your-local-settings-file-needs-trust)를 참조합니다.477* **파일이 추적되지 않은 상태에서 허용 규칙은 신뢰를 기다리지 않습니다.** 파일이 저장소의 것이 아니라 사용자의 것이므로, Claude Code는 커밋된 파일에 필요한 [워크스페이스 신뢰](/docs/ko/permissions#project-allow-rules-and-workspace-trust) 단계 없이 `allow` 규칙을 적용합니다. 파일이 git으로 추적되면 신뢰 단계도 적용됩니다. [로컬 설정 파일이 신뢰가 필요한 경우](/docs/ko/permissions#when-your-local-settings-file-needs-trust)를 참조합니다.
478 478
479<span id="where-claude-code-looks-for-each-file" />479<span id="where-claude-code-looks-for-each-file" />
480 480
486 Claude Code가 git 저장소에서 로컬 파일을 보관하는 위치486 Claude Code가 git 저장소에서 로컬 파일을 보관하는 위치
487</h4>487</h4>
488 488
489Claude가 Bash 명령을 실행할 권한을 요청하고 "Yes, and don't ask again"을 선택하면, Claude Code는 해당 승인을 `.claude/settings.local.json`의 `allow` 규칙으로 저장합니다. git 저장소의 하위 디렉토리에서 Claude Code를 시작하면 저장소 루트에서 해당 파일을 읽고 쓰며 전체 저장소에 승인을 적용합니다. [worktree](/docs/ko/worktrees)에서는 주 체크아웃의 루트에서 파일을 사용합니다.489Claude가 Bash 명령을 실행할 권한을 요청하고 "Yes, and don't ask again"을 선택하면, Claude Code는 해당 승인을 `.claude/settings.local.json`의 `allow` 규칙으로 저장합니다. git 저장소의 하위 디렉토리에서 Claude Code를 시작하면 저장소 루트에서 해당 파일을 읽고 작성하며 전체 저장소에 승인을 적용합니다. [worktree](/docs/ko/worktrees)에서는 주 체크아웃의 루트에 있는 파일을 사용합니다.
490 490
491두 가지 규칙이 루트 위치를 한정합니다:491두 가지 규칙이 루트 위치를 한정합니다:
492 492
493* **파일이 `.claude/settings.json` 대신 유지되는 경우**: git 저장소 외부, 저장소 루트가 홈 디렉토리인 경우, Windows에서, 또는 저장소 루트나 `.git` 또는 `.claude` 항목이 사용자가 소유하지 않은 경우.493* **파일이 `.claude/settings.json` 대신 유지되는 경우**: git 저장소 외부, 저장소 루트가 홈 디렉토리인 경우, Windows에서, 또는 저장소 루트나 `.git` 또는 `.claude` 항목이 사용자가 소유하지 않은 경우.
494* **파일의 경로는 저장소 루트에 고정되지 않습니다**: `/`로 시작하거나 상대 sandbox 경로인 권한 규칙은 [세션의 주 작업 디렉토리](/docs/ko/permissions#read-and-edit)에 고정됩니다.494* **파일의 경로는 저장소 루트에 고정되지 않습니다**: `/`로 시작하거나 상대 샌드박스 경로인 권한 규칙은 [세션의 기본 작업 디렉토리](/docs/ko/permissions#read-and-edit)에 고정됩니다.
495 495
496v2.1.211 이전에는 Claude Code가 시작 디렉토리에 파일을 보관했습니다. 이전 버전이 루트 파일 옆에 남긴 파일을 여전히 읽습니다. 둘 다 동일한 키를 설정하면 루트의 값이 적용되고, 두 파일의 권한 규칙이 적용됩니다. Agent SDK의 [`resolveSettings()`](/docs/ko/agent-sdk/typescript#resolvesettings) 헬퍼는 항상 시작 디렉토리에서 파일을 읽습니다.496v2.1.211 이전에는 Claude Code가 시작 디렉토리에 파일을 보관했습니다. 이전 버전이 루트 파일 옆에 남긴 파일을 여전히 읽습니다. 두 파일이 동일한 키를 설정하는 경우 루트의 값이 적용되고, 두 파일의 권한 규칙이 적용됩니다. Agent SDK의 [`resolveSettings()`](/docs/ko/agent-sdk/typescript#resolvesettings) 헬퍼는 항상 시작 디렉토리에서 파일을 읽습니다.
497 497
498Claude Code는 세션의 [주 작업 디렉토리](/docs/ko/permissions#working-directories)에서 공유 `.claude/settings.json`을 읽으므로, 저장소 루트에 커밋된 파일을 사용하려면 거기서 Claude Code를 시작합니다. [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)한 후, Claude Code는 대신 새 디렉토리에서 두 프로젝트 파일을 읽으며, 동일한 규칙으로 로컬 파일을 배치합니다. 이동한 디렉토리에서 읽으려면 Claude Code v2.1.246 이상이 필요합니다.498Claude Code는 공유 `.claude/settings.json`을 세션의 [기본 작업 디렉토리](/docs/ko/permissions#working-directories)에서 읽으므로, 저장소 루트에 커밋된 파일을 사용하려면 거기서 Claude Code를 시작합니다. [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)한 후, Claude Code는 대신 새 디렉토리에서 두 프로젝트 파일을 읽으며, 로컬 파일을 동일한 규칙으로 배치합니다. 이동한 디렉토리에서 읽으려면 Claude Code v2.1.246 이상이 필요합니다.
499 499
500<span id="managed-settings-delivery" />500<span id="managed-settings-delivery" />
501 501
511 조직이 적용하는 항목 확인511 조직이 적용하는 항목 확인
512</h3>512</h3>
513 513
514조직이 Claude Code를 관리하면 일부 설정이 결정되며 자신의 파일에 넣은 것이 변경하지 않습니다. 어떤 것인지 확인하려면 `/status`를 실행합니다. `Setting sources` 줄은 사용자에게 적용되는 관리되는 소스의 이름을 지정합니다. 관리되는 설정은 이 머신에서 Claude Code가 실행되는 모든 곳에 적용됩니다. [개발자가 변경할 수 있는 것](/docs/ko/managed-settings#what-a-developer-can-change)은 로컬 관리자 권한 및 Claude Code 이외의 도구를 다룹니다.514조직이 Claude Code를 관리하는 경우, 일부 설정은 사용자를 위해 결정되며 자신의 파일에 입력한 것이 이를 변경하지 않습니다. 어떤 것인지 확인하려면 `/status`를 실행합니다. `Setting sources` 줄은 사용자에게 적용되는 관리되는 소스의 이름을 지정합니다. 관리되는 설정은 이 머신에서 Claude Code가 실행되는 모든 곳에 적용됩니다. [개발자가 변경할 수 있는 항목](/docs/ko/managed-settings#what-a-developer-can-change)은 로컬 관리자 권한 및 Claude Code 이외의 도구를 다룹니다.
515 515
516관리되는 설정은 관리되는 설정 페이지의 [전달 메커니즘](/docs/ko/managed-settings#delivery-mechanisms)을 통해 사용자에게 도달합니다. 가장 일반적으로:516관리되는 설정은 관리되는 설정 페이지의 [전달 메커니즘](/docs/ko/managed-settings#delivery-mechanisms)을 통해 사용자에게 도달합니다. 가장 일반적으로:
517 517
518* [서버 관리 설정](/docs/ko/server-managed-settings), Claude Code가 claude.ai 관리 콘솔 또는 자체 호스팅 [Claude apps gateway](/docs/ko/claude-apps-gateway)에서 가져옴518* [서버 관리 설정](/docs/ko/server-managed-settings), Claude Code가 claude.ai 관리 콘솔 또는 자체 호스팅 [Claude 앱 게이트웨이](/docs/ko/claude-apps-gateway)에서 가져옴
519* MDM 또는 OS 수준 정책, 및 시스템 디렉토리의 `managed-settings.json` 파일519* MDM 또는 OS 수준 정책, 시스템 디렉토리의 `managed-settings.json` 파일
520* Claude Desktop과 같은 embedding host, SDK `managedSettings` 옵션을 통해. [embedding host에서 정책 제어](/docs/ko/managed-settings#parent-settings-from-embedding-hosts)를 참조합니다520* Claude Desktop과 같은 임베딩 호스트, SDK `managedSettings` 옵션을 통해. [임베딩 호스트에서 정책 제어](/docs/ko/managed-settings#parent-settings-from-embedding-hosts)를 참조합니다.
521 521
522Claude Desktop 앱에서 머신에서 실행되는 [Cowork](https://claude.com/docs/cowork/overview) 세션에서 Claude Code는 claude.ai 관리 콘솔에서 서버 관리 설정을 가져오지 않으며, 조직의 Claude Desktop 구성이 `requireCoworkFullVmSandbox`를 설정하지 않으면 디바이스에 배포된 정책을 읽습니다. [정책이 적용되는 위치 및 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)는 Cowork 및 클라우드 세션을 다룹니다.522Claude Desktop 앱에서 머신에서 실행되는 [Cowork](https://claude.com/docs/cowork/overview) 세션에서, Claude Code는 claude.ai 관리 콘솔에서 서버 관리 설정을 가져오지 않으며, 조직의 Claude Desktop 구성이 `requireCoworkFullVmSandbox`를 설정하지 않는 한 디바이스에 배포된 정책을 읽습니다. [정책이 적용되는 위치 및 시기](/docs/ko/managed-settings#where-and-when-a-policy-applies)는 Cowork 및 클라우드 세션을 다룹니다.
523 523
524관리자인 경우 [조직을 위해 Claude Code 설정](/docs/ko/admin-setup)은 적용할 항목 선택을 안내하고, [관리되는 설정 배포](/docs/ko/managed-settings)는 전달 및 정책이 적용 중인지 확인하는 방법을 다룹니다.524관리자인 경우, [조직을 위해 Claude Code 설정](/docs/ko/admin-setup)은 적용할 항목 선택을 안내하고, [관리되는 설정 배포](/docs/ko/managed-settings)는 전달 및 정책이 적용 중인지 확인하는 방법을 다룹니다.
525 525
526<h2 id="change-a-setting">526<h2 id="change-a-setting">
527 설정 변경527 설정 변경
598예를 들어 기본값을 변경하지 않고 한 세션을 Opus에서 시작하려면:598예를 들어 기본값을 변경하지 않고 한 세션을 Opus에서 시작하려면:
599 599
600```bash theme={null}600```bash theme={null}
601claude --settings '{"model": "claude-opus-4-8"}'601claude --settings '{"model": "claude-opus-5-5"}'
602```602```
603 603
604<h3 id="when-edits-take-effect">604<h3 id="when-edits-take-effect">
803 803
804[클라우드 세션](/docs/ko/claude-code-on-the-web)은 [클라우드 환경](/docs/ko/cloud-environments)에서 저장소의 신선한 복제본에서 실행되며, 머신에서 실행되지 않습니다. 이는 어느 설정이 도달하는지 변경합니다:804[클라우드 세션](/docs/ko/claude-code-on-the-web)은 [클라우드 환경](/docs/ko/cloud-environments)에서 저장소의 신선한 복제본에서 실행되며, 머신에서 실행되지 않습니다. 이는 어느 설정이 도달하는지 변경합니다:
805 805
806* **공유 프로젝트 설정** (`.claude/settings.json`): 한 저장소가 있는 세션에서 읽습니다. 파일이 복제본의 일부이고 세션이 그 안에서 시작되기 때문입니다. 해당 세션에 적용하려면 설정을 거기에 커밋합니다. 여러 저장소가 있는 세션은 복제본 위에서 시작되므로, 각 저장소의 `.claude/settings.json`에서 파일이 선언하는 플러그인과 마켓플레이스만 로드하고, 권한 규칙, hooks, `env` 또는 기타 키는 로드하지 않습니다. [설정에서 수행되는 것](/docs/ko/cloud-environments#what-carries-over-from-your-setup)을 참조하세요.806* **공유 프로젝트 설정** (`.claude/settings.json`): 한 저장소가 있는 세션에서 읽습니다. 파일이 복제본의 일부이고 세션이 그 안에서 시작되기 때문입니다. 해당 세션에 적용하려면 설정을 거기에 커밋합니다. 여러 저장소가 있는 세션은 복제본 위에서 시작되고 각 저장소의 `.claude/settings.json`에서 `enabledPlugins` 및 `extraKnownMarketplaces` 키만 읽으며, 권한 규칙, hooks, `env` 또는 기타 키는 읽지 않습니다. 이 두 키가 선언하는 마켓플레이스와 플러그인은 여전히 [클라우드 세션에서 로드되지 않습니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup).
807* **사용자 및 프로젝트 로컬 설정** (`~/.claude/settings.json` 및 `.claude/settings.local.json`): 읽지 않습니다. 둘 다 머신에 유지되고 로컬 파일은 복제본에 없습니다.807* **사용자 및 프로젝트 로컬 설정** (`~/.claude/settings.json` 및 `.claude/settings.local.json`): 읽지 않습니다. 둘 다 머신에 유지되고 로컬 파일은 복제본에 없습니다.
808* **관리되는 설정**: [서버 관리 설정](/docs/ko/server-managed-settings)만 클라우드 세션에 도달합니다. 장치의 `managed-settings.json` 파일이나 MDM 프로필은 도달하지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)도 실행기 이미지의 관리되는 설정 파일을 읽습니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 해당 파일이 적용되는 시기를 설명합니다.808* **관리되는 설정**: [서버 관리 설정](/docs/ko/server-managed-settings)만 클라우드 세션에 도달합니다. 장치의 `managed-settings.json` 파일이나 MDM 프로필은 도달하지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)도 실행기 이미지의 관리되는 설정 파일을 읽습니다. [Claude Code가 관리되는 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)은 해당 파일이 적용되는 시기를 설명합니다.
809* **`/config`**: 브라우저에서 claude.ai/code에서 설정 값을 변경하는 대신 claude.ai 설정의 Claude Code 섹션을 엽니다. 클라우드 세션에 대해 설정을 변경하려면 환경에서 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)를 설정하거나, 한 저장소가 있는 세션에서 해당 저장소의 `.claude/settings.json`에 키를 커밋합니다.809* **`/config`**: 브라우저에서 claude.ai/code에서 설정 값을 변경하는 대신 claude.ai 설정의 Claude Code 섹션을 엽니다. 클라우드 세션에 대해 설정을 변경하려면 환경에서 [환경 변수](/docs/ko/cloud-environments#set-environment-variables)를 설정하거나, 한 저장소가 있는 세션에서 해당 저장소의 `.claude/settings.json`에 키를 커밋합니다.